@demlik/tea 0.7.0 → 0.8.0

package/dist/chart/index.d.ts

@@ -1,791 +1,6 @@
 import { C as Cmd, T as Transitions, R as Reducer } from '../core-Bjc0bS8j.js';
-
-/**
- * A type smuggled through a value position. `ty<{ at: number }>()` is an empty
- * object at runtime whose TYPE remembers `{ at: number }` — which is what lets
- * an event declare its payload IN the chart instead of in a parallel type map
- * the author has to keep in step.
- */
-interface Ty<T> {
-    readonly __ty: T;
-}
-declare const ty: <T>() => Ty<T>;
-/** `Ty<T>` → `T`; anything else (an absent `data`) → the neutral `unknown`. */
-type Payload<X> = X extends Ty<infer T> ? T : unknown;
-type EvMap<C> = C extends {
-    readonly events: infer E;
-} ? E : never;
-type CmdMap<C> = C extends {
-    readonly cmds: infer M;
-} ? M : Record<never, never>;
-type Groups<C> = C extends {
-    readonly states: infer G;
-} ? G : never;
-type CtxOf<C> = C extends {
-    readonly ctx: infer T;
-} ? Payload<T> : unknown;
-type EventName<C> = Extract<keyof EvMap<C>, string>;
-type CmdName<C> = Extract<keyof CmdMap<C>, string>;
-/** The named phases — `keyof states`. A group name is declared by BEING a key. */
-type GroupName<C> = Extract<keyof Groups<C>, string>;
-type StateName<C> = Extract<{
-    [G in keyof Groups<C>]: keyof Groups<C>[G];
-}[keyof Groups<C>], string>;
-/** The node for state `S`, found by scanning the groups. Groups partition. */
-type NodeAt<C, S> = {
-    [G in keyof Groups<C>]: S extends keyof Groups<C>[G] ? Groups<C>[G][S] : never;
-}[keyof Groups<C>];
-/** The phase `S` lives in. A union here means `S` was declared twice. */
-type GroupOf<C, S> = Extract<{
-    [G in keyof Groups<C>]: S extends keyof Groups<C>[G] ? G : never;
-}[keyof Groups<C>], string>;
-type OnOf<X> = X extends {
-    readonly on: infer O;
-} ? O : Record<never, never>;
-type IgnoreOf<X> = X extends {
-    readonly ignore: readonly (infer I)[];
-} ? Extract<I, string> : never;
-type DataOf<X> = X extends {
-    readonly data: infer D;
-} ? Payload<D> : unknown;
-type IsEndOf<X> = X extends {
-    readonly end: true;
-} ? true : false;
-type IsInitialOf<X> = X extends {
-    readonly initial: true;
-} ? true : false;
-type IsForeignOf<X> = X extends {
-    readonly foreign: true;
-} ? true : false;
-type ScopeOf<X> = X extends {
-    readonly scope: infer S;
-} ? S extends readonly string[] ? S[number] : S : never;
-type On<C, S> = OnOf<NodeAt<C, S>>;
-type IgnoredAt<C, S> = IgnoreOf<NodeAt<C, S>>;
-/** A cmd reference on an edge: one declared name, or an ORDERED list of them. */
-type CmdRef<N extends string> = N | readonly N[];
-type EdgeSpec<SN extends string, CN extends string> = SN | {
-    readonly to: readonly SN[];
-    readonly cell: string;
-} | {
-    readonly target: SN;
-    readonly cmd?: CmdRef<CN>;
-} | {
-    readonly target: SN;
-    readonly when: string;
-    readonly otherwise: SN;
-    /** Fires only when the guard HOLDS. */
-    readonly cmd?: CmdRef<CN>;
-    /** Fires only when the guard FAILS — `Cmd.when` lifted onto the edge. */
-    readonly otherwiseCmd?: CmdRef<CN>;
-} | {
-    readonly resume: {
-        readonly fallback: SN;
-    };
-    readonly cmd?: CmdRef<CN>;
-};
-/** The `scope` field AS DECLARED — before the list is flattened to its members. */
-type ScopeDeclOf<X> = X extends {
-    readonly scope: infer S;
-} ? S : never;
-type ScopeElems<S> = S extends readonly (infer T)[] ? T : S;
-/**
- * Is this event's `scope` something the AUTHOR wrote, or is it tsc's fallback?
- *
- * When some OTHER error in the chart literal (a typo'd target, say) defeats
- * inference of `C`, tsc falls back to the `Chart<C>` constraint, where `scope`
- * is the whole `"edges" | "all" | GroupName<C> | readonly (…)[]` universe. Left
- * alone that makes every event look live in every phase and buries the one real
- * diagnostic under a wall of spurious unhandled-pair demands.
- *
- * The fallback is recognised BY ITS SHAPE, not by what it happens to cover: it
- * is the one form that is a union MIXING a string with a list, which no literal
- * can produce. An author's scope is either a word (`"all"`) or a list
- * (`["edges", "p"]`) — never both at once.
- *
- * The older test — "a scope that spans the entire universe is no scope" — was a
- * proxy for this, and it misfired on the genuinely authored `["edges","all","p"]`:
- * the type layer read it as NO scope (so `MissingPairs<C>` was `never` and the
- * chart looked total) while `compile`'s `scopeList(…).includes("all")` read it as
- * live everywhere and threw `NoCellError` on the first msg. Testing the shape
- * instead makes the two layers agree by construction.
- *
- * A `string`-typed (non-literal) scope is also not authorable as a decision, so
- * it keeps the old reading of "no scope".
- */
-type IsAuthoredScope<X, S = ScopeDeclOf<X>> = [S] extends [string] ? [string] extends [S] ? false : true : [S] extends [readonly string[]] ? [string] extends [ScopeElems<S>] ? false : true : false;
-/** The event's declared scope, once it is established that it IS a declaration. */
-type ScopeAt<C, E extends keyof EvMap<C>> = [
-    IsAuthoredScope<EvMap<C>[E]>
-] extends [true] ? ScopeOf<EvMap<C>[E]> : never;
-/** The events that are LIVE at `S` — i.e. that `S` owes a decision about. */
-type LiveAt<C, S> = {
-    [E in EventName<C>]: "all" extends ScopeAt<C, E> ? E : [GroupOf<C, S>] extends [ScopeAt<C, E>] ? E : never;
-}[EventName<C>];
-/** Pairs at `S` that are live, unhandled and unrefused. Empty = total. */
-type MissingAt<C, S> = [IsEndOf<NodeAt<C, S>>] extends [true] ? never : Exclude<LiveAt<C, S>, Extract<keyof On<C, S>, string> | IgnoredAt<C, S>>;
-/** Every unhandled pair in the whole chart — `never` when the chart is total. */
-type MissingPairs<C> = {
-    [S in StateName<C>]: `${S}.${Extract<MissingAt<C, S>, string>}`;
-}[StateName<C>];
-type Chart<C> = {
-    /** Data EVERY state carries. Declared once; intersected into all of them. */
-    readonly ctx?: Ty<object>;
-    readonly events: {
-        readonly [E in keyof EvMap<C>]: {
-            readonly data?: Ty<object>;
-            /**
-             * "This name is not mine." The Msg is minted by SOMEONE ELSE — a library
-             * Sub (`@demlik/tea/deadline` dispatching `deadline_exceeded`), a host
-             * bridge, another machine — so the author cannot rename it and the
-             * compiler must not decorate it. A foreign event keeps its BARE name in
-             * the emitted table under every namespace, which is what makes it the
-             * same event across all N instances. Everything else — payload, `scope`,
-             * totality, edges — is unchanged: it is a normal event that happens to
-             * belong to someone else.
-             */
-            readonly foreign?: true;
-            readonly scope: "edges" | "all" | GroupName<C> | readonly ("edges" | "all" | GroupName<C>)[];
-        };
-    };
-    readonly cmds?: {
-        readonly [N in keyof CmdMap<C>]: Ty<object>;
-    };
-    readonly states: {
-        readonly [G in keyof Groups<C>]: {
-            readonly [S in keyof Groups<C>[G]]: {
-                /** Exactly one state in a machine-bearing chart marks itself the entry. */
-                readonly initial?: true;
-                /** Extra data only THIS state carries, on top of `ctx`. */
-                readonly data?: Ty<object>;
-                readonly on?: {
-                    readonly [E in EventName<C>]?: EdgeSpec<StateName<C>, CmdName<C>>;
-                };
-                /** Per-state exception: refuse a live event by name. */
-                readonly ignore?: readonly EventName<C>[];
-                readonly end?: true;
-            };
-        };
-    };
-};
-type KnownEdgeField = "target" | "cmd" | "otherwiseCmd" | "when" | "otherwise" | "resume" | "to" | "cell";
-/**
- * A cell edge OWNS its transition end to end — it picks the target and returns
- * its own cmds. So every declarative field that would also decide one of those
- * is illegal ALONGSIDE it, rather than silently ignored by the walk:
- *
- *   `cmd`/`otherwiseCmd` — the cell already returns the cmd list (req. 4)
- *   `when`/`otherwise`   — the cell already chose (a guard would choose twice)
- *   `target`/`resume`    — same fact as `to`, said a second way
- *
- * The `assign` bypass (req. 6) is caught one level up: `Assigns` is keyed by
- * `EdgeKey` MINUS the cell edges, so writing `"polling.poll_failed"` in the
- * assign bag of a cell edge is an excess property, named by tsc.
- */
-type CellFieldConflict = "target" | "cmd" | "otherwiseCmd" | "when" | "otherwise" | "resume";
-/**
- * A resume edge OWNS its transition the same way a cell edge does: the target
- * is `st.was ?? fallback`, which is neither declared nor chosen by a guard. So
- * every field that would ALSO decide the target is illegal alongside it, rather
- * than accepted and then skipped by the walk — `buildCell` tests `edge.resume`
- * first, so a `when` beside it is a guard the author writes, maintains and
- * reads as load-bearing, and which is never once called.
- *
- * `cmd` is absent from this list deliberately: `EdgeSpec` admits `{ resume, cmd }`
- * and the walk fires it, so it is a real, working field on a resume edge.
- * `to`/`cell` are absent because `CellCheck` already names that conflict.
- */
-type ResumeFieldConflict = "target" | "when" | "otherwise" | "otherwiseCmd";
-type ResumeCheck<X> = X extends {
-    readonly resume: unknown;
-} ? [Extract<keyof X, ResumeFieldConflict>] extends [never] ? unknown : {
-    readonly __resumeEdgeCannotAlsoDeclare: Extract<keyof X, ResumeFieldConflict>;
-} : unknown;
-/**
- * `when` and `otherwise` are ONE fact — "this edge branches" — written in two
- * halves, and half of it is not a decision, it is a hole.
- *
- * The two layers used to key the `{ then, else }` assign shape off different
- * halves: `Cell<C, X, …>` off `X extends { target; otherwise }`, `buildCell`
- * off `edge.when !== undefined`. Omit either field and they picked opposite
- * shapes — the chart compiled and then died with `payloadFn is not a function`
- * on the first message. Both layers now read `when`, and this makes the two
- * halves inseparable, so there is no shape left on which they could disagree.
- */
-type GuardPairCheck<X> = X extends {
-    readonly when: string;
-} ? X extends {
-    readonly otherwise: unknown;
-} ? unknown : {
-    readonly __whenNeedsAnOtherwiseTarget: true;
-} : X extends {
-    readonly otherwise: unknown;
-} ? {
-    readonly __otherwiseNeedsAWhenGuard: true;
-} : unknown;
-type CellCheck<X> = X extends {
-    readonly cell: string;
-} ? X extends {
-    readonly to: readonly unknown[];
-} ? [Extract<keyof X, CellFieldConflict>] extends [never] ? unknown : {
-    readonly __cellEdgeCannotAlsoDeclare: Extract<keyof X, CellFieldConflict>;
-} : {
-    readonly __cellEdgeMustDeclareItsTargetsInTo: true;
-} : X extends {
-    readonly to: readonly unknown[];
-} ? {
-    readonly __toWithoutACellToPickFromIt: true;
-} : unknown;
-type EdgeCheck<X> = X extends string ? unknown : [Exclude<keyof X, KnownEdgeField>] extends [never] ? CellCheck<X> & ResumeCheck<X> & GuardPairCheck<X> & (X extends {
-    readonly otherwiseCmd: unknown;
-} ? X extends {
-    readonly when: string;
-} ? unknown : {
-    readonly __otherwiseCmdWithoutAGuard: true;
-} : unknown) : {
-    readonly __edgeHasUnknownField: Exclude<keyof X, KnownEdgeField>;
-};
-type KnownChartField = "ctx" | "events" | "cmds" | "states";
-type KnownEventField = "data" | "foreign" | "scope";
-type KnownNodeField = "initial" | "data" | "on" | "ignore" | "end";
-type UnknownKeys<X, Known extends string> = Exclude<keyof X, Known>;
-type EventCheck<X> = [UnknownKeys<X, KnownEventField>] extends [never] ? unknown : {
-    readonly __eventHasUnknownField: UnknownKeys<X, KnownEventField>;
-};
-type NodeCheck<N> = [UnknownKeys<N, KnownNodeField>] extends [never] ? unknown : {
-    readonly __stateNodeHasUnknownField: UnknownKeys<N, KnownNodeField>;
-};
-type StrictNode<C, N> = NodeCheck<N> & {
-    readonly on?: {
-        readonly [E in keyof OnOf<N>]: E extends EventName<C> ? EdgeCheck<OnOf<N>[E]> : {
-            readonly __onDeclaresAnUndeclaredEvent: E;
-        };
-    };
-};
-type IsDegenerate<N> = [string] extends [N] ? true : false;
-type LiteralAlphabets<C> = ([IsDegenerate<StateName<C>>] extends [true] ? {
-    readonly __stateNamesMustBeLiteralsNotAComputedStringKey: true;
-} : unknown) & ([IsDegenerate<EventName<C>>] extends [true] ? {
-    readonly __eventNamesMustBeLiteralsNotAComputedStringKey: true;
-} : unknown) & ([IsDegenerate<CmdName<C>>] extends [true] ? {
-    readonly __cmdNamesMustBeLiteralsNotAComputedStringKey: true;
-} : unknown) & ([IsDegenerate<GroupName<C>>] extends [true] ? {
-    readonly __phaseNamesMustBeLiteralsNotAComputedStringKey: true;
-} : unknown);
-type Strict<C> = LiteralAlphabets<C> & ([UnknownKeys<C, KnownChartField>] extends [never] ? unknown : {
-    readonly __chartHasUnknownField: UnknownKeys<C, KnownChartField>;
-}) & {
-    readonly events: {
-        readonly [E in keyof EvMap<C>]: EventCheck<EvMap<C>[E]>;
-    };
-    readonly states: {
-        readonly [G in keyof Groups<C>]: {
-            readonly [S in keyof Groups<C>[G]]: StrictNode<C, Groups<C>[G][S]>;
-        };
-    };
-};
-type Demand<S extends string, E extends string> = E extends string ? `unhandled pair "${S}.${E}" — declare it in \`on\`, or list "${E}" in this state's \`ignore\`, or narrow the \`scope\` of event "${E}"` : never;
-type IsUnion<T, U = T> = T extends unknown ? [U] extends [T] ? false : true : never;
-type Total<C> = {
-    readonly events: {
-        readonly [E in keyof EvMap<C>]: [IsForeignOf<EvMap<C>[E]>] extends [true] ? E extends `${string}.${string}` ? {
-            readonly __foreignEventNameCannotContainADot: E;
-        } : unknown : unknown;
-    };
-    readonly states: {
-        readonly [G in keyof Groups<C>]: {
-            readonly [S in keyof Groups<C>[G]]: ([MissingAt<C, S>] extends [never] ? unknown : {
-                readonly [K in Demand<Extract<S, string>, Extract<MissingAt<C, S>, string>>]: never;
-            }) & (Extract<S, string> extends `${string}.${string}` ? {
-                readonly __stateNameCannotContainADot: S;
-            } : unknown) & ([Extract<keyof On<C, S>, string>] extends [never] ? unknown : [IsEndOf<Groups<C>[G][S]>] extends [true] ? {
-                readonly __endStateCannotDeclareEdges: keyof On<C, S>;
-            } : unknown) & ([IsUnion<GroupOf<C, S>>] extends [true] ? {
-                readonly __stateDeclaredInTwoPhases: GroupOf<C, S>;
-            } : unknown) & ([Exclude<IgnoredAt<C, S>, LiveAt<C, S>>] extends [never] ? unknown : {
-                readonly __refusalRefusesNothing: Exclude<IgnoredAt<C, S>, LiveAt<C, S>>;
-            });
-        };
-    };
-};
-/**
- * `const C` preserves the nested literals with no `as const` at the call site
- * (without it every edge value widens to `string` and every derivation below
- * collapses). `Strict` and `Total` sit on the PARAMETER, not on the constraint:
- * intersecting them into the constraint makes the typo'd-target diagnostic
- * collapse to an index-signature complaint about `string` and lose tsc's
- * "Did you mean '"review"'?" suggestion.
- */
-declare function defineChart<const C extends Chart<C>>(c: C & Strict<C> & Total<C>): C;
-type EdgeAt<C, S, E> = E extends keyof On<C, S> ? On<C, S>[E] : never;
-/** The `State.Event` pairs that are ACTUALLY declared — not the cross product. */
-type EdgeKey<C> = {
-    [S in StateName<C>]: `${S}.${Extract<keyof On<C, S>, string>}`;
-}[StateName<C>];
-/** The subset of `EdgeKey` whose transition is delegated to a cell. */
-type CellEdgeKey<C> = Extract<{
-    [S in StateName<C>]: {
-        [E in keyof On<C, S>]: On<C, S>[E] extends {
-            readonly cell: string;
-        } ? `${S}.${Extract<E, string>}` : never;
-    }[keyof On<C, S>];
-}[StateName<C>], string>;
-/** The state marked `initial: true` — the chart's entry, as data. */
-type InitialState<C> = Extract<{
-    [S in StateName<C>]: [IsInitialOf<NodeAt<C, S>>] extends [true] ? S : never;
-}[StateName<C>], string>;
-/** States that carry a `resume` edge out of them — the parking states. */
-type ParkingState<C> = Extract<{
-    [S in StateName<C>]: {
-        [E in keyof On<C, S>]: On<C, S>[E] extends {
-            readonly resume: unknown;
-        } ? S : never;
-    }[keyof On<C, S>];
-}[StateName<C>], string>;
-/** The targets a CELL edge declares — the union its cell is clamped to. */
-type ToOf<X> = X extends {
-    readonly to: readonly (infer T)[];
-} ? T : never;
-/**
- * Every state an edge can land on. A guarded edge contributes both arms; a
- * cell edge contributes its whole declared `to` fan-out — which is precisely
- * why the escape hatch does not blind the derivations (`ResumeTargets`,
- * `chartMermaid`) that read the graph's shape.
- */
-type TargetOf<X> = X extends string ? X : X extends {
-    readonly to: readonly unknown[];
-} ? ToOf<X> : X extends {
-    readonly target: infer T;
-} ? T | (X extends {
-    readonly otherwise: infer O;
-} ? O : never) : never;
-/** States with an edge INTO `P` — i.e. the states you could be parked from. */
-type ResumeSource<C, P> = {
-    [S in StateName<C>]: {
-        [E in keyof On<C, S>]: P extends TargetOf<On<C, S>[E]> ? S : never;
-    }[keyof On<C, S>];
-}[StateName<C>];
-/** The `fallback` declared on `P`'s resume edge — Umut's `?? initial`. */
-type FallbackOf<C, P> = {
-    [E in keyof On<C, P>]: On<C, P>[E] extends {
-        readonly resume: {
-            readonly fallback: infer F;
-        };
-    } ? F : never;
-}[keyof On<C, P>];
-/**
- * Where a resume edge out of parking state `P` can land: any state with an edge
- * into `P`, plus the declared fallback. `was ?? initial` lifted to a type — and
- * DERIVED, so adding a `BLOCKED` edge from a new state widens the legal `was`.
- */
-type ResumeTargets<C, P> = Extract<ResumeSource<C, P> | FallbackOf<C, P>, string>;
-/**
- * `was` is INJECTED here, not authored: a parking state is one with a `resume`
- * edge, which the chart already says. Writing `blocked: Ctx & { was: … }` by
- * hand would be that same fact a second time.
- */
-type StateOf<C> = {
-    [S in StateName<C>]: {
-        readonly type: S;
-    } & CtxOf<C> & DataOf<NodeAt<C, S>> & (S extends ParkingState<C> ? {
-        readonly was: ResumeTargets<C, S>;
-    } : unknown);
-}[StateName<C>];
-type MsgOf<C> = {
-    [E in EventName<C>]: {
-        readonly type: E;
-    } & DataOf<EvMap<C>[E]>;
-}[EventName<C>];
-type CmdOf<C> = [CmdName<C>] extends [never] ? Cmd<never> : {
-    [N in CmdName<C>]: {
-        readonly type: N;
-    } & Payload<CmdMap<C>[N]>;
-}[CmdName<C>];
-/** The events the chart declares FOREIGN — the names that are not ours to decorate. */
-type ForeignEvent<C> = Extract<{
-    [E in EventName<C>]: [IsForeignOf<EvMap<C>[E]>] extends [true] ? E : never;
-}[EventName<C>], string>;
-/**
- * How the compiled table keys event `E`. Namespacing is PER-EVENT, not
- * per-machine: `NS` omitted (`undefined`) namespaces nothing, and a foreign
- * event keeps its bare name even under a namespace. Everything stays a literal.
- */
-type KeyOf<C, NS extends string | undefined, E extends string> = E extends ForeignEvent<C> ? E : NS extends string ? `${NS}.${E}` : E;
-/**
- * The Msg union AS THE COMPILED TABLE CONSUMES IT — the same derivation as
- * `MsgOf`, with the keys the namespace produces. Two namespaces give genuinely
- * disjoint literal unions for the author's OWN events, while the foreign events
- * are literally shared, because they are the same event.
- */
-type MsgIn<C, NS extends string | undefined = undefined> = {
-    [E in EventName<C>]: {
-        readonly type: KeyOf<C, NS, E>;
-    } & DataOf<EvMap<C>[E]>;
-}[EventName<C>];
-type Narrow<U, K> = Extract<U, {
-    type: K;
-}>;
-type Data<S, K> = K extends string ? Omit<Narrow<S, K>, "type"> : never;
-type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
-/**
- * What an `assign` must return for a given target. `was` is stripped when the
- * target is a parking state: the compiler injects it from `state.type`, so the
- * author can neither forget it nor type it wrong.
- */
-type Assigned<C, S, T> = T extends string ? T extends ParkingState<C> ? Omit<Data<S, T>, "was"> : Data<S, T> : never;
-/**
- * What `boot()` must return: the initial state's payload, minus the `type` the
- * compiler stamps on. The two degenerate charts get a NAMED marker type rather
- * than a silent `never`, so the diagnostic says which rule was broken.
- */
-type InitialData<C, S extends {
-    type: string;
-}> = [
-    InitialState<C>
-] extends [never] ? {
-    readonly __chartDeclaresNoInitialState: true;
-} : [IsUnion<InitialState<C>>] extends [true] ? {
-    readonly __chartDeclaresManyInitialStates: InitialState<C>;
-} : Data<S, InitialState<C>>;
-type Fn<S, M, From, Ev, R> = (state: Narrow<S, From>, msg: Narrow<M, Ev>) => R;
-type Cell<C, X, S, M, From, Ev> = X extends {
-    readonly resume: unknown;
-} ? Fn<S, M, From, Ev, UnionToIntersection<Assigned<C, S, ResumeTargets<C, From>>>> : X extends {
-    readonly when: string;
-} ? {
-    readonly then: Fn<S, M, From, Ev, Assigned<C, S, X extends {
-        readonly target: infer T;
-    } ? T : never>>;
-    readonly else: Fn<S, M, From, Ev, Assigned<C, S, X extends {
-        readonly otherwise: infer O;
-    } ? O : never>>;
-} : X extends {
-    readonly target: infer T;
-} ? Fn<S, M, From, Ev, Assigned<C, S, T>> : X extends string ? Fn<S, M, From, Ev, Assigned<C, S, X>> : never;
-/**
- * The payload builders — one per DECLARATIVE edge. Cell edges are excluded:
- * a cell returns the whole next state itself, so an `assign` entry for one
- * would be dead code the walk never calls. Because this is a mapped type over
- * a closed key union, writing that entry anyway is an excess property and tsc
- * names it (req. 6 — the bypass is a compile error, not a surprise).
- */
-type Assigns<C, S extends {
-    type: string;
-}, M extends {
-    type: string;
-}> = {
-    [K in Exclude<EdgeKey<C>, CellEdgeKey<C>>]: K extends `${infer From}.${infer Ev}` ? Cell<C, EdgeAt<C, From, Ev>, S, M, From, Ev> : never;
-};
-type GuardName<C> = Extract<{
-    [S in StateName<C>]: {
-        [E in keyof On<C, S>]: On<C, S>[E] extends {
-            readonly when: infer W;
-        } ? W : never;
-    }[keyof On<C, S>];
-}[StateName<C>], string>;
-/** Every cell named by a `{ to, cell }` edge — the escape hatch's alphabet. */
-type CellName<C> = Extract<{
-    [S in StateName<C>]: {
-        [E in keyof On<C, S>]: On<C, S>[E] extends {
-            readonly cell: infer W;
-        } ? W : never;
-    }[keyof On<C, S>];
-}[StateName<C>], string>;
-/** Flatten a `CmdRef` — one name, or every name in an ordered list. */
-type Flatten<X> = X extends readonly string[] ? X[number] : X;
-/** Every cmd an edge can fire, across BOTH guard arms. */
-type EdgeCmds<X> = (X extends {
-    readonly cmd: infer Q;
-} ? Flatten<Q> : never) | (X extends {
-    readonly otherwiseCmd: infer Q;
-} ? Flatten<Q> : never);
-/** Every cmd name any edge in the chart actually FIRES declaratively. */
-type UsedCmdName<C> = Extract<{
-    [S in StateName<C>]: {
-        [E in keyof On<C, S>]: EdgeCmds<On<C, S>[E]>;
-    }[keyof On<C, S>];
-}[StateName<C>], string>;
-/** What field `F` on an edge REFERENCES — a guard/cell name, or its cmd names. */
-type Referenced<X, F extends "when" | "cmd" | "cell"> = F extends "when" ? X extends {
-    readonly when: infer W;
-} ? W : never : F extends "cell" ? X extends {
-    readonly cell: infer W;
-} ? W : never : EdgeCmds<X>;
-/**
- * Scan the chart for every edge that references `Name` through field `F`.
- * `[Name] extends [Referenced<…>]` rather than an equality check, because an
- * edge's cmd list references SEVERAL names at once.
- */
-type SitesWhere<C, F extends "when" | "cmd" | "cell", Name> = {
-    [S in StateName<C>]: {
-        [E in keyof On<C, S>]: [Name] extends [Referenced<On<C, S>[E], F>] ? `${S}.${Extract<E, string>}` : never;
-    }[keyof On<C, S>];
-}[StateName<C>];
-/**
- * `"review.FAIL"` → `[state: ReviewState, msg: FailMsg, at: "review.FAIL"]`.
- * Distributes over N sites, so a multi-site name yields a UNION OF TUPLES.
- *
- * The third element is the correlator. A union of tuples does not, on its own,
- * keep `state` and `msg` in step: narrowing `state.type` is a NESTED
- * discriminant, and TypeScript's dependent-parameter control-flow analysis
- * (TS 4.6, microsoft/TypeScript#47109) only re-narrows sibling parameters from
- * a discriminant that is a DIRECT, literal-typed element of the union. `at` is
- * exactly that: one `switch (at)` collapses the tuple union to a single member,
- * and `state` AND `msg` both narrow with it.
- *
- * For a single-site name `K` is not a union, so this is a lone tuple and the
- * author may keep writing `(s, m) => …`.
- */
-type SiteArgs<K, S, M> = K extends `${infer From}.${infer Ev}` ? [state: Narrow<S, From>, msg: Narrow<M, Ev>, at: K] : never;
-/**
- * THE POINT. A guard's parameters come from the edges that REFERENCE it, not
- * from a standalone registry declaration — so `retriesRemaining`, used only at
- * `review.FAIL`, receives exactly `review`'s state and `FAIL`'s msg.
- */
-type Guards<C, S extends {
-    type: string;
-}, M extends {
-    type: string;
-}> = {
-    [N in GuardName<C>]: (...args: SiteArgs<SitesWhere<C, "when", N>, S, M>) => boolean;
-};
-/**
- * Same technique: a cmd's parameters come from the edges that REFERENCE it, and
- * the payload it owes is the one DECLARED in the chart's `cmds` section — the
- * single site where the effect alphabet lives. A cmd fired from two edges gets
- * the union of both sites' `[state, msg]` tuples.
- */
-type Cmds<C, S extends {
-    type: string;
-}, M extends {
-    type: string;
-}> = {
-    [N in UsedCmdName<C>]: (...args: SiteArgs<SitesWhere<C, "cmd", N>, S, M>) => Payload<CmdMap<C>[N]>;
-};
-/**
- * THE ESCAPE HATCH's parts bag. Same shape and the same `SitesWhere`/`SiteArgs`
- * narrowing as `guards` and `cmds` — a cell used at one site gets exactly that
- * site's state and msg, a cell used at N sites gets the union of N tuples plus
- * the `at` correlator to discriminate on.
- *
- * What is different is the RETURN: a cell returns the transition itself,
- * `[nextState, cmds]`, clamped to the states the edge DECLARED in `to`. That
- * clamp is the whole bargain — code may decide, but only among the targets the
- * chart admits, so the chart stays a truthful drawing of the machine.
- */
-type Cells<C, S extends {
-    type: string;
-}, M extends {
-    type: string;
-}> = {
-    [N in CellName<C>]: CellForm<C, SitesWhere<C, "cell", N>, S, M>;
-};
-/** The `to` union of every site `N` is used at, resolved to real State members. */
-type CellTarget<C, Sites, S> = Sites extends `${infer From}.${infer Ev}` ? Narrow<S, ToOf<EdgeAt<C, From, Ev>>> : never;
-type CellReturn<C, Sites, S> = readonly [
-    CellTarget<C, Sites, S>,
-    readonly CmdOf<C>[]
-];
-/**
- * THE MULTI-SITE RETURN, EXACTLY. One entry per use site, each a lone tuple of
- * parameters and each clamped to THAT site's `to` — so `a.X` returning a `c` is
- * rejected at `a.X` rather than waved through because some OTHER site admits a
- * `c`. The `at` element is still passed (the walk hands it over uniformly), and
- * is simply redundant here: the key already says which site this is.
- */
-type CellBySite<C, Sites, S, M> = {
-    readonly [K in Extract<Sites, string>]: (...args: SiteArgs<K, S, M>) => CellReturn<C, K, S>;
-};
-/**
- * A cell is written in ONE of two forms, and the choice is the precision dial.
- *
- *   the FUNCTION form — one body, `switch (at)` inside. Parameters narrow per
- *     site (the `SiteArgs` correlator); the RETURN does not, because the whole
- *     thing is one rest signature over a union of tuples and TypeScript has no
- *     dependent return type over that (5.7: a union of function types is
- *     reduced back to exactly this shape, an intersection loses the parameter
- *     correlation, and a generic on the site key correlates nothing and merely
- *     rejects every body — all three measured, none of them work). The clamp is
- *     therefore the union of every site's `to`.
- *
- *   the PER-SITE form — one entry per site, each exact in both directions.
- *
- * The second is offered ONLY when the cell is genuinely multi-site: with one
- * site the function form is already exact in both directions, so its type stays
- * byte-for-byte what it was and the common case cannot regress.
- *
- * The looseness the function form keeps is closed at RUNTIME instead: the walk
- * checks the returned `type` against the edge's declared `to` and throws
- * `CellTargetError`. Worth less than a compile error, worth more than nothing —
- * and `to` is right there, so it costs one `includes`.
- */
-type CellForm<C, Sites, S, M> = ((...args: SiteArgs<Sites, S, M>) => CellReturn<C, Sites, S>) | ([IsUnion<Sites>] extends [true] ? CellBySite<C, Sites, S, M> : never);
-/** The declared state names — a flat tuple, not a grouped record of nodes. */
-type RStateName<C> = C extends {
-    readonly states: readonly (infer S)[];
-} ? Extract<S, string> : never;
-/** The top-level edge bag. One edge per event; that IS the totality obligation. */
-type ROn<C> = C extends {
-    readonly on: infer O;
-} ? O : never;
-type REdgeAt<C, E> = E extends keyof ROn<C> ? ROn<C>[E] : never;
-type ReducerChart<C> = {
-    /** Data EVERY state carries — and, here, the ONLY data any state carries. */
-    readonly ctx?: Ty<object>;
-    readonly states: readonly RStateName<C>[];
-    /** The entry state, by name. One word where the grid form marks a node. */
-    readonly initial: RStateName<C>;
-    readonly events: {
-        readonly [E in keyof EvMap<C>]: {
-            readonly data?: Ty<object>;
-            /** Same meaning as the grid form's: this name is not ours to decorate. */
-            readonly foreign?: true;
-        };
-    };
-    readonly cmds?: {
-        readonly [N in keyof CmdMap<C>]: Ty<object>;
-    };
-    /**
-     * TOTAL, not partial. Every declared event owes an edge — the `?` the grid
-     * form's per-state `on` carries is exactly what `Total<C>` had to police
-     * there, and here the mapped type does it for free.
-     */
-    readonly on: {
-        readonly [E in EventName<C>]: EdgeSpec<RStateName<C>, CmdName<C>>;
-    };
-};
-/**
- * `resume` needs a phase dimension: `was` is derived from "the states with an
- * edge INTO the parking state", and here every edge is reachable from every
- * state, so the derivation degenerates to "all of them" and says nothing. It
- * is rejected by name rather than silently accepted and ignored by the walk.
- */
-type RStrictEdge<X> = X extends {
-    readonly resume: unknown;
-} ? {
-    readonly __resumeNeedsAPhaseDimension: true;
-} : EdgeCheck<X>;
-/** The reducer form's key alphabet — `scope` has no meaning without phases. */
-type KnownReducerChartField = "ctx" | "states" | "initial" | "events" | "cmds" | "on";
-type KnownReducerEventField = "data" | "foreign";
-type REventCheck<X> = [UnknownKeys<X, KnownReducerEventField>] extends [never] ? unknown : {
-    readonly __eventHasUnknownField: UnknownKeys<X, KnownReducerEventField>;
-};
-type StrictR<C> = ([IsDegenerate<RStateName<C>>] extends [true] ? {
-    readonly __stateNamesMustBeLiteralsNotAComputedStringKey: true;
-} : unknown) & ([IsDegenerate<EventName<C>>] extends [true] ? {
-    readonly __eventNamesMustBeLiteralsNotAComputedStringKey: true;
-} : unknown) & ([IsDegenerate<CmdName<C>>] extends [true] ? {
-    readonly __cmdNamesMustBeLiteralsNotAComputedStringKey: true;
-} : unknown) & ([UnknownKeys<C, KnownReducerChartField>] extends [never] ? unknown : {
-    readonly __chartHasUnknownField: UnknownKeys<C, KnownReducerChartField>;
-}) & {
-    readonly on: {
-        readonly [E in keyof ROn<C>]: E extends EventName<C> ? RStrictEdge<ROn<C>[E]> : {
-            readonly __onDeclaresAnUndeclaredEvent: E;
-        };
-    };
-    readonly events: {
-        readonly [E in keyof EvMap<C>]: REventCheck<EvMap<C>[E]> & ([IsForeignOf<EvMap<C>[E]>] extends [true] ? E extends `${string}.${string}` ? {
-            readonly __foreignEventNameCannotContainADot: E;
-        } : unknown : unknown);
-    };
-};
-/** Same contract as `defineChart`, one dimension smaller. */
-declare function defineReducerChart<const C extends ReducerChart<C>>(c: C & StrictR<C>): C;
-/**
- * ONE object, not a union: every state carries `ctx` and nothing else, so the
- * only thing that varies is the tag. This is the original's
- * `interface State { phase: Phase; … }` with `phase` named `type`.
- */
-type RStateOf<C> = {
-    readonly type: RStateName<C>;
-} & CtxOf<C>;
-/** The events whose transition is delegated to a cell. */
-type RCellEvent<C> = Extract<{
-    [E in EventName<C>]: ROn<C>[E & keyof ROn<C>] extends {
-        readonly cell: string;
-    } ? E : never;
-}[EventName<C>], string>;
-type RNames<C, F extends "when" | "cmd" | "cell"> = Extract<{
-    [E in keyof ROn<C>]: Referenced<ROn<C>[E], F>;
-}[keyof ROn<C>], string>;
-type RGuardName<C> = RNames<C, "when">;
-type RCellName<C> = RNames<C, "cell">;
-type RUsedCmdName<C> = RNames<C, "cmd">;
-/**
- * A site is an EVENT. The grid form's `SitesWhere` scans `state × event`; with
- * one dimension the scan is the same shape with the outer loop removed.
- */
-type RSitesWhere<C, F extends "when" | "cmd" | "cell", Name> = Extract<{
-    [E in keyof ROn<C>]: [Name] extends [Referenced<ROn<C>[E], F>] ? E : never;
-}[keyof ROn<C>], string>;
-/**
- * The state is NOT narrowed — there is nothing to narrow it to. Everything
- * else is `SiteArgs` verbatim, including the `at` correlator that lets a
- * multi-site helper discriminate its msg with one `switch`.
- */
-type RSiteArgs<K, S, M> = K extends string ? [state: S, msg: Narrow<M, K>, at: K] : never;
-type RGuards<C, S, M extends {
-    type: string;
-}> = {
-    [N in RGuardName<C>]: (...args: RSiteArgs<RSitesWhere<C, "when", N>, S, M>) => boolean;
-};
-type RCmds<C, S, M extends {
-    type: string;
-}> = {
-    [N in RUsedCmdName<C>]: (...args: RSiteArgs<RSitesWhere<C, "cmd", N>, S, M>) => Payload<CmdMap<C>[N & keyof CmdMap<C>]>;
-};
-type RCells<C, S extends {
-    type: string;
-}, M extends {
-    type: string;
-}> = {
-    [N in RCellName<C>]: RCellForm<C, RSitesWhere<C, "cell", N>, S, M>;
-};
-/** The `to` clamp, unchanged in spirit: the tag is restricted, `ctx` is not. */
-type RCellTarget<C, Sites> = Sites extends string ? {
-    readonly type: Extract<ToOf<REdgeAt<C, Sites>>, string>;
-} & CtxOf<C> : never;
-type RCellReturn<C, Sites> = readonly [
-    RCellTarget<C, Sites>,
-    readonly CmdOf<C>[]
-];
-/**
- * `CellForm`, with the phase dimension removed — the same two forms, offered on
- * the same condition, for the same reason. A site here is an EVENT, so the
- * per-site bag is keyed `"X" | "Y"` rather than `"a.X" | "b.Y"`; everything
- * else, including the runtime `CellTargetError` under the function form, is the
- * grid form's machinery reused verbatim (`buildCell` serves both).
- */
-type RCellForm<C, Sites, S, M extends {
-    type: string;
-}> = ((...args: RSiteArgs<Sites, S, M>) => RCellReturn<C, Sites>) | ([IsUnion<Sites>] extends [true] ? {
-    readonly [K in Extract<Sites, string>]: (...args: RSiteArgs<K, S, M>) => RCellReturn<C, K>;
-} : never);
-/**
- * What an `assign` returns: `ctx`, for every target. The compiler stamps
- * `type` from the edge, so — as in the grid form — the author cannot forget it
- * and cannot get it wrong.
- */
-type RAssigned<C> = CtxOf<C>;
-type RFn<S, M extends {
-    type: string;
-}, E, R> = (state: S, msg: Narrow<M, E>) => R;
-type RCell<C, X, S, M extends {
-    type: string;
-}, E> = X extends {
-    readonly when: string;
-} ? {
-    readonly then: RFn<S, M, E, RAssigned<C>>;
-    readonly else: RFn<S, M, E, RAssigned<C>>;
-} : RFn<S, M, E, RAssigned<C>>;
-/** One builder per DECLARATIVE event. Cell events own their whole transition. */
-type RAssigns<C, S, M extends {
-    type: string;
-}> = {
-    [E in Exclude<EventName<C>, RCellEvent<C>>]: RCell<C, REdgeAt<C, E>, S, M, E>;
-};
+import { A as Assigns, G as GuardName, l as Guards, U as UsedCmdName, m as Cmds, n as CellName, o as Cells, p as RAssigns, q as RGuardName, r as RGuards, s as RUsedCmdName, t as RCmds, u as RCellName, v as RCells, C as Chart, S as StateOf, M as MsgOf, a as CmdOf, j as MsgIn, R as ReducerChart, b as RStateOf, I as InitialData, f as InitialState } from '../graph-CcjWZVrd.js';
+export { w as CmdEvent, x as CmdName, y as EdgeKey, z as EdgeSpec, B as EndPolarity, i as ErrorFinal, E as EventName, k as EventOrigin, F as ForeignEvent, D as GroupName, H as GroupOf, J as MissingPairs, O as OriginAt, P as ParkingState, K as RStateName, c as StateName, L as SubEvent, h as SuccessFinal, g as Ty, W as WorldEvent, N as WorldRole, Q as defineChart, V as defineReducerChart, X as ty } from '../graph-CcjWZVrd.js';
 
 /**
  * A cell returned a state OUTSIDE its edge's declared `to`.
@@ -929,6 +144,74 @@ declare function initialStateOf<const C extends Chart<C>>(chart: C): InitialStat
 declare function initFrom<const C extends Chart<C>, S extends {
     type: string;
 }, K extends Cmd>(chart: C, boot: () => InitialData<C, S>): (loaded: S | null) => readonly [S, readonly K[]];
-declare function chartMermaid<const C extends Chart<C>>(chart: C): string;
+/** How many times each {@link edgeKey} was walked. */
+type WalkCounts = ReadonlyMap<string, number>;
+/**
+ * The key a {@link ChartMermaidOptions.walked} map is read by.
+ *
+ * One spelling, shared by whoever counts the walk and the drawing that marks
+ * it — the names are the chart's OWN, unsanitized, because the counter reads
+ * them off a log and has no business knowing what mermaid can spell.
+ *
+ * NOT `EdgeKey<C>` (`graph.ts`), despite the casing. That one is the SITE tag
+ * — `"state.event"` — which is what a guard or a cmd builder is keyed by,
+ * because a site is where code hangs. This one names a drawn ARROW, and a
+ * guarded site draws two of them, so it needs the target as well.
+ */
+declare const edgeKey: (from: string, event: string, to: string) => string;
+/**
+ * Options for {@link chartMermaid}. Every field is optional and every default
+ * reproduces the drawing this function emitted before options existed — a flat
+ * node set, `direction TB`, no title, no highlight, no polarity and no walk —
+ * so an existing caller is untouched.
+ *
+ * Shaped after `MachineVizOptions` (`../machine-viz`) where the two overlap
+ * (`direction`, `title`), because the two drawings are read side by side and a
+ * second spelling of the same knob is a fact said twice. What is NOT shared is
+ * `samples`: `toMermaid` needs them because it must EXECUTE a compiled cell to
+ * learn a target; the chart declares its targets, so there is nothing to
+ * resolve and nothing to sample.
+ */
+interface ChartMermaidOptions {
+    /**
+     * Draw this state as the ACTIVE node — a `classDef`/`class` pair Mermaid
+     * renders with the highlight fill. Pass the live `state.type`. A name that is
+     * not in the chart is ignored rather than drawn as a phantom node.
+     */
+    readonly highlight?: string;
+    /**
+     * Draw each phase as a Mermaid COMPOSITE state (`state working { … }`).
+     *
+     * The chart groups its states into named phases and the flat drawing throws
+     * that away — which is the one structural fact `chartMermaid` knew and did
+     * not show. Off by default: turning it on changes the emitted text, and the
+     * drawing is something a reviewer approves rather than something that moves
+     * under them.
+     */
+    readonly phases?: boolean;
+    /**
+     * Draw the two ENDINGS differently — a dashed outline on every `end:
+     * "error"` final, a heavier one on every `end: true`.
+     *
+     * A success final and an error final both terminate, so both draw the `[*]`
+     * edge, and a picture that stopped there paints `shipped` and `frozen` alike
+     * in the one place a reader looks first. Off by default for the same reason
+     * `phases` is: it changes the emitted text.
+     */
+    readonly polarity?: boolean;
+    /**
+     * Edges the caller actually WALKED, keyed by {@link edgeKey} — each drawn
+     * edge that has a count picks up a `»` (or `»×N`) on its label.
+     *
+     * A missing or zero count marks nothing, so a chart nobody has run through
+     * draws exactly as it does without this option.
+     */
+    readonly walked?: WalkCounts;
+    /** Mermaid layout direction. Default `"TB"`. */
+    readonly direction?: "TB" | "LR";
+    /** Optional title, emitted as a Mermaid front-matter `title:` block. */
+    readonly title?: string;
+}
+declare function chartMermaid<const C extends Chart<C>>(chart: C, opts?: ChartMermaidOptions): string;
 
-export { type Assigns, type CellName, CellTargetError, type Cells, type Chart, type CmdName, type CmdOf, type Cmds, type EdgeKey, type EdgeSpec, type EventName, type ForeignEvent, type GroupName, type GroupOf, type GuardName, type Guards, type InitialState, type MissingPairs, type MsgIn, type MsgOf, type ParkingState, type Parts, type RAssigns, type RCellName, type RCells, type RCmds, type RGuardName, type RGuards, type RParts, type RStateName, type RStateOf, type RUsedCmdName, type ReducerChart, type StateName, type StateOf, type Ty, type UsedCmdName, chartMermaid, compile, compileReducer, defineChart, defineReducerChart, initFrom, initialStateOf, reducerInitFrom, reducerMermaid, ty };
+export { Assigns, CellName, CellTargetError, Cells, Chart, type ChartMermaidOptions, CmdOf, Cmds, GuardName, Guards, InitialState, MsgIn, MsgOf, type Parts, RAssigns, RCellName, RCells, RCmds, RGuardName, RGuards, type RParts, RStateOf, RUsedCmdName, ReducerChart, StateOf, UsedCmdName, type WalkCounts, chartMermaid, compile, compileReducer, edgeKey, initFrom, initialStateOf, reducerInitFrom, reducerMermaid };