@demlik/tea 0.12.0 → 0.14.0

package/dist/core-CTzMJ82M.d.ts

@@ -0,0 +1,562 @@
+import { z } from 'zod';
+
+/**
+ * @demlik/tea — pure-core leaf (ADR 0006).
+ *
+ * This is the runtime-free pure core of the substrate. It holds the
+ * client-prediction fold seam (`foldMsgs`), the form reader
+ * (`formOf`/`detectUpdateForm`), and the pure type vocabulary (`Machine`,
+ * `Reducer`, `Transitions`, `Cmd`, `Sub`, `Port`, …).
+ *
+ * **Dependency direction (the actual decoupling):** this module imports
+ * NOTHING from the runtime — no `better-result`, no `run`/host/`Store`. The
+ * runtime (`run`, the host, interpret, `Store`, subscribe — all in
+ * `../index.ts`) imports *from* here; never the reverse. The root door
+ * re-exports this surface through `./index.ts`, and
+ * `pure/import-graph.test.ts` is the regression fence asserting the pure
+ * entrypoint's import graph never reaches `run`.
+ *
+ * The one external name it reaches for is zod's TYPE surface (`import type`),
+ * erased at compile time — `Cmd.define` accepts zod schemas, and the parse
+ * against them happens at the interpret edge in `../run.ts`, never here.
+ */
+
+type RequirementsOf<C> = C extends {
+    readonly __r?: infer R;
+} ? R : unknown;
+/** The `E` union one Cmd can settle with; `unknown` for an untyped Cmd. */
+type ErrorsOf<C> = C extends {
+    readonly __e?: infer E;
+} ? E : unknown;
+type UnionToIntersection<U> = (U extends unknown ? (u: U) => void : never) extends (u: infer I) => void ? I : never;
+type RequirementsBoxed<C> = C extends unknown ? [RequirementsOf<C>] : never;
+type KnownRequirements<B> = B extends [infer R] ? unknown extends R ? never : R : never;
+/**
+ * The `ctx` a machine's whole Cmd union requires: every Cmd's `R`, intersected.
+ * `run` types its `ctx` as `Ctx & RequiredCtx<C>`, so handing a machine whose
+ * Cmds need `{ http }` to a `run` whose ctx lacks it is a compile error. A Cmd
+ * that requires nothing — untyped, or `Cmd.define`d without `requirements` — leaves
+ * the demand of its siblings intact (#56).
+ *
+ * This is the requirement. `provide` is what satisfies it: hand `run` a
+ * `provide({ … })` graph in place of the object and the same `Ctx` is built once
+ * at boot, in dependency order, and released in reverse when the run ends.
+ */
+type RequiredCtx<C> = UnionToIntersection<KnownRequirements<RequirementsBoxed<C>>>;
+/** The shape every settled failure has (ADR 0011): a plain `_tag` record. */
+type Tagged = {
+    readonly _tag: string;
+};
+/**
+ * One declared failure per tag. Distributive, so `TaggedError<"a" | "b">` is
+ * the two-arm union a `switch (error._tag)` narrows; the index signature lets a
+ * settle site carry detail beside the tag (`{ _tag: "timeout", afterMs }`).
+ */
+type TaggedError<Tag extends string> = Tag extends string ? {
+    readonly _tag: Tag;
+    readonly [detail: string]: unknown;
+} : never;
+/**
+ * The kernel-minted failure: a handler returned a `_ok` value the Cmd's `ok`
+ * schema rejects. Plain data, so it folds into Model like any settled error;
+ * `issues` is zod's issue list flattened to `path` + `message` strings.
+ */
+type MalformedResult = {
+    readonly _tag: "malformed_result";
+    readonly issues: ReadonlyArray<{
+        readonly path: string;
+        readonly message: string;
+    }>;
+};
+/**
+ * The payload a constructor accepts: a plain record spread beside `type`. A
+ * `type` key is refused at the type level — it would overwrite the discriminant.
+ */
+type CmdInput = {
+    readonly type?: never;
+} & Record<string, unknown>;
+/**
+ * Phantom carrier for a Cmd's `R`. `Cmd.requirements<{ http: Http }>()` is how a
+ * declaration names the `Ctx` slice its handler reads — a type, not a value, so
+ * nothing is constructed and nothing is checked at runtime.
+ */
+type Requirements<R> = {
+    readonly __r?: R;
+};
+/** The value `Cmd.define("fetch", …)` builds: `{ type: "fetch", ...input }`. */
+type CmdValue<Name extends string, Input extends CmdInput, E extends Tagged, R> = Cmd<Name, E | MalformedResult, R> & Readonly<Input>;
+type SettledOk<Name extends string, C, Ok> = {
+    readonly type: `${Name}_ok`;
+    readonly cmd: C;
+    readonly value: Ok;
+    /** Stamped by the runtime at the interpret edge (`run`'s `clock`). */
+    readonly at: number;
+};
+type SettledErr<Name extends string, C, E extends Tagged> = {
+    readonly type: `${Name}_err`;
+    readonly cmd: C;
+    readonly error: E | MalformedResult;
+    /** Stamped by the runtime at the interpret edge (`run`'s `clock`). */
+    readonly at: number;
+};
+/**
+ * What `Cmd.define` returns: the Cmd builder itself (`fetch({ url })`), with
+ * the minted Msg builders and the declaration hung on it. `E` here is the
+ * DECLARED tag union; the settled `_err` arm widens it by `MalformedResult`.
+ *
+ * `ok` / `err` take an optional `at` for minting OUTSIDE the runtime (a
+ * `replay` log, a unit test); inside `run` the interpret edge stamps it from
+ * the clock, so a handler never reads `Date.now()` itself.
+ */
+interface CmdDef<Name extends string, Input extends CmdInput, Ok, E extends Tagged, R> {
+    (input: Input): CmdValue<Name, Input, E, R>;
+    /** The `type` discriminant of every Cmd this builds. */
+    readonly cmdType: Name;
+    readonly okType: `${Name}_ok`;
+    readonly errType: `${Name}_err`;
+    readonly ok: (cmd: CmdValue<Name, Input, E, R>, value: Ok, at?: number) => SettledOk<Name, CmdValue<Name, Input, E, R>, Ok>;
+    readonly err: (cmd: CmdValue<Name, Input, E, R>, error: E, at?: number) => SettledErr<Name, CmdValue<Name, Input, E, R>, E>;
+    readonly schema: {
+        readonly input: z.ZodType<Input>;
+        readonly ok: z.ZodType<Ok>;
+    };
+    /** The declared `_tag` list, verbatim. */
+    readonly errTags: ReadonlyArray<E["_tag"]>;
+}
+/**
+ * The declaration-erased view the runtime reads: which `type` a def builds,
+ * which two Msg types it settles with, and the `ok` schema the edge parses
+ * against. Every `CmdDef<…>` is one of these structurally.
+ */
+type AnyCmdDef = {
+    readonly cmdType: string;
+    readonly okType: string;
+    readonly errType: string;
+    readonly schema: {
+        readonly ok: z.ZodType;
+    };
+};
+/** The Cmd value a def (or a union of defs) builds. */
+type CmdOf<D extends AnyCmdDef> = D extends ((input: never) => infer C extends Cmd) ? C : never;
+/**
+ * The settled-Msg union a def (or a union of defs) mints: `<name>_ok` carrying
+ * `value`, `<name>_err` carrying `error`. `defineMachine({ cmds })` folds this
+ * into the machine's `M` so the user never spells the effect half of it.
+ */
+type Settled<D extends AnyCmdDef> = D extends CmdDef<infer Name, infer Input, infer Ok, infer E, infer R> ? SettledOk<Name, CmdValue<Name, Input, E, R>, Ok> | SettledErr<Name, CmdValue<Name, Input, E, R>, E> : never;
+/** The `Ok` a def's handler must produce. */
+type OkOf<D extends AnyCmdDef> = D extends CmdDef<infer _Name, infer _Input, infer Ok, infer _E, infer _R> ? Ok : never;
+/** The DECLARED failure union a def's handler may settle with. */
+type ErrOf<D extends AnyCmdDef> = D extends CmdDef<infer _Name, infer _Input, infer _Ok, infer E, infer _R> ? E : never;
+declare function defineCmd<const Name extends string, Input extends CmdInput, Ok, const Tags extends readonly string[], R = unknown>(name: Name, spec: {
+    readonly input: z.ZodType<Input>;
+    readonly ok: z.ZodType<Ok>;
+    readonly err: Tags;
+    readonly requirements?: Requirements<R>;
+}): CmdDef<Name, Input, Ok, TaggedError<Tags[number]>, R>;
+type SyncReturn<S, C extends Cmd> = readonly [S, readonly C[]] & {
+    readonly then?: never;
+};
+type UpdateForm = "reducer" | "transitions";
+declare function detectUpdateForm(update: object): UpdateForm;
+declare function formOf(machine: {
+    update: object;
+    __form?: UpdateForm;
+}): UpdateForm;
+declare class NoCellError extends Error {
+    readonly msgType: string;
+    readonly stateName: string;
+    /** The Msg types the refusing state has cells for; empty when it has none. */
+    readonly acceptedTypes: readonly string[];
+    readonly name = "NoCellError";
+    readonly _tag: "NoCellError";
+    constructor(msgType: string, stateName: string, 
+    /** The Msg types the refusing state has cells for; empty when it has none. */
+    acceptedTypes: readonly string[]);
+}
+/**
+ * The Msg types this machine would accept in this state — the same set a
+ * `NoCellError` reports, asked before anything is dispatched. Returns the
+ * state's own row keys in transitions form and the flat table's keys in
+ * reducer form, counting only keys whose cell is a function, and an empty
+ * array (never `undefined`, never a throw) for a state with no cells, no row
+ * at all, or no state value at all.
+ */
+declare function acceptedTypes<S>(machine: {
+    update: object;
+    __form?: UpdateForm;
+}, state: S): readonly string[];
+declare function applyCell<S, M extends {
+    type: string;
+}, C extends Cmd>(machine: {
+    update: object;
+    __form?: UpdateForm;
+}, state: S, msg: M): readonly [S, readonly C[]];
+declare function applyCellChecked<S, M extends {
+    type: string;
+}, C extends Cmd>(machine: {
+    update: object;
+    __form?: UpdateForm;
+}, state: S, msg: M): readonly [S, readonly C[]];
+declare function msgKeysOf(machine: {
+    update: object;
+    __form?: UpdateForm;
+}): readonly string[];
+type MachineShape = {
+    readonly form: "reducer";
+    /** Every `Msg.type` the flat reducer has a cell for. */
+    readonly msgs: readonly string[];
+} | {
+    readonly form: "transitions";
+    /** The union of every row's `Msg.type` keys (see `msgKeysOf`). */
+    readonly msgs: readonly string[];
+    /** Every `state.type` the table has a row for, in table order. */
+    readonly states: readonly string[];
+    /** `state.type` → the `Msg.type`s that state has a cell for. */
+    readonly accepts: Readonly<Record<string, readonly string[]>>;
+};
+declare function describeMachine(machine: {
+    update: object;
+    __form?: UpdateForm;
+}): MachineShape;
+declare function acceptsOf(machine: {
+    update: object;
+    __form?: UpdateForm;
+}, stateType: string): readonly string[];
+type Reducer<S, M extends {
+    type: string;
+}, C extends Cmd> = {
+    [K in M["type"]]: (state: S, msg: Extract<M, {
+        type: K;
+    }>) => SyncReturn<S, C>;
+};
+/**
+ * The state × message table form of `update`. Every state of `S` needs a row;
+ * a cell inside a row is optional, and leaving one out DECLARES that the state
+ * does not accept that message — the runtime refuses it with `NoCellError`
+ * naming `acceptedTypes`. `ExhaustiveTransitions` requires every cell instead.
+ */
+type Transitions<S extends {
+    type: string;
+}, M extends {
+    type: string;
+}, C extends Cmd> = {
+    [P in S["type"]]: Partial<ExhaustiveTransitions<S, M, C>[P]>;
+};
+/**
+ * `Transitions<S, M, C>` with every cell REQUIRED — the opt-in floor for a
+ * machine that wants the compiler to force a decision on every (state,
+ * message) pair. An annotation on your own table, not a third update form:
+ * `defineMachine` takes the annotated table unchanged.
+ */
+type ExhaustiveTransitions<S extends {
+    type: string;
+}, M extends {
+    type: string;
+}, C extends Cmd> = {
+    [P in S["type"]]: {
+        [K in M["type"]]: (state: Extract<S, {
+            type: P;
+        }>, msg: Extract<M, {
+            type: K;
+        }>) => SyncReturn<S, C>;
+    };
+};
+/**
+ * A tagged-union, one-shot effect — JSON-plain, hashable, replayable.
+ *
+ * `T` is the tag. `E` and `R` are Effect's Error and **Requirements** channels,
+ * carried as phantom type parameters (ADR 0014): `E` is the `_tag` union this
+ * Cmd can settle with, and `R` is the slice of `Ctx` its interpret handler
+ * reads. `R` is a requirement, not a wiring — what SATISFIES it is the `ctx`
+ * handed to `run`, built by hand or by a `provide` graph that acquires each
+ * dependency once and releases it when the run ends.
+ *
+ * @see {@link RequiredCtx} — every Cmd's `R`, intersected: what `run` demands.
+ * @see `provide` — the host-side graph that builds a `ctx` satisfying `R`.
+ */
+type Cmd<T extends string = string, E = unknown, R = unknown> = {
+    readonly type: T;
+    /** Phantom — the `_tag` union this Cmd can settle with. Never assigned. */
+    readonly __e?: E;
+    /** Phantom — the `Ctx` slice this Cmd's handler needs. Never assigned. */
+    readonly __r?: R;
+};
+declare const Cmd: {
+    /**
+     * Declare a typed Cmd constructor (ADR 0014). Returns the builder —
+     * `fetch({ url })` yields `{ type: "fetch", url }` — carrying the minted Msg
+     * builders `fetch.ok(cmd, value)` / `fetch.err(cmd, error)` and the
+     * declaration the runtime edge parses against. `Settled<typeof fetch>` is
+     * the two-arm Msg union it settles with; `defineMachine({ cmds: [fetch] })`
+     * folds that union into the machine's `M`.
+     *
+     *   const fetch = Cmd.define("fetch", {
+     *     input: z.object({ url: z.string() }),
+     *     ok: z.object({ status: z.number(), body: z.string() }),
+     *     err: ["not_found", "timeout"],
+     *     requirements: Cmd.requirements<{ http: Http }>(),
+     *   });
+     *
+     * `err` is the `_tag` list the handler may settle with; the runtime adds
+     * `malformed_result` for an `_ok` value the `ok` schema rejects. `requirements`
+     * names the `Ctx` slice the handler reads — `run` refuses a ctx without it.
+     *
+     * A Cmd must not wait; see `DepKeyedSub` for anything that watches.
+     */
+    readonly define: typeof defineCmd;
+    /**
+     * Name a Cmd's `R` — the `Ctx` slice its handler reads. A phantom: nothing
+     * is built, nothing is checked at runtime; the type is what `run` reads.
+     */
+    readonly requirements: <R>() => Requirements<R>;
+    /**
+     * The empty Cmd array. Typed `readonly never[]` so it's assignable to any
+     * `readonly C[]` for any `C extends Cmd`. Use in `init` returns and
+     * Transitions cells that emit zero effects:
+     *
+     *   init: (loaded) => [loaded ?? initial, Cmd.none],
+     *   tick: (state) => [state, Cmd.none],
+     *
+     * Elm's `Cmd.none` analogue. Cultural signal alongside the runtime help:
+     * `[state, Cmd.none]` reads as intent ("this transition emits nothing"),
+     * `[state, []]` reads as "empty array of what".
+     *
+     * Frozen at runtime so a downstream consumer can't `.push()` into the
+     * shared reference.
+     */
+    readonly none: readonly never[];
+    /**
+     * Flat concat of cmd arrays. Use when a cell composes effects from
+     * multiple conditional sources:
+     *
+     *   return [next, Cmd.batch(
+     *     Cmd.whenDefined(state.queueItemId, (id) => ({ type: "complete", id })),
+     *     Cmd.when(state.windowId !== undefined, { type: "close_window", windowId }),
+     *     [{ type: "detach_debugger", tabId: state.tabId }],
+     *   )];
+     *
+     * `<const C>` keeps inline cmd literals' discriminants narrow (same
+     * rationale as `when` / `whenDefined` above).
+     */
+    readonly batch: <const C extends Cmd>(...arrs: readonly (readonly C[])[]) => readonly C[];
+    /**
+     * Emit `cmd` wrapped in a single-element array iff `cond` is true.
+     * Otherwise return the empty array. Spreads cleanly into the cmds array
+     * returned by a Transitions cell.
+     *
+     * `const C` (TypeScript 5.0+) keeps the inferred `type:` discriminator
+     * literal narrow when called with an object literal — so `Cmd.when(b,
+     * { type: "x", ... })` infers as `{ type: "x", ... }`, not `{ type:
+     * string, ... }`, and stays assignable to a discriminated-union arm
+     * without `as const` at the call site.
+     */
+    readonly when: <const C extends Cmd>(cond: boolean, cmd: C) => readonly C[];
+    /**
+     * If `value` is defined, call `build(value)` and emit the resulting cmd
+     * wrapped in a single-element array. If `value` is `undefined`, return
+     * the empty array. `value` is narrowed to `T` inside `build`.
+     *
+     * `const C` on the return type keeps the callback's object-literal
+     * `type:` field narrow (see `when` above for the full rationale).
+     */
+    readonly whenDefined: <T, const C extends Cmd>(value: T | undefined, build: (value: T) => C) => readonly C[];
+};
+type SubId = string & {
+    readonly __brand: "SubId";
+};
+/**
+ * Construct a `SubId` from a string. Use this everywhere a Sub literal is
+ * built — including ids derived from runtime data (`subId(\`ws:${auditId}\`)`).
+ * The brand is structural, not nominal, so dynamic ids are permitted; the
+ * constructor's job is to make the identity decision explicit at every call
+ * site so the type system can catch accidental raw-string drift.
+ *
+ * Strengthens invariant 7 (identity is explicit).
+ */
+declare function subId(s: string): SubId;
+type Sub<T extends string = string> = {
+    readonly id: SubId;
+    readonly type: T;
+};
+type Dispose = () => void | Promise<void>;
+declare function structuralHash(deps: unknown): string;
+interface DepKeyedSub<S, M, Ctx = unknown> {
+    /**
+     * The slice of state this Sub depends on. `null` OR `undefined` ⇒ the Sub is
+     * inactive in this state (the substrate disposes it if it was running) — see
+     * `depsInactive`, so `(s) => s.optionalRunId` gates correctly. Otherwise the
+     * Sub is active, keyed on `structuralHash(deps)`.
+     *
+     * Pure (invariant 2). Plain JSON-compatible data only (invariant 1) — the
+     * structural hash walks it deterministically and THROWS on a `Date`, `Map`,
+     * `Set`, `Error` or class instance rather than collapsing them all onto one
+     * id. Project such a value first (`startedAt.toISOString()`).
+     */
+    readonly deps: (state: S) => unknown;
+    /**
+     * Open the resource for the current `state` (whose `deps` the kernel just
+     * found non-null). Receives `dispatch` to fire follow-up Msgs (a timer's
+     * fire, an inbound frame) and the machine's `ctx` (the host's transport
+     * factory, storage handles). Returns the `Dispose` the substrate runs on
+     * teardown / re-arm. Same role as a `subscribe[type]` handler's returned
+     * cleanup.
+     *
+     * `source` takes `state` (not the deps slice) so the slice type `D` never
+     * escapes the entry — each battery's `.depKeyed` closes over its own typed
+     * deps internally (cast-free existential: the entry that produced the deps
+     * is the entry that consumes them).
+     */
+    readonly source: (state: S, dispatch: (msg: M) => void, ctx: Ctx) => Dispose;
+}
+interface Identity<S, M> {
+    /** The identity THIS instance owns. Pure (invariant 2); plain value. */
+    readonly ofState: (state: S) => unknown;
+    /**
+     * The identity a message is addressed to, or `undefined` when the message
+     * carries no identity (lifecycle / pre-identity messages — never dropped).
+     * Pure (invariant 2); plain value when defined.
+     */
+    readonly ofMsg: (msg: M) => unknown;
+}
+interface Port<T> {
+    readonly __brand: "port";
+    readonly name: string;
+    readonly __t?: T;
+}
+/**
+ * Augmentation injected onto `ctx` inside Cmd handlers. Handlers receive
+ * `ctx & PortEmitter` so they can call `ctx.emit(port, value)` synchronously.
+ * Subscribers registered via `runtime.subscribePort(port, listener)` receive
+ * the value immediately.
+ *
+ * Emitting to a port with no subscribers is a no-op (does not throw).
+ */
+interface PortEmitter {
+    emit<T>(port: Port<T>, value: T): void;
+}
+type NoCtx = Readonly<Record<never, never>>;
+type Interpret<M extends {
+    type: string;
+}, C extends Cmd, Ctx> = {
+    [K in C["type"]]: (cmd: Extract<C, {
+        type: K;
+    }>, ctx: Ctx & RequirementsOf<Extract<C, {
+        type: K;
+    }>> & PortEmitter, dispatch?: (msg: M) => void) => Promise<M | void>;
+};
+type InterpretDetached<C extends Cmd, Allowed extends {
+    type: string;
+}, Ctx> = (cmd: C, ctx: Ctx & PortEmitter, dispatch: (msg: Allowed) => void) => Promise<void>;
+type Subscribe<M extends {
+    type: string;
+}, U extends Sub, Ctx> = {
+    [K in U["type"]]: (sub: Extract<U, {
+        type: K;
+    }>, ctx: Ctx, dispatch: (msg: M) => void) => Dispose;
+};
+type Machine<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx> = {
+    /**
+     * Boot the runtime. Called once by `run(...)` with whatever `Store.load()`
+     * returned: `null` on fresh boot, the persisted state on rehydrate.
+     *
+     * **Contract:** when `loaded !== null`, init MUST return `[loaded, []]` —
+     * no Cmds. Init's rehydrate branch is the migration / parse boundary, not
+     * the boot-effect hook. See Invariant 2 in `.patterns/tea/tea-invariants.md`.
+     *
+     * Boot effects routes:
+     *   - Stateless infrastructure → host module top, outside TEA.
+     *   - State-conditional resume → a `boot` Msg the host dispatches once
+     *     after `run(...)` returns.
+     *
+     * Violations are caught at runtime by `replay` (which throws with a
+     * pointer to the alternatives).
+     */
+    init: (loaded: S | null, ctx: Ctx) => readonly [S, readonly C[]];
+    /**
+     * The typed Cmd constructors this machine emits (`Cmd.define`). Declared
+     * through `defineMachine({ cmds })`, which derives `C` and the settled half
+     * of `M` from them; the runtime reads the list to parse each handler's
+     * `_ok` value against its `ok` schema and stamp `at` at the interpret edge.
+     * A machine of hand-written Cmds omits it and runs exactly as before.
+     */
+    readonly cmds?: readonly AnyCmdDef[];
+    update: Reducer<S, M, C> | ([S] extends [{
+        type: string;
+    }] ? Transitions<S, M, C> : never);
+    /**
+     * Dep-keyed Subs. Each declares the state slice it depends on; the substrate
+     * derives the id (`structuralHash(deps)`) and the gate (`deps` non-null) and
+     * folds them into the SAME reconcile loop `subscriptions` feeds. The author
+     * never writes `subId(...)` and never lists Subs in a central
+     * `subscriptions(state)` aggregate — a per-Sub gate travels with the Sub, so
+     * a new phase can't silently forget to arm it.
+     *
+     * The deps slice type is erased to `unknown` per entry — each Sub's slice
+     * differs, but the slice type never crosses this field (the kernel only needs
+     * to hash it and pass `state` back to that same entry's `source`).
+     *
+     * Optional and independent of `subscriptions` / `subscribe`: a machine that
+     * omits `subs` reconciles exactly as before.
+     *
+     * Strengthens invariant 4 (lifecycle owned by the substrate) and invariant 7
+     * (identity derived, not hand-authored).
+     */
+    subs?: ReadonlyArray<DepKeyedSub<S, M, Ctx>>;
+    /**
+     * Instance-identity filter. Declares THIS instance's identity once; the
+     * substrate drops any message addressed to a DIFFERENT identity before it
+     * reaches `update`. Replaces the per-cell `if (msg.runId !== state.runId)`
+     * guard entirely — the reducer never sees a foreign-instance message, so no
+     * cell needs to check.
+     *
+     * Opt-in: a machine that omits `identity` skips the filter (every message
+     * reaches `update`, exactly as before). A message whose `ofMsg` returns
+     * `undefined` is identity-agnostic and always reaches `update` (lifecycle /
+     * pre-identity messages).
+     *
+     * Strengthens invariant 7 (identity is explicit — declared once, enforced by
+     * the substrate) and invariant 6 (mis-addressed messages dropped at one
+     * observable point, not per cell).
+     */
+    identity?: Identity<S, M>;
+    /**
+     * Manual Sub aggregate — the documented escape hatch, KEPT alongside `subs`.
+     * The machine that needs cross-Sub logic the per-Sub `deps` fold can't
+     * express lists Subs here; the substrate reconciles them via `subscribe`.
+     * Both paths feed ONE reconcile pass.
+     */
+    subscriptions?: (state: S) => readonly U[];
+    subscribe?: Subscribe<M, U, Ctx>;
+    /**
+     * The update form ("reducer" | "transitions"), stamped non-enumerably by
+     * `defineMachine` at construction (see `UpdateForm` / `formOf`). Optional in
+     * the type so the structural `Machine` annotation form keeps accepting plain
+     * object literals; readers go through `formOf`, which falls back to
+     * `detectUpdateForm` when the tag is absent. Never written by hand.
+     */
+    readonly __form?: UpdateForm;
+} & ([C] extends [Cmd<never>] ? {
+    interpret?: Interpret<M, C, Ctx>;
+} : {
+    interpret: Interpret<M, C, Ctx>;
+}) & ([U] extends [Sub<never>] ? unknown : {
+    subscriptions: (state: S) => readonly U[];
+    subscribe: Subscribe<M, U, Ctx>;
+});
+declare function foldUpdates<S, M extends {
+    type: string;
+}, C extends Cmd>(machine: {
+    update: object;
+    __form?: UpdateForm;
+}, initialState: S, msgs: readonly M[]): {
+    state: S;
+    cmds: C[];
+};
+declare function foldMsgs<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, base: S, msgs: readonly M[]): S;
+
+export { type AnyCmdDef as A, applyCell as B, Cmd as C, type Dispose as D, type ErrOf as E, applyCellChecked as F, describeMachine as G, detectUpdateForm as H, type Interpret as I, foldMsgs as J, foldUpdates as K, formOf as L, type Machine as M, NoCellError as N, type OkOf as O, type Port as P, msgKeysOf as Q, type RequiredCtx as R, type Sub as S, type Transitions as T, type UpdateForm as U, structuralHash as V, subId as W, type CmdOf as a, type CmdDef as b, type SubId as c, type Reducer as d, type Settled as e, type RequirementsOf as f, type PortEmitter as g, type InterpretDetached as h, type CmdValue as i, type Tagged as j, type NoCtx as k, type MalformedResult as l, type Requirements as m, type TaggedError as n, type DepKeyedSub as o, type CmdInput as p, type ErrorsOf as q, type ExhaustiveTransitions as r, type Identity as s, type MachineShape as t, type SettledErr as u, type SettledOk as v, type Subscribe as w, type SyncReturn as x, acceptedTypes as y, acceptsOf as z };

package/dist/devtools/index.d.ts

@@ -15,7 +15,7 @@ interface MsgLogProps {
 declare function MsgLog({ history, className }: MsgLogProps): react_jsx_runtime.JSX.Element;
 
 /**
- * A single differing cell between two states.
+ * A single differing leaf value between two states.
  *
  *   - `kind: "added"`   — the path exists in `actual` but not `expected`
  *                         (`expected` is `undefined`).
@@ -35,7 +35,7 @@ interface StateChange {
     actual: unknown;
 }
 /**
- * Deep-walk two states and return EVERY differing cell, in deterministic
+ * Deep-walk two states and return EVERY differing leaf value, in deterministic
  * pre-order (the node before its children; children in array-index order, then
  * sorted-union key order for objects). The empty array means the two states are
  * deeply equal.