@demlik/tea 0.12.0 → 0.14.0

package/dist/reducer-BqyoVyBG.d.ts

@@ -1,447 +0,0 @@
-import { k as EventOrigin, C as Chart, R as ReducerChart } from './graph-CcjWZVrd.js';
-import { R as RtSamples } from './samples-DCt6nF8H.js';
-
-/**
- * WHY a (state, event) pair is refused. The chart's three refusal mechanisms,
- * each carrying the evidence that produced it, so a UI can say *"`WIP` is not
- * addressed to `blocked` — its scope is `edges`"* rather than "disabled".
- *
- * `undeclared` is the fourth case the type layer forbids: a pair that is live,
- * unhandled and unrefused. It cannot occur on a chart that compiled through
- * `defineChart`, and it is reported rather than swallowed because reaching it
- * means the types were bypassed with a cast — which is precisely when a
- * debugger should say so instead of drawing a well-behaved button.
- */
-type RefusalReason = {
-    readonly kind: "end";
-    /** Terminal state: it accepts nothing, by declaration. */
-    readonly state: string;
-} | {
-    readonly kind: "out-of-scope";
-    /** The event's declared `scope`, flattened to its members. */
-    readonly scope: readonly string[];
-    /** The phase this state lives in — the one that is not in `scope`. */
-    readonly phase: string;
-} | {
-    /**
-     * `scope: "edges"` — the event is live exactly where an edge declares it,
-     * and this state declares none.
-     *
-     * SPLIT OUT OF `out-of-scope` because the phase has nothing to do with it.
-     * `"edges"` is not a phase name, so the phase test could never pass and
-     * the refusal came back naming a phase the reader then went looking for:
-     * *"`DONE` is not addressed to phase `working` (scope: edges)"* — three
-     * pieces of vocabulary for one fact, and the fact is not in there. The
-     * default scope is `edges`, so this was most refusals on most charts.
-     */
-    readonly kind: "no-edge";
-    readonly state: string;
-} | {
-    readonly kind: "ignored";
-    /** The event is live here and this state refuses it BY NAME. */
-    readonly state: string;
-} | {
-    readonly kind: "undeclared";
-};
-/** A one-line, human-readable rendering of a {@link RefusalReason}. */
-declare function explainRefusal(event: string, reason: RefusalReason): string;
-/** What kind of transition an edge declares. */
-type EdgeKind = "plain" | "guarded" | "cell" | "resume";
-/** One declared edge — a `(state, event)` pair the chart routes. */
-interface ChartEdge {
-    readonly from: string;
-    readonly event: string;
-    /** `"${from}.${event}"` — the site key guards/cmds/cells are indexed by. */
-    readonly at: string;
-    readonly kind: EdgeKind;
-    /**
-     * Every state this edge can land on, in declaration order. A guarded edge
-     * contributes both arms; a cell edge contributes its whole declared `to`.
-     * For a resume edge this is the fallback alone — the real target is
-     * `state.was`, which is a property of the LIVE state, not of the chart.
-     */
-    readonly targets: readonly string[];
-    /** The guard's name, on a guarded edge. */
-    readonly guard?: string;
-    /** The target taken when the guard HOLDS. */
-    readonly then?: string;
-    /** The target taken when the guard FAILS. */
-    readonly otherwise?: string;
-    /** The cell's name, on a `{ to, cell }` edge. */
-    readonly cell?: string;
-    /** The declared fallback, on a `resume` edge. */
-    readonly fallback?: string;
-    /** Cmds fired when the edge fires (the guard's `then` arm, if guarded). */
-    readonly cmds: readonly string[];
-    /** Cmds fired when the guard FAILS. Empty unless the edge is guarded. */
-    readonly otherwiseCmds: readonly string[];
-}
-/** A (state, event) pair the chart explicitly refuses, and why. */
-interface ChartRefusal {
-    readonly from: string;
-    readonly event: string;
-    readonly reason: RefusalReason;
-}
-/** One state, with the facts the chart declares about it. */
-interface ChartStateInfo {
-    readonly name: string;
-    /** The phase it was declared under. */
-    readonly phase: string;
-    /** `initial: true` — the entry state. Exactly one per machine-bearing chart. */
-    readonly initial: boolean;
-    /**
-     * Terminal by DECLARATION, not by "has no outgoing edges" — `true` for both
-     * polarities, because both accept nothing and both owe nothing.
-     */
-    readonly end: boolean;
-    /**
-     * WHICH ending. `true` a success final, `"error"` the failure terminal,
-     * `false` not a final at all.
-     *
-     * `end` answers "does this accept anything"; this answers "did the machine
-     * win or lose". A lane needs both and they are not the same question —
-     * `shipped` and `frozen` are equally terminal and are not the same outcome.
-     */
-    readonly endPolarity: false | true | "error";
-    /** Carries a `resume` edge out of it, so the compiler injects `was` here. */
-    readonly parking: boolean;
-}
-/** One event of the alphabet. */
-interface ChartEventInfo {
-    readonly name: string;
-    /** The declared `scope`, flattened: `"edges"`, `"all"`, or phase names. */
-    readonly scope: readonly string[];
-    /** `foreign: true` — the name belongs to someone else and stays bare. */
-    readonly foreign: boolean;
-    /**
-     * WHERE THIS EVENT COMES FROM — `from`, read back off the chart.
-     *
-     * `undefined` means the chart does not say, which is a fact of its own and
-     * never a default: a UI that groups its button row by sender must render the
-     * undeclared ones as undeclared rather than filing them under a guess.
-     */
-    readonly from?: EventOrigin;
-    /**
-     * Whether the event DECLARED a payload (`data: ty<…>()`).
-     *
-     * `ty<T>()` is `{}` at runtime, so `T` is unreadable — but the `data` KEY is
-     * right there in the literal, so "does this event carry a payload at all" IS
-     * a runtime fact. It is what decides whether a sample is required.
-     */
-    readonly hasPayload: boolean;
-}
-/**
- * A whole chart, as data a UI can build itself from. Nothing here is supplied
- * by the caller; every field is read off the one chart value.
- */
-interface ChartDescription {
-    /** The phases, in declaration order, each with its member states. */
-    readonly phases: readonly {
-        readonly name: string;
-        readonly states: readonly string[];
-    }[];
-    readonly states: readonly ChartStateInfo[];
-    /** The state marked `initial: true`, or `undefined` on a chart with none. */
-    readonly initial: string | undefined;
-    readonly events: readonly ChartEventInfo[];
-    /** Every cmd DECLARED in the `cmds` section — the effect alphabet. */
-    readonly cmds: readonly string[];
-    /** Every guard name any edge references. */
-    readonly guards: readonly string[];
-    /** Every cell name any `{ to, cell }` edge references. */
-    readonly cells: readonly string[];
-    readonly edges: readonly ChartEdge[];
-    readonly refusals: readonly ChartRefusal[];
-}
-/**
- * A read edge MINUS the state it leaves — everything about an edge that is a
- * fact of the edge itself rather than of the grid it sits in.
- *
- * The reducer form has no state dimension (`src/chart/inspect/reducer.ts`), so
- * its edges are exactly this: same kinds, same targets, same guard/cell/cmd
- * fields, with `from` unrepresentable rather than blank.
- */
-type EdgeCore = Omit<ChartEdge, "from">;
-/**
- * Read a chart into its {@link ChartDescription}.
- *
- * Pure, total, and allocation-only — it never executes a guard, a cell or a
- * payload builder, so it is safe on a chart whose parts do not exist yet.
- */
-declare function describeChart<const C extends Chart<C>>(chart: C): ChartDescription;
-/** The declared edge out of `state` on `event`, or `undefined`. */
-declare function edgeAt(desc: ChartDescription, state: string, event: string): ChartEdge | undefined;
-/** Why `state` refuses `event`, or `undefined` when it does not. */
-declare function refusalAtState(desc: ChartDescription, state: string, event: string): RefusalReason | undefined;
-/** The record for `state`, or `undefined` when the chart has no such state. */
-declare function stateInfo(desc: ChartDescription, state: string): ChartStateInfo | undefined;
-
-/** Any guard, however narrowly its use sites typed it. */
-type AnyGuard = (...args: never[]) => boolean;
-/** Any cell, in either the single-body or the per-site form. */
-type AnyCell = ((...args: never[]) => readonly [{
-    readonly type: string;
-}, unknown]) | Readonly<Record<string, unknown>>;
-/**
- * The code parts a preview may consult — the SAME bag `compile` receives, so
- * an author passes the one they already built rather than a second copy.
- * Every field is optional: the preview degrades where a part is absent.
- */
-interface InspectParts {
-    readonly guards?: Readonly<Record<string, AnyGuard | undefined>>;
-    readonly cells?: Readonly<Record<string, AnyCell | undefined>>;
-}
-/** Everything a live preview may consult, beyond the state itself. */
-interface InspectOptions {
-    /** The parts bag `compile` was given. Guards/cells are read from it. */
-    readonly parts?: InspectParts;
-    /** Sample payload per event — see `./samples`. */
-    readonly samples?: RtSamples;
-}
-/** Why a guard could not be evaluated. Each is a fact, not a guess. */
-type GuardUnknown = "no-guard-bag" | "no-implementation" | "no-sample" | "threw";
-/**
- * Which branch a guarded edge would take right now.
- *
- * `then` / `else` are ANSWERS — the guard ran, on this state, with this msg.
- * `unknown` is the honest non-answer, carrying the reason and (for a throwing
- * guard) the message, so a UI shows "cannot evaluate: no sample for FAIL"
- * rather than a confidently wrong arrow.
- */
-type GuardPreview = {
-    readonly guard: string;
-    readonly branch: "then" | "else";
-    /** The state that branch lands on. */
-    readonly target: string;
-    /** The cmds that branch fires. */
-    readonly cmds: readonly string[];
-} | {
-    readonly guard: string;
-    readonly branch: "unknown";
-    readonly why: GuardUnknown;
-    /** The thrown error's message, when `why` is `"threw"`. */
-    readonly error?: string;
-};
-/** How a single target was determined, when one could be. */
-type ResolvedBy = "declared" | "guard" | "resume" | "cell";
-/**
- * What would happen if `event` were dispatched at the current state.
- *
- * A refusal is FIRST-CLASS: it carries the reason and a rendered explanation,
- * so a UI draws it as visibly refused rather than omitting the control. That
- * is the totality property paying rent — the chart knows the difference
- * between "not routed here", "deliberately dropped here" and "this state is
- * over", and a debugger that hides all three behind a missing button throws
- * away the one thing this substrate knows and others do not.
- */
-interface EventPreview {
-    readonly event: string;
-    readonly status: "legal" | "refused";
-    /**
-     * Who would send this — the event's declared `from`, carried through rather
-     * than recomputed, so a button row can be grouped by sender with the same
-     * answer the report's "waiting on" line gives. `undefined` when the chart
-     * does not say.
-     */
-    readonly from?: EventOrigin;
-    /** Present iff `status` is `"refused"`. */
-    readonly reason?: RefusalReason;
-    /** A one-line rendering of `reason`. Present iff refused. */
-    readonly why?: string;
-    /** The declared edge. Present iff legal. */
-    readonly edge?: ChartEdge;
-    /** Present iff the edge is guarded. */
-    readonly guard?: GuardPreview;
-    /**
-     * The cmds that WOULD fire — read off the edge's declaration. For a guarded
-     * edge whose branch resolved, the cmds of THAT arm; for one that did not, the
-     * `then` arm's (the declared happy path) — `guard.branch === "unknown"` is
-     * what says so.
-     *
-     * This is the BEFORE question, and a `{ to, cell }` edge answers it with an
-     * empty list BY DECLARATION: the cell builds its cmds inside its body, so the
-     * chart has none to declare. For what actually fired, ask the after question
-     * — `captureCmds` in `./captured`, which reads the emitted cmds off the
-     * machine's own output.
-     */
-    readonly cmds: readonly string[];
-    /** Every state the edge declares it can reach. */
-    readonly targets: readonly string[];
-    /** The single target, when one is determined. */
-    readonly resolved?: string;
-    /** How {@link EventPreview.resolved} was determined. */
-    readonly resolvedBy?: ResolvedBy;
-    /**
-     * The msg this preview used — the sample plus the chart's `type`. `undefined`
-     * when the event declares a payload and no sample was supplied, which is
-     * also why a guard or cell may have come back `unknown`.
-     */
-    readonly msg?: {
-        readonly type: string;
-    };
-}
-/**
- * Preview one event against a live state.
- *
- * @param desc  the chart's {@link ChartDescription}.
- * @param state the live state — anything with a `type` (and `was`, on a
- *              parking state, which is what makes a resume target resolvable).
- */
-declare function previewEvent<S extends {
-    readonly type: string;
-}>(desc: ChartDescription, state: S, event: string, opts?: InspectOptions): EventPreview;
-/**
- * Preview EVERY event of the alphabet against a live state, in the chart's
- * declaration order.
- *
- * This is the button row: one entry per declared event, each either legal
- * (with its branch, targets and cmds) or refused (with its reason). Nothing is
- * filtered out — a refused event is a control the UI draws, not one it lacks.
- */
-declare function inspectState<S extends {
-    readonly type: string;
-}>(desc: ChartDescription, state: S, opts?: InspectOptions): readonly EventPreview[];
-/**
- * {@link inspectState}, plus the two roll-ups a caller almost always wants
- * next: the legal event names and the refused ones.
- *
- * The whole verdict list is still there — the split is a convenience, not a
- * filter, and `events` remains the surface a UI renders so a refusal keeps its
- * reason.
- */
-declare function inspectStateSummary<S extends {
-    readonly type: string;
-}>(desc: ChartDescription, state: S, opts?: InspectOptions): {
-    readonly state: S;
-    readonly events: readonly EventPreview[];
-    readonly legal: readonly string[];
-    readonly refused: readonly string[];
-};
-
-/**
- * A QUESTION THIS FORM CANNOT ANSWER, carried in the slot where the grid form
- * carries the answer.
- *
- * `answerable: false` is the whole type: there is no `true` member, because a
- * question this form CAN answer is answered with the answer. So `desc.refusals`
- * on a reducer description is not an empty list a UI silently renders — it is a
- * value whose only shape says why the list is not there, and code written
- * against the grid form's array fails to compile against it.
- */
-interface Unanswerable<Q extends string> {
-    readonly answerable: false;
-    /** Which question — the grid-form field this stands in for. */
-    readonly question: Q;
-    /** One line, ready to render. */
-    readonly why: string;
-}
-/** One edge of a reducer chart — an edge with no state to leave from. */
-type ReducerEdge = EdgeCore;
-/** One event of a reducer chart's alphabet. `scope` has no counterpart here. */
-interface ReducerEventInfo {
-    readonly name: string;
-    /** `foreign: true` — the name belongs to someone else and stays bare. */
-    readonly foreign: boolean;
-    /** WHO SENDS THIS. `undefined` means the chart does not say — never a guess. */
-    readonly from?: EventOrigin;
-    /** Whether the event declared a payload (`data: ty<…>()`). */
-    readonly hasPayload: boolean;
-    /** `false` iff the chart declares this event and routes it nowhere. */
-    readonly routed: boolean;
-}
-/**
- * A reducer-form chart, as data a UI can build itself from — the same contract
- * as {@link import("./describe").ChartDescription}, over the facts this form
- * actually has.
- */
-interface ReducerChartDescription {
-    /** The declared state names, in declaration order. Flat: there are no groups. */
-    readonly states: readonly string[];
-    /** The entry state — the chart's `initial` field, not a marked node. */
-    readonly initial: string;
-    readonly events: readonly ReducerEventInfo[];
-    /** Every cmd DECLARED in the `cmds` section — the effect alphabet. */
-    readonly cmds: readonly string[];
-    readonly guards: readonly string[];
-    readonly cells: readonly string[];
-    /** One edge per routed event, in the alphabet's declaration order. */
-    readonly edges: readonly ReducerEdge[];
-    /**
-     * TOTALITY, read back off the value: `true` iff every declared event owes and
-     * has an edge. Through the typed door this is always `true` — `on` is a
-     * required mapped type — so a `false` here means the types were bypassed with
-     * a cast, exactly as `refusals`' `undeclared` kind does in the grid form.
-     */
-    readonly total: boolean;
-    /** The declared events with no edge. Empty through the typed door. */
-    readonly missing: readonly string[];
-    /** NOT AVAILABLE — see {@link Unanswerable}. */
-    readonly phases: Unanswerable<"phases">;
-    /** NOT AVAILABLE — see {@link Unanswerable}. */
-    readonly refusals: Unanswerable<"refusals">;
-    /** NOT AVAILABLE — see {@link Unanswerable}. */
-    readonly scope: Unanswerable<"scope">;
-}
-/**
- * Read a reducer-form chart into its {@link ReducerChartDescription}.
- *
- * Pure, total and allocation-only, exactly as `describeChart` is: it never runs
- * a guard, a cell or a payload builder, so it is safe on a chart whose parts do
- * not exist yet.
- */
-declare function describeReducerChart<const C extends ReducerChart<C>>(chart: C): ReducerChartDescription;
-/** The edge that routes `event`, or `undefined` when the chart routes it nowhere. */
-declare function reducerEdgeAt(desc: ReducerChartDescription, event: string): ReducerEdge | undefined;
-/**
- * What would happen if `event` were dispatched at the current state.
- *
- * There is NO `status` field, and its absence is the honest part: this form
- * cannot refuse an event — `on` is total over the alphabet and there is no
- * state dimension to refuse from — so a "legal" tag would be a distinction
- * without a second case. Everything a grid preview can still say here it says:
- * the edge, the guard's branch, the declared fan-out, the target a cell picks.
- *
- * The cmds are the DECLARED ones — the before question. For what actually
- * fired, see `captureCmds` in `./captured`.
- */
-interface ReducerEventPreview {
-    readonly event: string;
-    /** The event's declared `from`, carried through rather than recomputed. */
-    readonly from?: EventOrigin;
-    /** The declared edge. `undefined` only when the chart routes the event nowhere. */
-    readonly edge?: ReducerEdge;
-    /** Present iff the edge is guarded. */
-    readonly guard?: GuardPreview;
-    /** The cmds the edge DECLARES for the arm that resolved. */
-    readonly cmds: readonly string[];
-    /** Every state the edge declares it can reach. */
-    readonly targets: readonly string[];
-    /** The single target, when one is determined. */
-    readonly resolved?: string;
-    /** How {@link ReducerEventPreview.resolved} was determined. */
-    readonly resolvedBy?: ResolvedBy;
-    /** The msg this preview used, or `undefined` when no sample was supplied. */
-    readonly msg?: {
-        readonly type: string;
-    };
-}
-/**
- * Preview one event of a reducer chart against a live state.
- *
- * The guard and cell previews are the SAME functions the grid form uses — a
- * guard is pure and a cell is pure in both forms, and the only difference is
- * that `at` is the bare event name.
- */
-declare function previewReducerEvent<S extends {
-    readonly type: string;
-}>(desc: ReducerChartDescription, state: S, event: string, opts?: InspectOptions): ReducerEventPreview;
-/**
- * Preview EVERY event of a reducer chart's alphabet against a live state, in
- * declaration order. The button row — and here every control is live, because
- * this form has nothing with which to refuse one.
- */
-declare function inspectReducerState<S extends {
-    readonly type: string;
-}>(desc: ReducerChartDescription, state: S, opts?: InspectOptions): readonly ReducerEventPreview[];
-
-export { type AnyCell as A, type ChartDescription as C, type EdgeCore as E, type GuardPreview as G, type InspectOptions as I, type ReducerChartDescription as R, type Unanswerable as U, type AnyGuard as a, type ChartEdge as b, type ChartEventInfo as c, type ChartRefusal as d, type ChartStateInfo as e, type EdgeKind as f, type EventPreview as g, type GuardUnknown as h, type InspectParts as i, type ReducerEdge as j, type ReducerEventInfo as k, type ReducerEventPreview as l, type RefusalReason as m, type ResolvedBy as n, describeChart as o, describeReducerChart as p, edgeAt as q, explainRefusal as r, inspectReducerState as s, inspectState as t, inspectStateSummary as u, previewEvent as v, previewReducerEvent as w, reducerEdgeAt as x, refusalAtState as y, stateInfo as z };