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

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

@@ -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>>>;
+};

package/dist/graph/graph.d.cts

@@ -0,0 +1,63 @@
+import type { RuntimeStep, RuntimeTransition } from "../core/runtime.types.js";
+import type { GraphJourneyMachine, GraphJourneyOptions, GraphStepConfig, LooseGraphDefinition } from "./graph.types.js";
+import type { AnySendWork } from "../core/runtime.types.js";
+import type { Bag, GraphDefinition, HandlersOf, MetaOf } from "./bag.types.js";
+import type { AnyJourneyPlugin, CompletePayloadOf, JourneyEventObject, JourneyTerminationPayloads, TerminatePayloadOf } from "../core/types.js";
+/**
+ * Flattens each step's colocated `on` into the runtime's flat transition list,
+ * in declaration order, and validates every target.
+ *
+ * Order is per step, then per event, then per candidate. That differs from the
+ * old central map's global per-event order, but only for the same event
+ * declared from two steps — and candidates are filtered by `from` before order
+ * is consulted, so the selected edge is unchanged. `first-enabled-in-declared-
+ * order` is asserted directly in graph.test.ts.
+ *
+ * `from` cannot dangle here: it is the key of the step that declares the entry.
+ */
+export declare function normalizeGraphDefinition(definition: LooseGraphDefinition): {
+    stepIds: string[];
+    steps: Record<string, RuntimeStep>;
+    transitions: RuntimeTransition[];
+    eventWork: Record<string, AnySendWork>;
+};
+/**
+ * Creates a graph journey runtime from a pure-data definition.
+ *
+ * `send(event, payload?)` is the primary verb; `goToStepById` is
+ * transition-gated sugar (fires only if an enabled transition targets that
+ * id). Timeline moves bypass transition gating — retracing a walked path is
+ * always legal. Step `onLeave` effects still run after those moves commit.
+ */
+export declare function createGraphJourney<TContext, TStepId extends string, TEvents extends JourneyEventObject = JourneyEventObject, THandlers = unknown, TMeta = Record<string, unknown>, const TPlugins extends readonly AnyJourneyPlugin[] = readonly [], TTerminationPayloads extends JourneyTerminationPayloads = JourneyTerminationPayloads>(definition: {
+    readonly steps: Readonly<Record<TStepId, GraphStepConfig<NoInfer<TContext>, NoInfer<TStepId>, NoInfer<TEvents>, TMeta, NoInfer<THandlers>>>>;
+    readonly initial: NoInfer<TStepId>;
+    readonly context: TContext;
+    readonly handlers?: THandlers;
+    /** @internal Builder-produced; opaque by design (see GraphJourneyDefinition). */
+    readonly eventWork?: Readonly<Record<string, unknown>>;
+    readonly $events?: TEvents;
+    readonly $payloads?: TTerminationPayloads;
+}, options?: GraphJourneyOptions<NoInfer<THandlers>, TPlugins, NoInfer<TStepId>>): GraphJourneyMachine<TContext, TStepId, TEvents, TMeta, TPlugins, CompletePayloadOf<TTerminationPayloads>, TerminatePayloadOf<TTerminationPayloads>>;
+/**
+ * Creates a graph journey factory with its types pinned up front instead of
+ * inferred.
+ *
+ * Reach for it when the definition cannot supply a type on its own —
+ * `handlers`, a `meta` shape, or a `run` result, none of which sit at an
+ * inference site — or when the same bag is shared by steps authored in
+ * separate files. The definition is then *checked* against the bag rather than
+ * read for types.
+ *
+ * ```ts
+ * const login = withGraphTypes<AuthBag>()({
+ *   initial: "login",
+ *   context: initialContext,
+ *   steps: { login: { on: { submit: "twofa" } }, twofa: {} }
+ * });
+ * ```
+ *
+ * Plain `createGraphJourney(definition)` stays the default: step ids infer from
+ * the `steps` keys and event names from the `on` keys.
+ */
+export declare const withGraphTypes: <TBag extends Bag>() => <const TPlugins extends readonly AnyJourneyPlugin[] = readonly []>(definition: GraphDefinition<TBag>, options?: GraphJourneyOptions<HandlersOf<TBag>, TPlugins, TBag["stepId"]>) => GraphJourneyMachine<TBag["context"], TBag["stepId"], TBag["events"], MetaOf<TBag>, TPlugins>;

package/dist/graph/graph.d.ts

@@ -0,0 +1,63 @@
+import type { RuntimeStep, RuntimeTransition } from "../core/runtime.types.js";
+import type { GraphJourneyMachine, GraphJourneyOptions, GraphStepConfig, LooseGraphDefinition } from "./graph.types.js";
+import type { AnySendWork } from "../core/runtime.types.js";
+import type { Bag, GraphDefinition, HandlersOf, MetaOf } from "./bag.types.js";
+import type { AnyJourneyPlugin, CompletePayloadOf, JourneyEventObject, JourneyTerminationPayloads, TerminatePayloadOf } from "../core/types.js";
+/**
+ * Flattens each step's colocated `on` into the runtime's flat transition list,
+ * in declaration order, and validates every target.
+ *
+ * Order is per step, then per event, then per candidate. That differs from the
+ * old central map's global per-event order, but only for the same event
+ * declared from two steps — and candidates are filtered by `from` before order
+ * is consulted, so the selected edge is unchanged. `first-enabled-in-declared-
+ * order` is asserted directly in graph.test.ts.
+ *
+ * `from` cannot dangle here: it is the key of the step that declares the entry.
+ */
+export declare function normalizeGraphDefinition(definition: LooseGraphDefinition): {
+    stepIds: string[];
+    steps: Record<string, RuntimeStep>;
+    transitions: RuntimeTransition[];
+    eventWork: Record<string, AnySendWork>;
+};
+/**
+ * Creates a graph journey runtime from a pure-data definition.
+ *
+ * `send(event, payload?)` is the primary verb; `goToStepById` is
+ * transition-gated sugar (fires only if an enabled transition targets that
+ * id). Timeline moves bypass transition gating — retracing a walked path is
+ * always legal. Step `onLeave` effects still run after those moves commit.
+ */
+export declare function createGraphJourney<TContext, TStepId extends string, TEvents extends JourneyEventObject = JourneyEventObject, THandlers = unknown, TMeta = Record<string, unknown>, const TPlugins extends readonly AnyJourneyPlugin[] = readonly [], TTerminationPayloads extends JourneyTerminationPayloads = JourneyTerminationPayloads>(definition: {
+    readonly steps: Readonly<Record<TStepId, GraphStepConfig<NoInfer<TContext>, NoInfer<TStepId>, NoInfer<TEvents>, TMeta, NoInfer<THandlers>>>>;
+    readonly initial: NoInfer<TStepId>;
+    readonly context: TContext;
+    readonly handlers?: THandlers;
+    /** @internal Builder-produced; opaque by design (see GraphJourneyDefinition). */
+    readonly eventWork?: Readonly<Record<string, unknown>>;
+    readonly $events?: TEvents;
+    readonly $payloads?: TTerminationPayloads;
+}, options?: GraphJourneyOptions<NoInfer<THandlers>, TPlugins, NoInfer<TStepId>>): GraphJourneyMachine<TContext, TStepId, TEvents, TMeta, TPlugins, CompletePayloadOf<TTerminationPayloads>, TerminatePayloadOf<TTerminationPayloads>>;
+/**
+ * Creates a graph journey factory with its types pinned up front instead of
+ * inferred.
+ *
+ * Reach for it when the definition cannot supply a type on its own —
+ * `handlers`, a `meta` shape, or a `run` result, none of which sit at an
+ * inference site — or when the same bag is shared by steps authored in
+ * separate files. The definition is then *checked* against the bag rather than
+ * read for types.
+ *
+ * ```ts
+ * const login = withGraphTypes<AuthBag>()({
+ *   initial: "login",
+ *   context: initialContext,
+ *   steps: { login: { on: { submit: "twofa" } }, twofa: {} }
+ * });
+ * ```
+ *
+ * Plain `createGraphJourney(definition)` stays the default: step ids infer from
+ * the `steps` keys and event names from the `on` keys.
+ */
+export declare const withGraphTypes: <TBag extends Bag>() => <const TPlugins extends readonly AnyJourneyPlugin[] = readonly []>(definition: GraphDefinition<TBag>, options?: GraphJourneyOptions<HandlersOf<TBag>, TPlugins, TBag["stepId"]>) => GraphJourneyMachine<TBag["context"], TBag["stepId"], TBag["events"], MetaOf<TBag>, TPlugins>;

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

@@ -0,0 +1,212 @@
+import type { AnySendWork, RuntimeStep, RuntimeTransition } from "../core/runtime.types.js";
+import type { AnyJourneyPlugin, ContextUpdater, GraphSnapshot, JourneyEventObject, JourneyEventPayload, JourneyMachineBase, JourneyRuntimeOptions, JourneyTerminationPayloads, NavigationResult, OnEnterHook, OnLeaveHook, PluginApis, StepHookArgs } from "../core/types.js";
+/**
+ * Guards are sync and pure: they are evaluated during snapshot derivation to
+ * compute `availableEvents`/`availableSteps`, so they receive no event payload
+ * and cannot be async. Caller-driven async validation belongs in navigation work.
+ */
+export type TransitionGuard<TContext, THandlers> = (args: {
+    readonly context: TContext;
+    readonly handlers: THandlers;
+}) => boolean;
+export type GraphHookArgs<TContext, TStepId extends string, TEvents extends JourneyEventObject, TMeta = Record<string, unknown>> = StepHookArgs<TContext, TStepId, TEvents, GraphSnapshot<TContext, TStepId, TMeta, TEvents>>;
+/** One colocated candidate; `from` is the step that declares it. */
+export type GraphTransition<TContext = unknown, TStepId extends string = string, TEvents extends JourneyEventObject = JourneyEventObject, THandlers = unknown, TMeta = Record<string, unknown>, TTrigger extends JourneyEventObject = TEvents> = {
+    readonly to: TStepId;
+    readonly when?: TransitionGuard<TContext, THandlers>;
+    /**
+     * Names this edge. Several candidates on one event differ only by guard, so
+     * the name is what tells them apart in timeout messages, step-hook
+     * `transition` args, and the plugin structure view — a priority index says
+     * where the edge sits, not what it is.
+     */
+    readonly label?: string;
+    /**
+     * Budget for this edge's `onTransition`, overriding `defaultTimeoutMs`. One
+     * edge waiting on a slow third party is not a reason to widen the budget for
+     * every other edge in the graph.
+     */
+    readonly timeoutMs?: number;
+    /** Async effect, post-commit, cannot cancel; a throw is handled like an `onEnter` throw. */
+    readonly onTransition?: (args: Omit<GraphHookArgs<TContext, TStepId, TEvents, TMeta>, "event"> & {
+        readonly event: TTrigger | null;
+    }) => void | Promise<void>;
+};
+/**
+ * What one event maps to on a step. Three forms, discriminated at the top
+ * level so nothing has to sniff inside a candidate:
+ *
+ * - a step id — one unguarded candidate;
+ * - an array — ordered candidates, first enabled wins;
+ * - an object — async the machine owns, whose staged context the candidates
+ *   are then evaluated against.
+ *
+ * A guarded lone candidate is `[{ to, when }]`: the extra brackets read
+ * honestly, since a guarded lone candidate means the event can fail.
+ */
+export type GraphOnEntry<TContext = unknown, TStepId extends string = string, TEvents extends JourneyEventObject = JourneyEventObject, THandlers = unknown, TMeta = Record<string, unknown>, TResult = unknown, TTrigger extends JourneyEventObject = TEvents> = TStepId | readonly GraphTransition<TContext, TStepId, TEvents, THandlers, TMeta, TTrigger>[] | {
+    readonly run: (args: SendWorkArgs<TStepId, TEvents, GraphSnapshot<TContext, TStepId, TMeta, TEvents>, THandlers>) => TResult | Promise<TResult>;
+    /**
+     * Declared as a method rather than a function-typed property on purpose.
+     * Method parameters are checked bivariantly, which is what lets a
+     * `commit` whose `result` is a concrete type sit in this slot when the
+     * slot's own `TResult` is the `unknown` fallback — the escape hatch the
+     * `work()` helper relies on to hand back an inferred config.
+     */
+    commit?(args: SendWorkArgs<TStepId, TEvents, GraphSnapshot<TContext, TStepId, TMeta, TEvents>, THandlers> & {
+        readonly result: TResult;
+        readonly updateContext: (updater: ContextUpdater<TContext>) => void;
+    }): void;
+    /** Names this work in timeout and error messages. */
+    readonly label?: string;
+    /**
+     * Budget for `run`, overriding `defaultTimeoutMs`. This is the edge that
+     * usually needs its own: `run` is where a definition's third-party call
+     * lives.
+     */
+    readonly timeoutMs?: number;
+    readonly candidates: readonly GraphTransition<TContext, TStepId, TEvents, THandlers, TMeta, TTrigger>[];
+};
+export type GraphStepConfig<TContext = unknown, TStepId extends string = string, TEvents extends JourneyEventObject = JourneyEventObject, TMeta = Record<string, unknown>, THandlers = unknown> = {
+    readonly metadata?: TMeta;
+    /** Outgoing transitions, keyed by event. */
+    readonly on?: {
+        readonly [TType in TEvents["type"]]?: GraphOnEntry<TContext, TStepId, TEvents, THandlers, TMeta, unknown, Extract<TEvents, {
+            type: TType;
+        }>>;
+    };
+    readonly onEnter?: OnEnterHook<TContext, TStepId, TEvents, GraphSnapshot<TContext, TStepId, TMeta, TEvents>>;
+    readonly onLeave?: OnLeaveHook<TContext, TStepId, TEvents, GraphSnapshot<TContext, TStepId, TMeta, TEvents>>;
+};
+/**
+ * Pure-data graph definition (also what the builder's `build()` produces).
+ * `$events` is a phantom carrier for the declared event union — never set at
+ * runtime.
+ */
+export type GraphJourneyDefinition<TContext = unknown, TStepId extends string = string, TEvents extends JourneyEventObject = JourneyEventObject, THandlers = unknown, TMeta = Record<string, unknown>, TTerminationPayloads extends JourneyTerminationPayloads = JourneyTerminationPayloads> = {
+    readonly steps: Readonly<Record<TStepId, GraphStepConfig<TContext, TStepId, TEvents, TMeta, THandlers>>>;
+    readonly initial: TStepId;
+    readonly context: TContext;
+    readonly handlers?: THandlers;
+    /**
+     * Work declared on an event, collected by `normalizeGraphDefinition`.
+     *
+     * @internal Its keys are a private encoding of the (origin step, event) pair
+     * and its values are internal work shapes. Typed as `unknown` on purpose so
+     * neither is nameable from the public surface: hand this field straight back
+     * to a factory, never construct or read it.
+     */
+    readonly eventWork?: Readonly<Record<string, unknown>>;
+    /**
+     * Phantom type carrier — never read at runtime. Names the event union, which
+     * the definition's other fields cannot infer on their own.
+     */
+    readonly $events?: TEvents;
+    /**
+     * Phantom type carrier — never read at runtime. Names the completion and
+     * termination payload types, so `controls.complete`/`terminate` and
+     * `snapshot.machine.outcome` are typed instead of `unknown`.
+     */
+    readonly $payloads?: TTerminationPayloads;
+};
+export type GraphJourneyOptions<THandlers = unknown, TPlugins extends readonly AnyJourneyPlugin[] = readonly [], TStepId extends string = string> = JourneyRuntimeOptions<TPlugins, TStepId> & {
+    /** Overrides the definition's handlers — one definition serves app and tests. */
+    handlers?: THandlers;
+};
+export type SendArgs<TEvents extends JourneyEventObject, TType extends TEvents["type"]> = JourneyEventPayload<TEvents, TType> extends undefined ? [] : [payload: JourneyEventPayload<TEvents, TType>];
+/**
+ * Arguments for work attached to a `send`.
+ *
+ * There is no `to`: the work runs *before* routing, so no target has been
+ * chosen yet. `handlers` is threaded through because this is the async that a
+ * definition owns, and injected clients reach it no other way — step hooks
+ * deliberately do not receive handlers.
+ */
+export type SendWorkArgs<TStepId extends string, TEvents extends JourneyEventObject, TSnap, THandlers> = {
+    readonly snapshot: TSnap;
+    readonly from: TStepId;
+    readonly event: TEvents;
+    readonly handlers: THandlers;
+};
+/**
+ * Async attached to an event, run before the guards choose an edge.
+ *
+ * `run` is awaited while the machine holds its position. `commit` then stages
+ * context synchronously, and the guards are evaluated against that staged
+ * context — so the work supplies the facts routing is decided from without
+ * guards ever becoming async. If `run` throws, or no candidate is enabled once
+ * the context is staged, nothing commits and the machine stays put.
+ */
+export type SendWork<TContext, TStepId extends string, TEvents extends JourneyEventObject, TSnap, THandlers = unknown, TResult = void> = {
+    readonly run: (args: SendWorkArgs<TStepId, TEvents, TSnap, THandlers>) => TResult | Promise<TResult>;
+    readonly commit?: (args: SendWorkArgs<TStepId, TEvents, TSnap, THandlers> & {
+        readonly result: TResult;
+        readonly updateContext: (updater: ContextUpdater<TContext>) => void;
+    }) => void;
+};
+/**
+ * Declared events get exact payload tuples; undeclared events fall back to
+ * `(type, payload?)`.
+ *
+ * `send` takes no work: async that decides an event's outcome is declared on
+ * the step, which is the graph's one channel for it.
+ */
+export type SendVerb<TStepId extends string, TEvents extends JourneyEventObject> = JourneyEventObject extends TEvents ? (type: string, payload?: unknown) => Promise<NavigationResult<TStepId>> : <TType extends TEvents["type"]>(type: TType, ...payload: SendArgs<TEvents, TType>) => Promise<NavigationResult<TStepId>>;
+export type GraphJourneyMachine<TContext, TStepId extends string, TEvents extends JourneyEventObject = JourneyEventObject, TMeta = Record<string, unknown>, TPlugins extends readonly AnyJourneyPlugin[] = readonly [], TCompletePayload = unknown, TTerminatePayload = unknown> = JourneyMachineBase<TContext, TStepId, GraphSnapshot<TContext, TStepId, TMeta, TEvents, TCompletePayload, TTerminatePayload>, TCompletePayload, TTerminatePayload> & {
+    /**
+     * The graph's primary verb — its presence is itself the machine-type
+     * discriminant (linear has no events).
+     */
+    send: SendVerb<TStepId, TEvents>;
+    readonly plugins: PluginApis<TPlugins>;
+};
+/**
+ * Internal, generics-erased view of one colocated `on` entry. The three forms
+ * are discriminated structurally at the top level — string, array, object —
+ * so normalization never has to sniff inside a candidate.
+ */
+export type LooseOnEntry = string | readonly LooseTransition[] | {
+    readonly run: AnySendWork["run"];
+    readonly commit?: AnySendWork["commit"];
+    readonly label?: string;
+    readonly timeoutMs?: number;
+    readonly candidates: readonly LooseTransition[];
+};
+/** A colocated candidate: `from` is the step that declares it. */
+export type LooseTransition = {
+    readonly to: string;
+    readonly when?: NonNullable<RuntimeTransition["when"]>;
+    readonly onTransition?: NonNullable<RuntimeTransition["onTransition"]>;
+    readonly label?: string;
+    readonly timeoutMs?: number;
+};
+/** Internal, generics-erased view of a definition used by normalization. */
+export type LooseGraphDefinition = {
+    readonly steps: Readonly<Record<string, GraphStepConfig & {
+        readonly on?: Readonly<Record<string, LooseOnEntry>>;
+    }>>;
+    readonly initial: string;
+    readonly context: unknown;
+    readonly handlers?: unknown;
+};
+export type MutableRuntimeStep = {
+    metadata: unknown;
+    onEnter?: NonNullable<RuntimeStep["onEnter"]>;
+    onLeave?: NonNullable<RuntimeStep["onLeave"]>;
+};
+export type MutableSendWork = {
+    run: AnySendWork["run"];
+    commit?: NonNullable<AnySendWork["commit"]>;
+    label?: string;
+    timeoutMs?: number;
+};
+export type MutableRuntimeTransition = {
+    event: string;
+    from: string;
+    to: string;
+    index: number;
+    label?: string;
+    timeoutMs?: number;
+    when?: NonNullable<RuntimeTransition["when"]>;
+    onTransition?: NonNullable<RuntimeTransition["onTransition"]>;
+};

package/dist/graph/graph.types.d.ts

@@ -0,0 +1,212 @@
+import type { AnySendWork, RuntimeStep, RuntimeTransition } from "../core/runtime.types.js";
+import type { AnyJourneyPlugin, ContextUpdater, GraphSnapshot, JourneyEventObject, JourneyEventPayload, JourneyMachineBase, JourneyRuntimeOptions, JourneyTerminationPayloads, NavigationResult, OnEnterHook, OnLeaveHook, PluginApis, StepHookArgs } from "../core/types.js";
+/**
+ * Guards are sync and pure: they are evaluated during snapshot derivation to
+ * compute `availableEvents`/`availableSteps`, so they receive no event payload
+ * and cannot be async. Caller-driven async validation belongs in navigation work.
+ */
+export type TransitionGuard<TContext, THandlers> = (args: {
+    readonly context: TContext;
+    readonly handlers: THandlers;
+}) => boolean;
+export type GraphHookArgs<TContext, TStepId extends string, TEvents extends JourneyEventObject, TMeta = Record<string, unknown>> = StepHookArgs<TContext, TStepId, TEvents, GraphSnapshot<TContext, TStepId, TMeta, TEvents>>;
+/** One colocated candidate; `from` is the step that declares it. */
+export type GraphTransition<TContext = unknown, TStepId extends string = string, TEvents extends JourneyEventObject = JourneyEventObject, THandlers = unknown, TMeta = Record<string, unknown>, TTrigger extends JourneyEventObject = TEvents> = {
+    readonly to: TStepId;
+    readonly when?: TransitionGuard<TContext, THandlers>;
+    /**
+     * Names this edge. Several candidates on one event differ only by guard, so
+     * the name is what tells them apart in timeout messages, step-hook
+     * `transition` args, and the plugin structure view — a priority index says
+     * where the edge sits, not what it is.
+     */
+    readonly label?: string;
+    /**
+     * Budget for this edge's `onTransition`, overriding `defaultTimeoutMs`. One
+     * edge waiting on a slow third party is not a reason to widen the budget for
+     * every other edge in the graph.
+     */
+    readonly timeoutMs?: number;
+    /** Async effect, post-commit, cannot cancel; a throw is handled like an `onEnter` throw. */
+    readonly onTransition?: (args: Omit<GraphHookArgs<TContext, TStepId, TEvents, TMeta>, "event"> & {
+        readonly event: TTrigger | null;
+    }) => void | Promise<void>;
+};
+/**
+ * What one event maps to on a step. Three forms, discriminated at the top
+ * level so nothing has to sniff inside a candidate:
+ *
+ * - a step id — one unguarded candidate;
+ * - an array — ordered candidates, first enabled wins;
+ * - an object — async the machine owns, whose staged context the candidates
+ *   are then evaluated against.
+ *
+ * A guarded lone candidate is `[{ to, when }]`: the extra brackets read
+ * honestly, since a guarded lone candidate means the event can fail.
+ */
+export type GraphOnEntry<TContext = unknown, TStepId extends string = string, TEvents extends JourneyEventObject = JourneyEventObject, THandlers = unknown, TMeta = Record<string, unknown>, TResult = unknown, TTrigger extends JourneyEventObject = TEvents> = TStepId | readonly GraphTransition<TContext, TStepId, TEvents, THandlers, TMeta, TTrigger>[] | {
+    readonly run: (args: SendWorkArgs<TStepId, TEvents, GraphSnapshot<TContext, TStepId, TMeta, TEvents>, THandlers>) => TResult | Promise<TResult>;
+    /**
+     * Declared as a method rather than a function-typed property on purpose.
+     * Method parameters are checked bivariantly, which is what lets a
+     * `commit` whose `result` is a concrete type sit in this slot when the
+     * slot's own `TResult` is the `unknown` fallback — the escape hatch the
+     * `work()` helper relies on to hand back an inferred config.
+     */
+    commit?(args: SendWorkArgs<TStepId, TEvents, GraphSnapshot<TContext, TStepId, TMeta, TEvents>, THandlers> & {
+        readonly result: TResult;
+        readonly updateContext: (updater: ContextUpdater<TContext>) => void;
+    }): void;
+    /** Names this work in timeout and error messages. */
+    readonly label?: string;
+    /**
+     * Budget for `run`, overriding `defaultTimeoutMs`. This is the edge that
+     * usually needs its own: `run` is where a definition's third-party call
+     * lives.
+     */
+    readonly timeoutMs?: number;
+    readonly candidates: readonly GraphTransition<TContext, TStepId, TEvents, THandlers, TMeta, TTrigger>[];
+};
+export type GraphStepConfig<TContext = unknown, TStepId extends string = string, TEvents extends JourneyEventObject = JourneyEventObject, TMeta = Record<string, unknown>, THandlers = unknown> = {
+    readonly metadata?: TMeta;
+    /** Outgoing transitions, keyed by event. */
+    readonly on?: {
+        readonly [TType in TEvents["type"]]?: GraphOnEntry<TContext, TStepId, TEvents, THandlers, TMeta, unknown, Extract<TEvents, {
+            type: TType;
+        }>>;
+    };
+    readonly onEnter?: OnEnterHook<TContext, TStepId, TEvents, GraphSnapshot<TContext, TStepId, TMeta, TEvents>>;
+    readonly onLeave?: OnLeaveHook<TContext, TStepId, TEvents, GraphSnapshot<TContext, TStepId, TMeta, TEvents>>;
+};
+/**
+ * Pure-data graph definition (also what the builder's `build()` produces).
+ * `$events` is a phantom carrier for the declared event union — never set at
+ * runtime.
+ */
+export type GraphJourneyDefinition<TContext = unknown, TStepId extends string = string, TEvents extends JourneyEventObject = JourneyEventObject, THandlers = unknown, TMeta = Record<string, unknown>, TTerminationPayloads extends JourneyTerminationPayloads = JourneyTerminationPayloads> = {
+    readonly steps: Readonly<Record<TStepId, GraphStepConfig<TContext, TStepId, TEvents, TMeta, THandlers>>>;
+    readonly initial: TStepId;
+    readonly context: TContext;
+    readonly handlers?: THandlers;
+    /**
+     * Work declared on an event, collected by `normalizeGraphDefinition`.
+     *
+     * @internal Its keys are a private encoding of the (origin step, event) pair
+     * and its values are internal work shapes. Typed as `unknown` on purpose so
+     * neither is nameable from the public surface: hand this field straight back
+     * to a factory, never construct or read it.
+     */
+    readonly eventWork?: Readonly<Record<string, unknown>>;
+    /**
+     * Phantom type carrier — never read at runtime. Names the event union, which
+     * the definition's other fields cannot infer on their own.
+     */
+    readonly $events?: TEvents;
+    /**
+     * Phantom type carrier — never read at runtime. Names the completion and
+     * termination payload types, so `controls.complete`/`terminate` and
+     * `snapshot.machine.outcome` are typed instead of `unknown`.
+     */
+    readonly $payloads?: TTerminationPayloads;
+};
+export type GraphJourneyOptions<THandlers = unknown, TPlugins extends readonly AnyJourneyPlugin[] = readonly [], TStepId extends string = string> = JourneyRuntimeOptions<TPlugins, TStepId> & {
+    /** Overrides the definition's handlers — one definition serves app and tests. */
+    handlers?: THandlers;
+};
+export type SendArgs<TEvents extends JourneyEventObject, TType extends TEvents["type"]> = JourneyEventPayload<TEvents, TType> extends undefined ? [] : [payload: JourneyEventPayload<TEvents, TType>];
+/**
+ * Arguments for work attached to a `send`.
+ *
+ * There is no `to`: the work runs *before* routing, so no target has been
+ * chosen yet. `handlers` is threaded through because this is the async that a
+ * definition owns, and injected clients reach it no other way — step hooks
+ * deliberately do not receive handlers.
+ */
+export type SendWorkArgs<TStepId extends string, TEvents extends JourneyEventObject, TSnap, THandlers> = {
+    readonly snapshot: TSnap;
+    readonly from: TStepId;
+    readonly event: TEvents;
+    readonly handlers: THandlers;
+};
+/**
+ * Async attached to an event, run before the guards choose an edge.
+ *
+ * `run` is awaited while the machine holds its position. `commit` then stages
+ * context synchronously, and the guards are evaluated against that staged
+ * context — so the work supplies the facts routing is decided from without
+ * guards ever becoming async. If `run` throws, or no candidate is enabled once
+ * the context is staged, nothing commits and the machine stays put.
+ */
+export type SendWork<TContext, TStepId extends string, TEvents extends JourneyEventObject, TSnap, THandlers = unknown, TResult = void> = {
+    readonly run: (args: SendWorkArgs<TStepId, TEvents, TSnap, THandlers>) => TResult | Promise<TResult>;
+    readonly commit?: (args: SendWorkArgs<TStepId, TEvents, TSnap, THandlers> & {
+        readonly result: TResult;
+        readonly updateContext: (updater: ContextUpdater<TContext>) => void;
+    }) => void;
+};
+/**
+ * Declared events get exact payload tuples; undeclared events fall back to
+ * `(type, payload?)`.
+ *
+ * `send` takes no work: async that decides an event's outcome is declared on
+ * the step, which is the graph's one channel for it.
+ */
+export type SendVerb<TStepId extends string, TEvents extends JourneyEventObject> = JourneyEventObject extends TEvents ? (type: string, payload?: unknown) => Promise<NavigationResult<TStepId>> : <TType extends TEvents["type"]>(type: TType, ...payload: SendArgs<TEvents, TType>) => Promise<NavigationResult<TStepId>>;
+export type GraphJourneyMachine<TContext, TStepId extends string, TEvents extends JourneyEventObject = JourneyEventObject, TMeta = Record<string, unknown>, TPlugins extends readonly AnyJourneyPlugin[] = readonly [], TCompletePayload = unknown, TTerminatePayload = unknown> = JourneyMachineBase<TContext, TStepId, GraphSnapshot<TContext, TStepId, TMeta, TEvents, TCompletePayload, TTerminatePayload>, TCompletePayload, TTerminatePayload> & {
+    /**
+     * The graph's primary verb — its presence is itself the machine-type
+     * discriminant (linear has no events).
+     */
+    send: SendVerb<TStepId, TEvents>;
+    readonly plugins: PluginApis<TPlugins>;
+};
+/**
+ * Internal, generics-erased view of one colocated `on` entry. The three forms
+ * are discriminated structurally at the top level — string, array, object —
+ * so normalization never has to sniff inside a candidate.
+ */
+export type LooseOnEntry = string | readonly LooseTransition[] | {
+    readonly run: AnySendWork["run"];
+    readonly commit?: AnySendWork["commit"];
+    readonly label?: string;
+    readonly timeoutMs?: number;
+    readonly candidates: readonly LooseTransition[];
+};
+/** A colocated candidate: `from` is the step that declares it. */
+export type LooseTransition = {
+    readonly to: string;
+    readonly when?: NonNullable<RuntimeTransition["when"]>;
+    readonly onTransition?: NonNullable<RuntimeTransition["onTransition"]>;
+    readonly label?: string;
+    readonly timeoutMs?: number;
+};
+/** Internal, generics-erased view of a definition used by normalization. */
+export type LooseGraphDefinition = {
+    readonly steps: Readonly<Record<string, GraphStepConfig & {
+        readonly on?: Readonly<Record<string, LooseOnEntry>>;
+    }>>;
+    readonly initial: string;
+    readonly context: unknown;
+    readonly handlers?: unknown;
+};
+export type MutableRuntimeStep = {
+    metadata: unknown;
+    onEnter?: NonNullable<RuntimeStep["onEnter"]>;
+    onLeave?: NonNullable<RuntimeStep["onLeave"]>;
+};
+export type MutableSendWork = {
+    run: AnySendWork["run"];
+    commit?: NonNullable<AnySendWork["commit"]>;
+    label?: string;
+    timeoutMs?: number;
+};
+export type MutableRuntimeTransition = {
+    event: string;
+    from: string;
+    to: string;
+    index: number;
+    label?: string;
+    timeoutMs?: number;
+    when?: NonNullable<RuntimeTransition["when"]>;
+    onTransition?: NonNullable<RuntimeTransition["onTransition"]>;
+};