@loomcli/core 0.4.0 → 0.5.0

package/dist/command.js

@@ -1,22 +1,47 @@
-var _a;
-import { commandSentence, commandSubject, DeclarationError, NonCallableCommandError, ResultError, UnexpectedArgumentError, UnknownCommandError, } from './errors.js';
-import { buildExtensions, extendStore, publishStore, storeCommandLayers, validateLayer, } from './extension.js';
+var _a, _b;
+import { checkEnvBinding, checkNoArgumentBinding } from './bindings.js';
+import { commandSentence, commandSubject, DeclarationError, InternalError, NonCallableCommandError, ResultError, UnexpectedArgumentError, UnknownCommandError, } from './errors.js';
+import { buildExtensions, extendStore, publishStore, registerDescriptor, storeCommandLayers, validateLayer, } from './extension.js';
 import { checkDeprecated, checkDescription, checkHidden, checkNoListingFacts, isPlainObject, } from './facts.js';
-import { buildGlobals, keyCollision, spellingCollision } from './globals.js';
-import { resultNode, snapshot } from './inspect.js';
-import { compileOptions, extractGlobals, mergeValues, parseInputs } from './options.js';
-import { captureConfig, validateValues } from './validation.js';
-/** Authored values register here, so the public type publishes no state to reach or replace. */
+import { buildGlobals, checkLocalOptions } from './globals.js';
+import { nodeAt, resultNode, snapshot } from './inspect.js';
+import { compileOptions, copyValues, emptyValues, extractGlobals, isOptionToken, mergeValues, parseInputs, } from './options.js';
+import { fillInputs } from './sources.js';
+import { captureConfig, checkDeclarations, validateValues } from './validation.js';
+/**
+ * The deepest level below the root a Command may sit at, and the word its diagnostic spells it with.
+ * A child of the root sits at level 1. Raising the cap relaxes a rule and breaks no application.
+ */
+const nestingCap = { depth: 2, words: 'two' };
+/**
+ * The shallowest level a parent can sit at: the root is level 0, and a named Command is attached
+ * somewhere below it, so it sits at level 1 or deeper.
+ */
+function parentLevel(name) {
+    return name === null ? 0 : 1;
+}
+/**
+ * Each authored value registers its handle here, so the public value holds no state to reach or
+ * replace.
+ */
 const nodes = new WeakMap();
-/** Reads the declarations behind an attached value; anything else is a declaration error. */
-function nodeOf(parent, child) {
-    const node = nodes.get(child);
-    if (!node) {
-        throw new DeclarationError(`${commandSentence(parent)} attaches a value that is not a Command. Attach the value returned by new Command(name).`);
-    }
-    return node;
+/**
+ * The handle one Command value registers, closed over its state. The value itself carries no
+ * member that reaches the state, so an attached Command stays final.
+ */
+function nodeHandle(name, state) {
+    return Object.freeze({
+        build: (context) => buildCommand(state, context),
+        declared: state,
+        hasAction: state.action !== undefined,
+        name,
+    });
 }
-/** Reject retired globals wiring at graph build, before any invocation reads the options. */
+/** The handle behind a value an author built as a Command, or nothing for any other value. */
+export function commandNode(value) {
+    return typeof value === 'object' && value !== null ? nodes.get(value) : undefined;
+}
+/** A named Command's options slot holds a plain options object, and never retired globals wiring. */
 function checkCommandOptions(name, options) {
     if (options !== undefined && !isPlainObject(options)) {
         throw new DeclarationError(`${commandSentence(name)} options must be an object. Supply a Command options object.`);
@@ -25,93 +50,240 @@ function checkCommandOptions(name, options) {
         throw new DeclarationError(`${commandSentence(name)} declares globals. Declare globals on the Application and register its environment.`);
     }
 }
-/** One name rule for every declared name in the graph, so a child and an argument read alike. */
+/** One name rule for an argument, option, or view name: a bare token the parser can read. */
 function isDeclaredName(name) {
     return typeof name === 'string' && Boolean(name) && !name.startsWith('-') && !/[\s=]/u.test(name);
 }
-function checkChildName(parent, name) {
-    if (!isDeclaredName(name)) {
-        throw new DeclarationError(`${commandSentence(parent)} attaches a child named "${String(name)}". Use a nonempty name without a leading hyphen, whitespace, or "=".`);
-    }
+/**
+ * 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 function isPortableName(name) {
+    return typeof name === 'string' && /^[A-Za-z0-9_][A-Za-z0-9._-]*$/u.test(name);
 }
-/** An alias is a bare token the way a child name is, so it answers to the same name rule. */
+/** The one correction every portable name diagnostic ends with. */
+export const portableNameCorrection = 'Use a nonempty name of A-Z, a-z, 0-9, ".", "_", and "-" that does not start with "-" or ".".';
+/** An alias is typed at the prompt the way a Command name is, so it answers to the portable rule. */
 function checkAliasName(command, alias) {
-    if (!isDeclaredName(alias)) {
-        throw new DeclarationError(`${commandSentence(command)} declares an alias named "${String(alias)}". Use a nonempty name without a leading hyphen, whitespace, or "=".`);
+    if (!isPortableName(alias)) {
+        throw new DeclarationError(`${commandSentence(command)} declares an alias named "${String(alias)}". ${portableNameCorrection}`);
     }
 }
+/** How the extension diagnostics of one Command's own layers name it. */
+export function layerOf(name) {
+    return { phrase: `on ${commandSubject(name)}`, sentence: commandSentence(name) };
+}
 /**
- * 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 function freshState(declaration) {
     return {
-        actions: [],
+        action: undefined,
         aliases: [],
         bind: () => ({ args: {}, options: {} }),
         children: [],
-        deprecated: declaration.deprecated,
-        description: declaration.description,
-        extensions: [declaration.extensions],
-        hidden: declaration.hidden,
+        descriptors: declaration.descriptors,
+        extensions: declaration.extensions,
+        facts: declaration.facts,
         inputs: [],
-        late: [],
         name: declaration.name,
-        options: declaration.options,
+        records: new Map(),
         results: [],
     };
 }
-/** A declaration after the action is an order fault; build reports the first one recorded. */
-function recordLate(state, declarations) {
-    return state.actions.length > 0 ? [...state.late, ...declarations] : state.late;
+/**
+ * A named Command's own declaration, checked before the value exists: the name, the options slot,
+ * the core facts, and the extension values the slot carries. A later change to the options object
+ * the author passed changes nothing the declaration holds.
+ */
+function namedState(name, options) {
+    if (!isPortableName(name)) {
+        throw new DeclarationError(`Command name "${String(name)}" is invalid. ${portableNameCorrection}`);
+    }
+    checkCommandOptions(name, options);
+    const slot = isPlainObject(options) ? options : undefined;
+    const sentence = commandSentence(name);
+    // The facts are read in the order their diagnostics have always ranked.
+    const description = checkDescription(sentence, slot?.description);
+    const hidden = checkHidden(sentence, slot?.hidden);
+    const deprecated = checkDeprecated(sentence, slot?.deprecated);
+    const descriptors = new Map();
+    const extensions = storeCommandLayers({
+        descriptors,
+        layers: [slot?.extensions],
+        subject: layerOf(name),
+    });
+    return {
+        name,
+        state: freshState({
+            descriptors,
+            extensions,
+            facts: { deprecated, description, hidden },
+            name,
+        }),
+    };
+}
+/**
+ * A declaration call after `action()` is an order fault the receiver's own earlier call makes
+ * certain. The types remove the call for a TypeScript author; a JavaScript author meets it here.
+ */
+function checkOpen(state, clause, remedy) {
+    if (state.action !== undefined) {
+        throw new DeclarationError(`${commandSentence(state.name)} ${clause} after its action. ${remedy}`);
+    }
+}
+/** The remedy a late argument or option earns. */
+const inputRemedy = 'Declare arguments and options before action().';
+/** One Command declares arguments or attaches children, whichever call came second. */
+function placementFault(name, argument, child) {
+    return new DeclarationError(`${commandSentence(name)} declares argument "${argument}" and attaches child "${child}". Move the argument into a child Command or remove the children.`);
+}
+/** The options one declaration list holds, in declaration order. */
+function optionsOf(inputs) {
+    return inputs.filter((input) => input.kind === 'option');
+}
+/** The positional slot one argument fills. */
+function slotOf(input) {
+    return {
+        input,
+        required: input.config.required === true,
+        variadic: input.config.variadic === true,
+    };
+}
+/**
+ * One input's extension values, validated at the call that declares it, and the descriptors they
+ * name joined to the declaration's own.
+ */
+function recordInput(state, input) {
+    const { name } = state;
+    const descriptors = new Map(state.descriptors);
+    const record = buildExtensions({
+        declared: input.config.extensions,
+        descriptors,
+        subject: {
+            phrase: `on ${commandSubject(name)} ${input.kind} "${input.name}"`,
+            sentence: `${commandSentence(name)} ${input.kind} "${input.name}"`,
+        },
+        target: input.kind,
+    });
+    return { descriptors, records: new Map([...state.records, [input, record]]) };
+}
+/**
+ * Every rule one argument answers at its own call: its name, a repeated name, children beside it,
+ * its place after the arguments before it, its own facts, and its declaration rules.
+ */
+function checkArgument(state, input) {
+    const { name } = state;
+    const subject = commandSubject(name);
+    if (!isDeclaredName(input.name)) {
+        throw new DeclarationError(`${commandSentence(name)} declares an argument named "${String(input.name)}". Use a nonempty name without a leading hyphen, whitespace, or "=".`);
+    }
+    const declared = state.inputs.filter((entry) => entry.kind === 'argument');
+    if (declared.some((entry) => entry.name === input.name)) {
+        throw new DeclarationError(`Argument "${input.name}" is declared more than once on ${subject}. Remove or rename the duplicate.`);
+    }
+    const child = state.children[0];
+    if (child) {
+        throw placementFault(name, input.name, child.name);
+    }
+    const previous = declared.at(-1);
+    if (previous) {
+        checkSlotOrder(slotOf(previous), slotOf(input), subject);
+    }
+    const sentence = `${commandSentence(name)} argument "${input.name}"`;
+    checkDescription(sentence, input.config.description);
+    checkNoListingFacts(sentence, input.config);
+    checkNoArgumentBinding(sentence, input.config);
+    checkDeclarations([input]);
 }
 /** The declared value joins `args` under its literal name, typed by its own config. */
 export function declareArgument(state, input) {
+    checkOpen(state, `declares argument "${input.name}"`, inputRemedy);
+    checkArgument(state, input);
+    const recorded = recordInput(state, input);
     const previous = state.bind;
     return {
         ...state,
+        ...recorded,
         bind: (values) => {
             const bound = previous(values);
             return { ...bound, args: { ...bound.args, ...values.argument(input) } };
         },
         inputs: [...state.inputs, input],
-        late: recordLate(state, [{ input, kind: 'input' }]),
     };
 }
-/** The declared value joins `options` under its literal name, typed by its own config. */
-export function declareOption(state, input) {
+/** The table a named Command's options meet at its own calls, before any Application holds it. */
+const noGlobals = { names: new Map(), options: new Map(), variables: new Map() };
+/**
+ * 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 function declareOption(state, input, table = noGlobals) {
+    checkOpen(state, `declares option "${input.name}"`, inputRemedy);
+    const sentence = `${commandSentence(state.name)} option "${input.name}"`;
+    checkDescription(sentence, input.config.description);
+    checkHidden(sentence, input.config.hidden);
+    checkDeprecated(sentence, input.config.deprecated);
+    checkEnvBinding(sentence, input.config);
+    const recorded = recordInput(state, input);
+    checkLocalOptions([...optionsOf(state.inputs), input], table, commandSubject(state.name));
+    checkDeclarations([input]);
     const previous = state.bind;
     return {
         ...state,
+        ...recorded,
         bind: (values) => {
             const bound = previous(values);
             return { ...bound, options: { ...bound.options, ...values.option(input) } };
         },
         inputs: [...state.inputs, input],
-        late: recordLate(state, [{ input, kind: 'input' }]),
     };
 }
-/** Globals close when composition starts; retain late calls for the shared build-order check. */
-export function recordGlobalOption(state, name) {
-    return {
-        ...state,
-        late: state.actions.length > 0 || state.children.length > 0
-            ? [...state.late, { kind: 'global', name }]
-            : state.late,
-    };
-}
-/** One call's names stay one group, so the empty call the types reject still reports as one. */
+/**
+ * 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 function declareAlias(state, names) {
-    return {
-        ...state,
-        aliases: [...state.aliases, names],
-        late: recordLate(state, names.map((alias) => ({ alias, kind: 'alias' }))),
-    };
+    const { name } = state;
+    const first = names[0];
+    if (first === undefined) {
+        throw new DeclarationError(`${commandSentence(name)} declares an alias with no names. Supply at least one name.`);
+    }
+    // The call's own input is judged before the receiver's state.
+    // A non-string name then reports as an alias name instead of failing to print in the order diagnostic.
+    for (const alias of names) {
+        checkAliasName(name, alias);
+    }
+    checkOpen(state, `declares alias "${first}"`, 'Declare aliases before action().');
+    const aliases = [...state.aliases];
+    for (const alias of names) {
+        if (alias === name) {
+            throw new DeclarationError(`${commandSentence(name)} declares alias "${alias}", which is its own name. Remove the alias.`);
+        }
+        if (aliases.includes(alias)) {
+            throw new DeclarationError(`${commandSentence(name)} declares alias "${alias}" twice. Remove the repeated alias.`);
+        }
+        aliases.push(alias);
+    }
+    return { ...state, aliases };
 }
-/** Extension layers remain open after inputs and the action have been fixed. */
+/**
+ * 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 function declareExtensions(state, values) {
-    return { ...state, extensions: [...state.extensions, values] };
+    const descriptors = new Map(state.descriptors);
+    const layer = validateLayer({
+        declared: values,
+        descriptors,
+        subject: layerOf(state.name),
+        target: 'command',
+    });
+    return { ...state, descriptors, extensions: extendStore(state.extensions, layer) };
 }
 /**
  * The same channel, read as the result the handler's own declaration names. The value one call
@@ -123,137 +295,201 @@ function declaredChannel(out) {
 }
 /**
  * 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 function declareAction(state, handler) {
-    const stored = (context) => handler({ ...context, out: declaredChannel(context.out) });
-    return { ...state, actions: [...state.actions, stored] };
+    if (state.action !== undefined) {
+        throw new DeclarationError(`${commandSentence(state.name)} has multiple actions. Register one action.`);
+    }
+    // The graph and the routed node stay getters, because a spread would build the graph on every run.
+    const stored = (context) => handler({
+        args: context.args,
+        get command() {
+            return context.command;
+        },
+        get graph() {
+            return context.graph;
+        },
+        host: context.host,
+        options: context.options,
+        out: declaredChannel(context.out),
+        passthrough: context.passthrough,
+        signal: context.signal,
+        style: context.style,
+    });
+    return { ...state, action: stored };
 }
-/** 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 function declareResult(state, kind, declaration) {
-    return {
-        ...state,
-        late: recordLate(state, [{ kind: 'result' }]),
-        results: [...state.results, { kind, views: recordOf(declaration, 'views') }],
-    };
+    checkOpen(state, 'declares its result', 'Declare result() or rows() before action().');
+    const results = [...state.results, { kind, views: recordOf(declaration, 'views') }];
+    mergeResult(state.name, results);
+    return { ...state, results };
 }
 /** A `views()` call reshapes views and closes nothing, so it is never a late declaration. */
 export function declareResultViews(state, replacements, options) {
-    return {
-        ...state,
-        results: [
-            ...state.results,
-            { default: recordOf(options, 'default'), kind: 'views', views: replacements },
-        ],
-    };
+    const results = [
+        ...state.results,
+        { default: recordOf(options, 'default'), kind: 'views', views: replacements },
+    ];
+    mergeResult(state.name, results);
+    return { ...state, results };
 }
-/** One property of an authoring argument, read defensively: build reports whatever it holds. */
+/** One property of an authoring argument, read defensively: the rules report whatever it holds. */
 function recordOf(declaration, key) {
     return isPlainObject(declaration) ? declaration[key] : undefined;
 }
-/** Attaching is a declaration call too, so the receiver keeps the children it already had. */
-export function attachChild(state, child) {
+/** The parent a declaration is, as attach reads it. */
+function parentOf(state) {
     return {
-        ...state,
-        children: [...state.children, child],
-        late: recordLate(state, [{ child, kind: 'child' }]),
+        argument: state.inputs.find((input) => input.kind === 'argument')?.name,
+        children: state.children,
+        hasAction: state.action !== undefined,
+        name: state.name,
     };
 }
-/** The types remove a late call for TypeScript authors; JavaScript authors read it here. */
-function checkDeclarationOrder(state) {
-    const { name } = state;
-    const late = state.late[0];
-    if (!late) {
-        return;
+/**
+ * One parent's namespace, which every canonical name and alias under it shares. The rule reads the
+ * same whichever sibling the author attached first.
+ */
+function checkSiblings(parent, child) {
+    const sentence = commandSentence(parent.name);
+    const { children } = parent;
+    if (children.some((entry) => entry.name === child.name)) {
+        throw new DeclarationError(`${sentence} attaches two children named "${child.name}". Rename or remove one.`);
+    }
+    for (const alias of child.node.declared.aliases) {
+        if (children.some((entry) => entry.name === alias)) {
+            throw new DeclarationError(`${sentence} attaches child "${child.name}" with alias "${alias}", which is also the name of child "${alias}". Rename or remove one.`);
+        }
+        const owner = children.find((entry) => entry.node.declared.aliases.includes(alias));
+        if (owner) {
+            throw new DeclarationError(`${sentence} attaches child "${child.name}" with alias "${alias}", which is also an alias of child "${owner.name}". Rename or remove one.`);
+        }
     }
-    if (late.kind === 'global') {
-        throw new DeclarationError(`The Application declares global option "${late.name}" after command() or action(). Declare global options before attaching Commands or registering an action.`);
+    const aliased = children.find((entry) => entry.node.declared.aliases.includes(child.name));
+    if (aliased) {
+        throw new DeclarationError(`${sentence} attaches child "${aliased.name}" with alias "${child.name}", which is also the name of child "${child.name}". Rename or remove one.`);
     }
-    if (late.kind === 'input') {
-        throw new DeclarationError(`${commandSentence(name)} declares ${late.input.kind} "${late.input.name}" after its action. Declare arguments and options before action().`);
+}
+/**
+ * A child at the cap holds no children. Attach reads the child at the shallowest level its parent
+ * can sit at, and the Application's join reads every node at its level below the root.
+ */
+function checkNesting(parent, child, level) {
+    if (level >= nestingCap.depth && child.node.declared.children.length > 0) {
+        throw new DeclarationError(`${commandSentence(parent)} attaches child "${child.name}", which has children of its own. Nest Commands at most ${nestingCap.words} levels below the root.`);
     }
-    if (late.kind === 'alias') {
-        throw new DeclarationError(`${commandSentence(name)} declares alias "${late.alias}" after its action. Declare aliases before action().`);
+}
+/**
+ * A Command without an action is a group, and routing sends an invocation on to one of its
+ * children. A group with no children receives an invocation no handler can answer, and a local
+ * option on a group reaches no handler either, because locals never inherit.
+ */
+function checkGroup(state) {
+    const { name } = state;
+    if (state.children.length === 0) {
+        throw new DeclarationError(`${commandSentence(name)} has no action. Register an action.`);
     }
-    if (late.kind === 'result') {
-        throw new DeclarationError(`${commandSentence(name)} declares its result after its action. Declare result() or rows() before action().`);
+    const option = state.inputs.find((input) => input.kind === 'option');
+    if (option) {
+        throw new DeclarationError(`${commandSentence(name)} declares option "${option.name}" but registers no action to receive it. Register an action or remove the option.`);
     }
-    // Child identity and names are settled before this call, so the node and its name are valid.
-    throw new DeclarationError(`${commandSentence(name)} attaches child "${String(nodeOf(name, late.child).name)}" after its action. Attach children before action().`);
 }
-/** Child names are checked before any child builds, so parent diagnostics come first. */
-function collectChildren(state) {
-    const attached = [];
-    const seen = new Set();
-    for (const child of state.children) {
-        const node = nodeOf(state.name, child);
-        const name = node.name;
-        checkChildName(state.name, name);
-        if (seen.has(name)) {
-            throw new DeclarationError(`${commandSentence(state.name)} attaches two children named "${name}". Rename or remove one.`);
-        }
-        seen.add(name);
-        attached.push([name, node]);
+/**
+ * The rules a finished Command answers, which attach applies to a child and build to the root: a
+ * result needs an action, its merged views record names at least one view and its default, and a
+ * Command without an action is a group. It answers with the resolved result.
+ */
+function checkFinished(declared, hasAction) {
+    const result = buildResult(declared, hasAction);
+    if (!hasAction) {
+        checkGroup(declared);
     }
-    return attached;
+    return result;
 }
 /**
- * A Command's own alias rules, and the flat list in declaration order that routing and inspection
- * read. Each call keeps its own group, so a call that names none reports as the call it is.
+ * 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.
  */
-function collectAliases(state) {
-    const { name } = state;
-    const aliases = [];
-    const seen = new Set();
-    for (const declaration of state.aliases) {
-        if (declaration.length === 0) {
-            throw new DeclarationError(`${commandSentence(name)} declares an alias with no names. Supply at least one name.`);
-        }
-        for (const alias of declaration) {
-            checkAliasName(name, alias);
-            if (alias === name) {
-                throw new DeclarationError(`${commandSentence(name)} declares alias "${alias}", which is its own name. Remove the alias.`);
-            }
-            if (seen.has(alias)) {
-                throw new DeclarationError(`${commandSentence(name)} declares alias "${alias}" twice. Remove the repeated alias.`);
-            }
-            seen.add(alias);
-            aliases.push(alias);
-        }
+export function attach(parent, node) {
+    const { name } = node;
+    if (parent.hasAction) {
+        throw new DeclarationError(`${commandSentence(parent.name)} attaches child "${name}" after its action. Attach children before action().`);
+    }
+    if (parent.argument !== undefined) {
+        throw placementFault(parent.name, parent.argument, name);
+    }
+    checkFinished(node.declared, node.hasAction);
+    const child = { name, node };
+    checkSiblings(parent, child);
+    checkNesting(parent.name, child, parentLevel(parent.name) + 1);
+    return child;
+}
+/** The handle behind the value one `command()` call received; anything else is a declaration error. */
+export function childNode(parent, child) {
+    const node = commandNode(child);
+    if (!node) {
+        throw new DeclarationError(`${commandSentence(parent)} attaches a value that is not a Command. Attach the value returned by new Command(name).`);
     }
-    return aliases;
+    return node;
+}
+/** Attaching is a declaration call too, so the receiver keeps the children it already had. */
+function attachChild(state, child) {
+    const attached = attach(parentOf(state), childNode(state.name, child));
+    return { ...state, children: [...state.children, attached] };
 }
 /**
- * One parent's namespace, which every canonical name and alias under it shares. Each child settled
- * its own alias rules while it built, so what is left is the collision with a sibling. The names are
- * read before the walk, so the rule reads the same whichever sibling the author declared first.
+ * Walks one subtree joining an Application, once, for the rules only the Application can judge: one
+ * Command value reached through two paths, two distinct descriptors under one identity, a local
+ * option that meets a global or plugin option's key, spelling, or variable, and the nesting cap
+ * measured from the root. A claim is by node identity, and the name serves the diagnostic alone.
+ * At a cap of two a named parent's `command()` already rejects every deeper tree, so the depth check
+ * here fires only once the cap rises: attach reads one level, and only this walk knows each level.
  */
-function aliasNamespace(parent, names) {
-    const owners = new Map();
-    return function claim(child, alias) {
-        if (names.has(alias)) {
-            throw new DeclarationError(`${commandSentence(parent)} attaches child "${child}" with alias "${alias}", which is also the name of child "${alias}". Rename or remove one.`);
-        }
-        const owner = owners.get(alias);
-        if (owner !== undefined) {
-            throw new DeclarationError(`${commandSentence(parent)} attaches child "${child}" with alias "${alias}", which is also an alias of child "${owner}". Rename or remove one.`);
-        }
-        owners.set(alias, child);
-    };
+function joinSubtree(scope, child, { level, parent }) {
+    const { name, node } = child;
+    checkNesting(parent, child, level);
+    if (scope.owners.has(node)) {
+        throw new DeclarationError(`${commandSentence(parent)} attaches child "${name}", which ${commandSubject(scope.owners.get(node) ?? null)} also attaches. Attach a Command value at one point; create a new Command for each placement.`);
+    }
+    scope.owners.set(node, parent);
+    for (const descriptor of node.declared.descriptors.values()) {
+        registerDescriptor(scope.descriptors, descriptor);
+    }
+    checkLocalOptions(optionsOf(node.declared.inputs), scope.table, commandSubject(name));
+    for (const entry of node.declared.children) {
+        joinSubtree(scope, entry, { level: level + 1, parent: name });
+    }
 }
 /**
- * Claims a child for its parent when the depth-first walk reaches it, then builds its subtree. A
- * claimed node always means a second parent, because the duplicate-name rule rejects one parent
- * attaching a value twice. Parents may share a name, so the claim is by node identity and the name
- * serves the diagnostic alone.
+ * 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.
  */
-function buildChild(parent, [name, node], context) {
-    const owner = context.owners.get(node);
-    if (owner !== undefined) {
-        throw new DeclarationError(`${commandSentence(parent)} attaches child "${name}", which ${commandSubject(owner)} also attaches. Attach a Command value at one point; create a new Command for each placement.`);
+export function attachToRoot(state, node, scope) {
+    const attached = attach(parentOf(state), node);
+    joinSubtree(scope, attached, { level: parentLevel(state.name) + 1, parent: state.name });
+    return { ...state, children: [...state.children, attached], descriptors: scope.descriptors };
+}
+/** Every attached Command's local options against a globals table that has just grown. */
+function checkAttachedOptions(table, children) {
+    for (const { name, node } of children) {
+        checkLocalOptions(optionsOf(node.declared.inputs), table, commandSubject(name));
+        checkAttachedOptions(table, node.declared.children);
     }
-    context.owners.set(node, parent);
-    return node.build({ ...context, path: [...context.path, name] });
+}
+/**
+ * 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 function checkDeclaredOptions(state, table) {
+    checkLocalOptions(optionsOf(state.inputs), table, commandSubject(state.name));
+    checkAttachedOptions(table, state.children);
 }
 /** A variadic or optional slot ends the positional list, so nothing may follow either one. */
 function checkSlotOrder(slot, next, subject) {
@@ -266,6 +502,10 @@ function checkSlotOrder(slot, next, subject) {
             : `Argument "${next.input.name}" follows optional argument "${slot.input.name}" on ${subject}. Declare an optional argument last.`);
     }
 }
+/**
+ * The positional slots one declaration holds. Every authored argument answered these rules at its
+ * own call, so they throw here only for an argument a lifecycle hook declared.
+ */
 function collectArguments(state, subject) {
     const slots = [];
     const seen = new Set();
@@ -277,11 +517,7 @@ function collectArguments(state, subject) {
             throw new DeclarationError(`Argument "${input.name}" is declared more than once on ${subject}. Remove or rename the duplicate.`);
         }
         seen.add(input.name);
-        slots.push({
-            input,
-            required: input.config.required === true,
-            variadic: input.config.variadic === true,
-        });
+        slots.push(slotOf(input));
     }
     for (let index = 0; index + 1 < slots.length; index += 1) {
         const slot = slots[index];
@@ -293,47 +529,8 @@ function collectArguments(state, subject) {
     return slots;
 }
 /**
- * One Command's own options against the shared globals table. The table holds the application's
- * globals and every plugin option, so a local collision reads the same sentence whichever scope on
- * the other side claimed the name or the spelling.
- */
-function compileLocalOptions(state, globals, subject) {
-    const declarations = state.inputs.filter((input) => input.kind === 'option');
-    const local = { kind: 'local', subject };
-    const application = { kind: 'application' };
-    for (const declaration of declarations) {
-        const claimed = globals.names.get(declaration.name);
-        if (claimed) {
-            throw keyCollision(declaration.name, claimed, local);
-        }
-    }
-    const options = compileOptions(declarations, subject);
-    for (const [spelling, option] of options) {
-        const global = globals.options.get(spelling);
-        if (global) {
-            throw spellingCollision(spelling, { name: global.name, owner: globals.names.get(global.name) ?? application }, { name: option.name, owner: local });
-        }
-    }
-    return options;
-}
-/**
- * A Command without an action is a group, and routing sends an invocation on to one of its
- * children. A group with no children receives an invocation no handler can answer, and a local
- * option on a group reaches no handler either, because locals never inherit.
- */
-function checkGroup(state, children) {
-    const { name } = state;
-    if (children.length === 0) {
-        throw new DeclarationError(`${commandSentence(name)} has no action. Register an action.`);
-    }
-    const option = state.inputs.find((input) => input.kind === 'option');
-    if (option) {
-        throw new DeclarationError(`${commandSentence(name)} declares option "${option.name}" but registers no action to receive it. Register an action or remove the option.`);
-    }
-}
-/**
- * A view name is a bare token the way a child name is, and never an array index, because an
- * integer-like key does not keep the position the author gave it.
+ * A view name is a bare token the way an argument or option name is, and never an array index,
+ * because an integer-like key does not keep the position the author gave it.
  */
 function isViewName(name) {
     return isDeclaredName(name) && !/^(?:0|[1-9]\d*)$/u.test(name);
@@ -386,15 +583,14 @@ function resultView(declaration, name, entry) {
     throw new DeclarationError(`${sentence} names view "${name}" with a value that is not a view. Supply a view with render or a row view with row.`);
 }
 /**
- * Every rule the results lane carries, applied to one Command's calls in the order it made them.
- * The merged record is what the rules read: a later `views()` call replaces a key in place and
- * appends a new one, so each name keeps the position the call that first named it gave it. A
- * `default` once named persists through later calls that name none, and the first key answers
- * until one is named.
+ * Every rule a results-lane call can judge on its own, applied to one Command's calls in the order
+ * it made them. The merged record is what the rules read: a later `views()` call replaces a key in
+ * place and appends a new one, so each name keeps the position the call that first named it gave
+ * it. A `default` once named persists through later calls that name none.
  */
-function buildResult(state, hasAction) {
-    const sentence = commandSentence(state.name);
-    const declarations = state.results.filter((call) => call.kind !== 'views');
+function mergeResult(name, results) {
+    const sentence = commandSentence(name);
+    const declarations = results.filter((call) => call.kind !== 'views');
     if (declarations.length > 1) {
         throw new DeclarationError(`${sentence} declares two results. Declare one result() or rows() call.`);
     }
@@ -402,28 +598,41 @@ function buildResult(state, hasAction) {
     // A `views()` call reshapes a result's views, so one with no result reshapes nothing.
     // The types publish the call where a result is carried, so this reaches a JavaScript author.
     if (!declaration) {
-        if (state.results.length > 0) {
+        if (results.length > 0) {
             throw new DeclarationError(`${sentence} reshapes its views and declares no result. Declare result() or rows() before action().`);
         }
         return undefined;
     }
-    if (!hasAction) {
-        throw new DeclarationError(`${sentence} declares a result and no action. Register an action or remove the result.`);
-    }
     const views = new Map();
     let selected = undefined;
-    for (const call of state.results) {
-        for (const [name, entry] of recordEntries(call.views)) {
-            const view = resultView({ kind: declaration.kind, sentence }, name, entry);
-            if (!isViewName(name)) {
-                throw new DeclarationError(`${sentence} names view "${name}". Use a nonempty name without whitespace, a leading hyphen, or "=", and not a number.`);
+    for (const call of results) {
+        for (const [key, entry] of recordEntries(call.views)) {
+            const view = resultView({ kind: declaration.kind, sentence }, key, entry);
+            if (!isViewName(key)) {
+                throw new DeclarationError(`${sentence} names view "${key}". Use a nonempty name without whitespace, a leading hyphen, or "=", and not a number.`);
             }
-            views.set(name, view);
+            views.set(key, view);
         }
         if (call.kind === 'views') {
             selected = selectedKey(call.default) ?? selected;
         }
     }
+    return { kind: declaration.kind, selected, views };
+}
+/**
+ * The finished result: the merged record, which needs an action, at least one view, and a default
+ * that names one of them. The first key answers until one is named.
+ */
+function buildResult(declared, hasAction) {
+    const merged = mergeResult(declared.name, declared.results);
+    if (!merged) {
+        return undefined;
+    }
+    const sentence = commandSentence(declared.name);
+    if (!hasAction) {
+        throw new DeclarationError(`${sentence} declares a result and no action. Register an action or remove the result.`);
+    }
+    const { selected, views } = merged;
     const first = views.keys().next();
     if (first.done === true) {
         throw new DeclarationError(`${sentence} declares a result with no views. Name at least one view.`);
@@ -431,7 +640,7 @@ function buildResult(state, hasAction) {
     if (selected !== undefined && !views.has(selected)) {
         throw new DeclarationError(`${sentence} selects default view "${selected}", which it does not name. Name the view or select a named one.`);
     }
-    return { default: selected ?? first.value, kind: declaration.kind, views };
+    return { default: selected ?? first.value, kind: merged.kind, views };
 }
 /** The values one build made, so a value a hook returns is one of them and never a forged shape. */
 const attachments = new WeakMap();
@@ -581,8 +790,8 @@ function runAttachHooks(start, facts, plugins) {
 }
 /**
  * One input a hook declared. It joins the values an action reads at run time and the declaration's
- * types not at all, and it records no late declaration, because a hook's calls are exempt from the
- * closures `action()` applies.
+ * types not at all, and it skips the order checks an authoring call makes, because a hook's calls
+ * are exempt from the closures `action()` applies.
  */
 function declareHookInput(state, input) {
     const previous = state.bind;
@@ -727,17 +936,23 @@ function checkAttachedInputs(declared, attached, globals) {
 }
 /** Binds one Command's declarations to its action, so an action reads only validated values. */
 function bindDispatch(state, action, globals) {
-    return ({ host, out, passthrough, signal, style, values }) => {
+    return ({ command, graph, host, out, passthrough, signal, style, values }) => {
         const bound = state.bind(values);
         // Last resort: no typed path exists.
         // The graph erases the binder's generic relationship.
         // It holds because attachment checks the global output requirement.
-        // Graph build rejects a collision between a global and a local.
+        // The call or the attach that met both options rejected a collision between a global and a local.
         // This binder returns the Application's validated globals alone.
         // oxlint-disable-next-line typescript/no-unsafe-type-assertion
         const globalOptions = globals.bind(values);
         return action({
             args: bound.args,
+            get command() {
+                return command();
+            },
+            get graph() {
+                return graph();
+            },
             host,
             options: { ...globalOptions, ...bound.options },
             out,
@@ -747,7 +962,10 @@ function bindDispatch(state, action, globals) {
         });
     };
 }
-/** Each declaration's own facts and extension values, whichever scope declared it. */
+/**
+ * The own facts and extension values of each input a lifecycle hook declared, which the calls that
+ * declared the author's inputs already checked.
+ */
 function checkInputFacts(inputs, command, context) {
     const { name, subject } = command;
     for (const input of inputs) {
@@ -755,10 +973,12 @@ function checkInputFacts(inputs, command, context) {
         checkDescription(sentence, input.config.description);
         if (input.kind === 'argument') {
             checkNoListingFacts(sentence, input.config);
+            checkNoArgumentBinding(sentence, input.config);
         }
         else {
             checkHidden(sentence, input.config.hidden);
             checkDeprecated(sentence, input.config.deprecated);
+            checkEnvBinding(sentence, input.config);
         }
         context.extensions.set(input, buildExtensions({
             declared: input.config.extensions,
@@ -771,45 +991,32 @@ function checkInputFacts(inputs, command, context) {
 /** One Command declares arguments or attaches children, whichever declaration made each of them. */
 function checkArgumentPlacement(name, slot, child) {
     if (slot && child) {
-        throw new DeclarationError(`${commandSentence(name)} declares argument "${slot.input.name}" and attaches child "${child[0]}". Move the argument into a child Command or remove the children.`);
+        throw placementFault(name, slot.input.name, child.name);
     }
 }
-/** Validates one declaration against the shared globals table and compiles it for dispatch. */
+/**
+ * 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 function buildCommand(state, context) {
-    const { actions, name } = state;
+    const { action, facts, name } = state;
     const { globals } = context;
     const subject = commandSubject(name);
-    const layer = { phrase: `on ${subject}`, sentence: commandSentence(name) };
-    checkCommandOptions(name, state.options);
-    const description = checkDescription(commandSentence(name), state.description);
-    const hidden = checkHidden(commandSentence(name), state.hidden);
-    const deprecated = checkDeprecated(commandSentence(name), state.deprecated);
-    // The author's layers validate before any hook runs on this Command, so a hook reads them.
-    const declaredExtensions = storeCommandLayers({
-        descriptors: context.descriptors,
-        layers: state.extensions,
-        subject: layer,
-    });
-    // Each declaration's own facts, in authoring order, before the rules that pair declarations.
-    checkInputFacts(state.inputs, { name, subject }, context);
-    const attached = collectChildren(state);
-    checkDeclarationOrder(state);
-    const aliases = collectAliases(state);
-    const declaredSlots = collectArguments(state, subject);
-    checkArgumentPlacement(name, declaredSlots[0], attached[0]);
-    if (actions.length > 1) {
-        throw new DeclarationError(`${commandSentence(name)} has multiple actions. Register one action.`);
+    const layer = layerOf(name);
+    for (const [input, record] of state.records) {
+        context.extensions.set(input, record);
     }
-    const action = actions[0];
+    const declaredSlots = collectArguments(state, subject);
     const hasAction = action !== undefined;
-    const declaredResult = buildResult(state, hasAction);
     /**
-     * The hooks run once the author's declaration is complete and its result is resolved, so a hook
-     * reads an exact record, and every rule below reads what the hooks returned.
+     * The hooks run once the author's declaration is complete, and each value a hook receives resolves
+     * its result, so a hook reads an exact record. Every rule below reads what the hooks returned.
      */
     // One token per Command per build, which binds a hook's return to the value it received.
     const lineage = {};
-    const progress = runAttachHooks({ declared: state, extensions: declaredExtensions, layer, registry: context.descriptors }, { hasAction, lineage, path: context.path }, context.plugins);
+    const progress = runAttachHooks({ declared: state, extensions: state.extensions, layer, registry: context.descriptors }, { hasAction, lineage, path: context.path }, context.plugins);
     const { calls } = progress;
     // The descriptors the returned value's extensions registered join the build's registry.
     for (const [identity, descriptor] of progress.registry) {
@@ -821,37 +1028,36 @@ export function buildCommand(state, context) {
     // The hook-declared names are checked first, so a collision reports in the plugin's voice.
     // A rule the author's own declaration voices never speaks for a name a hook declared.
     checkAttachedInputs(hooked, hookInputs, globals);
-    // Every value was validated once, the author's above and each hook's at its `extend()` call.
+    // Every value was validated once, the author's at each call and each hook's at its `extend()`.
     const extensions = publishStore(progress.extensions);
     const slots = hookInputs.length > 0 ? collectArguments(hooked, subject) : declaredSlots;
-    checkArgumentPlacement(name, slots[0], attached[0]);
-    const result = calls.length > 0 ? buildResult(hooked, hasAction) : declaredResult;
-    if (!action) {
-        checkGroup(hooked, attached);
-    }
-    const options = compileLocalOptions(hooked, globals, subject);
+    checkArgumentPlacement(name, slots[0], state.children[0]);
+    const result = checkFinished(hooked, hasAction);
+    const options = checkLocalOptions(optionsOf(hooked.inputs), globals, subject);
+    // A hook's erased calls answer the declaration rules an authored call answers at the call.
+    checkDeclarations(hookInputs.map((call) => call.input));
     const children = new Map();
     const routes = new Map();
-    const claim = aliasNamespace(name, new Set(attached.map((entry) => entry[0])));
-    for (const entry of attached) {
-        // The subtree builds before its aliases are claimed, so the tree rule keeps its precedence.
-        const routed = { command: buildChild(name, entry, context), name: entry[0] };
+    for (const child of state.children) {
+        const routed = {
+            command: child.node.build({ ...context, path: [...context.path, child.name] }),
+            name: child.name,
+        };
         children.set(routed.name, routed.command);
         routes.set(routed.name, routed);
         for (const alias of routed.command.aliases) {
-            claim(routed.name, alias);
             routes.set(alias, routed);
         }
     }
     return {
-        aliases,
+        aliases: state.aliases,
         arguments: slots,
         children,
-        deprecated,
-        description,
+        deprecated: facts.deprecated,
+        description: facts.description,
         dispatch: action ? bindDispatch(hooked, action, globals) : undefined,
         extensions,
-        hidden,
+        hidden: facts.hidden,
         inputs: hooked.inputs,
         name,
         options,
@@ -859,30 +1065,31 @@ export function buildCommand(state, context) {
         routes,
     };
 }
-/** The globals table and the owners record each compile once per invocation and the whole graph shares them. */
-export function buildGraph(root, globals, install) {
+/**
+ * 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 function buildGraph(root, globals, plugins) {
+    const extensions = new Map([
+        ...globals.records,
+        ...plugins.flatMap((installed) => [...installed.records]),
+    ]);
     const context = {
-        descriptors: install.descriptors,
-        extensions: install.extensions,
-        globals: buildGlobals(globals, install.plugins, install),
-        owners: new Map(),
+        descriptors: new Map(root.descriptors),
+        extensions,
+        globals: buildGlobals(globals, plugins),
         path: [],
-        plugins: install.plugins,
-    };
-    return {
-        extensions: context.extensions,
-        globals: context.globals,
-        root: buildCommand(root, context),
+        plugins,
     };
+    return { extensions, globals: context.globals, root: buildCommand(root, context) };
 }
 export class CommandBuilder {
+    #name;
     #state;
-    constructor(state) {
+    constructor(name, state) {
+        this.#name = name;
         this.#state = state;
-        nodes.set(this, this);
-    }
-    get name() {
-        return this.#state.name;
+        nodes.set(this, nodeHandle(name, state));
     }
     argument(name, config) {
         const input = {
@@ -890,7 +1097,7 @@ export class CommandBuilder {
             kind: 'argument',
             name,
         };
-        return this.derive(declareArgument(this.#state, input));
+        return this.#derive(declareArgument(this.#state, input));
     }
     option(name, config) {
         const input = {
@@ -898,66 +1105,61 @@ export class CommandBuilder {
             kind: 'option',
             name,
         };
-        return this.derive(declareOption(this.#state, input));
+        return this.#derive(declareOption(this.#state, input));
     }
     /**
-     * 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) {
-        return this.derive(declareAlias(this.#state, names));
+        return this.#derive(declareAlias(this.#state, names));
     }
     /** A child arrives in any type state, because its own action is the call that finished it. */
     command(child) {
-        return this.derive(attachChild(this.#state, child));
+        return this.#derive(attachChild(this.#state, child));
     }
     /**
      * 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(declaration) {
-        return this.derive(declareResult(this.#state, 'value', declaration));
+        return this.#derive(declareResult(this.#state, 'value', declaration));
     }
     /** The same declaration over a sequence, whose type argument is one row. */
     rows(declaration) {
-        return this.derive(declareResult(this.#state, 'rows', declaration));
+        return this.#derive(declareResult(this.#state, 'rows', declaration));
     }
     /**
      * 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, options) {
-        return this.derive(declareResultViews(this.#state, replacements, options));
+        return this.#derive(declareResultViews(this.#state, replacements, options));
     }
     /** The action closes input authoring; `extend()` remains outside this state transition. */
     action(handler) {
-        return this.derive(declareAction(this.#state, handler));
+        return this.#derive(declareAction(this.#state, handler));
     }
     extend(...values) {
-        return this.derive(declareExtensions(this.#state, values));
-    }
-    build(context) {
-        return buildCommand(this.#state, context);
+        return this.#derive(declareExtensions(this.#state, values));
     }
     /**
      * 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.
      */
-    derive(state) {
-        return new CommandBuilder(state);
+    #derive(state) {
+        return new _b(this.#name, state);
     }
 }
-/** The constructor uses the Application registration; public type defaults stay library-neutral. */
+_b = CommandBuilder;
+/**
+ * The constructor uses the Application registration; public type defaults stay library-neutral.
+ * Every rule on the name and the options slot throws before the value exists.
+ */
 class CommandDeclaration extends CommandBuilder {
     constructor(name, options) {
-        super(freshState({
-            deprecated: options?.deprecated,
-            description: options?.description,
-            extensions: options?.extensions,
-            hidden: options?.hidden,
-            name,
-            options,
-        }));
+        const declared = namedState(name, options);
+        super(declared.name, declared.state);
     }
 }
 /** The public constructor takes a name and one options object, as the Application does. */
@@ -977,14 +1179,20 @@ export function collectInputs(command) {
 function candidatesOf(command) {
     return [...command.children].filter(([, child]) => !child.hidden).map(([name]) => name);
 }
+/**
+ * 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 function readsAsChild(command, token) {
+    return command.children.size > 0 && !isOptionToken(token);
+}
 /** Bare tokens, names or aliases, select children until a Command has none; a hyphen commits. */
 export function route(root, tokens) {
     let command = root;
     const path = [];
     let index = 0;
-    while (command.children.size > 0) {
-        const token = tokens[index];
-        if (token === undefined || token === '--' || token.startsWith('-')) {
+    for (let token = tokens[index]; token !== undefined; token = tokens[index]) {
+        if (!readsAsChild(command, token)) {
             break;
         }
         const child = command.routes.get(token);
@@ -1005,29 +1213,33 @@ export function route(root, tokens) {
  */
 function bindArguments(command, path, positionals) {
     const values = new Map();
-    let index = 0;
-    for (const slot of command.arguments) {
-        if (slot.variadic) {
-            const rest = positionals.slice(index);
-            // An empty tail binds nothing, so validation reads it as `[]` or reports the omission.
-            if (rest.length > 0) {
-                values.set(slot.input, rest);
-            }
-            index = positionals.length;
+    for (const [position, token] of positionals.entries()) {
+        const slot = argumentSlot(command.arguments, position);
+        if (!slot) {
+            throw new UnexpectedArgumentError(path, command.arguments.length, positionals.slice(position));
+        }
+        // An empty variadic tail binds nothing, so validation reads it as `[]` or reports the omission.
+        const bound = values.get(slot.input);
+        if (!slot.variadic) {
+            values.set(slot.input, token);
+        }
+        else if (Array.isArray(bound)) {
+            bound.push(token);
         }
         else {
-            const value = positionals[index];
-            if (value !== undefined) {
-                values.set(slot.input, value);
-                index += 1;
-            }
+            values.set(slot.input, [token]);
         }
     }
-    if (index < positionals.length) {
-        throw new UnexpectedArgumentError(path, command.arguments.length, positionals.slice(index));
-    }
     return values;
 }
+/**
+ * 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 function argumentSlot(slots, position) {
+    const last = slots.at(-1);
+    return slots[position] ?? (last?.variadic ? last : undefined);
+}
 /** Consumes the globals table, then routes the remaining bare tokens to a Command. */
 export function routeInvocation(graph, argv) {
     const scan = extractGlobals(graph.globals.options, [...argv]);
@@ -1060,37 +1272,103 @@ function requestOf(command, values, passthrough) {
     });
 }
 /**
- * The phases that run ahead of the chain: the callable check, local parsing, and validation. 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.
+ * The callable check and local parsing. A group answers no invocation of its own, so it holds the
+ * missing-subcommand error with the rank the routing errors have and parses no token; a token
+ * fault holds the same way.
  */
-async function readyDispatch(graph, routed, invocation) {
-    const { command, path, scan } = routed;
+function parseLocal(routed) {
+    const { command, path } = routed;
     const { dispatch } = command;
-    // A group answers no invocation of its own, so it fails with the routing errors above it.
-    if (!dispatch) {
-        throw new NonCallableCommandError(path, candidatesOf(command));
+    try {
+        if (!dispatch) {
+            throw new NonCallableCommandError(path, candidatesOf(command));
+        }
+        const parsed = parseInputs(command.options, routed.tokens);
+        const args = bindArguments(command, path, parsed.positionals);
+        return {
+            args,
+            dispatch,
+            kind: 'parsed',
+            options: parsed.options,
+            passthrough: parsed.passthrough,
+        };
+    }
+    catch (error) {
+        return { fault: error, kind: 'held' };
+    }
+}
+/**
+ * The node of one option a configuration source is asked about: in the graph's globals, or among
+ * the routed Command's own options. Build published every declaration, so a missing node means the
+ * two readings of one graph disagree.
+ */
+function requestNode(graph, path, place) {
+    const options = place.global ? graph.globals : nodeAt(graph, path).options;
+    const node = options.find((option) => option.name === place.name);
+    if (!node) {
+        throw new InternalError(`Option "${place.name}" is not in the inspected graph.`, undefined);
     }
-    const parsed = parseInputs(command.options, routed.tokens);
-    const args = bindArguments(command, path, parsed.positionals);
+    return node;
+}
+/**
+ * The input-source stage over this run's own copies of the parsed values. The global and plugin
+ * options fill whatever local parsing held; the routed Command's own options fill only when local
+ * parsing held no fault, because the request is `null` otherwise.
+ */
+async function fillScope({ graph, invocation, routed }, local) {
+    const globals = copyValues(routed.scan);
+    const locals = copyValues(local.kind === 'parsed' ? local.options : emptyValues());
+    const sources = await fillInputs({
+        extensions: graph.extensions,
+        globals: {
+            global: true,
+            inputs: [...graph.globals.inputs, ...graph.globals.plugins.flatMap((entry) => entry.inputs)],
+            values: globals,
+        },
+        host: invocation.host,
+        inspected: invocation.inspected,
+        locals: local.kind === 'parsed'
+            ? { global: false, inputs: optionsOf(routed.command.inputs), values: locals }
+            : undefined,
+        out: invocation.sourceOut,
+        plugins: graph.globals.plugins,
+        request: (input, global) => requestNode(invocation.inspected(), routed.path, { global, name: input.name }),
+        signal: invocation.signal,
+        style: invocation.style,
+    });
+    return { globals, locals, sources };
+}
+/**
+ * Validation and the dispatch it prepares, over the values the input-source stage left. 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.
+ */
+async function readyDispatch({ graph, invocation, routed }, filled) {
+    const { command, path } = routed;
+    const { local } = filled;
     const values = await validateValues({
         command: path,
         defaults: invocation.defaults,
         host: invocation.host,
         inputs: { globals: graph.globals.inputs, locals: command.inputs },
-        passthrough: parsed.passthrough,
+        passthrough: local.passthrough,
+        plugins: graph.globals.plugins.flatMap((entry) => entry.inputs),
         signal: invocation.signal,
-        supplied: { args, options: mergeValues(scan, parsed.options) },
+        sources: filled.sources,
+        supplied: { args: local.args, options: filled.values },
     });
     return {
         dispatch: async (view) => {
             // The channel is built at the boundary, because the view a middleware selected is read there.
             const channel = invocation.channel({ path, result: command.result, view });
             try {
-                await dispatch({
+                await local.dispatch({
+                    // The run builds its graph once, so every read answers the same node.
+                    command: () => nodeAt(invocation.inspected(), path),
+                    graph: invocation.inspected,
                     host: invocation.host,
                     out: channel.out,
-                    passthrough: parsed.passthrough,
+                    passthrough: local.passthrough,
                     signal: invocation.signal,
                     style: invocation.style,
                     values,
@@ -1112,19 +1390,42 @@ async function readyDispatch(graph, routed, invocation) {
                 throw error;
             }
         },
-        request: requestOf(command, values, parsed.passthrough),
+        request: requestOf(command, values, local.passthrough),
     };
 }
 /**
  * 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 async function prepareDispatch(graph, routed, invocation) {
     const result = routed.command.result;
+    const local = parseLocal(routed);
+    const preparation = { graph, invocation, routed };
+    const { globals, locals, sources } = await fillScope(preparation, local);
+    const held = (fault) => ({
+        fault,
+        globals,
+        kind: 'held',
+        request: null,
+        result,
+    });
+    if (local.kind === 'held') {
+        return held(local.fault);
+    }
+    if (sources.fault) {
+        return held(sources.fault);
+    }
     try {
-        return { ...(await readyDispatch(graph, routed, invocation)), kind: 'ready', result };
+        const ready = await readyDispatch(preparation, {
+            local,
+            sources,
+            values: mergeValues(globals, locals),
+        });
+        return { ...ready, globals, kind: 'ready', result };
     }
     catch (error) {
-        return { fault: error, kind: 'held', request: null, result };
+        return held(error);
     }
 }