@demlik/tea 0.13.0 → 0.15.0

package/dist/fold-BJPdjc9w.d.ts

@@ -1,435 +0,0 @@
-import { k as EventOrigin } from './graph-B3L5e0N1.js';
-
-/** `TASK_1.DONE` and `DONE` are the same event; the namespace is presentation. */
-declare const bareEvent: (event: string) => string;
-/** A declarative edge, in the only three forms a lane region can produce. */
-/**
- * `cmd` / `otherwiseCmd` are carried but never AUTHORED here: a `workflow.json`
- * declares no effects, so an imported edge simply has neither. They exist
- * because the TYPED door has them and lowering used to drop them, which left a
- * lane page able to say where a click LANDS and never what it FIRES — a fact
- * the author wrote down, lost in translation.
- */
-type ImportedCmds = {
-    readonly cmd?: string | readonly string[];
-    readonly otherwiseCmd?: string | readonly string[];
-};
-type ImportedEdge = ({
-    readonly target: string;
-} & ImportedCmds) | ({
-    readonly target: string;
-    readonly when: string;
-    readonly otherwise: string;
-} & ImportedCmds) | ({
-    readonly resume: {
-        readonly fallback: string;
-    };
-} & ImportedCmds);
-interface ImportedNode {
-    readonly initial?: true;
-    readonly on?: Readonly<Record<string, ImportedEdge>>;
-    /** `true` success final, `"error"` the fallthrough final that trips the lane. */
-    readonly end?: true | "error";
-}
-/** One task's region, as a chart value. One phase group, named by the phase. */
-interface ImportedChart {
-    readonly events: Readonly<Record<string, {
-        readonly scope: "edges";
-        /**
-         * Where this event comes from — the chart's `from`, at runtime.
-         *
-         * OPTIONAL, and its absence is the document's honest answer:
-         * `workflow.json` records the topology and nothing about who sends
-         * what, so this is present exactly when the caller supplied it at
-         * {@link chartFromWorkflow}.
-         */
-        readonly from?: EventOrigin;
-    }>>;
-    readonly states: Readonly<Record<string, Readonly<Record<string, ImportedNode>>>>;
-    /**
-     * State name → the events that state ACCEPTS AND DROPS, leaving itself alone.
-     *
-     * THE THIRD ANSWER. A lane state either routes an event, or refuses it, or
-     * cannot replay it — tea's runtime has always had all three (`compile`'s
-     * `refused` self-loops a pair the state's `ignore` names or the event's
-     * `scope` does not address, and only a LIVE-but-undecided pair throws), and
-     * the lowered chart could carry only two. So `stepTask` threw
-     * `UnreplayableLogError` on a log `runLane` had accepted without blinking: a
-     * run and a report of that run disagreeing, which is the one thing this
-     * module promises they cannot do.
-     *
-     * IT IS ON THE CHART, NOT ON THE NODE, and that is deliberate.
-     * {@link ImportedNode} is a MIRROR of the node fabrika's own compiler emits —
-     * `golden.test.ts` compares the two — so a field fabrika never produces does
-     * not belong inside it. This is our layer's annotation about someone else's
-     * shape, and it sits one level out where it reads as one.
-     *
-     * ABSENT AT THE IMPORTED DOOR, always. A refusal is a fact about a state's
-     * `ignore` and an event's `scope`, and `workflow.json` records neither — so
-     * `chartFromWorkflow` writes none, an imported chart is the same value it
-     * always was, and an imported log naming an unrouted event is still refused
-     * loudly. Only `defineLane`'s lowering, which can SEE the two, fills it in.
-     */
-    readonly refusals?: Readonly<Record<string, readonly string[]>>;
-}
-interface ImportedPhase {
-    readonly name: string;
-    readonly tasks: readonly string[];
-}
-interface ImportedLane {
-    /** The document's own `id`, when it carries one. */
-    readonly id?: string;
-    /** What fires this lane — a chore workflow's own field, carried not invented. */
-    readonly trigger?: string;
-    readonly phases: readonly ImportedPhase[];
-    /** The workflow's two terminals, read off the last phase's `onDone` pair. */
-    readonly terminals: {
-        readonly complete: string;
-        readonly tripped: string;
-    };
-    /** One chart per task id — the ask's `charts`. */
-    readonly charts: Readonly<Record<string, ImportedChart>>;
-    /**
-     * The document's `context` per task, minus the retry bookkeeping the fold
-     * owns. `maxRetries` is split out because it is a transition input, not a
-     * passenger — the guarded arm reads it.
-     */
-    readonly context: Readonly<Record<string, {
-        readonly maxRetries: number;
-        readonly extras: Readonly<Record<string, unknown>>;
-    }>>;
-}
-/**
- * THE ONE PLACE PROVENANCE ENTERS.
- *
- * `workflow.json` carries topology and nothing else: it says `queued --WIP-->
- * build` and it does not say, and has never said, who sends a `WIP`. That fact
- * lives in fabrika's CODE, not in fabrika's document — so it cannot be read
- * here and it must not be guessed here.
- *
- * So the caller states it, ONCE, at the seam where their world meets ours, and
- * everything downstream derives from that: the charts carry it, the report
- * groups by it, the inspector reports it. One map, at the boundary the
- * information actually crosses — not a default sprinkled through the readers,
- * and not a table of fabrika's own event names baked in as a fallback, which
- * would put us right back to owning a copy of someone else's vocabulary.
- *
- * ```ts
- * chartFromWorkflow(document, {
- *   from: {
- *     WIP: { world: "the operator" },
- *     BLOCKED: { world: "the operator" },
- *     UNBLOCKED: { world: "a human" },
- *     DONE: "cmd",
- *     PASS: "cmd",
- *     FAIL: "cmd",
- *   },
- * });
- * ```
- *
- * Omit it and every reader degrades honestly — it says which events a state
- * accepts and refuses to say who they come from.
- */
-interface WorkflowImportOptions {
-    /**
-     * Event name → where its Msg comes from. Keyed by the BARE name, so one
-     * entry covers every task's namespaced spelling of it (`ISSUE.WIP`,
-     * `PARK_SWEEP.WIP`) — the namespace is presentation, the event is the event.
-     *
-     * A name with no entry is left undeclared rather than defaulted. "I do not
-     * know" and "the outside world" are different answers and only one of them
-     * is safe to invent.
-     */
-    readonly from?: Readonly<Record<string, EventOrigin>>;
-    /**
-     * Refuse a `from` key that names no event THIS document routes.
-     *
-     * The silent drop it closes is real: `UNBLOKED: { world: "a human" }` imports
-     * clean, and every reader downstream then answers "the chart does not say"
-     * for the one event the caller had just taken the trouble to declare. The
-     * cross-check needs no list of ours — {@link eventAlphabet} derives the
-     * document's own alphabet, which is precisely what that function exists for
-     * and what nothing was calling.
-     *
-     * OPT-IN, because the map is legitimately WIDER than one document. A
-     * consumer's cast is a property of their world, not of one template, so one
-     * `from` covers every workflow they run — `src/chart/report/__fixtures__/
-     * origins.ts` states fabrika's six once and imports two templates with it,
-     * and the chore template routes neither `PASS` nor `FAIL`. Defaulting to
-     * strict would make sharing a cast an error, which is the wrong half of the
-     * trade. So the caller says which of the two they meant: pass this when the
-     * map was written FOR this document, and a typo in it stops compiling.
-     */
-    readonly strictFrom?: true;
-}
-/**
- * The document does not fit — with EVERY defect named, never a half-import.
- *
- * Same contract as fabrika's `Malformed`: a `workflow.json` that cannot be
- * compiled comes back as a list of reasons rather than as a machine that works
- * for some states. Thrown rather than returned because the chart module's other
- * doors throw too (`initialStateOf`, `CellTargetError`) and an importer that
- * returned a union would be the only one a caller could forget to check.
- */
-declare class WorkflowImportError extends Error {
-    readonly defects: readonly string[];
-    readonly name = "WorkflowImportError";
-    readonly _tag: "WorkflowImportError";
-    constructor(defects: readonly string[]);
-}
-/**
- * `workflow.json` → one chart per task, plus the phase topology around them.
- *
- * WHICH HALF GUARANTEES WHAT — this matters, and it is the whole reason the
- * authored fixture (`src/chart/__fixtures__/lane.ts`) still exists beside this
- * function rather than being deleted in its favour:
- *
- *   THIS FUNCTION gives you FIDELITY. It reads bytes that only exist at
- *   runtime, so its result is `ImportedChart` — states, events and targets are
- *   `string`, and nothing about them is checked before the process starts. What
- *   it buys is that the drawing is of THE document the driver is actually
- *   folding, including a `workflow.json` this repo has never seen.
- *
- *   THE AUTHORED FIXTURE gives you TYPES. `lane.ts` is the same machine written
- *   as a literal, so `StateName`, `ResumeTargets`, `Assigns` and the totality
- *   obligation are all real there, and `assert.test-d.ts` pins them. What it
- *   cannot do is follow a document it was not written against.
- *
- * Neither replaces the other. The golden test is the seam: it asserts this
- * importer's edge set against what fabrika's own compiler produces for the same
- * file, so the runtime-typed half stays honest about the literal-typed one.
- *
- * @param document the PARSED `workflow.json` — `JSON.parse`'s output, not text.
- * @param options  {@link WorkflowImportOptions} — the facts the document does
- *                 not carry, stated once at the boundary they enter through.
- * @throws {WorkflowImportError} with every defect named, never a half-import.
- */
-declare function chartFromWorkflow(document: unknown, options?: WorkflowImportOptions): ImportedLane;
-/** Parse and import in one step — for a caller holding the document's bytes. */
-declare function chartFromWorkflowText(text: string, options?: WorkflowImportOptions): ImportedLane;
-/** Every state in an imported chart, flattened out of its one phase group. */
-declare function statesOf(chart: ImportedChart): ReadonlyMap<string, ImportedNode>;
-/** The state marked `initial: true`. */
-declare function initialOf(chart: ImportedChart): string;
-/**
- * Every event name this lane declares, in first-declaration order.
- *
- * THE ALPHABET, DERIVED — the answer a caller used to get from a constant in
- * this file listing one consumer's six. It is a fact about the document, so it
- * is read from the document: the bare names its states route, deduplicated
- * across tasks and phases. A consumer that adds an event gets it here the
- * commit it lands, without a release of ours.
- *
- * Use it to build the `from` map at the import boundary and know you covered
- * every name, or to diff two revisions of a workflow for a vocabulary change.
- */
-declare function eventAlphabet(lane: ImportedLane): readonly string[];
-/**
- * Where `event` comes from, or `undefined` when the chart does not say.
- *
- * The ONE read of provenance, so a reader that wants to group by origin and a
- * reader that wants to label one event cannot disagree about what "undeclared"
- * looks like.
- */
-declare function originOf(chart: ImportedChart, event: string): EventOrigin | undefined;
-/** `true` success, `"error"` tripped, `false` not a final — the ONE polarity read. */
-declare function endPolarityOf(node: ImportedNode | undefined): true | "error" | false;
-
-/**
- * The edge a step DREW, keyed as {@link edgeKey} spells it.
- *
- * ONE DECLARATION SITE for the resume rule, and that is the whole reason it is
- * a function rather than four lines inside {@link timeline}. A resume edge is
- * DRAWN once, to its fallback, and WALKED to wherever `was` pointed — so
- * recovering "which edge lit up" from the observed target lands on an edge the
- * drawing does not have. Any reader that knows `from`/`event`/`to` and wants
- * the drawn edge (a folded log's timeline; a live lane's recorded tape) asks
- * here, so the two cannot disagree about which edge to thicken.
- */
-declare function walkedEdgeKey(chart: ImportedChart, from: string, event: string, to: string): string;
-/** One appended line of `events.jsonl`: which task, which event, when. */
-interface LogEntry {
-    readonly task: string;
-    readonly event: string;
-    readonly at: string;
-}
-/** One task's folded state: the leaf, the retry budget, and the state it left. */
-interface TaskState {
-    readonly type: string;
-    readonly retries: number;
-    readonly maxRetries: number;
-    readonly was?: string;
-}
-/**
- * The derived answer `lane status` prints — reproduced here field for field,
- * because a report that computed its own vocabulary would contradict the driver
- * the moment the two disagreed.
- */
-interface LaneStatus {
-    readonly stateValue: string | Readonly<Record<string, Readonly<Record<string, string>> | string>>;
-    readonly status: "active" | "done";
-    readonly context: Readonly<Record<string, unknown>>;
-}
-/** The log does not replay against this workflow — with the reason named. */
-declare class UnreplayableLogError extends Error {
-    readonly defects: readonly string[];
-    readonly name = "UnreplayableLogError";
-    readonly _tag: "UnreplayableLogError";
-    constructor(defects: readonly string[]);
-}
-/**
- * Parse `events.jsonl`. A line that does not parse is a DEFECT, never a
- * silently skipped event — a report built on a log it half-read is worse than
- * no report.
- */
-declare function parseEventsJsonl(text: string): readonly LogEntry[];
-/** `lane history`'s stdout — a JSON array of the same entries, verbatim. */
-declare function parseHistoryJson(text: string): readonly LogEntry[];
-/** The initial state of every task — the fold's zero. */
-declare function initialStates(lane: ImportedLane): Readonly<Record<string, TaskState>>;
-/**
- * ONE event applied to ONE task. The three edge forms, and the two ways there
- * can be no edge.
- *
- * THERE ARE THREE ANSWERS, NOT TWO, and this used to give two. tea's runtime
- * has always distinguished a REFUSAL — an event the state accepts and drops,
- * because its `ignore` names the event or the event is broadcast to some other
- * phase — from a pair it cannot replay, which is the only one that throws. The
- * lowered chart could not carry the first, so a log the runtime had happily
- * accepted came back `UnreplayableLogError` here: a run and a report of that
- * run disagreeing about what the machine did. The refusal set now rides on the
- * chart (`ImportedChart.refusals`, written by `lowerRegion` and by nothing
- * else), so both sides refuse the same pairs by construction.
- *
- * `taskId` is for the DIAGNOSTIC only. `stepTask` folds one region and has
- * never needed to know which; a reader staring at `state "queued" holds no cell
- * for "DONE"` on a twelve-task lane needs to know very much, and the callers
- * have it.
- */
-declare function stepTask(chart: ImportedChart, state: TaskState, event: string, taskId?: string): TaskState;
-/**
- * Fold the whole log into per-task leaf states.
- *
- * PURE OVER A PREFIX: tasks are independent regions, so the global log
- * partitions cleanly and each task folds through its own chart. `foldLane(lane,
- * entries.slice(0, k))` is therefore the exact state after k events, for every
- * k — which is what {@link timeline} spends.
- */
-declare function foldLane(lane: ImportedLane, entries: readonly LogEntry[]): Readonly<Record<string, TaskState>>;
-/** One row of the timeline: the entry, plus the `from → to` nobody stored. */
-interface TimelineStep {
-    readonly index: number;
-    readonly at: string;
-    readonly task: string;
-    /** The event VERBATIM, namespace and all — the log's own spelling. */
-    readonly event: string;
-    readonly from: string;
-    readonly to: string;
-    /**
-     * The DECLARED edge this step fired, as {@link edgeKey} spells it.
-     *
-     * Not derivable from `from`/`event`/`to`, and that is the whole reason it is
-     * carried: a resume edge is DRAWN once, to its fallback, and WALKED to
-     * wherever `was` pointed. Recovering "which edge lit up" from the observed
-     * target would land on an edge the drawing does not have — so the step
-     * records the edge it took while it still knows.
-     */
-    readonly edge: string;
-}
-/**
- * The log with `from → to` recomputed per step.
- *
- * A single left-to-right pass, which is EXACTLY the prefix fold and not an
- * approximation of it: `foldLane` is a left fold over the same entries in the
- * same order, so the state carried into step k here is the state
- * `foldLane(lane, entries.slice(0, k))` returns. `fold.test.ts` asserts that
- * equality rather than asking you to take it on trust — the cheap form and the
- * definitional form, pinned to each other.
- */
-declare function timeline(lane: ImportedLane, entries: readonly LogEntry[]): readonly TimelineStep[];
-/**
- * Where one phase stands. The four are exhaustive over a phase in a lane whose
- * log has been folded, and they are POSITIONAL rather than local: a phase whose
- * tasks all happen to be final is `"waiting"` if an earlier phase stopped the
- * lane before it could have run.
- */
-type PhaseStanding = "complete" | "tripped" | "active" | "waiting";
-/** One phase, and where it stands after the fold. */
-interface PhaseStand {
-    readonly name: string;
-    /** Its position in the sequence — the phase order, as a number. */
-    readonly index: number;
-    readonly tasks: readonly string[];
-    readonly standing: PhaseStanding;
-    /** The tasks in this phase that landed on an ERROR final. */
-    readonly tripped: readonly string[];
-}
-/**
- * The ONE thing the phase walk reads off a task: which state it is standing in.
- *
- * {@link TaskState} satisfies it, and so does a RUNNING region's own
- * `StateOf<chart>` — which is the whole reason the parameter is spelled this
- * loosely. The fold and the runtime carry different per-task values (the fold's
- * carries `retries`, a region's carries its `ctx`), and the advancement rule
- * reads neither: it reads `type`, looks the node up in the chart, and asks its
- * `end` polarity. Widening the parameter to what the rule ACTUALLY reads is what
- * lets {@link phaseStandings} be called by both without a second copy of it.
- */
-type LeafStates = Readonly<Record<string, {
-    readonly type: string;
-}>>;
-/** Every task at an error final — the `errors` list, one declaration site. */
-declare function trippedTasks(lane: ImportedLane, states: LeafStates): readonly string[];
-/**
- * THE PHASE WALK — the one loop that decides which phase is running, which are
- * behind it, and which never got to start.
- *
- * It is fabrika's `deriveStatus` loop, factored out rather than copied: walk
- * phases in order, the first whose tasks are not ALL final is the active one
- * and the walk stops; a phase that IS all final but holds an error final trips
- * the lane and the walk stops there instead; everything after a stop is
- * `"waiting"`, whatever its tasks happen to read.
- *
- * That last clause is the whole reason this is positional. `foldLane` boots
- * every task of every phase, so a later phase's region can sit in a final
- * before its phase ever ran — a child the board abandoned boots straight into
- * an error final, which is exactly the case fabrika's emitter produces. Read
- * locally, that phase looks "tripped". Read in sequence, it is a phase that
- * never started, and the lane tripped somewhere else.
- *
- * {@link deriveLaneStatus} and the report both read this, so the compound state
- * value and the phase headings cannot disagree about what is running.
- */
-declare function phaseStandings(lane: ImportedLane, states: LeafStates): readonly PhaseStand[];
-/**
- * THE ADVANCEMENT RULE — has the lane left the phases, and by which door?
- *
- * `undefined` means "still running": some phase is active, so the lane is
- * sitting in it. A terminal name means the walk ran out of phases — every phase
- * completed (`onDone` chained all the way past the last one, which is what the
- * `complete` terminal IS), or one of them completed holding a region at an
- * `end: "error"` final, which trips the lane wherever it had got to.
- *
- * Three lines, and they are pulled out here rather than inlined below because
- * this is the rule the RUNTIME advances by (`runLane`, in `../lane/run`). The
- * runtime does not re-derive it and does not agree with it by inspection: it
- * calls {@link phaseStandings} over its own region states and then this, so
- * "the machine advanced" and "the fold says it advanced" are the same sentence
- * evaluated twice, not two sentences kept in sync.
- */
-declare function laneTerminalReached(stands: readonly PhaseStand[], terminals: ImportedLane["terminals"]): string | undefined;
-/**
- * The whole "compound machine", as a pure derivation.
- *
- * The active phase is the first whose tasks are not all final; a COMPLETED
- * phase holding a task in an error final trips the workflow. That is fabrika's
- * `noErrors` gate — never a machine event, and here it reads the chart's
- * `end: "error"` polarity, which is the same fact the document's guarded
- * fallthrough declared. The walk itself is {@link phaseStandings}, so the
- * status and the drawing are one derivation seen twice.
- */
-declare function deriveLaneStatus(lane: ImportedLane, states: Readonly<Record<string, TaskState>>): LaneStatus;
-/** `lane status`'s stdout, parsed back into the shape it was printed from. */
-declare function parseStatusJson(text: string): LaneStatus;
-
-export { timeline as A, trippedTasks as B, walkedEdgeKey as C, type ImportedLane as I, type LogEntry as L, type PhaseStanding as P, type TaskState as T, UnreplayableLogError as U, type WorkflowImportOptions as W, type ImportedChart as a, type LaneStatus as b, type ImportedEdge as c, type ImportedNode as d, type ImportedPhase as e, type LeafStates as f, type PhaseStand as g, type TimelineStep as h, WorkflowImportError as i, bareEvent as j, chartFromWorkflow as k, chartFromWorkflowText as l, deriveLaneStatus as m, endPolarityOf as n, eventAlphabet as o, foldLane as p, initialOf as q, initialStates as r, laneTerminalReached as s, originOf as t, parseEventsJsonl as u, parseHistoryJson as v, parseStatusJson as w, phaseStandings as x, statesOf as y, stepTask as z };