@demlik/tea 0.1.0 → 0.1.1

package/dist/snapshot/index.d.ts

@@ -0,0 +1,334 @@
+import { C as Cmd, I as Interpret } from '../core-CymXZCeY.js';
+
+/**
+ * @demlik/tea/snapshot — periodic state checkpoint to a host store (R2/KV-shaped).
+ *
+ * The problem it solves: a long-running machine (a multi-stage run, a paginated
+ * crawl, a saga) lives in TEA's in-memory `State` and is persisted as ONE blob
+ * by the substrate's `Store<S>` on every transition. That blob is fine for
+ * crash recovery of the *runtime* — but it is NOT a coarse, named checkpoint a
+ * human (or a separate recovery job) can point a restart at. `snapshot` adds
+ * the "every N units of progress, write a durable checkpoint to R2/KV"
+ * discipline on top, so a crashed long run restarts from the last checkpoint
+ * instead of from zero (the field-guide pain row).
+ *
+ * Shape: this is the same knob contract every L2 composition follows —
+ * `createSnapshot(config)` hands back a `{ init, <verbs>, handlers }` bundle you
+ * splice into your machine. The state it owns is a Model slice (durable +
+ * replayable, the two non-negotiables); the verbs are PURE decisions; the I/O
+ * (the actual `put` to the store) lives only in `handlers`.
+ *
+ * It is a LEAF module: it imports only the core substrate (`../index`, for
+ * `Cmd` / `Interpret`) and no sibling subpath. (It does NOT reuse
+ * `@demlik/tea/retry-backoff` — that is an even-leafier utility that depends on
+ * nothing at all, not even the core; the kinship here is "leaf with injected
+ * time", not a shared dependency.)
+ * Nothing here reads the clock or the RNG on its own behalf — time enters as an
+ * `at`/`now` parameter at the verb boundary and the store I/O is realized only
+ * when the runtime performs the emitted `Cmd`. That keeps every verb
+ * deterministic (invariant 2) and the checkpoint write a `Cmd` the runtime
+ * interprets (invariant 3).
+ *
+ * The Store port is deliberately ABSTRACT — `{ get, put }`, the lowest common
+ * shape of R2 and KV — so this module never imports `@cloudflare/workers-types`
+ * and can be checkpointed to anything (R2, KV, a DO sub-key, an in-memory map in
+ * tests). The host binds the concrete adapter at `handlers({ store })`.
+ *
+ * Typical wiring:
+ *
+ *   const snap = createSnapshot<RunState>({ every: 25, key: "run/checkpoint" });
+ *
+ *   // machine state:
+ *   type State = { run: RunState; snapshot: SnapshotState };
+ *   init: (loaded) => loaded ? [loaded, []] : [{ run: initRun(), snapshot: snap.init() }, []],
+ *
+ *   // in `update`, on each progress Msg, fold the snapshot slice:
+ *   progress: (s, msg) => {
+ *     const run = advance(s.run, msg);
+ *     const [snapshot, cmds] = snap.record(s.snapshot, run, msg.at);
+ *     return [{ ...s, run, snapshot }, cmds];
+ *   },
+ *   // the write completed → durable ack folds back through update:
+ *   snapshot_saved: (s, msg) => {
+ *     const [snapshot, cmds] = snap.confirm(s.snapshot, msg);
+ *     return [{ ...s, snapshot }, cmds];
+ *   },
+ *
+ *   // RECOVERY — the half that makes a checkpoint a restart point, not just a
+ *   // backup. A `boot` Msg the host dispatches once after `run(...)` asks the
+ *   // store for the durable checkpoint; the answer folds the recovered payload
+ *   // back into the run slice:
+ *   boot: (s) => snap.requestLoad(s),                       // emits snapshot_load Cmd
+ *   snapshot_loaded: (s, msg) => {
+ *     if (msg.payload === null) return [s, []];             // no checkpoint → keep fresh init
+ *     const [snapshot, cmds] = snap.boot(s.snapshot);
+ *     return [{ ...s, run: msg.payload, snapshot }, cmds];
+ *   },
+ *   snapshot_load_failed: (s) => [s, []],                   // errors are data — decide here
+ *
+ *   // splice the I/O — both effect cells (write + load):
+ *   interpret: { ...snap.handlers({ store: r2Adapter }) },
+ */
+
+/**
+ * The snapshot knob.
+ *
+ * `every` is the cadence: a checkpoint is written once `every` units of
+ * progress have accumulated since the last one (see `record`). It is the
+ * `snapshotEvery` field `monitored-run` threads through to this module.
+ *
+ * `key` is the store key the checkpoint is written under. A single machine
+ * keeps a single rolling checkpoint, so the key is fixed at config time rather
+ * than passed per write — the latest checkpoint overwrites the previous one
+ * (R2/KV are last-write-wins on a key). Defaults to `"@@snapshot"`, mirroring
+ * `doStore`'s `@@state` default-key convention.
+ */
+interface SnapshotConfig {
+    /**
+     * Write a checkpoint once this many progress units have accumulated since the
+     * last write. `every: 1` checkpoints on every `record`; a value `<= 0` is
+     * treated as `1` (every progress unit triggers a write) — a non-positive
+     * cadence has no other sensible meaning, and clamping keeps `record` from
+     * never checkpointing on a misconfigured `0`.
+     */
+    readonly every: number;
+    /** Store key the rolling checkpoint is written under. Defaults to `"@@snapshot"`. */
+    readonly key?: string;
+}
+/**
+ * The snapshot bookkeeping slice. Plain data — JSON-serializable so it rides
+ * inside the consumer's `Store<S>` blob and survives DO eviction / reload (the
+ * "durable" non-negotiable). It carries NO payload: the thing being
+ * checkpointed lives elsewhere in the machine's state; this slice only tracks
+ * *when* to checkpoint and *what has been acknowledged durable*.
+ *
+ *   - `sinceLast` — progress units accumulated since the last checkpoint
+ *     DECISION (reset to 0 the moment `record` decides to write, not when the
+ *     write lands). The cadence counter.
+ *   - `seq` — monotonic checkpoint sequence. Bumped each time a write is
+ *     emitted, so the write Cmd and its later acknowledgement can be matched
+ *     even if several are in flight. The "version" of the latest emitted
+ *     checkpoint.
+ *   - `lastSavedSeq` — the highest `seq` whose write the host has confirmed
+ *     durable (via `confirm`). `null` until the first confirmed write. The gap
+ *     `seq - lastSavedSeq` is the "writes emitted but not yet acknowledged"
+ *     depth — observable for backpressure / health.
+ *   - `lastSavedAt` — the `at` of the most recent confirmed write (epoch ms),
+ *     `null` until the first. Carried for observability, never compared inside
+ *     a verb (time is injected, never read here).
+ */
+interface SnapshotState {
+    readonly sinceLast: number;
+    readonly seq: number;
+    readonly lastSavedSeq: number | null;
+    readonly lastSavedAt: number | null;
+}
+/**
+ * The abstract checkpoint sink — the intersection of R2's and KV's surface,
+ * narrowed to exactly the two methods a rolling checkpoint needs. Deliberately
+ * NOT the substrate's `Store<S>` (`{ load, save, migrate }`): that is the
+ * runtime's whole-state persistence boundary keyed at a fixed cell, whereas a
+ * checkpoint store is keyed, value-typed, and host-supplied.
+ *
+ *   - `put(key, value)` — write the checkpoint. Last-write-wins on `key`.
+ *   - `get(key)` — read the latest checkpoint back, or `null` if none. Used by
+ *     a recovery path to seed `init`'s `loaded` from the durable checkpoint
+ *     when the runtime's own `Store<S>` blob is gone.
+ *
+ * No `@cloudflare/workers-types` import — an R2 bucket, a KV namespace, a DO
+ * sub-key, or an in-memory `Map` all satisfy this shape with a 3-line adapter
+ * at the host.
+ */
+interface SnapshotStore<V> {
+    get(key: string): Promise<V | null>;
+    put(key: string, value: V): Promise<void>;
+}
+/**
+ * The ports `handlers` binds. Just the store today — named so a future port
+ * (a metrics sink, a clock) can grow without breaking the `handlers(ports)`
+ * call shape.
+ */
+interface SnapshotPorts<V> {
+    readonly store: SnapshotStore<V>;
+}
+/**
+ * The checkpoint-write Cmd a `record` / `force` decision emits. Plain data
+ * (invariant 1 — Cmds are data, not closures): it carries the `payload` to
+ * write, the `key` to write it under, the `seq` it represents, and the `at` it
+ * was decided. The handler performs the `put` and routes the result back to a
+ * `confirm` / fail Msg.
+ *
+ * `payload` is `V` — the consumer's serializable checkpoint value (the run
+ * state, the cursor, whatever the machine wants restartable). The verb takes it
+ * as an argument so the snapshot slice never has to hold a copy of the
+ * machine's domain state.
+ */
+type SnapshotWriteCmd<V> = Cmd<"snapshot_write"> & {
+    readonly key: string;
+    readonly seq: number;
+    readonly at: number;
+    readonly payload: V;
+};
+/**
+ * The Msg the write handler dispatches on a SUCCESSFUL `put`. Fold it back
+ * through `confirm(state, msg)` to advance `lastSavedSeq` / `lastSavedAt`. The
+ * `seq` matches the emitting Cmd so a late acknowledgement of an older write
+ * can never regress a newer confirmed one.
+ */
+type SnapshotSavedMsg = {
+    readonly type: "snapshot_saved";
+    readonly seq: number;
+    readonly at: number;
+};
+/**
+ * The Msg the write handler dispatches on a FAILED `put`. Errors are data
+ * (never swallowed): the consumer's reducer decides whether a failed checkpoint
+ * is fatal, retryable (compose `@demlik/tea/retry-backoff`), or merely logged.
+ * `seq` identifies which checkpoint failed; `error` is carried, never
+ * interpreted here.
+ */
+type SnapshotFailedMsg = {
+    readonly type: "snapshot_failed";
+    readonly seq: number;
+    readonly error: unknown;
+};
+/**
+ * The checkpoint-READ Cmd a `requestLoad` decision emits — the recovery half of
+ * the module. Plain data (invariant 1): it carries only the `key` to read. The
+ * handler performs `store.get(key)` and routes the result back to a
+ * `snapshot_loaded` (Ok, payload-or-null) / `snapshot_load_failed` (Err) Msg.
+ *
+ * Distinct from `snapshot_write`: a write carries a payload OUT to the store; a
+ * load asks the store to hand a payload BACK. The consumer dispatches the
+ * triggering Msg once on resume (a `boot` Msg, never `init`'s rehydrate branch —
+ * invariant 2), folds the recovered payload into its run slice, then continues.
+ */
+type SnapshotLoadCmd = Cmd<"snapshot_load"> & {
+    readonly key: string;
+};
+/**
+ * The Msg the load handler dispatches when `store.get` RESOLVES. `payload` is
+ * the recovered checkpoint value, or `null` when the store has no checkpoint
+ * under `key` (fresh boot — never checkpointed, or a wiped store). The consumer
+ * folds this into `init`'s loaded branch: `payload === null` → keep the fresh
+ * `init` state; non-null → seed the run slice from the durable checkpoint and
+ * `boot` the snapshot slice's cadence counter.
+ *
+ * A `null` payload is NOT an error — "no checkpoint yet" is a normal first-run
+ * state, distinct from "the read failed" (`snapshot_load_failed`).
+ */
+type SnapshotLoadedMsg<V> = {
+    readonly type: "snapshot_loaded";
+    readonly payload: V | null;
+};
+/**
+ * The Msg the load handler dispatches when `store.get` REJECTS. Errors are data
+ * (never swallowed — the field-guide rule): a failed recovery read is a visible
+ * signal the consumer's reducer decides on (fatal-abort, retry via
+ * `@demlik/tea/retry-backoff`, or boot-fresh-and-log). `error` is carried, never
+ * interpreted here. Kept separate from `snapshot_loaded`'s `null` so "the store
+ * has no checkpoint" can never masquerade as "the read failed".
+ */
+type SnapshotLoadFailedMsg = {
+    readonly type: "snapshot_load_failed";
+    readonly error: unknown;
+};
+/** Construct a `snapshot_saved` Msg. Shared by the handler and tests so the wire shape can't drift. */
+declare function snapshotSaved(seq: number, at: number): SnapshotSavedMsg;
+/** Construct a `snapshot_failed` Msg. Shared by the handler and tests so the wire shape can't drift. */
+declare function snapshotFailed(seq: number, error: unknown): SnapshotFailedMsg;
+/** Construct a `snapshot_loaded` Msg. Shared by the handler and tests so the wire shape can't drift. */
+declare function snapshotLoaded<V>(payload: V | null): SnapshotLoadedMsg<V>;
+/** Construct a `snapshot_load_failed` Msg. Shared by the handler and tests so the wire shape can't drift. */
+declare function snapshotLoadFailed(error: unknown): SnapshotLoadFailedMsg;
+/**
+ * The bundle `createSnapshot` returns — the uniform knob contract. `subs` is
+ * omitted: a checkpoint is driven by progress (a `record` call from the
+ * consumer's reducer), not by a timer, so this module has no subscriptions.
+ */
+interface SnapshotKnob<V> {
+    /** The initial slice — zero progress, no checkpoint emitted or confirmed yet. */
+    init(): SnapshotState;
+    /**
+     * Account one unit of progress. PURE. Increments `sinceLast`; once the
+     * accumulated count reaches the configured cadence, DECIDES to checkpoint:
+     * resets `sinceLast` to 0, bumps `seq`, and emits a single `snapshot_write`
+     * Cmd carrying `payload` + `key` + the new `seq` + `at`. Below the cadence it
+     * returns the bumped slice and NO Cmd.
+     *
+     * `payload` is the checkpoint value to persist (the consumer's domain state);
+     * `at` is the caller-stamped time the progress occurred (epoch ms) — injected,
+     * never read from the clock here.
+     */
+    record(state: SnapshotState, payload: V, at: number): readonly [SnapshotState, readonly Cmd[]];
+    /**
+     * Force a checkpoint regardless of the cadence counter. PURE. Always bumps
+     * `seq`, resets `sinceLast`, and emits the write Cmd. Use on a phase boundary
+     * the cadence would otherwise miss — e.g. "the run just finished, checkpoint
+     * the terminal state now" — so the last durable checkpoint is the final state,
+     * not whatever the modulo happened to land on.
+     */
+    force(state: SnapshotState, payload: V, at: number): readonly [SnapshotState, readonly Cmd[]];
+    /**
+     * Record a confirmed durable write. PURE. Advances `lastSavedSeq` /
+     * `lastSavedAt` to the acknowledged `seq` / `at`, but only forward: an
+     * out-of-order acknowledgement of an OLDER `seq` (a slow write landing after a
+     * newer one) is ignored, so the confirmed watermark is monotonic. Fold the
+     * `snapshot_saved` Msg here.
+     *
+     * Returns the reducer-cell shape `readonly [SnapshotState, readonly Cmd[]]`
+     * (with `Cmd.none` — an ack emits nothing) for uniformity with every sibling
+     * knob, so it drops straight into a `snapshot_saved` cell without the caller
+     * re-wrapping a bare State.
+     */
+    confirm(state: SnapshotState, msg: SnapshotSavedMsg): readonly [SnapshotState, readonly Cmd[]];
+    /**
+     * Resume after a reload. PURE. Resets `sinceLast` to 0 because any
+     * un-checkpointed progress accumulated before the crash is moot — recovery
+     * resumes from the last DURABLE checkpoint (`get` from the store), so the
+     * cadence counter starts fresh from there. `seq` / `lastSavedSeq` /
+     * `lastSavedAt` are preserved (they describe what is durable, which a reload
+     * does not change). Call from a `boot` Msg the host dispatches once after
+     * `run(...)`, never from `init`'s rehydrate branch (invariant 2).
+     *
+     * Returns the reducer-cell shape `readonly [SnapshotState, readonly Cmd[]]`
+     * (with `Cmd.none` — a resume emits nothing) for uniformity with every sibling
+     * knob, so it drops straight into a `snapshot_loaded` cell without the caller
+     * re-wrapping a bare State.
+     */
+    boot(state: SnapshotState): readonly [SnapshotState, readonly Cmd[]];
+    /**
+     * Ask the store for the durable checkpoint. PURE. Emits a single
+     * `snapshot_load` Cmd carrying the configured `key`; returns the slice
+     * UNCHANGED (a read decides nothing about the cadence bookkeeping — only the
+     * later `snapshot_loaded` fold, via `boot`, touches the slice). This is the
+     * entry point of the recovery loop: the consumer dispatches a `boot` Msg once
+     * after `run(...)`, folds `requestLoad` here, and the emitted Cmd's handler
+     * reads `store.get(key)` and dispatches `snapshot_loaded` / `snapshot_load_failed`.
+     *
+     * Returns `readonly [SnapshotState, readonly Cmd[]]` (the reducer-cell shape)
+     * so it drops straight into a `boot: (s) => snap.requestLoad(s)` cell.
+     */
+    requestLoad(state: SnapshotState): readonly [SnapshotState, readonly Cmd[]];
+    /**
+     * The `interpret` map for this knob's two effect Cmds:
+     *
+     *   - `snapshot_write` — binds the store and performs the `put`, routing
+     *     Ok → `snapshot_saved` / Err → `snapshot_failed`.
+     *   - `snapshot_load`  — binds the store and performs the `get`, routing
+     *     Ok → `snapshot_loaded` (payload-or-null) / Err → `snapshot_load_failed`.
+     *
+     * Railway throughout — neither effect throws into the runtime; the outcome is
+     * always a Msg. Spread into your machine's `interpret`.
+     */
+    handlers(ports: SnapshotPorts<V>): Interpret<SnapshotSavedMsg | SnapshotFailedMsg | SnapshotLoadedMsg<V> | SnapshotLoadFailedMsg, SnapshotWriteCmd<V> | SnapshotLoadCmd, unknown>;
+}
+/**
+ * Create a snapshot knob from a `SnapshotConfig`. The returned bundle is spliced
+ * into a consumer machine: `init()` seeds the slice, `record` / `force` are
+ * folded in reducer cells, `confirm` / `boot` handle the acknowledgement +
+ * resume Msgs, and `handlers({ store })` supplies the write `interpret` cell.
+ */
+declare function createSnapshot<V>(config: SnapshotConfig): SnapshotKnob<V>;
+
+export { type SnapshotConfig, type SnapshotFailedMsg, type SnapshotKnob, type SnapshotLoadCmd, type SnapshotLoadFailedMsg, type SnapshotLoadedMsg, type SnapshotPorts, type SnapshotSavedMsg, type SnapshotState, type SnapshotStore, type SnapshotWriteCmd, createSnapshot, snapshotFailed, snapshotLoadFailed, snapshotLoaded, snapshotSaved };

package/dist/snapshot/index.js

@@ -0,0 +1,5 @@
+export { createSnapshot, snapshotFailed, snapshotLoadFailed, snapshotLoaded, snapshotSaved } from '../chunk-EIZJTYKR.js';
+import '../chunk-2WZHS4P2.js';
+import '../chunk-BNJYE4AU.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/snapshot/index.js.map

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

package/dist/subs/index.d.ts

@@ -1,5 +1,6 @@
-import { Sub, Runtime, Port } from '../index.js';
-import { S as SubscribeHandler } from '../types-CwBC5wMn.js';
+import { S as Sub, P as Port } from '../core-CymXZCeY.js';
+import { S as SubscribeHandler } from '../types-N9LZbdnr.js';
+import { Runtime } from '../index.js';
 
 interface MinimalEvent {
     readonly type: string;
@@ -11,6 +12,17 @@ interface MinimalEventTarget {
     addEventListener(type: string, listener: (event: MinimalEvent) => void): void;
     removeEventListener(type: string, listener: (event: MinimalEvent) => void): void;
 }
+interface MinimalCloseEvent extends MinimalEvent {
+    readonly code: number;
+    readonly reason: string;
+}
+interface MinimalWebSocket {
+    close(code?: number, reason?: string): void;
+    onopen: ((event: MinimalEvent) => void) | null;
+    onmessage: ((event: MinimalMessageEvent) => void) | null;
+    onerror: ((event: MinimalEvent) => void) | null;
+    onclose: ((event: MinimalCloseEvent) => void) | null;
+}
 
 type BroadcastSubData = {
     channelName: string;
@@ -34,14 +46,11 @@ type IntervalSubData = {
 };
 declare function fromInterval<S extends Sub & IntervalSubData, M>(msgFn: (sub: S) => M): SubscribeHandler<S, M, unknown>;
 
-declare function fromPort<S extends Sub, M, Ctx, T>(selectRuntime: (ctx: Ctx) => Runtime<unknown, {
+declare function fromPort<S extends Sub, M, Ctx, T, RS = unknown, RM extends {
     type: string;
-}>, port: Port<T>, msgFn: (value: T, sub: S) => M | null): SubscribeHandler<S, M, Ctx>;
-
-type TimeoutSubData = {
-    delayMs: number;
-};
-declare function fromTimeout<S extends Sub & TimeoutSubData, M>(msgFn: (sub: S) => M): SubscribeHandler<S, M, unknown>;
+} = {
+    type: string;
+}>(selectRuntime: (ctx: Ctx) => Runtime<RS, RM>, port: Port<T>, msgFn: (value: T, sub: S) => M | null): SubscribeHandler<S, M, Ctx>;
 
 type WebSocketSubData = {
     wsUrl: string;
@@ -54,4 +63,33 @@ interface WebSocketFactoryOpts<S, M> {
 }
 declare function fromWebSocket<S extends Sub & WebSocketSubData, M>(opts: WebSocketFactoryOpts<S, M>): SubscribeHandler<S, M, unknown>;
 
-export { type EventSourceFactoryOpts, SubscribeHandler, type WebSocketFactoryOpts, type WebSocketSubData, fromBroadcastChannel, fromEventSource, fromEventTarget, fromInterval, fromPort, fromTimeout, fromWebSocket };
+/** Cancels a scheduled reconnect timer (the inverse of `schedule`). */
+type CancelTimer = () => void;
+interface ReconnectingWebSocketFactoryOpts<S, M> {
+    onMessage: (data: unknown, sub: S) => M | null;
+    onOpen?: (sub: S) => M | null;
+    onError?: (event: MinimalEvent, sub: S) => M | null;
+    onClose?: (code: number, reason: string, sub: S) => M | null;
+    /**
+     * Fires when a reconnection (any open after the first) succeeds, carrying the
+     * 1-based reconnect count — the resync hook. Omitting drops reconnect events
+     * silently.
+     */
+    onReconnect?: (attempt: number, sub: S) => M | null;
+    /** First backoff delay in ms (doubles each failed attempt). Default 250. */
+    backoffBaseMs?: number;
+    /** Backoff ceiling in ms. Default 5000. */
+    backoffMaxMs?: number;
+    /** Inject the socket constructor (defaults to the global `WebSocket`); the test seam. */
+    connect?: (url: string) => MinimalWebSocket;
+    /** Inject the timer (defaults to `setTimeout`/`clearTimeout`); the test seam. */
+    schedule?: (fn: () => void, ms: number) => CancelTimer;
+}
+declare function fromReconnectingWebSocket<S extends Sub & WebSocketSubData, M>(opts: ReconnectingWebSocketFactoryOpts<S, M>): SubscribeHandler<S, M, unknown>;
+
+type TimeoutSubData = {
+    delayMs: number;
+};
+declare function fromTimeout<S extends Sub & TimeoutSubData, M>(msgFn: (sub: S) => M): SubscribeHandler<S, M, unknown>;
+
+export { type CancelTimer, type EventSourceFactoryOpts, type ReconnectingWebSocketFactoryOpts, SubscribeHandler, type WebSocketFactoryOpts, type WebSocketSubData, fromBroadcastChannel, fromEventSource, fromEventTarget, fromInterval, fromPort, fromReconnectingWebSocket, fromTimeout, fromWebSocket };

package/dist/subs/index.js

@@ -1,4 +1,4 @@
-export { fromBroadcastChannel, fromEventSource, fromEventTarget, fromInterval, fromPort, fromWebSocket } from '../chunk-Y5JM3UUH.js';
+export { fromBroadcastChannel, fromEventSource, fromEventTarget, fromInterval, fromPort, fromReconnectingWebSocket, fromWebSocket } from '../chunk-NSDFA6M6.js';
 export { fromTimeout } from '../chunk-2YFLOCWX.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/testing/index.d.ts

@@ -1,4 +1,109 @@
-import { Cmd, Sub, Machine, Runtime } from '../index.js';
+import { C as Cmd, S as Sub, M as Machine } from '../core-CymXZCeY.js';
+import { Runtime } from '../index.js';
+
+/**
+ * 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;
 
 /**
  * Shared options shape for every test assertion below. Mirrors the
@@ -217,4 +322,4 @@ declare function stateFactory<S extends {
     type: string;
 }>(defaults: StateFactoryDefaults<S>): StateFactoryAPI<S>;
 
-export { type BoundMachine, type ReplayOpts, type StateFactoryAPI, type StateFactoryDefaults, bindMachine, expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, noopRuntime, stateFactory, step };
+export { type AssertWrapperFaithfulOpts, type BoundMachine, type InterceptingOpt, type ReplayOpts, type StateFactoryAPI, type StateFactoryDefaults, type WrapperModel, assertWrapperFaithful, bindMachine, expectActiveSubs, expectCmdEmitted, expectCmdSequence, expectFinalState, noopRuntime, stateFactory, step };