@loomcli/core 0.4.0 → 0.5.0

package/dist/chain.js

@@ -1,8 +1,8 @@
 import { prepareDispatch, routeInvocation } from './command.js';
 import { InternalError, reasonOf, routedSubject, toFailure } from './errors.js';
-import { inspectGraph } from './inspect.js';
-import { booleanValue } from './options.js';
-import { pluginSentence } from './plugin.js';
+import { inspectGraph, nodeAt } from './inspect.js';
+import { isSupplied } from './options.js';
+import { loadDefault, pluginSentence, pluginSpellings, pluginValues } 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
@@ -72,79 +72,33 @@ class ViewSelection {
 function isMiddlewareExport(value) {
     return typeof value === 'function';
 }
-/** Whether one option name was supplied as a token, in any spelling a declaration accepts. */
-function supplied(scan, name) {
-    return scan.strings.has(name) || scan.lists.has(name) || scan.booleans.has(name);
-}
-/** A collected value, or the declared array default, as this run's own copy. */
-function collectedValue(collected, declared) {
-    if (collected) {
-        return [...collected];
-    }
-    return Array.isArray(declared) ? [...declared] : [];
-}
 /**
- * One plugin's own option values for one run: what the pre-scan produced, or the declared default,
- * filled without validation. A collected value and an array default are copied, so a middleware
- * that writes to what it received changes neither the declaration nor the next run.
+ * Whether one plugin's declared activation matched. A listed option activates when argv or an input
+ * source supplied it, whatever value it holds, and a declared default never does.
  */
-function pluginValues(inputs, scan) {
-    const values = {};
-    for (const { config, name } of inputs) {
-        const declared = config.default;
-        if (config.type === 'boolean') {
-            values[name] = booleanValue(scan, name, config);
-        }
-        else if (config.multiple === true) {
-            values[name] = collectedValue(scan.lists.get(name), declared);
-        }
-        else {
-            // Build already proved that a string option without a schema declares a string default.
-            values[name] =
-                scan.strings.get(name) ?? (typeof declared === 'string' ? declared : undefined);
-        }
-    }
-    return values;
-}
-/** Whether one plugin's declared activation matched the tokens the pre-scan consumed. */
-function activates(installed, scan) {
+function activates(installed, values) {
     const { middleware } = installed;
     if (!middleware) {
         return false;
     }
-    return (middleware.activate === 'always' || middleware.activate.some((name) => supplied(scan, name)));
+    return (middleware.activate === 'always' || middleware.activate.some((name) => isSupplied(values, name)));
 }
 /**
  * The chain for one invocation: each installed plugin whose activation matched, in installation
- * order. Activation is read from the pre-scan, before any plugin code loads, so a plugin whose
- * option was never supplied is not in the chain and its loader is never called.
+ * order. Activation is read after the input-source stage and before any plugin code loads, so a
+ * plugin whose option no tier supplied is not in the chain and its loader is never called.
  */
-function activatedEntries(plugins, scan) {
+function activatedEntries(plugins, values) {
     return plugins
-        .filter((installed) => activates(installed, scan))
+        .filter((installed) => activates(installed, values))
         .map((installed) => ({
         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, scan),
+        options: pluginValues(installed.inputs, values),
+        spellings: pluginSpellings(installed.inputs, values),
     }));
 }
-/**
- * The routed node inside the inspected graph, which routing already proved reachable. A missing
- * segment means the two readings of one graph disagree, so the chain stops rather than hand a
- * middleware the wrong Command.
- */
-function nodeAt(graph, path) {
-    let node = graph.root;
-    for (const name of path) {
-        const child = node.children.find((entry) => entry.name === name);
-        if (!child) {
-            throw new InternalError(`The routed command "${path.join(' ')}" is not in the inspected graph.`, undefined);
-        }
-        node = child;
-    }
-    return node;
-}
 /** A downstream promise core awaits for its completion alone; its outcome was recorded already. */
 async function quiet(pending) {
     if (pending) {
@@ -240,25 +194,12 @@ async function settle(turn, thrown) {
     // 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. */
-async function loadModule(entry) {
-    try {
-        return await entry.load();
-    }
-    catch (error) {
-        throw new InternalError(`Loading plugin "${entry.identity}" failed: ${reasonOf(error)}`, error);
-    }
-}
 /** A plugin's module is loaded when the chain reaches it, never before. */
-async function loadMiddleware(entry) {
-    const module = await loadModule(entry);
-    const handler = module !== null && typeof module === 'object' && 'default' in module
-        ? module.default
-        : undefined;
-    if (!isMiddlewareExport(handler)) {
-        throw new InternalError(`Loading plugin "${entry.identity}" failed: the module exports no default middleware function.`, undefined);
-    }
-    return handler;
+function loadMiddleware(entry) {
+    return loadDefault(entry.identity, entry.load, {
+        guard: isMiddlewareExport,
+        noun: 'middleware',
+    });
 }
 /** One entry's turn: its module loads here, when the chain reaches it and never before. */
 async function runEntry(entry, index, chain) {
@@ -278,7 +219,7 @@ async function runEntry(entry, index, chain) {
 }
 /** The whole chain, answering with the failure it raised when a middleware caught that failure. */
 async function runChain(invocation, routed, prepared) {
-    const entries = activatedEntries(invocation.plugins, routed.scan);
+    const entries = activatedEntries(invocation.plugins, prepared.globals);
     const run = { invoked: false, raised: undefined };
     const selection = new ViewSelection(prepared.result);
     /**
@@ -304,7 +245,7 @@ async function runChain(invocation, routed, prepared) {
         return undefined;
     }
     // The graph a middleware reads is the one `inspect()` returns, built once for the run.
-    const graph = inspectGraph(invocation.name, invocation.graph, invocation.facts);
+    const graph = invocation.inspected();
     const command = nodeAt(graph, routed.path);
     // Every fault this chain has reported, so the same one raised again carries no second report.
     const announced = new WeakSet();
@@ -320,6 +261,7 @@ async function runChain(invocation, routed, prepared) {
             out: invocation.out,
             request: prepared.request,
             signal: invocation.signal,
+            spellings: entry.spellings,
             get view() {
                 return selection.read();
             },
@@ -360,8 +302,13 @@ async function runChain(invocation, routed, prepared) {
 async function runInvocation(invocation) {
     const routed = routeInvocation(invocation.graph, invocation.host.argv);
     invocation.route(routed.path);
-    const prepared = await prepareDispatch(invocation.graph, routed, invocation);
-    const raised = await runChain(invocation, routed, prepared);
+    // The graph `inspect()` returns, built at most once for the run.
+    // A configuration source reads its requests from it, and the chain reads it after the source.
+    let graph = undefined;
+    const inspected = () => (graph ??= inspectGraph(invocation.name, invocation.graph, invocation.facts));
+    const run = { ...invocation, inspected };
+    const prepared = await prepareDispatch(invocation.graph, routed, run);
+    const raised = await runChain(run, routed, prepared);
     if (raised) {
         // The chain resolved because a middleware caught the rejection.
         // The failure it caught still decides the exit code.

package/dist/command.d.ts

@@ -1,11 +1,12 @@
 import type { RegisteredGlobals } from './environment.js';
-import type { DescriptorRegistry, ExtensionRecords, ExtensionValue } from './extension.js';
-import type { BuiltGlobals, GlobalsState } from './globals.js';
+import type { AnyExtension, 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 { 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, InputDeclaration, OptionInput, ValidatedInputs } from './validation.js';
 /** One positional slot: the declaration it fills and whether it takes the remaining tokens. */
 export interface ArgumentSlot {
@@ -13,7 +14,15 @@ export interface ArgumentSlot {
     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 +66,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,57 +78,48 @@ 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 attached child, under the canonical name its parent's namespace holds it by. */
+export interface AttachedChild {
+    readonly name: string;
+    readonly node: CommandNodeHandle;
+}
 /**
- * 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 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;
 /**
- * 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.
  */
 export type ResultCall = {
     kind: 'value' | 'rows';
@@ -129,64 +129,128 @@ export type ResultCall = {
     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, AnyExtension>;
+    /** 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, AnyExtension>;
+    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>;
+/**
+ * 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>, input: 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. */
+/** The parent one attach reads: its name, the children it holds, and the calls that close it. */
+interface AttachParent {
+    /** The first argument the parent declares, which no child may sit beside. */
+    argument: string | undefined;
+    children: readonly AttachedChild[];
+    hasAction: boolean;
+    name: string | null;
+}
+/**
+ * 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.
+ */
+export declare function attach(parent: AttachParent, node: CommandNodeHandle): 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;
+/** What an Application holds while a subtree joins it, each register a copy the caller commits. */
+interface JoinScope {
+    descriptors: DescriptorRegistry;
+    /** The parent that claimed each node the Application holds, by the name a diagnostic reads. */
+    owners: Map<CommandNodeHandle, string | null>;
+    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>, node: CommandNodeHandle, 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 +258,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 +304,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 +340,22 @@ 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[];
+/**
+ * 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. */
 export declare function route(root: BuiltCommand, tokens: readonly string[]): {
     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;
@@ -303,16 +371,23 @@ export interface DispatchInvocation {
     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;
     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 +401,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 {};