@demlik/tea 0.6.0 → 0.8.0

package/dist/chart/lane/index.d.ts

@@ -0,0 +1,361 @@
+import { g as EventPreview, d as ChartRefusal, I as InspectOptions, U as Unanswerable } from '../../reducer-BqyoVyBG.js';
+import { P as PhaseStanding, I as ImportedLane, L as LogEntry, T as TaskState } from '../../fold-Blbhru48.js';
+export { c as Lane, d as LaneChecks, e as LaneCmd, f as LaneErrorFinals, g as LaneHand, h as LaneHands, b as LaneHandsOf, i as LaneInitial, j as LaneMsg, k as LaneOf, l as LanePhaseName, m as LanePhaseOf, n as LanePhaseShape, o as LaneRegion, p as LaneRegions, q as LaneRunChecks, r as LaneRunMsg, s as LaneRunState, t as LaneRuntime, u as LaneShape, v as LaneShapeError, w as LaneSiblings, x as LaneSpec, y as LaneState, z as LaneSuccessFinals, a as LaneTaskChart, L as LaneTaskId, A as LaneTaskShape, B as LaneTasksIn, C as LaneTerminal, P as PhaseAtRest, D as defineLane, E as laneShape, F as runLane } from '../../run-BVeqJDBF.js';
+import '../../graph-CcjWZVrd.js';
+import '../../core-Bjc0bS8j.js';
+import '../../samples-DCt6nF8H.js';
+import '../index.js';
+
+/** Why a task cannot move. `null` when it can. */
+type StuckReason = {
+    /** It reached an error final: as finished as a shipped task, and lost. */
+    readonly kind: "tripped";
+    readonly state: string;
+} | {
+    /**
+     * A non-final state that routes NOTHING. The chart's totality means this
+     * cannot happen on a chart that compiled — it is reported rather than
+     * swallowed because reaching it means a document declared a dead end, and
+     * a lane parked there will sit forever with no one to say why.
+     */
+    readonly kind: "dead-end";
+    readonly state: string;
+} | {
+    /** The retry budget is spent: the next guarded event is a one-way door. */
+    readonly kind: "budget-spent";
+    readonly state: string;
+    readonly event: string;
+    readonly landsOn: string;
+} | {
+    /**
+     * Every event this state routes comes from the OUTSIDE WORLD — no `cmd`
+     * result and no `sub` will ever arrive here, so the lane advances only
+     * when a person acts.
+     *
+     * This is the fourth kind, and it was missing until a real epic was
+     * rendered and looked at: a task parked at a human approval reported
+     * "nothing is stuck — every task can still move", which is true of the
+     * machine and false of the day. Nothing will happen until someone does
+     * something, which is precisely what a stuck list is for.
+     *
+     * Derived from `from`, never from a state name: `roles` carries the
+     * consumer's own words for who is owed, in declaration order.
+     */
+    readonly kind: "awaiting-world";
+    readonly state: string;
+    readonly roles: readonly string[];
+    readonly events: readonly string[];
+};
+/** One task of a lane, inspected. */
+interface LaneTaskInspection {
+    readonly task: string;
+    readonly phase: string;
+    /** The leaf it is in right now, out of the fold. */
+    readonly state: string;
+    /** `false` still running, `true` a success final, `"error"` tripped. */
+    readonly endPolarity: false | true | "error";
+    /** The state it will resume to, while it is parked. `undefined` otherwise. */
+    readonly was?: string;
+    readonly retries: number;
+    readonly maxRetries: number;
+    /**
+     * The events this state routes, grouped by who sends them — {@link waitingOn},
+     * read rather than recomputed. `null` at a final. On a lane imported without
+     * a provenance map it degrades to the events alone, and says so.
+     */
+    readonly waitingOn: string | null;
+    readonly stuck: StuckReason | null;
+    /** Every event of this task's alphabet, legal or refused, with the reason. */
+    readonly events: readonly EventPreview[];
+    /** The refused half of {@link LaneTaskInspection.events}, pulled out. */
+    readonly refusals: readonly ChartRefusal[];
+    /** The legal half, as names — the button row. */
+    readonly legal: readonly string[];
+}
+/** One phase of a lane, inspected. */
+interface LanePhaseInspection {
+    readonly name: string;
+    readonly index: number;
+    readonly standing: PhaseStanding;
+    /** The phase's tasks, each inspected — running concurrently, all of them. */
+    readonly tasks: readonly LaneTaskInspection[];
+    /** The tasks in this phase sitting on an error final. */
+    readonly tripped: readonly string[];
+}
+/** A whole lane, as data a UI can build itself from. */
+interface LaneInspection {
+    readonly id?: string;
+    readonly status: "active" | "done";
+    /** The terminal it landed on, or `null` while it is still running. */
+    readonly terminal: string | null;
+    /** The phase running right now, or `null` once the lane has ended. */
+    readonly activePhase: string | null;
+    readonly phases: readonly LanePhaseInspection[];
+    /** Every task on an error final, lane-wide — fabrika's `context.errors`. */
+    readonly tripped: readonly string[];
+    /** Every task that cannot move, and why. The list a human is paged on. */
+    readonly stuck: readonly {
+        readonly task: string;
+        readonly reason: StuckReason;
+    }[];
+}
+/**
+ * A whole lane, inspected at the state its log folds to.
+ *
+ * ```ts
+ * const lane = chartFromWorkflow(JSON.parse(workflowJson));
+ * const view = inspectLane(lane, parseEventsJsonl(eventsJsonl));
+ * view.activePhase;            // "phase2"
+ * view.phases[1]?.tasks[0];    // state, waiting-on, legal events, refusals
+ * view.stuck;                  // what a human has to go and do
+ * ```
+ *
+ * Takes the LOG rather than a folded state, deliberately: the fold is pure over
+ * a prefix, so `inspectLane(lane, entries.slice(0, k))` is the exact view at
+ * step k and time travel costs a `slice`.
+ */
+declare function inspectLane(lane: ImportedLane, entries: readonly LogEntry[], optsFor?: (taskId: string) => InspectOptions): LaneInspection;
+/**
+ * The same view, from the LEAVES rather than from a log.
+ *
+ * The two callers differ in exactly one thing and it is which of these doors
+ * they come through. A reader holding `workflow.json` + `events.jsonl` has no
+ * states, so it folds — {@link inspectLane}. A reader watching a lane RUN has
+ * the states and no log worth folding: `runLane` boots each region where its
+ * sub-issue actually is, so re-deriving the leaves from a log that starts at
+ * every chart's `initial: true` would answer a different question than the one
+ * on screen. It hands the leaves it has.
+ *
+ * @param optsFor per-task {@link InspectOptions} — the `parts` bag and the
+ *   sample payloads, which only the LIVE door has. Omit it and every preview
+ *   degrades honestly, exactly as `inspectState` does with no bag at all.
+ */
+declare function inspectLaneStates(lane: ImportedLane, states: Readonly<Record<string, TaskState>>, optsFor?: (taskId: string) => InspectOptions): LaneInspection;
+
+/** A task's retry bookkeeping, when the source carries it. */
+interface RetryBudget {
+    readonly retries: number;
+    readonly maxRetries: number;
+}
+/**
+ * One event control, for one task.
+ *
+ * `send` is where the two sources part company, and it is a VALUE rather than a
+ * flag: the answer to "what would clicking this dispatch" is the msg itself, so
+ * a source that can answer it answers with the msg, and a source that cannot
+ * holds the reason. There is no third state and no boolean to get backwards.
+ */
+interface LaneControl {
+    readonly task: string;
+    readonly event: string;
+    /** `"legal"`, or the refusal's kind — the CSS hook, as in `<ChartInspector>`. */
+    readonly kind: string;
+    readonly refused: boolean;
+    /** The refusal's one-line explanation. Present iff refused. */
+    readonly why?: string;
+    /** Where this would land and what it would fire — the DECLARED answer. */
+    readonly outcome: string;
+    /** The msg a click dispatches, or why this source cannot offer one. */
+    readonly send: {
+        readonly type: string;
+    } | Unanswerable<"dispatch">;
+}
+/** One task of the lane, at the scrubbed moment. */
+interface LaneTaskView {
+    readonly task: string;
+    readonly phase: string;
+    readonly state: string;
+    readonly endPolarity: false | true | "error";
+    /**
+     * The state it resumes to — present ONLY while the task is actually parked.
+     * A region keeps `was` after it leaves the park, and rendering that made a
+     * finished task claim a return it cannot make.
+     */
+    readonly was?: string;
+    /** Grouped by who sends them — `report.ts`'s own derivation. `null` at a final. */
+    readonly waitingOn: string | null;
+    readonly stuck: StuckReason | null;
+    /**
+     * `false` while the task still sits at its chart's entry state.
+     *
+     * The editorial rule's input: a task that has not moved has a story one line
+     * long, and six of them side by side are six copies of one picture.
+     */
+    readonly moved: boolean;
+    readonly budget: RetryBudget | Unanswerable<"retries">;
+    readonly controls: readonly LaneControl[];
+    /** This region, drawn at this moment. See {@link draw}. */
+    readonly diagram: string;
+}
+/** One phase of the lane, at the scrubbed moment. */
+interface LanePhaseView {
+    readonly name: string;
+    readonly index: number;
+    readonly standing: PhaseStanding;
+    readonly tasks: readonly LaneTaskView[];
+    /** The tasks in this phase sitting on an error final. */
+    readonly tripped: readonly string[];
+    /**
+     * The tasks worth showing in full, by id — `report.ts`'s rule, applied.
+     *
+     * Only the ACTIVE phase expands anything: a finished phase's story is which
+     * ending each of its tasks reached, and a phase that never started has no
+     * story at all. Within the active phase, a task that has moved is expanded and
+     * a task still at its entry state is not — unless NOTHING in the phase has
+     * moved, in which case the first is the representative, because collapsing
+     * every task would leave the reader with no picture at all.
+     */
+    readonly expanded: readonly string[];
+}
+/** One step of the run, as the timeline table draws it. */
+interface LaneStepView {
+    readonly index: number;
+    readonly task: string;
+    /** The event VERBATIM — the source's own spelling. */
+    readonly event: string;
+    readonly from: string;
+    readonly to: string;
+    /** The edge that fired, keyed as the drawing keys it. */
+    readonly edge: string;
+    /**
+     * The msg arrived and NOTHING happened — the chart routes no such edge here.
+     *
+     * A total chart answers every msg, so a refused one is still a line in the
+     * log and still a step of the tape; it is just not a WALK. Left unmarked it
+     * reads as a real transition that happened to land where it started
+     * (`issue_1 DONE review → review`), which is the one row on the timeline a
+     * reader would take at face value and be wrong about.
+     */
+    readonly refused: boolean;
+}
+/** A whole lane, at one moment, ready to render. */
+interface LaneViewModel {
+    readonly source: "replay" | "live";
+    readonly title: string;
+    readonly status: "active" | "done";
+    /** The terminal it landed on, or `null` while it is still running. */
+    readonly terminal: string | null;
+    readonly activePhase: string | null;
+    /** Every task on an error final, lane-wide. */
+    readonly tripped: readonly string[];
+    /**
+     * WHICH OF TWELVE THINGS IS STUCK — the reader's first question, answered
+     * first. `inspectLane`'s own list, with the phase attached so the answer names
+     * a place as well as a task.
+     */
+    readonly stuck: readonly {
+        readonly task: string;
+        readonly phase: string;
+        readonly reason: StuckReason;
+    }[];
+    readonly phases: readonly LanePhaseView[];
+    /** Every step up to the cursor. */
+    readonly steps: readonly LaneStepView[];
+    /**
+     * When each step happened, indexed by step — or why this source cannot say.
+     *
+     * A fabrika log stamps every line. A recorded tape carries ORDER and nothing
+     * else, so the live source answers this with the reason rather than with a
+     * column of invented times.
+     */
+    readonly clock: readonly string[] | Unanswerable<"clock">;
+    readonly cursor: number;
+    readonly total: number;
+    /** `true` while the cursor is behind the present. */
+    readonly scrubbed: boolean;
+    /**
+     * Why THIS SOURCE can dispatch nothing at all — absent on a source that can.
+     *
+     * A fact about the source, so it is stated once by the source rather than
+     * scraped back off whichever control still happens to carry it. Scraping is
+     * what it used to be, and it went silent on exactly the lane that needed it
+     * most: on a finished lane every control is refused BY THE CHART, so the one
+     * sentence explaining why the whole page is dead had nowhere left to live.
+     */
+    readonly noDispatch?: Unanswerable<"dispatch">;
+}
+/** Every region's leaf, keyed by task. */
+type LaneLeaves = Readonly<Record<string, TaskState>>;
+/**
+ * What a lane view is fed. Two implementations, {@link replayFeed} and
+ * {@link liveFeed}, and the component branches on none of it.
+ */
+interface LaneFeed {
+    readonly kind: "replay" | "live";
+    readonly lane: ImportedLane;
+    /** How many steps have happened — the scrubber's extent. */
+    readonly total: number;
+    /** Every region's leaf after the first `n` steps. EXACT, on both sides. */
+    readonly leavesAt: (n: number) => LaneLeaves;
+    /** The steps, in order. */
+    readonly steps: readonly LaneStepView[];
+    /** {@link LaneViewModel.clock}. */
+    readonly clock: readonly string[] | Unanswerable<"clock">;
+    /** The retry budget, or why this source cannot state it. */
+    readonly budget: (task: string, leaves: LaneLeaves) => RetryBudget | Unanswerable<"retries">;
+    /** The `parts` bag and samples, per task. Absent where there are none. */
+    readonly optsFor?: (task: string) => InspectOptions;
+    /**
+     * What a click dispatches — or why this source offers no click.
+     *
+     * The task is a parameter because a lane's dispatch surface is addressed:
+     * `compile(chart, parts, taskId)` keys the table `${task}.${event}`, so the
+     * msg a control sends is the region's event WEARING its task. The preview's
+     * own `msg` is the bare one; namespacing it is the feed's job, once.
+     */
+    readonly send: (task: string, preview: EventPreview) => LaneControl["send"];
+    /** {@link LaneViewModel.noDispatch} — set it iff NO control of this source can be sent. */
+    readonly noDispatch?: Unanswerable<"dispatch">;
+}
+/**
+ * THE FABRIKA CASE: a lane plus the log it actually produced.
+ *
+ * Every field is the report module's own function. The scrubber is
+ * `foldLane(lane, entries.slice(0, n))`, which is not an approximation of the
+ * state at step n — it is the definition of it.
+ */
+declare function replayFeed(lane: ImportedLane, entries: readonly LogEntry[]): LaneFeed;
+/** A running region's leaf: a state name, plus whatever ctx that chart keeps. */
+type RunningLeaf = {
+    readonly type: string;
+} & Readonly<Record<string, unknown>>;
+/** What {@link liveFeed} needs from the runtime it is watching. */
+interface LiveFeedInput {
+    /**
+     * The regions after the first `n` recorded msgs, by PURE replay — `init` +
+     * `update` only, exactly as `<ChartInspector>`'s scrubber does it.
+     */
+    readonly regionsAt: (n: number) => Readonly<Record<string, RunningLeaf>>;
+    /** The recorded tape: `${task}.${event}` per step, in order. */
+    readonly msgs: readonly {
+        readonly type: string;
+    }[];
+    /** The `parts` bag and samples, per task — the hands the run was given. */
+    readonly optsFor?: (task: string) => InspectOptions;
+}
+/**
+ * THE RUNNING CASE: a lane under `runLane`, watched.
+ *
+ * The leaves come off the RUNTIME rather than off a fold, and that distinction
+ * is load-bearing: `runLane` boots each region where its sub-issue actually is,
+ * so a fold that started every task at its chart's `initial: true` would draw a
+ * different lane than the one running.
+ *
+ * The steps are derived from the same replay: `from` is the leaf before the msg
+ * and `to` is the leaf after, both exact, and the edge they walked is
+ * {@link walkedEdgeKey} — the fold's own answer, so the live drawing thickens
+ * the same edges the markdown would.
+ */
+declare function liveFeed(lane: ImportedLane, input: LiveFeedInput): LaneFeed;
+/**
+ * The lane at step `cursor`, as one value a view renders straight.
+ *
+ * ```ts
+ * const feed = replayFeed(chartFromWorkflow(document), parseEventsJsonl(log));
+ * const view = laneView(feed, feed.total);   // now
+ * const then = laneView(feed, 3);            // exactly after three events
+ * ```
+ */
+declare function laneView(feed: LaneFeed, cursor: number, title?: string): LaneViewModel;
+
+export { type LaneControl, type LaneFeed, type LaneInspection, type LaneLeaves, type LanePhaseInspection, type LanePhaseView, type LaneStepView, type LaneTaskInspection, type LaneTaskView, type LaneViewModel, type LiveFeedInput, type RetryBudget, type RunningLeaf, type StuckReason, inspectLane, inspectLaneStates, laneView, liveFeed, replayFeed };

package/dist/chart/lane/index.js

@@ -0,0 +1,9 @@
+export { LaneShapeError, defineLane, inspectLane, inspectLaneStates, laneShape, laneView, liveFeed, replayFeed, runLane } from '../../chunk-ZCL7SCBK.js';
+import '../../chunk-ZD6PNZBK.js';
+import '../../chunk-5KJKJOFC.js';
+import '../../chunk-E6GEDSF4.js';
+import '../../chunk-UOC2PL46.js';
+import '../../chunk-5EHLEUTL.js';
+import '../../chunk-B5VXOFMZ.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/chart/lane/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/chart/lane/react.d.ts

@@ -0,0 +1,83 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { a as Samples } from '../../samples-DCt6nF8H.js';
+import { I as ImportedLane, L as LogEntry } from '../../fold-Blbhru48.js';
+import { L as LaneTaskId, a as LaneTaskChart, b as LaneHandsOf } from '../../run-BVeqJDBF.js';
+import '../../graph-CcjWZVrd.js';
+import '../../core-Bjc0bS8j.js';
+import '../index.js';
+
+/**
+ * Everything `<LaneView>` needs, and it is the two files a fabrika lane IS.
+ *
+ * There is no prop for the phases, the tasks, the states, the standings, the
+ * terminal or what anything is waiting on: every one of those is derived from
+ * these two, and a prop restating one would be the fact said twice.
+ */
+interface LaneViewProps {
+    /** The lane. `chartFromWorkflow(document)` or `defineLane(spec)` — either door. */
+    readonly lane: ImportedLane;
+    /** Its event log — `parseEventsJsonl(...)` or `parseHistoryJson(...)`. */
+    readonly log: readonly LogEntry[];
+    /** Heading. Cosmetic — defaults to the document's own `id`. */
+    readonly title?: string;
+    /** Appended to the container's class list. */
+    readonly className?: string;
+}
+/**
+ * One sample bag per task, each typed by THAT task's chart.
+ *
+ * The one thing a lane genuinely cannot derive, and the only reason it is a
+ * prop: `ty<T>()` is `{}` at runtime, so a payload's shape is erased before any
+ * runtime code could read it. Optional per task, because a task whose events
+ * declare no payload has nothing to supply.
+ *
+ * WHAT A LANE LOSES, said here rather than found out. `defineLane` LOWERS its
+ * charts to the runtime-typed form the fold and the drawing share, and that form
+ * records which events a state routes and NOT which of them declare a payload.
+ * So no control is ever reported as blocked for want of a sample: a msg is built
+ * either way, with the sample merged in when one was given. Supply one where a
+ * guard reads a payload field, and the guard preview reads the field you meant.
+ */
+type LaneSamples<L> = {
+    readonly [T in LaneTaskId<L>]?: Samples<LaneTaskChart<L, T>>;
+};
+/**
+ * Everything `<LiveLaneView>` needs — the lane, and the hands `runLane` demands.
+ *
+ * `hands` is not a restatement of the lane: it is the code the lane deliberately
+ * does not own (each region's `parts`, and where each instance BOOTS, which an
+ * emitted epic decides per sub-issue). It is the same bag `runLane` takes, so
+ * an author passes the one they already built.
+ */
+interface LiveLaneViewProps<L, H, Ctx> {
+    readonly lane: L;
+    /** The parts and boot state per task — the same bag `runLane` demands. */
+    readonly hands: H;
+    /** One payload sample per event that declares one, per task. */
+    readonly samples?: LaneSamples<L>;
+    /** The runtime ctx. Omit for a lane whose regions read nothing from one. */
+    readonly ctx?: Ctx;
+    readonly title?: string;
+    readonly className?: string;
+}
+/**
+ * A lane that has already run, looked at: the REPLAY source.
+ *
+ * The scrubber folds a prefix of the real log, which is not an approximation of
+ * the state at step k but the definition of it (`fold.ts`), so dragging it
+ * backwards shows exactly what the driver would have printed at that moment.
+ * Nothing is dispatchable and every control says why.
+ */
+declare function LaneView(props: LaneViewProps): react_jsx_runtime.JSX.Element;
+/**
+ * The same page over a lane that is RUNNING — the LIVE source.
+ *
+ * It owns a runtime for its lifetime (`runLane`'s `init`/`update`, built into a
+ * `Machine` here rather than asked for, so the drawing and the runtime provably
+ * come from the same lane) and records it, so the scrubber time-travels by the
+ * same pure `replay` `<ChartInspector>`'s does: `init` + `update` only, never
+ * `interpret`, so dragging backwards cannot re-fire an effect.
+ */
+declare function LiveLaneView<L extends ImportedLane, const H extends LaneHandsOf<L, H>, Ctx = Record<never, never>>(props: LiveLaneViewProps<L, H, Ctx>): react_jsx_runtime.JSX.Element;
+
+export { type LaneSamples, LaneView, type LaneViewProps, LiveLaneView, type LiveLaneViewProps };