@rxova/journey-core 1.0.0-rc.3 → 1.0.1

package/dist/core/types.d.ts

@@ -0,0 +1,481 @@
+/**
+ * Shared core contracts for `@rxova/journey-core`.
+ *
+ * The machine object holds only stable methods; every piece of changing state
+ * lives in an immutable {@link JourneySnapshot} rebuilt at defined emission
+ * points (navigation accepted → commit → settle, plus lifecycle and context
+ * changes) and delivered to subscribers.
+ */
+import type { JourneyStorage } from "../plugins/persistence/persistence.types.js";
+/** Journey lifecycle status (meta-state-machine, enforced in core). */
+export type JourneyStatus = "idle" | "running" | "paused" | "completed" | "terminated";
+/** An event declaration: discriminated union member `{ type; payload? }`. */
+export type JourneyEventObject = {
+    readonly type: string;
+    readonly payload?: unknown;
+};
+/** Extracts the payload type of event `TType` from a declared event union. */
+export type JourneyEventPayload<TEvents extends JourneyEventObject, TType extends TEvents["type"]> = Extract<TEvents, {
+    type: TType;
+}> extends {
+    payload: infer P;
+} ? P : undefined;
+/**
+ * Why a navigation was rejected.
+ *
+ * - `error` — navigation work threw, rejected, timed out, or failed to commit.
+ * - `transitioning` — another navigation's hook chain is still pending.
+ * - `not-running` — the machine is idle, paused, completed, or terminated.
+ * - `invalid-target` — unknown step id, or (graph) no transition targets it.
+ * - `no-enabled-transition` — the event matched no enabled candidate.
+ * - `out-of-bounds` — timeline move past its edge (back at index 0, forward at tip).
+ * - `no-op` — navigation to the current position.
+ * - `disposed` — the machine was disposed; all methods are safe no-ops.
+ */
+export type NavigationFailureReason = "error" | "transitioning" | "not-running" | "invalid-target" | "no-enabled-transition" | "out-of-bounds" | "no-op" | "disposed";
+/**
+ * Result of every navigation verb (and of graph `send`).
+ *
+ * The failure arm carries `from`/`to` so a caller awaiting the result can log
+ * *which* target was rejected without also subscribing to `navigationBlocked`.
+ * `to` is null when the machine never resolved one — a graph `send` with no
+ * enabled candidate, for instance.
+ */
+export type NavigationResult<TStepId extends string = string> = {
+    readonly ok: true;
+    readonly from: TStepId | null;
+    readonly to: TStepId;
+} | {
+    readonly ok: false;
+    readonly reason: NavigationFailureReason;
+    readonly from: TStepId | null;
+    readonly to: TStepId | null;
+    readonly error?: unknown;
+};
+/** Journey outcome recorded by `complete(payload?)` / `terminate(payload?)`. */
+export type JourneyOutcome<TCompletePayload = unknown, TTerminatePayload = unknown> = {
+    readonly type: "completed";
+    readonly payload: TCompletePayload | undefined;
+} | {
+    readonly type: "terminated";
+    readonly payload: TTerminatePayload | undefined;
+};
+/** Machine-level async transition state (a snapshot source of truth). */
+export type TransitionState<TStepId extends string = string> = {
+    readonly pending: boolean;
+    readonly phase: "working" | "leaving" | "entering" | null;
+    readonly from: TStepId | null;
+    readonly to: TStepId | null;
+};
+/** Async state of the current navigation work or lifecycle effect chain. */
+export type StepAsyncState = {
+    readonly isLoading: boolean;
+    readonly isSuccess: boolean;
+    readonly isError: boolean;
+    readonly error: unknown | null;
+};
+/** Fields present on `currentStep` for every journey kind. */
+export type CurrentStepBase<TStepId extends string, TMeta> = {
+    readonly id: TStepId;
+    readonly metadata: TMeta;
+    /** True while this is the first ever entry of the step in this run. */
+    readonly isFirstTimeVisit: boolean;
+    readonly async: StepAsyncState;
+};
+/** Browser-like timeline state shared by every journey kind. */
+export type JourneyHistoryState<TStepId extends string> = {
+    readonly timeline: readonly TStepId[];
+    /** Pointer into `timeline`; -1 while idle. */
+    readonly currentIndex: number;
+    readonly visited: Readonly<Record<TStepId, boolean>>;
+    readonly canGoBack: boolean;
+    readonly canGoForward: boolean;
+};
+/**
+ * How the run ended, once it has.
+ *
+ * This used to also carry six derived booleans — `isLoading` and one per
+ * status. They were each another spelling of something the snapshot already
+ * said: the five status flags were `status === x`, and `isLoading` was
+ * `transition.pending` computed a second time. `outcome` is the only value here
+ * that is not derivable from another field.
+ */
+export type MachineState<TCompletePayload = unknown, TTerminatePayload = unknown> = {
+    readonly outcome: JourneyOutcome<TCompletePayload, TTerminatePayload> | null;
+};
+/** Fields shared by every snapshot kind (discriminated on `type`). */
+export type JourneySnapshotBase<TContext, TStepId extends string, TMeta, TCompletePayload = unknown, TTerminatePayload = unknown> = {
+    readonly status: JourneyStatus;
+    readonly context: TContext;
+    readonly transition: TransitionState<TStepId>;
+    readonly history: JourneyHistoryState<TStepId>;
+    readonly machine: MachineState<TCompletePayload, TTerminatePayload>;
+    readonly plugins: Readonly<Record<string, unknown>>;
+    readonly currentStep: CurrentStepBase<TStepId, TMeta> | null;
+};
+/** Linear snapshots carry declared-order derivations; graph fields don't exist. */
+export type LinearSnapshot<TContext, TStepId extends string, TMeta, TCompletePayload = unknown, TTerminatePayload = unknown> = Omit<JourneySnapshotBase<TContext, TStepId, TMeta, TCompletePayload, TTerminatePayload>, "currentStep"> & {
+    readonly type: "linear";
+    readonly currentStep: (CurrentStepBase<TStepId, TMeta> & {
+        /** Index in declared order. */
+        readonly index: number;
+        readonly isFirstStep: boolean;
+        readonly isLastStep: boolean;
+    }) | null;
+    readonly steps: {
+        readonly totalSteps: number;
+        readonly stepOrder: readonly TStepId[];
+        readonly visitedStepCount: number;
+    };
+};
+/** Guard evaluation recorded for an outgoing graph transition candidate. */
+export type GraphGuardState = "none" | "passed" | "failed";
+/** Serializable routing state for one candidate declared from the current graph step. */
+export type GraphTransitionSnapshot<TStepId extends string, TEventType extends string> = {
+    /** Event that evaluates this candidate. */
+    readonly event: TEventType;
+    /** Candidate destination. */
+    readonly to: TStepId;
+    /** Zero-based declaration order among candidates for the same event. */
+    readonly priority: number;
+    /** Current result of the candidate's guard, or `none` when no guard is declared. */
+    readonly guard: GraphGuardState;
+    /** Whether the candidate's guard currently permits routing. */
+    readonly enabled: boolean;
+    /** Whether sending this event would select this candidate under first-enabled semantics. */
+    readonly selected: boolean;
+};
+/** Graph snapshots carry declared and enabled transition derivations; order fields don't exist. */
+export type GraphSnapshot<TContext, TStepId extends string, TMeta, TEvents extends JourneyEventObject = JourneyEventObject, TCompletePayload = unknown, TTerminatePayload = unknown> = Omit<JourneySnapshotBase<TContext, TStepId, TMeta, TCompletePayload, TTerminatePayload>, "currentStep"> & {
+    readonly type: "graph";
+    readonly currentStep: (CurrentStepBase<TStepId, TMeta> & {
+        /** No outgoing transitions are defined from this step. */
+        readonly isTerminal: boolean;
+    }) | null;
+    readonly steps: {
+        readonly totalSteps: number;
+        readonly visitedStepCount: number;
+    };
+    /** Event names declared by outgoing candidates from the current step. */
+    readonly declaredEvents: readonly TEvents["type"][];
+    /** Events with at least one enabled candidate from the current step. */
+    readonly availableEvents: readonly TEvents["type"][];
+    /** Targets of enabled candidates from the current step. */
+    readonly availableSteps: readonly TStepId[];
+    /** Guard and selection state for every outgoing candidate from the current step. */
+    readonly outgoingTransitions: readonly GraphTransitionSnapshot<TStepId, TEvents["type"]>[];
+};
+export type JourneySnapshot<TContext = unknown, TStepId extends string = string, TMeta = unknown, TEvents extends JourneyEventObject = JourneyEventObject, TCompletePayload = unknown, TTerminatePayload = unknown> = LinearSnapshot<TContext, TStepId, TMeta, TCompletePayload, TTerminatePayload> | GraphSnapshot<TContext, TStepId, TMeta, TEvents, TCompletePayload, TTerminatePayload>;
+/** Context updater used by `machine.context.update` and hook args. */
+export type ContextUpdater<TContext> = (previous: TContext) => TContext;
+/**
+ * Which edge a hook is running for.
+ *
+ * `event` and `to` alone do not identify it: several candidates on one event
+ * can share a target and differ only by guard. `label` is the edge's declared
+ * name; `index` is its position among the candidates the origin step declares
+ * for that event, so an anonymous edge is still identifiable.
+ */
+export type TransitionInfo = {
+    readonly event: string;
+    readonly from: string;
+    readonly to: string;
+    readonly label: string | null;
+    readonly index: number;
+};
+/**
+ * Arguments passed to step hooks.
+ *
+ * `event` is the graph event that caused the transition; `null` for timeline
+ * moves, linear navigation, and the initial entry on `start()`.
+ * Hooks run after navigation commits. Context updates made inside hooks apply
+ * immediately and are side effects; hook failures never roll navigation back.
+ */
+export type StepHookArgs<TContext, TStepId extends string, TEvents extends JourneyEventObject = never, TSnap = JourneySnapshot<TContext, TStepId>> = {
+    readonly snapshot: TSnap;
+    readonly from: TStepId | null;
+    readonly to: TStepId;
+    readonly event: TEvents | null;
+    /**
+     * The edge that caused this move, or `null` for timeline moves, linear
+     * navigation, and the initial entry. Present on every step hook, not just
+     * `onTransition`, so `onEnter` can tell which candidate routed into it.
+     */
+    readonly transition: TransitionInfo | null;
+    readonly updateContext: (updater: ContextUpdater<TContext>) => void;
+    /**
+     * Queues an event for processing after the current transition fully settles
+     * (FIFO). Only meaningful on graph journeys; linear hooks receive a no-op.
+     */
+    readonly raise: (event: TEvents) => void;
+};
+/** `onLeave` is an awaited post-commit side effect and cannot block navigation. */
+export type OnLeaveHook<TContext, TStepId extends string, TEvents extends JourneyEventObject = never, TSnap = JourneySnapshot<TContext, TStepId>> = (args: StepHookArgs<TContext, TStepId, TEvents, TSnap>) => void | Promise<void>;
+/** `onEnter` is an awaited post-commit side effect and cannot block navigation. */
+export type OnEnterHook<TContext, TStepId extends string, TEvents extends JourneyEventObject = never, TSnap = JourneySnapshot<TContext, TStepId>> = (args: StepHookArgs<TContext, TStepId, TEvents, TSnap>) => void | Promise<void>;
+/**
+ * Completion and termination payload types supplied to a journey factory.
+ *
+ * Shared by both tiers: linear takes it as a generic parameter, graph names it
+ * through the definition's `$payloads` phantom carrier.
+ */
+export type JourneyTerminationPayloads = {
+    readonly complete?: unknown;
+    readonly terminate?: unknown;
+};
+export type CompletePayloadOf<TTypes extends JourneyTerminationPayloads> = TTypes extends {
+    readonly complete: infer TPayload;
+} ? TPayload : unknown;
+export type TerminatePayloadOf<TTypes extends JourneyTerminationPayloads> = TTypes extends {
+    readonly terminate: infer TPayload;
+} ? TPayload : unknown;
+/** Subscription event names. */
+export type JourneySubscriptionEvent = "stepEnter" | "stepLeave" | "statusChange" | "contextChange" | "navigationBlocked" | "error";
+export type JourneyEventPayloads<TContext, TStepId extends string, TSnap = JourneySnapshot<TContext, TStepId>> = {
+    stepEnter: {
+        readonly snapshot: TSnap;
+        readonly from: TStepId | null;
+        readonly to: TStepId;
+        readonly direction: StepEnterDirection;
+    };
+    stepLeave: {
+        readonly snapshot: TSnap;
+        readonly from: TStepId;
+        readonly to: TStepId;
+    };
+    statusChange: {
+        readonly snapshot: TSnap;
+        readonly previous: JourneyStatus;
+        readonly current: JourneyStatus;
+    };
+    contextChange: {
+        readonly snapshot: TSnap;
+        readonly previous: TContext;
+        readonly current: TContext;
+    };
+    navigationBlocked: {
+        readonly snapshot: TSnap;
+        readonly reason: NavigationFailureReason;
+        readonly from: TStepId | null;
+        readonly to: TStepId | null;
+        readonly error?: unknown;
+    };
+    error: {
+        readonly snapshot: TSnap;
+        readonly error: unknown;
+        /** Which pipeline stage threw. */
+        readonly phase: "work" | "leave" | "enter" | "transition" | "raise";
+        readonly stepId: TStepId | null;
+    };
+};
+export type Unsubscribe = () => void;
+export type JourneySubscriptions<TContext, TStepId extends string, TSnap = JourneySnapshot<TContext, TStepId>> = {
+    /**
+     * Fires on every committed snapshot; read the current one with
+     * `getSnapshot()`. Deriving a slice and skipping unchanged values belongs to
+     * the caller — React's `useSelector` owns that comparison because it must
+     * anyway, to keep render identity stable.
+     */
+    subscribe(listener: () => void): Unsubscribe;
+    subscribeEvent<TEvent extends JourneySubscriptionEvent>(event: TEvent, listener: (payload: JourneyEventPayloads<TContext, TStepId, TSnap>[TEvent]) => void): Unsubscribe;
+};
+/**
+ * Lifecycle verbs. Each returns `true` when the lifecycle change applied and
+ * `false` when rejected (wrong source status, pending transition, disposed).
+ */
+export type JourneyControls<TCompletePayload = unknown, TTerminatePayload = unknown> = {
+    /** idle → running; enters the first/initial step. */
+    start(): boolean;
+    /** running → paused; navigation is rejected while paused. */
+    pause(): boolean;
+    /** paused → running. */
+    resume(): boolean;
+    /** running → completed. Explicit only — never fired by navigation. */
+    complete(payload?: TCompletePayload): boolean;
+    /** any → terminated. Wins over a pending transition. */
+    terminate(payload?: TTerminatePayload): boolean;
+    /** completed | terminated → running; resets timeline + context to initial. */
+    restart(): boolean;
+};
+export type NavigationDirection = "forward" | "backward";
+/**
+ * How a step was entered, by intent rather than index math: only
+ * `goToNextStep`/`goToPreviousStep` report `"forward"`/`"backward"`; the
+ * initial entry, absolute verbs (`goToStepById`, `goToStepByIndex`,
+ * `goToLastVisitedStep`), and graph `send` report `"jump"`.
+ */
+export type StepEnterDirection = NavigationDirection | "jump";
+/** Read-only arguments for work that must succeed before navigation commits. */
+export type NavigationWorkArgs<TStepId extends string, TSnap> = {
+    readonly snapshot: TSnap;
+    readonly from: TStepId;
+    readonly to: TStepId;
+    readonly direction: NavigationDirection;
+};
+/**
+ * Transactional work attached to next/previous navigation.
+ *
+ * `run` is awaited before movement. If it throws, rejects, or times out, the
+ * machine stays on the current step. `commit` runs synchronously after `run`
+ * succeeds; its context updates are staged and published atomically with the
+ * position change.
+ */
+export type NavigationWork<TContext, TStepId extends string, TSnap, TResult = void> = {
+    readonly run: (args: NavigationWorkArgs<TStepId, TSnap>) => TResult | Promise<TResult>;
+    readonly commit?: (args: NavigationWorkArgs<TStepId, TSnap> & {
+        readonly result: TResult;
+        readonly updateContext: (updater: ContextUpdater<TContext>) => void;
+    }) => void;
+    /**
+     * Budget for this `run`, overriding `defaultTimeoutMs`. Left unset, the
+     * global default applies; set it when this one call is slower than the rest.
+     */
+    readonly timeoutMs?: number;
+};
+export type JourneyNavigation<TContext, TStepId extends string, TSnap> = {
+    goToStepById(id: TStepId): Promise<NavigationResult<TStepId>>;
+    /** Timeline pointer back `n`; clamps to start; fails only at index 0. */
+    goToPreviousStep(n?: number): Promise<NavigationResult<TStepId>>;
+    /** Timeline forward; linear falls back to next-in-declared-order at tip. */
+    goToNextStep<TResult = void>(work?: NavigationWork<TContext, TStepId, TSnap, TResult>): Promise<NavigationResult<TStepId>>;
+    /** Pointer → timeline tip; fails if already there. */
+    goToLastVisitedStep(): Promise<NavigationResult<TStepId>>;
+};
+/** Machine surface shared by linear and graph journeys. */
+export type JourneyMachineBase<TContext, TStepId extends string, TSnap = JourneySnapshot<TContext, TStepId>, TCompletePayload = unknown, TTerminatePayload = unknown> = {
+    getSnapshot(): TSnap;
+    controls: JourneyControls<TCompletePayload, TTerminatePayload>;
+    navigate: JourneyNavigation<TContext, TStepId, TSnap>;
+    subscriptions: JourneySubscriptions<TContext, TStepId, TSnap>;
+    context: {
+        update(updater: ContextUpdater<TContext>): void;
+    };
+    async: {
+        clearError(): void;
+    };
+    /** Irreversible teardown: drops listeners; all methods become safe no-ops. */
+    dispose(): void;
+};
+/** A read-only structural view of the running definition, for analysis plugins. */
+export type JourneyStructure = {
+    readonly kind: "linear" | "graph";
+    readonly stepIds: readonly string[];
+    readonly initial: string;
+    /** Flattened transitions in declaration order (empty for linear). */
+    readonly transitions: readonly {
+        readonly event: string;
+        readonly from: string;
+        readonly to: string;
+        readonly guarded: boolean;
+        /** The edge's declared name, or `null` when it was left anonymous. */
+        readonly label: string | null;
+        /** Position among the candidates this step declares for this event. */
+        readonly index: number;
+    }[];
+};
+/** Observe-only taps + reads — no interception in v1. */
+export type PluginHost<TContext = unknown, TStepId extends string = string> = {
+    getSnapshot(): JourneySnapshot<TContext, TStepId>;
+    readonly structure: JourneyStructure;
+    /** Fires after commit + settle of every successful navigation (incl. initial entry). */
+    onTransition(callback: (info: {
+        readonly from: TStepId | null;
+        readonly to: TStepId;
+        readonly snapshot: JourneySnapshot<TContext, TStepId>;
+    }) => void): Unsubscribe;
+    onNavigationBlocked(callback: (info: JourneyEventPayloads<TContext, TStepId>["navigationBlocked"]) => void): Unsubscribe;
+    onStatusChange(callback: (info: JourneyEventPayloads<TContext, TStepId>["statusChange"]) => void): Unsubscribe;
+    onContextChange(callback: (info: JourneyEventPayloads<TContext, TStepId>["contextChange"]) => void): Unsubscribe;
+    onError(callback: (info: JourneyEventPayloads<TContext, TStepId>["error"]) => void): Unsubscribe;
+    onDispose(callback: () => void): void;
+    /**
+     * Routes a plugin's own failure to the machine's `onListenerError`.
+     *
+     * A plugin tap that throws synchronously is already isolated and reported.
+     * Work that outlives the tap — an awaited storage write, a debounced flush —
+     * has no such path, and would otherwise have to choose between an unhandled
+     * rejection and a `console.error` that ignores the configured reporter.
+     */
+    reportError(error: unknown): void;
+};
+/**
+ * A journey plugin: observes via {@link PluginHost} taps and extends the
+ * machine (`machine.plugins[name]`) and snapshot (`snapshot.plugins[name]`).
+ * Extensions are always namespaced, never merged into core fields.
+ */
+export type JourneyPlugin<TName extends string = string, TApi = unknown, TSnapExt = unknown> = {
+    readonly name: TName;
+    setup(host: PluginHost): {
+        api?: TApi;
+        deriveSnapshot?: (snapshot: JourneySnapshot, previousExtension: TSnapExt | undefined) => TSnapExt;
+    };
+};
+/**
+ * Variance-friendly plugin bound: `deriveSnapshot`'s `previousExtension`
+ * parameter is contravariant, so concrete `JourneyPlugin<N, Api, Ext>` types
+ * are not assignable to bare `JourneyPlugin`. Constraints use this instead.
+ */
+export type AnyJourneyPlugin = {
+    readonly name: string;
+    setup(host: PluginHost): {
+        api?: unknown;
+        deriveSnapshot?: (snapshot: JourneySnapshot, previousExtension: never) => unknown;
+    };
+};
+/** Maps a plugin tuple to the `machine.plugins` record. */
+export type PluginApis<TPlugins extends readonly AnyJourneyPlugin[]> = {
+    readonly [P in TPlugins[number] as P["name"]]: P extends JourneyPlugin<string, infer TApi, infer TSnapExt> ? TApi : never;
+};
+/** Sugar over the persistence plugin, expanded at creation. */
+export type JourneyPersistOption = {
+    readonly key: string;
+    /** Defaults to `globalThis.localStorage`; creation throws when neither is available. */
+    readonly storage?: JourneyStorage;
+};
+/** Runtime options shared by linear and graph journeys. */
+export type JourneyRuntimeOptions<TPlugins extends readonly AnyJourneyPlugin[] = readonly [], TStepId extends string = string> = {
+    /**
+     * Defaults to `true`: creating a journey starts it, so the common case needs
+     * no second call.
+     *
+     * The trade this makes, stated plainly because it cannot be worked around:
+     * starting happens inside the constructor and the initial entry commits
+     * synchronously, so the first `stepEnter` has already fired by the time the
+     * factory returns. A subscriber attached afterwards cannot see it.
+     *
+     * Pass `false` when that first event matters — it is the subscribe-then-start
+     * order, and saying so out loud is better than a default that silently
+     * assumes it:
+     *
+     * ```ts
+     * const machine = createLinearJourney(definition, { autoStart: false });
+     * machine.subscriptions.subscribeEvent("stepEnter", onEnter);
+     * machine.controls.start();
+     * ```
+     */
+    autoStart?: boolean;
+    /**
+     * Start (and restart) directly at this step instead of the first/initial
+     * one: only the target's `onEnter` fires, earlier steps are neither entered
+     * nor visited, and the timeline begins as `[startAt]`. An unknown id throws
+     * at creation.
+     */
+    startAt?: TStepId;
+    /**
+     * Expands into the persistence plugin, prepended to `plugins`. Combining it
+     * with an explicit persistence plugin fails as a duplicate plugin name.
+     */
+    persist?: JourneyPersistOption;
+    /**
+     * Applied to navigation work and every async hook invocation. Work timeouts
+     * block movement; post-commit hook timeouts surface as step errors.
+     */
+    defaultTimeoutMs?: number;
+    /**
+     * Called when a subscriber (selector or event listener) throws. Listener
+     * failures are always isolated — this hook only routes the report. Defaults
+     * to a `console.error`; a throwing reporter falls back to that default.
+     */
+    onListenerError?: (error: unknown) => void;
+    plugins?: TPlugins;
+};

package/dist/diagnostics/diagnostics.helpers.d.cts

@@ -0,0 +1,17 @@
+import type { DiagnosticsResult } from "./diagnostics.types.js";
+/**
+ * Structural analysis of a graph definition: unreachable steps, shadowed
+ * transitions (an earlier unguarded candidate on the same `(from, event)`
+ * always wins), cycles, and terminal-path existence. Completion is explicit in
+ * this model, so terminal steps are reported as facts in the summary, not as
+ * dead-end issues.
+ *
+ * A plain function over the definition rather than a plugin over a machine.
+ * Nothing here needs a runtime — it is the definition that is being checked —
+ * so this runs in a test or a build step, before any machine exists. Linear
+ * journeys have no transition graph and so nothing to analyze.
+ */
+export declare function analyzeStructure(definition: {
+    readonly steps: object;
+    readonly initial: string;
+}): DiagnosticsResult;

package/dist/diagnostics/diagnostics.helpers.d.ts

@@ -0,0 +1,17 @@
+import type { DiagnosticsResult } from "./diagnostics.types.js";
+/**
+ * Structural analysis of a graph definition: unreachable steps, shadowed
+ * transitions (an earlier unguarded candidate on the same `(from, event)`
+ * always wins), cycles, and terminal-path existence. Completion is explicit in
+ * this model, so terminal steps are reported as facts in the summary, not as
+ * dead-end issues.
+ *
+ * A plain function over the definition rather than a plugin over a machine.
+ * Nothing here needs a runtime — it is the definition that is being checked —
+ * so this runs in a test or a build step, before any machine exists. Linear
+ * journeys have no transition graph and so nothing to analyze.
+ */
+export declare function analyzeStructure(definition: {
+    readonly steps: object;
+    readonly initial: string;
+}): DiagnosticsResult;

package/dist/diagnostics/diagnostics.types.d.cts

@@ -0,0 +1,22 @@
+export type DiagnosticsIssue = {
+    readonly code: "unreachable-step" | "shadowed-transition" | "cycle-detected" | "no-terminal-path";
+    readonly severity: "warning" | "error";
+    readonly message: string;
+    readonly stepId?: string;
+    readonly from?: string;
+    readonly event?: string;
+    readonly steps?: readonly string[];
+};
+export type DiagnosticsResult = {
+    readonly issues: readonly DiagnosticsIssue[];
+    readonly summary: {
+        readonly stepCount: number;
+        readonly reachableStepCount: number;
+        readonly unreachableStepCount: number;
+        /** Steps with no defined outgoing transitions (legal rest points). */
+        readonly terminalStepIds: readonly string[];
+        readonly cycleCount: number;
+        readonly shadowedTransitionCount: number;
+        readonly terminalPathExists: boolean;
+    };
+};

package/dist/diagnostics/diagnostics.types.d.ts

@@ -0,0 +1,22 @@
+export type DiagnosticsIssue = {
+    readonly code: "unreachable-step" | "shadowed-transition" | "cycle-detected" | "no-terminal-path";
+    readonly severity: "warning" | "error";
+    readonly message: string;
+    readonly stepId?: string;
+    readonly from?: string;
+    readonly event?: string;
+    readonly steps?: readonly string[];
+};
+export type DiagnosticsResult = {
+    readonly issues: readonly DiagnosticsIssue[];
+    readonly summary: {
+        readonly stepCount: number;
+        readonly reachableStepCount: number;
+        readonly unreachableStepCount: number;
+        /** Steps with no defined outgoing transitions (legal rest points). */
+        readonly terminalStepIds: readonly string[];
+        readonly cycleCount: number;
+        readonly shadowedTransitionCount: number;
+        readonly terminalPathExists: boolean;
+    };
+};

package/dist/graph/bag.types.d.cts

@@ -0,0 +1,91 @@
+import type { GraphOnEntry, GraphStepConfig } from "./graph.types.js";
+import type { JourneyEventObject } from "../core/types.js";
+/**
+ * One declaration point for a journey's types.
+ *
+ * Two things need it. Steps authored in separate files have to name the shape
+ * they satisfy, and `withTypes` needs somewhere to pin types that the
+ * definition cannot infer on its own. Everything except `context`, `stepId`
+ * and `events` is optional and falls back.
+ */
+export type Bag = {
+    context: unknown;
+    stepId: string;
+    events: JourneyEventObject;
+    meta?: unknown;
+    handlers?: unknown;
+    /**
+     * Result type per event name, for events declaring `run`.
+     *
+     * Load-bearing rather than a convenience: a declared `run` sits at a property
+     * position, which is not an inference site, so `commit`'s `result` is
+     * `unknown` unless it is pinned here. One result type per event name — not
+     * per (step, event) pair.
+     */
+    results?: Record<string, unknown>;
+};
+/**
+ * `meta`, `handlers` and `results` are optional on the bag, so these must infer
+ * from an optional property. Matching `{ meta: infer T }` — a *required*
+ * property — silently skipped anyone who mirrored the constraint and wrote
+ * `meta?: MyMeta`: they got the fallback instead of their own type, and the
+ * eventual error pointed nowhere near the bag declaration. `NonNullable` strips
+ * the `undefined` that optionality adds.
+ */
+export type MetaOf<TBag extends Bag> = TBag extends {
+    meta?: infer TMeta;
+} ? [TMeta] extends [undefined] ? Record<string, unknown> : NonNullable<TMeta> : Record<string, unknown>;
+export type HandlersOf<TBag extends Bag> = TBag extends {
+    handlers?: infer THandlers;
+} ? [THandlers] extends [undefined] ? Record<string, never> : NonNullable<THandlers> : Record<string, never>;
+export type ResultsOf<TBag extends Bag> = TBag extends {
+    results?: infer TResults;
+} ? [TResults] extends [undefined] ? Record<string, never> : NonNullable<TResults> : Record<string, never>;
+/**
+ * The declared result for one event, or `unknown` when the bag pins none.
+ *
+ * The empty-default check comes first and is load-bearing: `ResultsOf` falls
+ * back to `Record<string, never>`, whose `keyof` is `string`, so without it
+ * every event name "matches" and resolves to `never` — which rejects every
+ * `run` rather than accepting any.
+ */
+export type ResultOf<TBag extends Bag, TType extends string> = [ResultsOf<TBag>] extends [
+    Record<string, never>
+] ? unknown : TType extends keyof ResultsOf<TBag> ? ResultsOf<TBag>[TType] : unknown;
+/**
+ * One step's config for a pinned bag — what a step authored in its own file
+ * annotates itself with.
+ *
+ * ```ts
+ * export const loginStep: GraphStep<AuthBag> = {
+ *   metadata: { label: "Login" },
+ *   on: { submit: "twofa" }
+ * };
+ * ```
+ */
+export type GraphStep<TBag extends Bag> = Omit<GraphStepConfig<TBag["context"], TBag["stepId"], TBag["events"], MetaOf<TBag>, HandlersOf<TBag>>, "on"> & {
+    readonly on?: {
+        readonly [TType in TBag["events"]["type"]]?: GraphOnEntry<TBag["context"], TBag["stepId"], TBag["events"], HandlersOf<TBag>, MetaOf<TBag>, ResultOf<TBag, TType>, Extract<TBag["events"], {
+            type: TType;
+        }>>;
+    };
+};
+/**
+ * A whole graph definition for a pinned bag, for the case `withTypes` cannot
+ * express: a standalone definition passed to the factory more than once, with
+ * different options each time.
+ *
+ * ```ts
+ * export const definition = {
+ *   initial: "login",
+ *   context: initialContext,
+ *   steps: { login: { on: { submit: "twofa" } }, twofa: {} }
+ * } satisfies GraphDefinition<AuthBag>;
+ * ```
+ */
+export type GraphDefinition<TBag extends Bag> = {
+    readonly initial: TBag["stepId"];
+    readonly context: TBag["context"];
+    readonly handlers?: HandlersOf<TBag>;
+    readonly steps: Readonly<Record<TBag["stepId"], GraphStep<TBag>>>;
+};