@demlik/tea 0.15.0 → 0.17.0

package/dist/{core-DnzqWy6u.d.ts → core-rDbOaJTN.d.ts}

@@ -1,4 +1,4 @@
-import { z } from 'zod';
+import { StandardSchemaV1 } from '@standard-schema/spec';
 
 /**
  * @demlik/tea — pure-core leaf (ADR 0006).
@@ -9,40 +9,48 @@ import { z } from 'zod';
  * `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
+ * NOTHING from the runtime — 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.
+ * The one external name it reaches for is the Standard Schema TYPE surface
+ * (`import type` from `@standard-schema/spec`), erased at compile time —
+ * `Cmd.define` accepts any Standard Schema (zod, Effect Schema through
+ * `Schema.toStandardSchemaV1`, …), and it imports no schema library.
  */
 
-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.
+ * The two builders the Promise engine hands a `Cmd.define`d handler on its
+ * ctx: `ok(value)` and `err({ _tag })`, with `err` typed to the def's declared
+ * tags.
  */
-type RequiredCtx<C> = UnionToIntersection<KnownRequirements<RequirementsBoxed<C>>>;
+interface OutcomeHelpers<Ok, E> {
+    readonly ok: (value: Ok) => Outcome<Ok, never>;
+    readonly err: (error: E) => Outcome<never, E>;
+}
+/** The result a `Cmd.define`d handler returns: its value, or a declared failure. */
+type Outcome<Ok, E> = {
+    readonly _tag: "Ok";
+    readonly value: Ok;
+} | {
+    readonly _tag: "Err";
+    readonly error: E;
+};
+/**
+ * Build an {@link Outcome} outside a handler's helpers — in a test that calls a
+ * handler directly, or in an adapter converting another result type.
+ */
+declare const Outcome: {
+    readonly ok: <Ok>(value: Ok) => Outcome<Ok, never>;
+    readonly err: <E>(error: E) => Outcome<never, E>;
+};
 /** The shape every settled failure has (ADR 0011): a plain `_tag` record. */
 type Tagged = {
     readonly _tag: string;
@@ -57,9 +65,9 @@ type TaggedError<Tag extends string> = Tag extends string ? {
     readonly [detail: string]: unknown;
 } : never;
 /**
- * The kernel-minted failure: a handler returned a `_ok` value the Cmd's `ok`
+ * The kernel-minted failure: a handler returned an `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.
+ * `issues` is the schema's issue list flattened to `path` + `message` strings.
  */
 type MalformedResult = {
     readonly _tag: "malformed_result";
@@ -68,6 +76,51 @@ type MalformedResult = {
         readonly message: string;
     }>;
 };
+/**
+ * A schema whose `validate` returned a Promise where the kernel needs an answer
+ * now — the `ok` check at the interpret edge, the `args` check in a reducer.
+ * A contract breach (ADR 0021 §5): it goes to the error sink.
+ */
+declare class AsyncSchemaError extends Error {
+    /** What the schema was checking, e.g. `the "fetch" Cmd's ok schema`. */
+    readonly where: string;
+    readonly name = "AsyncSchemaError";
+    readonly _tag: "AsyncSchemaError";
+    constructor(
+    /** What the schema was checking, e.g. `the "fetch" Cmd's ok schema`. */
+    where: string);
+}
+/**
+ * A `Cmd.define`d handler failed outside its declared channel: its `Err` carried
+ * no `_tag`, or a tag the def does not declare. A contract breach (ADR 0011,
+ * 0021 §4): it goes to the error sink, never to `<name>_err`.
+ */
+declare class UndeclaredFailureError extends Error {
+    readonly cmdType: string;
+    /** The `error` the handler's `Err` carried, verbatim. */
+    readonly failure: unknown;
+    /** The tags the def declares. */
+    readonly declared: readonly string[];
+    readonly name = "UndeclaredFailureError";
+    readonly _tag: "UndeclaredFailureError";
+    constructor(cmdType: string, 
+    /** The `error` the handler's `Err` carried, verbatim. */
+    failure: unknown, 
+    /** The tags the def declares. */
+    declared: readonly string[]);
+}
+/**
+ * A `Cmd.define`d handler returned something the engine cannot settle: any Msg
+ * (the engine mints the Cmd's `<name>_ok` / `<name>_err`, never the handler —
+ * ADR 0021), or any other value that is neither an {@link Outcome} nor nothing.
+ * Also thrown when such a handler dispatches its own `_ok` / `_err` Msg.
+ */
+declare class OutcomeContractError extends Error {
+    readonly cmdType: string;
+    readonly name = "OutcomeContractError";
+    readonly _tag: "OutcomeContractError";
+    constructor(cmdType: string, detail: 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.
@@ -75,16 +128,8 @@ type MalformedResult = {
 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 CmdValue<Name extends string, Input extends CmdInput, Ok, E extends Tagged> = Cmd<Name, Ok, E | MalformedResult> & Readonly<Input>;
 type SettledOk<Name extends string, C, Ok> = {
     readonly type: `${Name}_ok`;
     readonly cmd: C;
@@ -104,37 +149,39 @@ type SettledErr<Name extends string, C, E extends Tagged> = {
  * 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.
+ * `ok` / `err` mint a settled Msg OUTSIDE the runtime (a `replay` log, a unit
+ * test) and take an optional `at`. A handler never calls them: it returns an
+ * {@link Outcome}, and inside `run` the interpret edge mints and stamps.
  */
-interface CmdDef<Name extends string, Input extends CmdInput, Ok, E extends Tagged, R> {
-    (input: Input): CmdValue<Name, Input, E, R>;
+interface CmdDef<Name extends string, Input extends CmdInput, Ok, E extends Tagged> {
+    (input: Input): CmdValue<Name, Input, Ok, E>;
     /** 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 ok: (cmd: CmdValue<Name, Input, Ok, E>, value: Ok, at?: number) => SettledOk<Name, CmdValue<Name, Input, Ok, E>, Ok>;
+    readonly err: (cmd: CmdValue<Name, Input, Ok, E>, error: E, at?: number) => SettledErr<Name, CmdValue<Name, Input, Ok, E>, E>;
     readonly schema: {
-        readonly input: z.ZodType<Input>;
-        readonly ok: z.ZodType<Ok>;
+        readonly input: StandardSchemaV1<unknown, Input>;
+        readonly ok: StandardSchemaV1<unknown, 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.
+ * which two Msg types it settles with, the `ok` schema the edge parses against
+ * and the tags an `Err` may carry. Every `CmdDef<…>` is one of these
+ * structurally.
  */
 type AnyCmdDef = {
     readonly cmdType: string;
     readonly okType: string;
     readonly errType: string;
     readonly schema: {
-        readonly ok: z.ZodType;
+        readonly ok: StandardSchemaV1;
     };
+    readonly errTags: ReadonlyArray<string>;
 };
 /** 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;
@@ -143,17 +190,16 @@ type CmdOf<D extends AnyCmdDef> = D extends ((input: never) => infer C extends C
  * `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;
+type Settled<D extends AnyCmdDef> = D extends CmdDef<infer Name, infer Input, infer Ok, infer E> ? SettledOk<Name, CmdValue<Name, Input, Ok, E>, Ok> | SettledErr<Name, CmdValue<Name, Input, Ok, E>, 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;
+type OkOf<D extends AnyCmdDef> = D extends CmdDef<infer _Name, infer _Input, infer Ok, infer _E> ? 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>;
+type ErrOf<D extends AnyCmdDef> = D extends CmdDef<infer _Name, infer _Input, infer _Ok, infer E> ? E : never;
+declare function defineCmd<const Name extends string, Input extends CmdInput, Ok, const Tags extends readonly string[]>(name: Name, spec: {
+    readonly input: StandardSchemaV1<unknown, Input>;
+    readonly ok: StandardSchemaV1<unknown, Ok>;
     readonly err: Tags;
-    readonly requirements?: Requirements<R>;
-}): CmdDef<Name, Input, Ok, TaggedError<Tags[number]>, R>;
+}): CmdDef<Name, Input, Ok, TaggedError<Tags[number]>>;
 type SyncReturn<S, C extends Cmd> = readonly [S, readonly C[]] & {
     readonly then?: never;
 };
@@ -265,51 +311,50 @@ type ExhaustiveTransitions<S extends {
 /**
  * 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`.
+ * `T` is the tag. `Ok` and `E` are phantom type parameters (ADR 0014): `Ok` is
+ * the value this Cmd settles with, and `E` is the `_tag` union it can fail
+ * with. A Cmd carries no requirements (ADR 0020) — its handler gets its
+ * services from the plain `ctx` handed to `run`.
  */
-type Cmd<T extends string = string, E = unknown, R = unknown> = {
+type Cmd<T extends string = string, Ok = unknown, E = unknown> = {
     readonly type: T;
+    /** Phantom — the value this Cmd settles with. Never assigned. */
+    readonly __ok?: Ok;
     /** 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 —
+     * Declare a typed Cmd constructor (ADR 0014, 0021). 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`.
+     * builders `fetch.ok(cmd, value)` / `fetch.err(cmd, error)` (for replay
+     * logs and tests) 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.
+     * `input` and `ok` take any Standard Schema whose `validate` is synchronous:
+     * zod directly, Effect Schema through `Schema.toStandardSchemaV1(...)`. `err`
+     * is the `_tag` list the handler may fail with; the runtime adds
+     * `malformed_result` for an `Ok` value the `ok` schema rejects.
+     *
+     * The handler returns an outcome and the engine mints the Msg:
+     *
+     *   fetch: async (cmd, { ok, err }) =>
+     *     res.status === 404 ? err({ _tag: "not_found" }) : ok(await res.json()),
+     *
+     * A throw or an undeclared tag goes to the error sink, never to `fetch_err`.
+     * The handler reads its services off the plain `ctx` handed to `run` (ADR
+     * 0020).
      *
      * 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
@@ -375,40 +420,40 @@ type SubId = string & {
  * Strengthens invariant 7 (identity is explicit).
  */
 declare function subId(s: string): SubId;
-type Sub<T extends string = string> = {
+type Sub<T extends string = string, D = unknown> = {
     readonly id: SubId;
     readonly type: T;
+    readonly deps: D;
 };
 type Dispose = () => void | Promise<void>;
+/** The `deps` a `timer` Sub declares: fire `msg` once, `ms` after it starts. */
+type TimerDeps<M> = {
+    readonly ms: number;
+    readonly msg: M;
+};
+/** The built-in `timer` Sub, as its runner sees it. */
+type TimerSub<M> = Sub<"timer", TimerDeps<M>>;
+/** The Sub types every engine ships a runner for. */
+type BuiltinSubType = "timer";
+/** The built-in Subs a machine over `M` may declare without declaring them. */
+type BuiltinSub<M> = TimerSub<M>;
+/**
+ * The one `id` of a Sub: a structural hash of its `type` and its `deps`
+ * value. Same type and same deps → same id → the running Sub is left alone.
+ */
+declare function subIdOf(type: string, deps: unknown): SubId;
 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;
+type DepKeyedSub<S, U extends Sub = Sub> = U extends Sub<infer T, infer D> ? {
+    readonly type: T;
     /**
-     * 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).
+     * The slice of state this Sub depends on. `null` or `undefined` ⇒ off in
+     * this state (see `depsInactive`), so `(s) => s.optionalRunId` gates
+     * correctly. Pure (invariant 2). Plain JSON-compatible data only
+     * (invariant 1): the structural hash THROWS on a `Date`, `Map`, `Set`,
+     * `Error` or class instance rather than collapsing them onto one id.
      */
-    readonly source: (state: S, dispatch: (msg: M) => void, ctx: Ctx) => Dispose;
-}
+    readonly deps: (state: S) => D | null | undefined;
+} : never;
 interface Identity<S, M> {
     /** The identity THIS instance owns. Pure (invariant 2); plain value. */
     readonly ofState: (state: S) => unknown;
@@ -436,18 +481,33 @@ interface PortEmitter {
     emit<T>(port: Port<T>, value: T): void;
 }
 type NoCtx = Readonly<Record<never, never>>;
+type HandlerCtx<Ctx> = (0 extends 1 & Ctx ? Ctx : [
+    Ctx
+] extends [void] ? unknown : Ctx) & PortEmitter;
 type Interpret<M extends {
     type: string;
 }, C extends Cmd, Ctx> = {
-    [K in C["type"]]: (cmd: Extract<C, {
+    [K in C["type"]]: InterpretCell<M, Extract<C, {
         type: K;
-    }>, ctx: Ctx & RequirementsOf<Extract<C, {
-        type: K;
-    }>> & PortEmitter, dispatch?: (msg: M) => void) => Promise<M | void>;
+    }>, Ctx>;
 };
+/**
+ * One cell of {@link Interpret}: the outcome-returning form for a
+ * `Cmd.define`d Cmd, the Msg-returning form for a hand-written one. A Cmd is
+ * `Cmd.define`d exactly when its `E` phantom is declared (not `unknown`).
+ */
+type InterpretCell<M extends {
+    type: string;
+}, C extends Cmd, Ctx> = unknown extends ErrorsOf<C> ? (cmd: C, ctx: HandlerCtx<Ctx>, dispatch?: (msg: M) => void) => Promise<M | void> : (cmd: C, ctx: HandlerCtx<Ctx> & OutcomeHelpers<OkOfCmd<C>, DeclaredErrorsOf<C>>, dispatch?: (msg: M) => void) => Promise<Outcome<OkOfCmd<C>, DeclaredErrorsOf<C>> | void>;
+/** The value a Cmd settles with; `unknown` for a hand-written Cmd. */
+type OkOfCmd<C> = C extends {
+    readonly __ok?: infer Ok;
+} ? Ok : unknown;
+/** The failures a `Cmd.define`d Cmd's handler may return: its declared tags. */
+type DeclaredErrorsOf<C> = Exclude<ErrorsOf<C>, MalformedResult>;
 type InterpretDetached<C extends Cmd, Allowed extends {
     type: string;
-}, Ctx> = (cmd: C, ctx: Ctx & PortEmitter, dispatch: (msg: Allowed) => void) => Promise<void>;
+}, Ctx> = (cmd: C, ctx: HandlerCtx<Ctx>, dispatch: (msg: Allowed) => void) => Promise<void>;
 type Subscribe<M extends {
     type: string;
 }, U extends Sub, Ctx> = {
@@ -455,6 +515,54 @@ type Subscribe<M extends {
         type: K;
     }>, ctx: Ctx, dispatch: (msg: M) => void) => Dispose;
 };
+/**
+ * The `interpret` option of an engine's `run`: optional for a machine that
+ * emits no Cmd, required — one handler per Cmd variant — for one that does.
+ */
+type InterpretArg<M extends {
+    type: string;
+}, C extends Cmd, Ctx> = [
+    C
+] extends [Cmd<never>] ? {
+    interpret?: Interpret<M, C, Ctx>;
+} : {
+    interpret: Interpret<M, C, Ctx>;
+};
+/**
+ * The `subscribe` option of an engine's `run`: one runner per Sub type the
+ * machine declares, except the built-ins (`timer`) the engine already ships.
+ * Optional when every declared type is a built-in. An entry named after a
+ * built-in replaces it (#270 R2.1), which is how a test drives time.
+ */
+type SubscribeArg<M extends {
+    type: string;
+}, U extends Sub, Ctx> = [
+    Exclude<U["type"], BuiltinSubType>
+] extends [never] ? {
+    readonly subscribe?: Partial<Subscribe<M, Exclude<U, Sub<never>> | BuiltinSub<M>, Ctx>>;
+} : {
+    readonly subscribe: Subscribe<M, Exclude<U, {
+        readonly type: BuiltinSubType;
+    }>, Ctx> & Partial<Subscribe<M, BuiltinSub<M>, Ctx>>;
+};
+/**
+ * The handlers an engine is handed beside a machine: the {@link InterpretArg}
+ * Cmd handlers and the {@link SubscribeArg} sub runners. A machine carries
+ * neither — it is data, and one machine file runs under any engine.
+ */
+type RunHandlers<M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx> = InterpretArg<M, C, Ctx> & SubscribeArg<M, U, Ctx>;
+/**
+ * A machine beside the handlers it runs under — what a wrapper, a battery's
+ * `toMachine` or an agent host hands around, and what an engine takes apart:
+ * `run(wired.machine, { ...wired, ctx })`.
+ */
+type Wired<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx> = {
+    readonly machine: Machine<S, M, C, U, Ctx>;
+} & RunHandlers<M, C, U, Ctx>;
 type Machine<S, M extends {
     type: string;
 }, C extends Cmd, U extends Sub, Ctx> = {
@@ -487,24 +595,27 @@ type Machine<S, M 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`).
+     * The machine's Subs, as data: each entry names a Sub `type` and the state
+     * slice it depends on (`deps`). The engine derives the id
+     * (`structuralHash({ type, deps })`) and the gate (`deps` non-null), starts
+     * the runner for `type` when an entry turns on, leaves it alone while the id
+     * holds, restarts it when the id changes, and stops it on `null` or `stop()`.
      *
-     * Optional and independent of `subscriptions` / `subscribe`: a machine that
-     * omits `subs` reconciles exactly as before.
+     * `U` is the machine's own Sub union (`types.sub`); the built-in `timer`
+     * (`{ type: "timer", deps: (s) => ({ ms, msg }) }`) is always available.
      *
      * Strengthens invariant 4 (lifecycle owned by the substrate) and invariant 7
      * (identity derived, not hand-authored).
      */
-    subs?: ReadonlyArray<DepKeyedSub<S, M, Ctx>>;
+    readonly subs?: ReadonlyArray<DepKeyedSub<S, U | BuiltinSub<M>>>;
+    /**
+     * Phantom — never assigned, never read. `subs` reaches `U` only through a
+     * conditional type, which is no inference site, so this is the slot a caller
+     * like `run(machine, …)` infers the Sub union from (and so what types its
+     * `subscribe` runners). Same device as `Cmd`'s `__ok`. Tuple-wrapped so an
+     * empty union (`never`) is still a candidate rather than `undefined`.
+     */
+    readonly __sub?: readonly [U];
     /**
      * Instance-identity filter. Declares THIS instance's identity once; the
      * substrate drops any message addressed to a DIFFERENT identity before it
@@ -522,14 +633,6 @@ type Machine<S, M extends {
      * 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
@@ -538,14 +641,7 @@ type Machine<S, M extends {
      * `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: {
@@ -559,4 +655,4 @@ 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 NoCtx as i, type Tagged as j, type MalformedResult as k, type CmdValue 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 };
+export { applyCell as $, type AnyCmdDef as A, type BuiltinSubType as B, Cmd as C, type DeclaredErrorsOf as D, type ErrorsOf as E, type InterpretCell as F, type MachineShape as G, type HandlerCtx as H, type InterpretDetached as I, type NoCtx as J, OutcomeContractError as K, type OutcomeHelpers as L, type Machine as M, NoCellError as N, type OkOfCmd as O, type Port as P, type PortEmitter as Q, type RunHandlers as R, type Sub as S, type TimerDeps as T, type UpdateForm as U, type SubscribeArg as V, type Wired as W, type SyncReturn as X, UndeclaredFailureError as Y, acceptedTypes as Z, acceptsOf as _, type BuiltinSub as a, applyCellChecked as a0, describeMachine as a1, detectUpdateForm as a2, foldMsgs as a3, foldUpdates as a4, formOf as a5, msgKeysOf as a6, structuralHash as a7, subId as a8, subIdOf as a9, type CmdDef as b, type CmdOf as c, type Subscribe as d, type SettledOk as e, type SettledErr as f, type TaggedError as g, type Dispose as h, type Reducer as i, type Settled as j, type Transitions as k, Outcome as l, type SubId as m, type DepKeyedSub as n, type Interpret as o, type TimerSub as p, type MalformedResult as q, type Tagged as r, type OkOf as s, type ErrOf as t, type CmdValue as u, AsyncSchemaError as v, type CmdInput as w, type ExhaustiveTransitions as x, type Identity as y, type InterpretArg as z };