@loomcli/core 0.2.0 → 0.4.0

package/dist/chain.js

@@ -1,8 +1,69 @@
 import { prepareDispatch, routeInvocation } from './command.js';
-import { InternalError, reasonOf, toFailure } from './errors.js';
+import { InternalError, reasonOf, routedSubject, toFailure } from './errors.js';
 import { inspectGraph } from './inspect.js';
 import { booleanValue } from './options.js';
 import { pluginSentence } from './plugin.js';
+/**
+ * The view one run selects, which is one value whichever middleware wrote it. The assignment is
+ * kept as it arrived, because a JavaScript caller reaches the setter with any value and the check
+ * belongs at the dispatch boundary, where the fault it raises ranks behind a held fault.
+ */
+class ViewSelection {
+    #assigned = undefined;
+    #reached = false;
+    #result;
+    constructor(result) {
+        this.#result = result;
+    }
+    /**
+     * What `view` reads: the assigned name, or the declaration's default until one is assigned, and
+     * `null` on a Command that declares no result, whatever was assigned there. An assignment that is
+     * not a name reads as the default, because the getter answers a view name and the assignment is
+     * the boundary's fault. The assignment itself is kept either way, so the boundary still raises it.
+     */
+    read() {
+        if (!this.#result) {
+            return null;
+        }
+        const assigned = this.#assigned;
+        if (assigned !== undefined && typeof assigned.name === 'string') {
+            return assigned.name;
+        }
+        return this.#result.default;
+    }
+    /** The last assignment before the boundary wins; one made after it changes nothing. */
+    assign(identity, name) {
+        if (!this.#reached) {
+            this.#assigned = { identity, name };
+        }
+    }
+    /** The chain reached the dispatch boundary, so this run's view is fixed whatever follows. */
+    reach() {
+        this.#reached = true;
+    }
+    /**
+     * The name the boundary dispatches through: `null` when no middleware assigned one and the
+     * declaration's default stands. A plugin that selected a view has the name checked here.
+     */
+    resolve(path) {
+        const assigned = this.#assigned;
+        if (assigned === undefined) {
+            return null;
+        }
+        const plugin = pluginSentence(assigned.identity);
+        const { name } = assigned;
+        if (!this.#result) {
+            throw new InternalError(`${plugin} selected view "${String(name)}" on ${routedSubject(path)}, which declares no result.`, undefined);
+        }
+        if (typeof name !== 'string') {
+            throw new InternalError(`${plugin} selected a view that is not a string on ${routedSubject(path)}.`, undefined);
+        }
+        if (!this.#result.views.has(name)) {
+            throw new InternalError(`${plugin} selected view "${name}", which ${routedSubject(path)} does not name.`, undefined);
+        }
+        return name;
+    }
+}
 /**
  * The default export a loader must resolve to. A loaded module is data core never declared, so the
  * check is the one runtime fact that decides it: the export is callable. Core calls it with the
@@ -133,8 +194,9 @@ function nextOf(turn) {
             throw error;
         });
         state.downstream = pending;
-        // Core awaits the downstream promise itself, so a middleware that never awaits `next()` still
-        // Holds the chain open and never ends the run with an unobserved rejection.
+        // Core awaits the downstream promise itself.
+        // A middleware that never awaits `next()` still holds the chain open.
+        // The run therefore never ends with an unobserved rejection.
         void pending.catch(() => undefined);
         return pending;
     };
@@ -174,8 +236,8 @@ async function settle(turn, thrown) {
         return reported(chain, 'taken-over');
     }
     await quiet(state.downstream);
-    // A middleware that caught the rejection reports what the chain reached; the recorded failure
-    // Still decides the exit code.
+    // A middleware that caught the rejection reports what the chain reached.
+    // The recorded failure still decides the exit code.
     return reported(chain, state.outcome ?? (chain.invoked() ? 'dispatched' : 'taken-over'));
 }
 /** The module one loader answers with, whether it throws where it is called or rejects later. */
@@ -215,12 +277,23 @@ async function runEntry(entry, index, chain) {
     return settle(turn, thrown);
 }
 /** The whole chain, answering with the failure it raised when a middleware caught that failure. */
-async function runChain(invocation, routed, entries) {
+async function runChain(invocation, routed, prepared) {
+    const entries = activatedEntries(invocation.plugins, routed.scan);
     const run = { invoked: false, raised: undefined };
+    const selection = new ViewSelection(prepared.result);
+    /**
+     * The dispatch boundary: the point the chain reaches when its last middleware continues. Core
+     * raises the held fault here, so it ranks ahead of a bad view assignment, or else reads the
+     * selected view and dispatches the action.
+     */
     const terminal = async () => {
-        const dispatch = await prepareDispatch(invocation.graph, routed, invocation);
+        selection.reach();
+        if (prepared.kind === 'held') {
+            throw prepared.fault;
+        }
+        const view = selection.resolve(routed.path);
         run.invoked = true;
-        await dispatch();
+        await prepared.dispatch(view);
         return 'dispatched';
     };
     const cancelled = () => invocation.signal.aborted;
@@ -245,7 +318,14 @@ async function runChain(invocation, routed, entries) {
             next,
             options: entry.options,
             out: invocation.out,
+            request: prepared.request,
             signal: invocation.signal,
+            get view() {
+                return selection.read();
+            },
+            set view(name) {
+                selection.assign(entry.identity, name);
+            },
         }),
         invoked: () => run.invoked,
         record: (error) => {
@@ -271,17 +351,21 @@ async function runChain(invocation, routed, entries) {
     return run.raised;
 }
 /**
- * Runs one invocation: the global pre-scan, routing, the middleware chain, and the phases the chain
- * terminates in. A middleware that returns without calling `next()` has taken over, so the
- * remaining tokens are never parsed and nothing later in the chain runs.
+ * Runs one invocation: the global pre-scan, routing, the dispatch this invocation prepares, and the
+ * middleware chain it then runs. Local parsing and validation run ahead of the chain so that a
+ * middleware reads the request, and the fault they find is held until the dispatch boundary. A
+ * middleware that returns without calling `next()` has taken over, so the held fault is never
+ * raised and nothing later in the chain runs.
  */
 async function runInvocation(invocation) {
     const routed = routeInvocation(invocation.graph, invocation.host.argv);
-    const entries = activatedEntries(invocation.plugins, routed.scan);
-    const raised = await runChain(invocation, routed, entries);
+    invocation.route(routed.path);
+    const prepared = await prepareDispatch(invocation.graph, routed, invocation);
+    const raised = await runChain(invocation, routed, prepared);
     if (raised) {
-        // The chain resolved because a middleware caught the rejection. The failure it caught still
-        // Decides the exit code, the rule an action's caught output rejection already follows.
+        // The chain resolved because a middleware caught the rejection.
+        // The failure it caught still decides the exit code.
+        // That is the rule an action's caught output rejection already follows.
         throw raised;
     }
 }

package/dist/command.d.ts

@@ -1,9 +1,11 @@
+import type { RegisteredGlobals } from './environment.js';
 import type { DescriptorRegistry, ExtensionRecords, ExtensionValue } from './extension.js';
-import type { BuiltGlobals, GlobalOptions } from './globals.js';
+import type { BuiltGlobals, GlobalsState } from './globals.js';
 import { compileOptions } from './options.js';
 import type { OptionValues } from './options.js';
 import type { BuiltPlugin, PluginBuild } from './plugin.js';
-import type { Action, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredTypes, DefaultConstraint, GlobalNameConstraint, Host, MultipleConstraint, NameConstraint, OptionConfig, OptionValue, Out, ValidateOmittedConstraint } from './types.js';
+import type { ContextualStyle } from './style.js';
+import type { Action, ActionChannel, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredResult, DeclaredTypes, DefaultConstraint, GlobalNameConstraint, Host, MultipleConstraint, NameConstraint, OpenResult, OptionConfig, OptionValue, Out, Request, ResultBinding, ResultViews, ResultViewsOf, RowViews, ValidateOmittedConstraint } from './types.js';
 import type { ArgumentInput, DefaultValues, InputDeclaration, OptionInput, ValidatedInputs } from './validation.js';
 /** One positional slot: the declaration it fills and whether it takes the remaining tokens. */
 export interface ArgumentSlot {
@@ -12,8 +14,10 @@ export interface ArgumentSlot {
     variadic: boolean;
 }
 export interface DispatchInput {
+    style: ContextualStyle;
     host: Host;
-    out: Out;
+    /** The action's channel, whose `results` accepts whatever the routed declaration named. */
+    out: Out<OpenResult>;
     passthrough: string[];
     signal: AbortSignal;
     values: ValidatedInputs;
@@ -44,29 +48,39 @@ export interface BuiltCommand {
     inputs: readonly InputDeclaration[];
     name: string | null;
     options: ReturnType<typeof compileOptions>;
+    /** The result the Command declares, or nothing where it declares none. */
+    /** The built declaration is the shape the write site reads, so the channel carries it. */
+    result: DeclaredResult | undefined;
     routes: ReadonlyMap<string, RoutedChild>;
 }
 /** Phantom key. It marks a Command value, so only a Command can be attached as a child. */
 export declare const commandValue: unique symbol;
 /**
- * Every authoring call a Command can publish. A Command's type state is a subset of these names,
+ * The input, alias, child, and action calls a Command can publish. Its type state is a subset,
  * and each call removes the names it invalidates. A Command attaches children at any depth, so
  * `command()` belongs to every Command and to the unnamed root alike.
  */
-export type CommandMethod = 'action' | 'alias' | 'argument' | 'command' | 'option';
+export type CommandMethod = 'action' | 'alias' | 'argument' | 'command' | 'option' | 'result' | 'rows';
 /** One Command declares arguments or attaches children, so the first call removes the other. */
 export type AfterArgument<State> = Exclude<State, 'command'>;
 /** The same rule read from the other side. */
 export type AfterCommand<State> = Exclude<State, 'argument'>;
-/** The action is the last declaration call, so no declaration call survives it. */
+/** One Command declares one result, so either call removes both. */
+export type AfterResult<State> = Exclude<State, 'result' | 'rows'>;
+/** Registering the action closes input, alias, child, and further action declarations. */
 export type AfterAction = never;
-/** A declaration made after the action, kept in authoring order so build reports the first. */
+/** A declaration made after its authoring phase closed; build reports the first in call order. */
 type LateDeclaration = {
     alias: string;
     kind: 'alias';
+} | {
+    name: string;
+    kind: 'global';
 } | {
     child: object;
     kind: 'child';
+} | {
+    kind: 'result';
 } | {
     input: InputDeclaration;
     kind: 'input';
@@ -76,8 +90,8 @@ type LateDeclaration = {
  * which the types reject and a JavaScript author can still write, reports as the call it is.
  */
 type AliasDeclaration = readonly string[];
-/** The attachable shape of a Command, without its inferred declaration types. */
-interface AttachedCommand {
+/** The private handle one graph node is built through, without its inferred declaration types. */
+interface CommandNodeHandle {
     readonly name: string | null;
     build(context: BuildContext): BuiltCommand;
 }
@@ -92,15 +106,36 @@ interface BuildContext {
     descriptors: DescriptorRegistry;
     extensions: ExtensionRecords;
     globals: BuiltGlobals;
-    owners: Map<AttachedCommand, string | null>;
+    owners: Map<CommandNodeHandle, string | null>;
+    /** The route from the root to the Command being built, which a lifecycle hook reads. */
+    path: readonly string[];
+    /** The installed plugins in installation order, whose hooks run over every Command. */
+    plugins: readonly BuiltPlugin[];
 }
 /**
  * Everything one Command declaration holds. The transitions below copy it with fields replaced, and
  * the Command and Application builders share them, so one declaration call has one implementation.
- * Absent globals stay `undefined`, so every declaration without globals agrees on identity.
  */
+/**
+ * One call of the results lane, in the order it was made. A `result()` or `rows()` call declares
+ * the unit, and a `views()` call reshapes the views of whichever declaration it follows.
+ * Each record arrives unexamined, because build owns every rule the lane carries.
+ */
+export type ResultCall = {
+    kind: 'value' | 'rows';
+    views: unknown;
+} | {
+    default: unknown;
+    kind: 'views';
+    views: unknown;
+};
 export interface CommandState<Args, Options, Globals> {
-    actions: readonly Action<Args, Globals & Options>[];
+    /**
+     * The registered actions, with the declared result erased. An action is stored under the widest
+     * result, so a handler typed from its own declaration stores here and the channel that carries
+     * the result is built for it at dispatch.
+     */
+    actions: readonly Action<Args, Globals & Options, OpenResult>[];
     aliases: readonly AliasDeclaration[];
     bind: (values: ValidatedInputs) => {
         args: Args;
@@ -109,13 +144,13 @@ export interface CommandState<Args, Options, Globals> {
     children: readonly object[];
     deprecated: unknown;
     description: unknown;
-    extensions: unknown;
+    extensions: readonly unknown[];
     hidden: unknown;
-    globals: GlobalOptions<Globals> | undefined;
     inputs: readonly InputDeclaration[];
     late: readonly LateDeclaration[];
     name: string | null;
     options: unknown;
+    results: readonly ResultCall[];
 }
 /**
  * The state every declaration starts from. The unnamed root and each named Command share it.
@@ -126,7 +161,6 @@ export declare function freshState<Globals>(declaration: {
     deprecated: unknown;
     description: unknown;
     extensions: unknown;
-    globals: GlobalOptions<Globals> | undefined;
     hidden: unknown;
     name: string | null;
     options: unknown;
@@ -135,9 +169,21 @@ export declare function freshState<Globals>(declaration: {
 export declare function declareArgument<Args, Options, Globals, Name extends string, Config extends ArgumentConfig>(state: CommandState<Args, Options, Globals>, input: ArgumentInput<Name, Config>): CommandState<Args & Record<Name, ArgumentValue<Config>>, Options, Globals>;
 /** The declared value joins `options` under its literal name, typed by its own config. */
 export declare function declareOption<Args, Options, Globals, Name extends string, Config extends OptionConfig>(state: CommandState<Args, Options, Globals>, input: OptionInput<Name, Config>): CommandState<Args, Options & Record<Name, OptionValue<Config>>, Globals>;
+/** Globals close when composition starts; retain late calls for the shared build-order check. */
+export declare function recordGlobalOption<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, name: string): CommandState<Args, Options, Globals>;
 /** One call's names stay one group, so the empty call the types reject still reports as one. */
 export declare function declareAlias<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, names: AliasDeclaration): CommandState<Args, Options, Globals>;
-export declare function declareAction<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, handler: Action<Args, Globals & Options>): CommandState<Args, Options, Globals>;
+/** Extension layers remain open after inputs and the action have been fixed. */
+export declare function declareExtensions<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, values: readonly ExtensionValue<'command'>[]): CommandState<Args, Options, Globals>;
+/**
+ * The handler is typed against the result its own declaration carries, and the state holds one
+ * list for every declaration, so the context each handler receives is read back at the call.
+ */
+export declare function declareAction<Args, Options, Globals, Result>(state: CommandState<Args, Options, Globals>, handler: Action<Args, Globals & Options, Result>): CommandState<Args, Options, Globals>;
+/** The result declaration, which closes both result calls and reports lateness like the rest. */
+export declare function declareResult<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, kind: 'value' | 'rows', declaration: unknown): CommandState<Args, Options, Globals>;
+/** A `views()` call reshapes views and closes nothing, so it is never a late declaration. */
+export declare function declareResultViews<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, replacements: unknown, options: unknown): CommandState<Args, Options, Globals>;
 /** Attaching is a declaration call too, so the receiver keeps the children it already had. */
 export declare function attachChild<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, child: object): CommandState<Args, Options, Globals>;
 /** Validates one declaration against the shared globals table and compiles it for dispatch. */
@@ -149,27 +195,57 @@ export interface BuiltGraph {
     root: BuiltCommand;
 }
 /** The globals table and the owners record each compile once per invocation and the whole graph shares them. */
-export declare function buildGraph<Args, Options, Globals>(root: CommandState<Args, Options, Globals>, install: PluginBuild & {
+export declare function buildGraph<Args, Options, Globals>(root: CommandState<Args, Options, Globals>, globals: GlobalsState<Globals>, install: PluginBuild & {
     plugins: readonly BuiltPlugin[];
 }): BuiltGraph;
-export declare class CommandBuilder<Args, Options, Globals, State extends CommandMethod = CommandMethod> {
+export declare class CommandBuilder<Args, Options, Globals, State extends CommandMethod = CommandMethod, Result = unknown> {
     #private;
     readonly [commandValue]: true;
-    readonly [declaredTypes]: DeclaredTypes<Args, Options, Globals>;
+    readonly [declaredTypes]: DeclaredTypes<Args, Options, Globals, Result>;
     constructor(state: CommandState<Args, Options, Globals>);
     get name(): string | null;
-    argument<const Name extends string, const Config extends ArgumentConfig>(name: Name, config: Config & NameConstraint<Name> & NoInfer<DefaultConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Command<Args & Record<Name, ArgumentValue<Config>>, Options, Globals, AfterArgument<State>>;
-    option<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & GlobalNameConstraint<Name, Globals> & NoInfer<DefaultConstraint<Config>> & NoInfer<MultipleConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Command<Args, Options & Record<Name, OptionValue<Config>>, Globals, State>;
+    argument<const Name extends string, const Config extends ArgumentConfig>(name: Name, config: Config & NameConstraint<Name> & NoInfer<DefaultConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Command<Args & Record<Name, ArgumentValue<Config>>, Options, Globals, AfterArgument<State>, Result>;
+    option<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & GlobalNameConstraint<Name, Globals> & NoInfer<DefaultConstraint<Config>> & NoInfer<MultipleConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Command<Args, Options & Record<Name, OptionValue<Config>>, Globals, State, Result>;
     /**
      * Aliases are other bare tokens that route to this Command. They invalidate no call, and the
      * tuple rest parameter rejects a call that names none.
      */
-    alias(...names: [string, ...string[]]): Command<Args, Options, Globals, State>;
+    alias(...names: [string, ...string[]]): Command<Args, Options, Globals, State, Result>;
     /** A child arrives in any type state, because its own action is the call that finished it. */
-    command(child: Command<unknown, unknown, Globals>): Command<Args, Options, Globals, AfterCommand<State>>;
-    /** The action is the last declaration call, so the value it returns publishes `AfterAction`. */
-    action(handler: Action<Args, Globals & Options>): Command<Args, Options, Globals>;
+    command<const Child extends Command<unknown, unknown, Globals>>(child: Child & NoInfer<AttachmentConstraint<Globals, Child>>): Command<Args, Options, Globals, AfterCommand<State>, Result>;
+    /**
+     * The value this Command produces for its consumer. The type argument is stated by the author,
+     * so the views record states no type of its own and an omitted argument names none either.
+     */
+    result<Value>(declaration: {
+        views: ResultViews<NoInfer<Value>>;
+    }): Command<Args, Options, Globals, AfterResult<State>, {
+        kind: 'value';
+        value: Value;
+    }>;
+    /** The same declaration over a sequence, whose type argument is one row. */
+    rows<Row>(declaration: {
+        views: RowViews<NoInfer<Row>>;
+    }): Command<Args, Options, Globals, AfterResult<State>, {
+        kind: 'rows';
+        row: Row;
+    }>;
+    /**
+     * Views after the fact. It merges by key, so an existing name is replaced in place and a new one
+     * is appended, and `default` names the key core renders when nothing selects another.
+     */
+    views(replacements: ResultViewsOf<Result>, options?: {
+        default?: string;
+    }): Command<Args, Options, Globals, State, Result>;
+    /** The action closes input authoring; `extend()` remains outside this state transition. */
+    action(handler: Action<Args, Globals & Options, Result>): Command<Args, Options, Globals, AfterAction, Result>;
+    extend(...values: readonly ExtensionValue<'command'>[]): Command<Args, Options, Globals, State, Result>;
     build(context: BuildContext): BuiltCommand;
+    /**
+     * The same runtime value in the state the calling method's return type names. Each call states
+     * its own transition, and the declared result travels with it unless the call replaces it.
+     */
+    private derive;
 }
 /**
  * The authoring surface of a Command in one type state. Every call returns a new declaration value,
@@ -178,22 +254,30 @@ export declare class CommandBuilder<Args, Options, Globals, State extends Comman
  * calls a value still offers. It defaults to the state after `action()`, which publishes the fewest
  * calls, so `Command<A, O, G>` accepts a Command in any state, a finished one included.
  */
-export type Command<Args = {}, Options = {}, Globals = {}, State extends CommandMethod = AfterAction> = Pick<CommandBuilder<Args, Options, Globals, State>, typeof commandValue | typeof declaredTypes | State>;
+export type Command<Args = {}, Options = {}, Globals = {}, State extends CommandMethod = AfterAction, Result = unknown> = Pick<CommandBuilder<Args, Options, Globals, State, Result>, typeof commandValue | typeof declaredTypes | 'extend' | State | ResultMethod<Result>>;
 /**
- * Everything a Command configures beside its declarations: the options value every Command in one
- * application shares, and the core facts the declaration carries.
+ * `views()` is published in every state on a declaration that carries a result, and on none that
+ * carries none. It is a key of the picked surface rather than a member of the state union, because
+ * the state union answers the calls a declaration closes and this one closes nothing.
  */
-export interface CommandOptions<Globals = {}> {
-    globals?: GlobalOptions<Globals>;
+export type ResultMethod<Result> = unknown extends Result ? never : 'views';
+/**
+ * The core facts and initial extension values a named Command carries.
+ */
+export interface CommandOptions {
     description?: string;
     hidden?: boolean;
     deprecated?: string;
     extensions?: readonly ExtensionValue<'command'>[];
 }
-interface CommandConstructor {
-    new (name: string): Command<{}, {}, {}, CommandMethod>;
-    new <Globals = {}>(name: string, options: CommandOptions<Globals>): Command<{}, {}, Globals, CommandMethod>;
-}
+/** Collect every union member's known local keys before testing for a global collision. */
+type LocalKeys<Child> = Child extends {
+    readonly [declaredTypes]: {
+        options: infer Options;
+    };
+} ? keyof Options : never;
+export type AttachmentConstraint<Globals, Child> = Extract<keyof Globals, LocalKeys<Child>> extends never ? unknown : never;
+type CommandConstructor = new (name: string, options?: CommandOptions) => Command<{}, {}, RegisteredGlobals, CommandMethod>;
 /** The public constructor takes a name and one options object, as the Application does. */
 export declare const Command: CommandConstructor;
 /** Every declaration in the graph, so defaults are validated before any token is read. */
@@ -213,15 +297,35 @@ export interface RoutedInvocation {
 }
 /** Consumes the globals table, then routes the remaining bare tokens to a Command. */
 export declare function routeInvocation(graph: BuiltGraph, argv: readonly string[]): RoutedInvocation;
-/**
- * The phases the middleware chain terminates in: the callable check, local parsing, validation, and
- * the action. It answers with the call that dispatches, so the caller records that the action was
- * invoked at the moment it invokes it and no earlier failure reads as a dispatch.
- */
-export declare function prepareDispatch(graph: BuiltGraph, routed: RoutedInvocation, invocation: {
+/** What one invocation reaches the middleware chain with. */
+export interface DispatchInvocation {
+    /** The channel the action receives, which the results lane builds from the routed node. */
+    channel: (binding: ResultBinding) => ActionChannel;
     defaults: DefaultValues;
     host: Host;
-    out: Out;
     signal: AbortSignal;
-}): Promise<() => unknown>;
+    style: ContextualStyle;
+}
+/**
+ * One invocation prepared ahead of the middleware chain. `'ready'` carries the request a middleware
+ * reads and the call that dispatches; `'held'` carries the fault this phase found, which core
+ * raises at the dispatch boundary and never before, so a takeover swallows it. `result` is what the
+ * routed Command declared, whose views a middleware selects among, on either shape.
+ */
+export type Prepared = {
+    result: DeclaredResult | undefined;
+} & ({
+    dispatch: (view: string | null) => Promise<void>;
+    kind: 'ready';
+    request: Request;
+} | {
+    fault: unknown;
+    kind: 'held';
+    request: null;
+});
+/**
+ * Prepares one dispatch ahead of the middleware chain and holds whatever fault it found, so a
+ * middleware reads the request before the action runs and a takeover never observes the fault.
+ */
+export declare function prepareDispatch(graph: BuiltGraph, routed: RoutedInvocation, invocation: DispatchInvocation): Promise<Prepared>;
 export {};