@loomcli/core 0.7.0 → 0.8.0

package/dist/application.d.ts

@@ -3,10 +3,10 @@ import type { ApplicationEnvironment, applicationEnvironment } from './environme
 import type { ExtensionValue } from './extension.js';
 import type { GlobalsState } from './globals.js';
 import type { CommandGraph } from './inspect.js';
-import type { BuiltPlugin, Plugin } from './plugin.js';
+import type { BuiltPlugin, InstalledOptionValues, Plugin } from './plugin.js';
 import type { RenderingPolicy } from './rendering.js';
 import type { Translation, TranslatorRegistry } from './translators.js';
-import type { Action, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredTypes, DefaultConstraint, GlobalNameConstraint, GlobalOmissionConstraint, PerValueConstraint, NameConstraint, ExitCode, OptionConfig, OptionValue, ResultViews, ResultViewsOf, RowViews, RunOptions, ValidateOmittedConstraint } from './types.js';
+import type { Action, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredTypes, DefaultConstraint, ImpliedConstraint, GlobalNameConstraint, GlobalOmissionConstraint, PerValueConstraint, NameConstraint, ExitCode, OptionConfig, OptionValue, ResultViews, ResultViewsOf, RowViews, RunOptions, ValidateOmittedConstraint } from './types.js';
 import type { ViewContributions, ViewOverride } from './view.js';
 /**
  * Every authoring call an Application can publish, beside `run()` and `name`, which always remain.
@@ -65,15 +65,15 @@ declare class ApplicationBuilder<Args, Options, Globals, State extends Applicati
     readonly [declaredTypes]: DeclaredTypes<Args, Options, Globals, Result>;
     constructor(name: string, declared: {
         config: ApplicationConfig;
-        globals: GlobalsState<Globals>;
+        globals: GlobalsState;
         root: CommandState<Args, Options, Globals>;
     });
     get name(): string;
     argument<const Name extends string, const Config extends ArgumentConfig>(name: Name, config: Config & NameConstraint<Name> & NoInfer<DefaultConstraint<Config>> & NoInfer<PerValueConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Application<Args & Record<Name, ArgumentValue<Config>>, Options, Globals, AfterArgument<State>, Plugins, 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>>): Application<Args, Options & Record<Name, OptionValue<Config>>, Globals, State, Plugins, Result>;
+    option<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & GlobalNameConstraint<Name, Globals> & NoInfer<DefaultConstraint<Config>> & NoInfer<ImpliedConstraint<Config>> & NoInfer<PerValueConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Application<Args, Options & Record<Name, OptionValue<Config>>, Globals, State, Plugins, Result>;
     globalOption<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & (Name extends keyof Options ? {
         'This option name is already declared as a local option': Name;
-    } : unknown) & NoInfer<DefaultConstraint<Config>> & NoInfer<PerValueConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>> & NoInfer<GlobalOmissionConstraint<Config>>): Application<Args, Options, Globals & Record<Name, OptionValue<Config>>, State, Plugins, Result>;
+    } : unknown) & NoInfer<DefaultConstraint<Config>> & NoInfer<ImpliedConstraint<Config>> & NoInfer<PerValueConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>> & NoInfer<GlobalOmissionConstraint<Config>>): Application<Args, Options, Globals & Record<Name, OptionValue<Config>>, State, Plugins, Result>;
     /** Registering the action closes input authoring; extension configuration remains available. */
     action(handler: Action<Args, Globals & Options, Result>): Application<Args, Options, Globals, AfterAction, Plugins, Result>;
     /** A child arrives in any type state, because its own action is the call that finished it. */
@@ -133,9 +133,14 @@ declare class ApplicationBuilder<Args, Options, Globals, State extends Applicati
  * `Application<A, O, G>` accepts an application in any state, a finished one included.
  */
 export type Application<Args = {}, Options = {}, Globals = {}, State extends ApplicationMethod = AfterAction, Plugins extends readonly Plugin[] = readonly Plugin[], Result = unknown> = Pick<ApplicationBuilder<Args, Options, Globals, State, Plugins, Result>, typeof applicationEnvironment | typeof declaredTypes | 'extend' | 'inspect' | 'name' | 'run' | State | ResultMethod<Result>>;
+/**
+ * An Application starts with the option values its installed plugins contribute as its globals,
+ * computed once from the constructor's `plugins`, so every action reads them typed and each
+ * `globalOption()` call adds its own to them.
+ */
 interface ApplicationConstructor {
     new (name: string): Application<{}, {}, {}, ApplicationMethod, readonly []>;
-    new <const Plugins extends readonly Plugin[] = readonly []>(name: string, options: ApplicationOptions<Plugins>): Application<{}, {}, {}, ApplicationMethod, Plugins>;
+    new <const Plugins extends readonly Plugin[] = readonly []>(name: string, options: ApplicationOptions<Plugins>): Application<{}, {}, InstalledOptionValues<Plugins>, ApplicationMethod, Plugins>;
 }
 /** The core facts one Application declares, validated at construction and reported by `inspect()`. */
 interface ApplicationFacts {

package/dist/application.js

@@ -21,7 +21,7 @@ import { renderingPolicy } from './rendering.js';
 import { brokenOutputView, runOptions, viewCorrection } from './rules.js';
 import { bracketRun, cancellationCode, isCancellationEcho } from './signals.js';
 import { readTranslations, translateThrow } from './translators.js';
-import { checkDeclarations, prepareInputs } from './validation.js';
+import { checkDeclarations, prepareDeclaredValues } from './validation.js';
 import { buildViews, viewIdentities } from './view.js';
 /** The registry a failure is reported through when the application's own could not be built. */
 const noViews = [];
@@ -339,7 +339,8 @@ class ApplicationBuilder {
                     inspected();
                 }
                 const inputs = { globals: graph.globals.inputs, locals: collectInputs(graph.root) };
-                const defaults = await prepareInputs(inputs, host, inputPlaces(graph));
+                const places = inputPlaces(graph);
+                const declaredValues = await prepareDeclaredValues(inputs, host, places);
                 graphBuilt = true;
                 if (!controller.signal.aborted) {
                     /**
@@ -349,12 +350,13 @@ class ApplicationBuilder {
                     signals.install(ownedSignals(built.plugins));
                     await runInvocation({
                         channel: (binding) => invocationOutput.channel(binding),
-                        defaults,
+                        declaredValues,
                         graph,
                         host,
                         inspected,
                         offer,
                         out: output.out,
+                        places,
                         plugins: built.plugins,
                         report: (fault) => faults.push(fault),
                         route: (path) => {
@@ -583,7 +585,8 @@ function captureOptions(name, options) {
  * application's own view overrides, its translations, the rendering policy, the options slot and
  * its facts, the installed list and every rule between two plugins, the root's extension values,
  * and then each plugin's Commands, which attach to the root first, in installation order and list
- * order. Each reads the one copy of the options `captureOptions` takes.
+ * order. Each reads the one copy of the options `captureOptions` takes. The root's globals are
+ * the option values the declared `plugins` tuple contributes.
  */
 function declareApplication(name, declared) {
     const slot = captureOptions(name, declared);
@@ -651,7 +654,10 @@ function checkApplicationName(name) {
     }
     return name;
 }
-/** Constructor inference preserves the installed plugin tuple; globals start empty. */
+/**
+ * Constructor inference preserves the installed plugin tuple, and the globals start as the option
+ * values the installed plugins contribute.
+ */
 class ApplicationDeclaration extends ApplicationBuilder {
     constructor(name, options) {
         // The arguments evaluate in order, so the name is checked before any option is read.

package/dist/chain.d.ts

@@ -4,7 +4,7 @@ import type { CommandGraph, CommandNode } from './inspect.js';
 import type { BuiltPlugin, PluginOptions, PluginOptionSpellings, PluginOptionValues } from './plugin.js';
 import type { ContextualStyle } from './style.js';
 import type { ActionChannel, Host, OpenResult, Out, Request, ResultBinding } from './types.js';
-import type { DefaultValues } from './validation.js';
+import type { InputPlaces, DeclaredValues } from './validation.js';
 /**
  * What the rest of one chain did: the action ran, a later middleware took over by returning without
  * calling its own `next()`, or the run was cancelled before the action ran.
@@ -12,17 +12,21 @@ import type { DefaultValues } from './validation.js';
 type ChainOutcome = 'cancelled' | 'dispatched' | 'taken-over';
 /**
  * What one middleware receives. `graph` is the frozen graph `inspect()` returns, built once for the
- * run, and `command` is the routed node inside it. `options` holds this plugin's own option values
- * and never another plugin's or the application's globals, and `spellings` holds the spelling that
- * supplied each of them as a token, which a filled or defaulted option never has. `request` is the
- * routed Command's invocation, parsed and validated ahead of the chain, and `null` while core holds
- * a fault and on a group. `view` names the view the result renders through: it reads as the
- * declaration's default until a middleware assigns one, and as `null` on a Command that declares
- * none. The last assignment before the dispatch boundary wins, and one made after it changes
- * nothing.
+ * run, and `command` is the routed node inside it. `options` holds the validated value of every
+ * global option, the application's and every plugin's, keyed by declared name: the plugin's own
+ * options are typed from its declaration and every other key reads `unknown`, because a plugin
+ * compiles without the Application that installs it. It is `null` when a global option has a
+ * structural fault or was rejected, so a middleware never reads a global value no validator
+ * accepted, and a fault on a local option alone leaves it set. `spellings` holds the spelling that
+ * supplied each of the plugin's own options as a token, which a filled or defaulted option never
+ * has. `request` is the routed Command's invocation, parsed and validated ahead of the chain, and
+ * `null` while core holds a fault and on a group. `view` names the view the result renders
+ * through: it reads as the declaration's default until a middleware assigns one, and as `null` on
+ * a Command that declares none. The last assignment before the dispatch boundary wins, and one
+ * made after it changes nothing.
  */
 interface MiddlewareContext<Options extends PluginOptions = PluginOptions> {
-    readonly options: PluginOptionValues<Options>;
+    readonly options: (PluginOptionValues<Options> & Readonly<Record<string, unknown>>) | null;
     readonly spellings: PluginOptionSpellings<Options>;
     readonly graph: CommandGraph;
     readonly command: CommandNode;
@@ -34,12 +38,14 @@ interface MiddlewareContext<Options extends PluginOptions = PluginOptions> {
     readonly signal: AbortSignal;
     readonly next: () => Promise<ChainOutcome>;
 }
-/** Everything one invocation needs after its graph is built and its defaults are validated. */
+/**
+ * Everything one invocation needs after its graph is built and its defaults and implied values are
+ * validated.
+ */
 interface Invocation {
     style: ContextualStyle;
     /** The action's own channel, built from the routed Command's declaration when it dispatches. */
     channel: (binding: ResultBinding) => ActionChannel;
-    defaults: DefaultValues;
     graph: BuiltGraph;
     host: Host;
     /**
@@ -60,7 +66,11 @@ interface Invocation {
     out: Out<OpenResult>;
     /** The channel a configuration source receives, whose results call names the source. */
     sourceOut: Out<OpenResult>;
+    /** Where every input of the graph was declared, which a broken validator's finding rebuilds. */
+    places: InputPlaces;
     plugins: readonly BuiltPlugin[];
+    /** Every declared default and implied value, validated before any token was read. */
+    declaredValues: DeclaredValues;
     /** A fault reported after the primary outcome, which turns a would-be 0 into 1. */
     report: (fault: LoomError) => void;
     /**
@@ -71,11 +81,12 @@ interface Invocation {
     signal: AbortSignal;
 }
 /**
- * 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.
+ * Runs one invocation: routing on the global options and a parent's own options, the routed
+ * Command's words read against its table, the dispatch this invocation prepares, and the
+ * middleware chain it then runs. Only an unknown Command is raised before the chain. Parsing and validation run ahead of the chain so
+ * that a middleware reads the request, and every other 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.
  */
 declare function runInvocation(invocation: Invocation): Promise<void>;
 export type { ChainOutcome, Invocation, MiddlewareContext };

package/dist/chain.js

@@ -1,8 +1,9 @@
-import { prepareDispatch, routeInvocation } from './command.js';
+import { prepareDispatch } from './command.js';
 import { foreignFailure, InternalError, routedSubject } from './errors.js';
 import { nodeAt } from './inspect.js';
 import { isSupplied } from './options.js';
-import { loadDefault, pluginSentence, pluginSpellings, pluginValues } from './plugin.js';
+import { parseInvocation } from './parse.js';
+import { loadDefault, pluginSentence, pluginSpellings } from './plugin.js';
 import { nextMisuse, viewSelection, viewSelectionCorrection } from './rules.js';
 /**
  * The view one run selects, which is one value whichever middleware wrote it. The assignment is
@@ -96,7 +97,6 @@ function activatedEntries(plugins, values) {
         identity: installed.identity,
         // Activation proved the middleware exists, so the empty loader is never the one core calls.
         load: installed.middleware?.load ?? (() => undefined),
-        options: pluginValues(installed.inputs, values),
         spellings: pluginSpellings(installed.inputs, values),
     }));
 }
@@ -276,7 +276,7 @@ async function runChain(invocation, routed, prepared) {
             graph,
             host: invocation.host,
             next,
-            options: entry.options,
+            options: prepared.options,
             out: invocation.out,
             request: prepared.request,
             signal: invocation.signal,
@@ -312,14 +312,15 @@ async function runChain(invocation, routed, prepared) {
     return run.raised;
 }
 /**
- * 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.
+ * Runs one invocation: routing on the global options and a parent's own options, the routed
+ * Command's words read against its table, the dispatch this invocation prepares, and the
+ * middleware chain it then runs. Only an unknown Command is raised before the chain. Parsing and validation run ahead of the chain so
+ * that a middleware reads the request, and every other 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, invocation.route);
+    const routed = parseInvocation(invocation.graph, invocation.host.argv, invocation.route);
     const prepared = await prepareDispatch(invocation.graph, routed, invocation);
     let raised = undefined;
     try {

package/dist/command-rules.d.ts

@@ -18,7 +18,7 @@ declare const variadicArgumentLast: import("./diagnostic-text.js").DiagnosticRul
 declare const optionalArgumentLast: import("./diagnostic-text.js").DiagnosticRule;
 /** An `alias()` call that names no alias. */
 declare const aliasWithoutNames: import("./diagnostic-text.js").DiagnosticRule;
-/** An alias that repeats its own Command's name or another of its aliases. */
+/** An alias that repeats its own Command's or option's name or another of its aliases. */
 declare const repeatedAlias: import("./diagnostic-text.js").DiagnosticRule;
 /** A child whose name or alias repeats a sibling's name or alias. */
 declare const siblingNameTaken: import("./diagnostic-text.js").DiagnosticRule;

package/dist/command-rules.js

@@ -54,9 +54,9 @@ const aliasWithoutNames = registerRule('@loomcli/core/alias-without-names', {
     explanation: 'alias() adds each name it receives to the names that route to its Command, so a call with none adds nothing.',
     headline: 'Alias with no names',
 });
-/** An alias that repeats its own Command's name or another of its aliases. */
+/** An alias that repeats its own Command's or option's name or another of its aliases. */
 const repeatedAlias = registerRule('@loomcli/core/repeated-alias', {
-    explanation: 'A Command answers to its name and to each of its aliases, so an alias that repeats one of them routes nothing new.',
+    explanation: 'A Command or an option answers to its name and to each of its aliases, so an alias that repeats one of them adds nothing new.',
     headline: 'Alias repeats a name',
 });
 /** A child whose name or alias repeats a sibling's name or alias. */

package/dist/command.d.ts

@@ -4,12 +4,12 @@ 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 { OptionValues, SpellingTable } from './options.js';
+import type { ParsedInvocation } from './parse.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, 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';
+import type { Action, ActionChannel, ArgumentConfig, ArgumentValue, declaredTypes, DeclaredResult, DeclaredTypes, DefaultConstraint, ImpliedConstraint, GlobalNameConstraint, Host, PerValueConstraint, NameConstraint, OpenResult, OptionConfig, OptionValue, Out, Request, ResultBinding, ResultViews, ResultViewsOf, RowViews, ValidateOmittedConstraint } from './types.js';
+import type { ArgumentInput, InputPlaces, InputDeclaration, OptionInput, DeclaredValues, ValidatedInputs } from './validation.js';
 /** One positional slot: the declaration it fills and whether it takes the remaining tokens. */
 export interface ArgumentSlot {
     input: InputDeclaration;
@@ -58,7 +58,12 @@ export interface BuiltCommand {
     hidden: boolean;
     inputs: readonly InputDeclaration[];
     name: string | null;
-    options: ReturnType<typeof compileOptions>;
+    /**
+     * The one table the parser reads this Command's words against, built after every lifecycle hook
+     * ran: its own options, hook-declared ones included, and every global option. Each entry names
+     * one declaration, so a group's table holds the global options alone.
+     */
+    table: SpellingTable;
     /** 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;
@@ -290,14 +295,14 @@ export interface 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 function buildGraph<Args, Options, Globals>(root: CommandState<Args, Options, Globals>, globals: GlobalsState, 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(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>;
+    option<const Name extends string, const Config extends OptionConfig>(name: Name, config: Config & NameConstraint<Name> & GlobalNameConstraint<Name, Globals> & NoInfer<DefaultConstraint<Config>> & NoInfer<ImpliedConstraint<Config>> & NoInfer<PerValueConstraint<Config>> & NoInfer<ValidateOmittedConstraint<Config>>): Command<Args, Options & Record<Name, OptionValue<Config>>, Globals, State, Result>;
     /**
      * 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.
@@ -369,48 +374,20 @@ 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[];
 /**
- * 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.
+ * Where every input of one graph was declared: each global option at its `globalOption()` call or
+ * in its plugin's `options` record, 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;
-    path: readonly string[];
-    scan: OptionValues;
-    tokens: readonly string[];
-}
-/**
- * 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;
+    /** Where every input of the graph was declared, which a broken validator's finding rebuilds. */
+    places: InputPlaces;
+    /** Every declared default and implied value, validated before any token was read. */
+    declaredValues: DeclaredValues;
     /** 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. */
@@ -425,11 +402,14 @@ export interface DispatchInvocation {
  * 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. `globals` holds
- * the globals table's values after the input-source stage, which activation and every plugin's own
- * options read on either shape.
+ * the globals table's values after the input-source stage, which activation and each plugin's
+ * spellings read on either shape. `options` is every global option's validated value, which every
+ * middleware reads, or `null` when a global option has a structural fault or was rejected, or the
+ * values could not be read.
  */
 export type Prepared = {
     globals: OptionValues;
+    options: Readonly<Record<string, unknown>> | null;
     result: DeclaredResult | undefined;
 } & ({
     dispatch: (view: string | null) => Promise<void>;
@@ -443,8 +423,12 @@ 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.
+ * The phases run in order: the structural fault parsing held, a group's missing subcommand, the
+ * input-source stage, and validation. Either of the first two outranks a configuration source's
+ * fault, and a source's fault takes the place of every validation problem. Validation checks the
+ * global options whatever was held, so a middleware reads them after a local fault; a structural
+ * fault on a global option, a rejected global option, a source's fault, or a validator's own fault
+ * leaves `options` `null`.
  */
-export declare function prepareDispatch(graph: BuiltGraph, routed: RoutedInvocation, invocation: DispatchInvocation): Promise<Prepared>;
+export declare function prepareDispatch(graph: BuiltGraph, routed: ParsedInvocation, invocation: DispatchInvocation): Promise<Prepared>;
 export {};