@loomcli/core 0.4.0 → 0.6.0

package/dist/command.d.ts

@@ -1,19 +1,30 @@
+import type { Finding } from './diagnostic-text.js';
 import type { RegisteredGlobals } from './environment.js';
-import type { DescriptorRegistry, ExtensionRecords, ExtensionValue } from './extension.js';
-import type { BuiltGlobals, GlobalsState } from './globals.js';
+import type { LoomError } from './errors.js';
+import type { AdmittedDescriptor, DescriptorRegistry, ExtensionRecords, ExtensionStore, ExtensionSubject, ExtensionValue } from './extension.js';
+import type { BuiltGlobals, GlobalsState, GlobalTable, InputRecords } from './globals.js';
+import type { CommandGraph, CommandNode } from './inspect.js';
 import { compileOptions } from './options.js';
 import type { OptionValues } from './options.js';
-import type { BuiltPlugin, PluginBuild } from './plugin.js';
+import type { BuiltPlugin } from './plugin.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';
+import type { Action, ActionChannel, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredResult, DeclaredTypes, DefaultConstraint, GlobalNameConstraint, Host, PerValueConstraint, NameConstraint, OpenResult, OptionConfig, OptionValue, Out, Request, ResultBinding, ResultViews, ResultViewsOf, RowViews, ValidateOmittedConstraint } from './types.js';
+import type { ArgumentInput, DefaultValues, InputPlaces, InputDeclaration, OptionInput, ValidatedInputs } from './validation.js';
 /** One positional slot: the declaration it fills and whether it takes the remaining tokens. */
 export interface ArgumentSlot {
     input: InputDeclaration;
     required: boolean;
     variadic: boolean;
 }
+/**
+ * What one dispatch hands its action. `graph` and `command` are the run's inspected graph and the
+ * routed node inside it, the values its middleware read. Each builds on its first read, so a run
+ * whose action reads neither, whose chain is empty, and which asks no configuration source renders
+ * no graph and calls no converter.
+ */
 export interface DispatchInput {
+    command: () => CommandNode;
+    graph: () => CommandGraph;
     style: ContextualStyle;
     host: Host;
     /** The action's channel, whose `results` accepts whatever the routed declaration named. */
@@ -57,8 +68,8 @@ export interface BuiltCommand {
 export declare const commandValue: unique symbol;
 /**
  * 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.
+ * and each call removes the names it invalidates. `command()` belongs to every Command and to the
+ * unnamed root alike, and attach bounds how deep the children it adds may nest.
  */
 export type CommandMethod = 'action' | 'alias' | 'argument' | 'command' | 'option' | 'result' | 'rows';
 /** One Command declares arguments or attaches children, so the first call removes the other. */
@@ -69,124 +80,205 @@ export type AfterCommand<State> = Exclude<State, 'argument'>;
 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 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';
-};
 /**
- * The names one `alias()` call declares. Each call keeps its own group, so a call that names none,
- * which the types reject and a JavaScript author can still write, reports as the call it is.
+ * The private handle one graph node is reached through, without its inferred declaration types:
+ * what attach and the Application's walk read, and the build that compiles the node.
  */
-type AliasDeclaration = readonly string[];
-/** The private handle one graph node is built through, without its inferred declaration types. */
-interface CommandNodeHandle {
-    readonly name: string | null;
+export interface CommandNodeHandle {
+    readonly declared: Declared;
+    readonly hasAction: boolean;
+    readonly name: string;
     build(context: BuildContext): BuiltCommand;
 }
 /**
- * One graph build's shared state. `globals` compiles once and every Command reads it. `owners`
- * records the name of the parent that claimed each node, so a second parent holding the same value
- * is building a graph with more than one path to that node, not a tree. The build is a depth-first
- * walk in attachment order, and a parent claims each child as the walk reaches it, so the first
- * owner is the parent whose attachment the walk meets first.
+ * One attached child, under the canonical name its parent's namespace holds it by, with the call
+ * that attached it, which a diagnostic about the child as a whole marks.
+ */
+export interface AttachedChild {
+    readonly name: string;
+    readonly node: CommandNodeHandle;
+    readonly placement: Finding;
+}
+/**
+ * One graph build's shared state. `globals` compiles once and every Command reads it. The build is
+ * a depth-first walk in attachment order.
  */
 interface BuildContext {
     descriptors: DescriptorRegistry;
     extensions: ExtensionRecords;
     globals: BuiltGlobals;
-    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[];
 }
+/** The handle behind a value an author built as a Command, or nothing for any other value. */
+export declare function commandNode(value: unknown): CommandNodeHandle | undefined;
+/** A call's arguments as its author wrote them: the trailing ones left undefined are dropped. */
+export declare function callArguments(...values: readonly unknown[]): readonly unknown[];
+/** A Command value as a finding prints it, which it would otherwise print as an ellipsis. */
+export declare function commandCode(name: string): object;
+/** The finding for one `command()` call that attached a child under the Command at `path`. */
+export declare function commandPlacement(path: readonly string[], child: string): Finding;
 /**
- * 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.
+ * The portable name rule, for every name an operator types as a command at a shell prompt: the
+ * application name, every Command name, and every alias. The characters are the POSIX portable
+ * filename set, and a name starts with neither `-`, which reads as an option, nor `.`, which a
+ * shell hides.
  */
+export declare function isPortableName(name: unknown): name is string;
+/** The one correction every portable name diagnostic ends with. */
+export declare const portableNameCorrection = "Use a nonempty name of A-Z, a-z, 0-9, \".\", \"_\", and \"-\" that does not start with \"-\" or \".\".";
 /**
- * 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.
+ * One call of the results lane, in the order it was made, with the arguments a finding rebuilds it
+ * from. A `result()` or `rows()` call declares the unit, and a `views()` call reshapes the views of
+ * whichever declaration it follows.
  */
 export type ResultCall = {
+    arguments: readonly unknown[];
+} & ({
     kind: 'value' | 'rows';
     views: unknown;
 } | {
     default: unknown;
     kind: 'views';
     views: unknown;
-};
+});
+/** The core facts a named Command declares, which its constructor checked. The root carries none. */
+export interface CommandFacts {
+    deprecated: string | undefined;
+    description: string | undefined;
+    hidden: boolean;
+}
+/**
+ * Everything one Command declaration holds, each part checked by the call that added it. The
+ * transitions below copy it with fields replaced, and the Command and Application builders share
+ * them, so one declaration call has one implementation.
+ */
 export interface CommandState<Args, Options, Globals> {
     /**
-     * The registered actions, with the declared result erased. An action is stored under the widest
+     * The registered action, 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[];
+    action: Action<Args, Globals & Options, OpenResult> | undefined;
+    aliases: readonly string[];
     bind: (values: ValidatedInputs) => {
         args: Args;
         options: Options;
     };
-    children: readonly object[];
-    deprecated: unknown;
-    description: unknown;
-    extensions: readonly unknown[];
-    hidden: unknown;
+    children: readonly AttachedChild[];
+    /**
+     * Every descriptor this declaration's extension values name, by identity. The root's holds the
+     * whole Application's: its plugins', its global options', and every attached subtree's.
+     */
+    descriptors: ReadonlyMap<string, AdmittedDescriptor>;
+    /** The extension values of every layer, validated at the call that carried each one. */
+    extensions: ExtensionStore;
+    facts: CommandFacts;
     inputs: readonly InputDeclaration[];
-    late: readonly LateDeclaration[];
     name: string | null;
-    options: unknown;
+    /** The extension record each input's own call validated. */
+    records: InputRecords;
     results: readonly ResultCall[];
 }
+/** The untyped part of a declaration, which every attach and build check reads. */
+export type Declared = Pick<CommandState<unknown, unknown, unknown>, 'aliases' | 'children' | 'descriptors' | 'inputs' | 'name' | 'records' | 'results'>;
+/** How the extension diagnostics of one Command's own layers name it. */
+export declare function layerOf(name: string | null): ExtensionSubject;
 /**
- * The state every declaration starts from. The unnamed root and each named Command share it.
- * The declaration values arrive captured, because a later change to the options object the author
- * passed changes nothing the declaration holds.
+ * The state every declaration starts from. The unnamed root and each named Command share it. The
+ * declaration values arrive checked, because the constructor that read them threw for any fault.
  */
 export declare function freshState<Globals>(declaration: {
-    deprecated: unknown;
-    description: unknown;
-    extensions: unknown;
-    hidden: unknown;
+    descriptors: ReadonlyMap<string, AdmittedDescriptor>;
+    extensions: ExtensionStore;
+    facts: CommandFacts;
     name: string | null;
-    options: unknown;
 }): CommandState<{}, {}, Globals>;
 /** The declared value joins `args` under its literal name, typed by its own config. */
-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>;
-/** 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>;
+export declare function declareArgument<Args, Options, Globals, Name extends string, Config extends ArgumentConfig>(state: CommandState<Args, Options, Globals>, declared: 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. The root's
+ * options also meet the Application's globals table, which a named Command meets when its subtree
+ * joins an Application.
+ */
+export declare function declareOption<Args, Options, Globals, Name extends string, Config extends OptionConfig>(state: CommandState<Args, Options, Globals>, declared: OptionInput<Name, Config>, table?: GlobalTable): CommandState<Args, Options & Record<Name, OptionValue<Config>>, Globals>;
+/**
+ * One call's names join the Command's aliases. A call that names none, which the types reject and
+ * a JavaScript author can still write, reports as the call it is.
+ */
+export declare function declareAlias<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, names: readonly string[]): CommandState<Args, Options, Globals>;
+/**
+ * Extension layers remain open after inputs and the action have been fixed. Each layer is validated
+ * at its own call, against every descriptor the declaration already names.
+ */
+export declare function declareExtensions<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, values: readonly unknown[]): 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.
+ * action for every declaration, so the context the 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. */
+/**
+ * The result declaration, which closes both result calls. Every rule its own call can judge throws
+ * here; the empty record and the default wait for attach, because `views()` can still add keys.
+ */
 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. */
+/** One Command a rule judges: the name its sentence reads, and the path its findings open with. */
+interface CommandPlace {
+    name: string | null;
+    path: readonly string[];
+}
+/** The parent one attach reads: its place, the children it holds, and the calls that close it. */
+interface AttachParent extends CommandPlace {
+    /** The first argument the parent declares, which no child may sit beside. */
+    argument: InputDeclaration | undefined;
+    children: readonly AttachedChild[];
+    hasAction: boolean;
+}
+/**
+ * The one attach operation `Command.command()`, `Application.command()`, and a plugin's
+ * `commands` list share. A Command is an immutable value, so the child is final here: it is checked
+ * as a finished Command, against the parent's current children, and against the nesting cap from
+ * the shallowest level the parent can sit at. The placement is the call that attached it, which a
+ * finding about the child as a whole marks.
+ */
+export declare function attach(parent: AttachParent, node: CommandNodeHandle, placement: Finding): AttachedChild;
+/** The handle behind the value one `command()` call received; anything else is a declaration error. */
+export declare function childNode(parent: string | null, child: unknown): CommandNodeHandle;
+/** The first place an Application holds one Command value: its parent's name and the attach call. */
+export interface ChildOwner {
+    name: string | null;
+    placement: Finding;
+}
+/** What an Application holds while a subtree joins it, each register a copy the caller commits. */
+interface JoinScope {
+    descriptors: DescriptorRegistry;
+    /** The first place that claimed each node the Application holds. */
+    owners: Map<CommandNodeHandle, ChildOwner>;
+    table: GlobalTable;
+}
+/**
+ * Attaches one child to an Application's root and walks the subtree it brings, once. The scope's
+ * registers are copies: the caller commits the owners, and the returned root holds the descriptors.
+ */
+export declare function attachToRoot<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, child: {
+    node: CommandNodeHandle;
+    placement: Finding;
+}, scope: JoinScope): CommandState<Args, Options, Globals>;
+/**
+ * A declaration's own options and every attached Command's, against a globals table that has just
+ * grown. The table's new option reads as the other side of any collision.
+ */
+export declare function checkDeclaredOptions(state: Declared, table: GlobalTable): void;
+/**
+ * Compiles one declaration for dispatch against the shared globals table. Every authored rule threw
+ * at the call or the attach that first held its data, so what can still fail here is the root's
+ * finished-Command rules, the root never being attached, and whatever the lifecycle hooks
+ * contributed.
+ */
 export declare function buildCommand<Args, Options, Globals>(state: CommandState<Args, Options, Globals>, context: BuildContext): BuiltCommand;
 /** One built graph: the shared globals table, the root Command, and the facts each node carries. */
 export interface BuiltGraph {
@@ -194,20 +286,20 @@ export interface BuiltGraph {
     globals: BuiltGlobals;
     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>, globals: GlobalsState<Globals>, install: PluginBuild & {
-    plugins: readonly BuiltPlugin[];
-}): BuiltGraph;
+/**
+ * The globals table compiles once per build and the whole graph shares it. The root's registry
+ * holds every descriptor the Application names, so a hook's `extend()` call meets all of them.
+ */
+export declare function buildGraph<Args, Options, Globals>(root: CommandState<Args, Options, Globals>, globals: GlobalsState<Globals>, plugins: readonly BuiltPlugin[]): BuiltGraph;
 export declare class CommandBuilder<Args, Options, Globals, State extends CommandMethod = CommandMethod, Result = unknown> {
     #private;
     readonly [commandValue]: true;
     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>, 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>;
+    constructor(name: string, state: CommandState<Args, Options, Globals>);
+    argument<const Name extends string, const Config extends ArgumentConfig>(name: Name, config: Config & NameConstraint<Name> & NoInfer<DefaultConstraint<Config>> & NoInfer<PerValueConstraint<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<PerValueConstraint<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
+     * Aliases are other portable names 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, Result>;
@@ -240,12 +332,6 @@ export declare class CommandBuilder<Args, Options, Globals, State extends Comman
     /** 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,
@@ -282,12 +368,31 @@ type CommandConstructor = new (name: string, options?: CommandOptions) => Comman
 export declare const Command: CommandConstructor;
 /** Every declaration in the graph, so defaults are validated before any token is read. */
 export declare function collectInputs(command: BuiltCommand): InputDeclaration[];
-/** Bare tokens, names or aliases, select children until a Command has none; a hyphen commits. */
-export declare function route(root: BuiltCommand, tokens: readonly string[]): {
+/**
+ * Where every input of one graph was declared: each global option at its `globalOption()` call,
+ * and each Command's own inputs at their calls on the Command, under its path from the root.
+ */
+export declare function inputPlaces(graph: BuiltGraph): InputPlaces;
+/**
+ * Whether a token names one of the Command's children: the Command has children and the token is
+ * no option token. Routing and `locate` read a bare word through this rule.
+ */
+export declare function readsAsChild(command: BuiltCommand, token: string): boolean;
+/**
+ * Bare tokens, names or aliases, select children until a Command has none; a hyphen commits.
+ * `walked` receives the path after each name routes, so an unknown Command leaves its caller
+ * holding the partial path walked before it.
+ */
+export declare function route(root: BuiltCommand, tokens: readonly string[], walked?: (path: readonly string[]) => void): {
     command: BuiltCommand;
     path: string[];
     tokens: string[];
 };
+/**
+ * The slot the positional at one index fills: the slot at that index, else a variadic last slot,
+ * which accepts every later positional, else none. Binding and `locate` read positions through it.
+ */
+export declare function argumentSlot(slots: readonly ArgumentSlot[], position: number): ArgumentSlot | undefined;
 /** One invocation after the pre-scan and routing, which the middleware chain runs on top of. */
 export interface RoutedInvocation {
     command: BuiltCommand;
@@ -295,24 +400,36 @@ export interface RoutedInvocation {
     scan: OptionValues;
     tokens: readonly string[];
 }
-/** Consumes the globals table, then routes the remaining bare tokens to a Command. */
-export declare function routeInvocation(graph: BuiltGraph, argv: readonly string[]): RoutedInvocation;
+/**
+ * Consumes the globals table, then routes the remaining bare tokens to a Command. `walked`
+ * receives the path as routing extends it, the partial path of an unknown Command included.
+ */
+export declare function routeInvocation(graph: BuiltGraph, argv: readonly string[], walked: (path: readonly string[]) => void): RoutedInvocation;
 /** 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;
+    /** The graph `inspect()` returns for the run, built on its first read, which a source reads. */
+    inspected: () => CommandGraph;
+    /** Offers a configuration source's foreign throw to the translators where its call settles. */
+    offer: (thrown: unknown) => LoomError | undefined;
     signal: AbortSignal;
+    /** The channel a configuration source writes through, whose results call names the source. */
+    sourceOut: Out<OpenResult>;
     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.
+ * routed Command declared, whose views a middleware selects among, on either shape. `globals` holds
+ * the globals table's values after the input-source stage, which activation and every plugin's own
+ * options read on either shape.
  */
 export type Prepared = {
+    globals: OptionValues;
     result: DeclaredResult | undefined;
 } & ({
     dispatch: (view: string | null) => Promise<void>;
@@ -326,6 +443,8 @@ export type Prepared = {
 /**
  * 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.
+ * The phases run in order: local parsing, the input-source stage, and validation. A local fault
+ * outranks a configuration source's fault, and after either one core runs no validation.
  */
 export declare function prepareDispatch(graph: BuiltGraph, routed: RoutedInvocation, invocation: DispatchInvocation): Promise<Prepared>;
 export {};