@demlik/tea 0.11.0 → 0.13.0

package/dist/{core-Bjc0bS8j.d.ts → core-Co0LWkIA.d.ts}

@@ -1,3 +1,151 @@
+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
+ * `@demlik/tea/pure` subpath re-exports this surface, 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 NeedsOf<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;
+/**
+ * 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.
+ */
+type RequiredCtx<C> = UnionToIntersection<NeedsOf<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.needs<{ 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 Needs<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 needs?: Needs<R>;
+}): CmdDef<Name, Input, Ok, TaggedError<Tags[number]>, R>;
 type SyncReturn<S, C extends Cmd> = readonly [S, readonly C[]] & {
     readonly then?: never;
 };
@@ -71,10 +219,39 @@ type Transitions<S extends {
         }>) => SyncReturn<S, C>;
     };
 };
-type Cmd<T extends string = string> = {
+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"],
+     *     needs: Cmd.needs<{ 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. `needs`
+     * names the `Ctx` slice the handler reads — `run` refuses a ctx without it.
+     */
+    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 needs: <R>() => Needs<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
@@ -215,7 +392,9 @@ type Interpret<M extends {
 }, C extends Cmd, Ctx> = {
     [K in C["type"]]: (cmd: Extract<C, {
         type: K;
-    }>, ctx: Ctx & PortEmitter, dispatch?: (msg: M) => void) => Promise<M | void>;
+    }>, ctx: Ctx & NeedsOf<Extract<C, {
+        type: K;
+    }>> & PortEmitter, dispatch?: (msg: M) => void) => Promise<M | void>;
 };
 type InterpretDetached<C extends Cmd, Allowed extends {
     type: string;
@@ -247,6 +426,14 @@ type Machine<S, M extends {
      * 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);
@@ -323,4 +510,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 { Cmd as C, type DepKeyedSub as D, type Interpret as I, type Machine as M, NoCellError as N, type PortEmitter as P, type Reducer as R, type Sub as S, type Transitions as T, type UpdateForm as U, type Port as a, type SubId as b, type InterpretDetached as c, type ContextFree as d, type Dispose as e, type Identity as f, type MachineShape as g, type NoCtx as h, type Subscribe as i, type SyncReturn as j, acceptsOf as k, applyCell as l, applyCellChecked as m, describeMachine as n, detectUpdateForm as o, foldMsgs as p, foldUpdates as q, formOf as r, msgKeysOf as s, structuralHash as t, subId as u };
+export { type AnyCmdDef as A, applyCellChecked as B, Cmd as C, type DepKeyedSub as D, type ErrOf as E, describeMachine as F, detectUpdateForm as G, foldMsgs as H, type Interpret as I, foldUpdates as J, formOf as K, msgKeysOf as L, type Machine as M, NoCellError as N, type OkOf as O, type PortEmitter as P, structuralHash as Q, type RequiredCtx as R, type Sub as S, type Transitions as T, type UpdateForm as U, subId as V, type Port as a, type SubId as b, type Reducer as c, type Settled as d, type CmdOf as e, type NeedsOf as f, type InterpretDetached as g, type CmdDef as h, type CmdInput as i, type CmdValue as j, type ContextFree as k, type Dispose as l, type ErrorsOf as m, type Identity as n, type MachineShape as o, type MalformedResult as p, type Needs as q, type NoCtx as r, type SettledErr as s, type SettledOk as t, type Subscribe as u, type SyncReturn as v, type Tagged as w, type TaggedError as x, acceptsOf as y, applyCell as z };

package/dist/deadline/index.d.ts

@@ -1,5 +1,6 @@
-import { S as Sub, b as SubId } from '../core-Bjc0bS8j.js';
-import { S as SubscribeHandler } from '../types-D7u9DkH7.js';
+import { S as Sub, b as SubId } from '../core-Co0LWkIA.js';
+import { S as SubscribeHandler } from '../types-XS_miRnB.js';
+import 'zod';
 
 /**
  * @demlik/tea/deadline — a one-shot Sub that fires when an ABSOLUTE wall-clock

package/dist/deadline/index.js

@@ -1,6 +1,6 @@
-export { deadlineExceeded, deadlineSub, setTimeoutArmTimer, subscribeDeadline, subscribeWith } from '../chunk-JGVL3WPL.js';
+export { deadlineExceeded, deadlineSub, setTimeoutArmTimer, subscribeDeadline, subscribeWith } from '../chunk-DGE4PV4A.js';
 import '../chunk-2YFLOCWX.js';
-import '../chunk-5EHLEUTL.js';
-import '../chunk-B5VXOFMZ.js';
+import '../chunk-ZSUUOEPL.js';
+import '../chunk-OOYD44JI.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/do/index.d.ts

@@ -1,14 +1,15 @@
-import { S as Store, R as Runtime, B as BootingRuntime } from '../runtime-types-Bxc637bp.js';
-import { P as PendingEffectsRecorder, b as EffectOwed, a as EffectConfirmed } from '../durable-effects-D8SqU_if.js';
-export { D as DeliveryId, E as EffectLedgerEvent, O as OwedEffect, c as PendingEffectsLedger, d as applyEffectEvent, e as emptyLedger, f as foldLedger, i as isOwed, p as pendingEffectsLedger, s as survivingEffects } from '../durable-effects-D8SqU_if.js';
+import { S as Store, R as Runtime, B as BootingRuntime } from '../runtime-types-CNLmhWif.js';
+import { P as PendingEffectsRecorder, b as EffectOwed, a as EffectConfirmed } from '../durable-effects-C6uwzjb5.js';
+export { D as DeliveryId, E as EffectLedgerEvent, O as OwedEffect, c as PendingEffectsLedger, d as applyEffectEvent, e as emptyLedger, f as foldLedger, i as isOwed, p as pendingEffectsLedger, s as survivingEffects } from '../durable-effects-C6uwzjb5.js';
 import { RetryPolicy, Rng } from '../retry-backoff/index.js';
-import { C as Cmd, S as Sub, M as Machine } from '../core-Bjc0bS8j.js';
-import { k as AgentEvent, A as AgentTurn, s as AgentState, p as AgentMachineMsg, t as AgentStatus } from '../machine-0OmPvsy_.js';
+import { C as Cmd, S as Sub, M as Machine, R as RequiredCtx } from '../core-Co0LWkIA.js';
+import { k as AgentEvent, A as AgentTurn, s as AgentState, p as AgentMachineMsg, t as AgentStatus } from '../machine-BtFWQmmq.js';
 import 'better-result';
+import 'zod';
 import '../llm-call/index.js';
 import '../resilient-call/index.js';
 import '../cache/index.js';
-import '../types-D7u9DkH7.js';
+import '../types-XS_miRnB.js';
 import '../circuit-breaker/index.js';
 import '../deadline/index.js';
 import '../protocol-B5YmJr0d.js';
@@ -1067,8 +1068,11 @@ interface AgentHostConfig<Stage, P extends string, O extends Record<P, AgentTurn
     readonly buildMachine: () => Machine<AgentState<Stage, P, O, R>, AgentMachineMsg<P, O, R>, C, U, Ctx>;
     /** The durable `Store` for the agent slice (typically `doStore(storage, parse)`). */
     readonly store: Store<AgentState<Stage, P, O, R>>;
-    /** The Ctx the machine threads to its interpret cells — checked against `buildMachine`'s. */
-    readonly ctx: Ctx;
+    /**
+     * The Ctx the machine threads to its interpret cells — checked against
+     * `buildMachine`'s, plus every typed Cmd's `R` (what `run` itself demands).
+     */
+    readonly ctx: Ctx & RequiredCtx<C>;
     /**
      * The run-terminality predicate (#46) — what makes `result()` first-class.
      * Defaults to the agent's own terminal phases (`done` / `failed`).

package/dist/do/index.js

@@ -1,27 +1,27 @@
-import { status, agentBootMsg, agentEvents } from '../chunk-ZF6WDK2D.js';
+import { status, agentBootMsg, agentEvents } from '../chunk-3I52QZZ5.js';
 export { applyEffectEvent, emptyLedger, foldLedger, isOwed, pendingEffectsLedger, survivingEffects } from '../chunk-25LBDCBC.js';
-import '../chunk-WLGO64WC.js';
-import '../chunk-ND3DH6KM.js';
-import '../chunk-7V4EVLZA.js';
-import '../chunk-EUF7XOEE.js';
+import '../chunk-DMYGQB4O.js';
+import '../chunk-COS5MSTO.js';
+import '../chunk-O4MVQTEJ.js';
+import '../chunk-4KLG43GY.js';
 import '../chunk-JELSZN25.js';
 import '../chunk-D736QUGF.js';
 import { createIntake } from '../chunk-ZVJZ72HY.js';
-import '../chunk-JGVL3WPL.js';
+import '../chunk-RH5EFRVJ.js';
+import '../chunk-DGE4PV4A.js';
 import { defaultRetryPolicy, initRetry, recordFailure, shouldRetry, nextDelayMs } from '../chunk-Q2UM7BXU.js';
 import '../chunk-S2EGRPCM.js';
 import '../chunk-BYQUGDD3.js';
 import '../chunk-K575PT4S.js';
 import '../chunk-UF4MZSLT.js';
-import '../chunk-7SVIRMC6.js';
+import '../chunk-G5E74IJB.js';
 import '../chunk-MU6MCIAC.js';
 import '../chunk-FV3Z5MBE.js';
-import '../chunk-3JU6657S.js';
+import '../chunk-VYFAZN3F.js';
 import '../chunk-2YFLOCWX.js';
 import '../chunk-ZJ5AOYBH.js';
-import '../chunk-G5E74IJB.js';
-import { replay, run } from '../chunk-5EHLEUTL.js';
-import '../chunk-B5VXOFMZ.js';
+import { replay, run } from '../chunk-ZSUUOEPL.js';
+import '../chunk-OOYD44JI.js';
 
 // src/do/durable-timer.ts
 function durableTimer(config) {