@loomcli/core 0.4.0 → 0.6.0

package/dist/command.js

@@ -1,117 +1,443 @@
-var _a;
-import { commandSentence, commandSubject, DeclarationError, NonCallableCommandError, ResultError, UnexpectedArgumentError, UnknownCommandError, } from './errors.js';
-import { buildExtensions, extendStore, publishStore, 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. */
+var _a, _b;
+import { checkEnvBinding, checkNoArgumentBinding } from './bindings.js';
+import { aliasWithoutNames, argumentDeclaredTwice, argumentsBesideChildren, commandAttachedTwice, commandGlobals, commandWithoutAction, declaredAfterAction, declaredName, groupOption, multipleActions, multipleResults, nestingDepth, notACommand, optionalArgumentLast, portableName, repeatedAlias, resultWithoutAction, resultWithoutViews, rowViewOnValue, siblingNameTaken, unknownDefaultView, variadicArgumentLast, viewName, viewShape, viewsWithoutResult, } from './command-rules.js';
+import { quoteString, spelled } from './diagnostic-text.js';
+import { asSentence, commandSentence, commandSubject, DeclarationError, NonCallableCommandError, quoted, ResultError, toFailure, UnexpectedArgumentError, UnknownCommandError, reasonOf, } from './errors.js';
+import { buildExtensions, extendStore, publishStore, registerDescriptor, storeCommandLayers, validateLayer, } from './extension.js';
+import { checkDeprecated, checkDescription, checkHidden, checkNoListingFacts, siteFinding, } from './facts.js';
+import { buildGlobals, checkLocalOptions } from './globals.js';
+import { nameSharedAcrossKinds, optionDeclaredTwice, spellingTaken } from './input-rules.js';
+import { graphMismatch, nodeAt, resultNode, snapshot } from './inspect.js';
+import { checkOptionName, compileOptions, copyValues, emptyValues, extractGlobals, isOptionToken, mergeValues, parseInputs, spellingMark, } from './options.js';
+import { isPlainObject } from './plain.js';
+import { brokenAttachHook, notAnObject } from './plugin-rules.js';
+import { fillInputs } from './sources.js';
+import { captureConfig, checkInputConfig, checkDeclarations, declaringSite, inputPlace, 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).`);
+/**
+ * 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,
+    });
+}
+/** 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;
+}
+/**
+ * The path a finding opens with for a declaration call on one Command. The root's is empty. A named
+ * Command's call cannot know the parent it will join, so its path is its own name.
+ */
+function pathOf(name) {
+    return name === null ? [] : [name];
+}
+/** A call's arguments as its author wrote them: the trailing ones left undefined are dropped. */
+export function callArguments(...values) {
+    let length = values.length;
+    while (length > 0 && values[length - 1] === undefined) {
+        length -= 1;
     }
-    return node;
+    return values.slice(0, length);
+}
+/** A Command value as a finding prints it, which it would otherwise print as an ellipsis. */
+export function commandCode(name) {
+    return spelled(`new Command(${quoteString(name)})`);
 }
-/** Reject retired globals wiring at graph build, before any invocation reads the options. */
+/** The finding for one `command()` call that attached a child under the Command at `path`. */
+export function commandPlacement(path, child) {
+    return { arguments: [commandCode(child)], call: 'command', mark: '0', path };
+}
+/** The finding for one `new Command()` call, which carries the name and the options slot. */
+function constructorFinding(name, options, mark) {
+    return { arguments: callArguments(name, options), call: 'new Command', mark };
+}
+/** 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.`);
+        throw new DeclarationError(notAnObject, {
+            correction: 'Supply a Command options object.',
+            findings: [constructorFinding(name, options, '1')],
+            sentence: `${commandSentence(name)} declares options that are not an object.`,
+        });
     }
     if (isPlainObject(options) && 'globals' in options) {
-        throw new DeclarationError(`${commandSentence(name)} declares globals. Declare globals on the Application and register its environment.`);
+        throw new DeclarationError(commandGlobals, {
+            correction: 'Declare globals on the Application and register its environment.',
+            findings: [constructorFinding(name, options, '1.globals')],
+            sentence: `${commandSentence(name)} declares globals.`,
+        });
     }
 }
-/** 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. */
-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 "=".`);
+/** 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 checkAliasNames(command, names) {
+    for (const [index, alias] of names.entries()) {
+        if (!isPortableName(alias)) {
+            throw new DeclarationError(portableName, {
+                correction: portableNameCorrection,
+                findings: [{ arguments: names, call: 'alias', mark: String(index), path: pathOf(command) }],
+                sentence: `${commandSentence(command)} declares an alias named ${quoted(alias)}.`,
+            });
+        }
     }
 }
 /**
- * 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 finding for the `alias()` call that declared one alias on the Command at `path`, rebuilt from
+ * every alias the Command holds.
+ */
+function aliasFinding(command, alias, note) {
+    const { aliases, path } = command;
+    return { arguments: aliases, call: 'alias', mark: String(aliases.indexOf(alias)), note, path };
+}
+/** 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 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(portableName, {
+            correction: portableNameCorrection,
+            findings: [constructorFinding(name, options, '0')],
+            sentence: `Command name ${quoted(name)} is invalid.`,
+        });
+    }
+    checkCommandOptions(name, options);
+    const slot = isPlainObject(options) ? options : undefined;
+    const site = {
+        at: '1',
+        declaration: { arguments: [name, options], call: 'new Command' },
+        subject: commandSentence(name),
+    };
+    // The facts are read in the order their diagnostics have always ranked.
+    const description = checkDescription(site, slot?.description);
+    const hidden = checkHidden(site, slot?.hidden);
+    const deprecated = checkDeprecated(site, slot?.deprecated);
+    const descriptors = new Map();
+    const extensions = storeCommandLayers({
+        descriptors,
+        layers: [slot?.extensions],
+        site: { ...site, at: '1.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, late) {
+    if (state.action !== undefined) {
+        throw new DeclarationError(declaredAfterAction, {
+            correction: late.remedy,
+            findings: [
+                {
+                    arguments: late.arguments,
+                    call: late.call,
+                    mark: '0',
+                    note: 'after action()',
+                    path: pathOf(state.name),
+                },
+            ],
+            sentence: `${commandSentence(state.name)} ${late.clause} after its action.`,
+        });
+    }
+}
+/** The remedy a late argument or option earns. */
+const inputRemedy = 'Declare arguments and options before action().';
+/** Where one input was declared: the call on the Command at `path` that declared it. */
+function inputSite(name, path, input) {
+    return declaringSite(input, inputPlace(input, { global: false, path }), `${commandSentence(name)} ${input.kind} ${quoted(input.name)}`);
+}
+/** The finding for the `argument()` or `option()` call that declared one input, marking its name. */
+function inputFinding(path, input, note) {
+    const site = declaringSite(input, inputPlace(input, { global: false, path }));
+    return siteFinding(site, site.named, note);
+}
+/** The scope one Command's own options compile under: its subject, and each option's call. */
+function localScope(name, path) {
+    return { siteOf: (input) => inputSite(name, path, input), subject: commandSubject(name) };
+}
+/** One Command declares arguments or attaches children, whichever call came second. */
+function placementFault(parent, argument, child) {
+    return new DeclarationError(argumentsBesideChildren, {
+        correction: 'Move the argument into a child Command or remove the children.',
+        findings: [
+            inputFinding(parent.path, argument, 'the argument'),
+            { ...child.placement, note: 'the child' },
+        ],
+        sentence: `${commandSentence(parent.name)} declares argument "${argument.name}" and attaches child "${child.name}".`,
+    });
+}
+/** 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,
+        site: { ...inputSite(name, pathOf(name), input), at: '1.extensions' },
+        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 path = pathOf(name);
+    const command = { name, path, subject: commandSubject(name) };
+    const declared = state.inputs.filter((entry) => entry.kind === 'argument');
+    checkArgumentName(command, declared, input);
+    const child = state.children[0];
+    if (child) {
+        throw placementFault(command, input, child);
+    }
+    const previous = declared.at(-1);
+    if (previous) {
+        checkSlotOrder(slotOf(previous), slotOf(input), command);
+    }
+    const site = inputSite(name, path, input);
+    checkDescription(site, input.config.description);
+    checkNoListingFacts(site, input.config);
+    checkNoArgumentBinding(site, input.config);
+    checkDeclarations([{ input, site }]);
+}
+/** One argument's name answers the declared-name rule and names no argument declared before it. */
+function checkArgumentName(command, declared, input) {
+    const { path } = command;
+    if (!isDeclaredName(input.name)) {
+        throw new DeclarationError(declaredName, {
+            correction: 'Use a nonempty name without a leading hyphen, whitespace, or "=".',
+            findings: [inputFinding(path, input)],
+            sentence: `${commandSentence(command.name)} declares an argument named ${quoted(input.name)}.`,
+        });
+    }
+    const first = declared.find((entry) => entry.name === input.name);
+    if (first) {
+        throw new DeclarationError(argumentDeclaredTwice, {
+            correction: 'Remove or rename the duplicate.',
+            findings: [
+                inputFinding(path, first, 'the first declaration'),
+                inputFinding(path, input, 'the second declaration'),
+            ],
+            sentence: `Argument "${input.name}" is declared more than once on ${command.subject}.`,
+        });
+    }
 }
 /** The declared value joins `args` under its literal name, typed by its own config. */
-export function declareArgument(state, input) {
+export function declareArgument(state, declared) {
+    // The call's own input is judged before the receiver's state, as alias() judges its names.
+    // A name of another kind then reports as a declared name instead of failing to print in the order diagnostic.
+    // The config is judged right after its name, and only then captured.
+    const { name } = state;
+    checkArgumentName({ name, path: pathOf(name), subject: commandSubject(name) }, [], declared);
+    checkInputConfig(declared, { call: 'argument', path: pathOf(name) });
+    const input = { ...declared, config: captureConfig(declared.config) };
+    checkOpen(state, {
+        arguments: [input.name, input.config],
+        call: 'argument',
+        clause: `declares argument ${quoted(input.name)}`,
+        remedy: 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, declared, table = noGlobals) {
+    // The call's own input is judged before the receiver's state, as alias() judges its names.
+    // The config is judged right after its name, and only then captured.
+    checkOptionName(declared.name, inputSite(state.name, pathOf(state.name), declared));
+    checkInputConfig(declared, { call: 'option', path: pathOf(state.name) });
+    const input = { ...declared, config: captureConfig(declared.config) };
+    const site = inputSite(state.name, pathOf(state.name), input);
+    checkOpen(state, {
+        arguments: [input.name, input.config],
+        call: 'option',
+        clause: `declares option ${quoted(input.name)}`,
+        remedy: inputRemedy,
+    });
+    checkDescription(site, input.config.description);
+    checkHidden(site, input.config.hidden);
+    checkDeprecated(site, input.config.deprecated);
+    checkEnvBinding(site, input.config);
+    const recorded = recordInput(state, input);
+    checkLocalOptions([...optionsOf(state.inputs), input], table, localScope(state.name, pathOf(state.name)));
+    checkDeclarations([{ input, site }]);
     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 path = pathOf(name);
+    const first = names[0];
+    if (first === undefined) {
+        throw new DeclarationError(aliasWithoutNames, {
+            correction: 'Supply at least one name.',
+            findings: [{ arguments: [], call: 'alias', path }],
+            sentence: `${commandSentence(name)} declares an alias with no names.`,
+        });
+    }
+    // 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.
+    checkAliasNames(name, names);
+    checkOpen(state, {
+        arguments: names,
+        call: 'alias',
+        clause: `declares alias "${first}"`,
+        remedy: 'Declare aliases before action().',
+    });
+    const aliases = [...state.aliases];
+    for (const [index, alias] of names.entries()) {
+        const repeated = { arguments: names, call: 'alias', mark: String(index), path };
+        if (alias === name) {
+            throw new DeclarationError(repeatedAlias, {
+                correction: 'Remove the alias.',
+                findings: [{ ...repeated, note: 'its own name' }],
+                sentence: `${commandSentence(name)} declares alias "${alias}", which is its own name.`,
+            });
+        }
+        if (aliases.includes(alias)) {
+            throw new DeclarationError(repeatedAlias, {
+                correction: 'Remove the repeated alias.',
+                findings: [{ ...repeated, note: 'already an alias' }],
+                sentence: `${commandSentence(name)} declares alias "${alias}" twice.`,
+            });
+        }
+        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,
+        site: { at: '', declaration: { arguments: values, call: 'extend', path: pathOf(state.name) } },
+        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,217 +449,360 @@ 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(multipleActions, {
+            correction: 'Register one action.',
+            findings: [
+                {
+                    arguments: [handler],
+                    call: 'action',
+                    mark: '0',
+                    note: 'the second action',
+                    path: pathOf(state.name),
+                },
+            ],
+            sentence: `${commandSentence(state.name)} has multiple actions.`,
+        });
+    }
+    // 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') }],
+    const call = {
+        arguments: callArguments(declaration),
+        kind,
+        views: recordOf(declaration, 'views'),
     };
+    checkOpen(state, {
+        arguments: call.arguments,
+        call: resultCallName(call),
+        clause: 'declares its result',
+        remedy: 'Declare result() or rows() before action().',
+    });
+    const results = [...state.results, call];
+    mergeResult({ name: state.name, path: pathOf(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) {
+    const results = [...state.results, viewsCall(replacements, options)];
+    mergeResult({ name: state.name, path: pathOf(state.name) }, results);
+    return { ...state, results };
+}
+/** One `views()` call as the results lane records it. */
+function viewsCall(replacements, options) {
     return {
-        ...state,
-        results: [
-            ...state.results,
-            { default: recordOf(options, 'default'), kind: 'views', views: replacements },
-        ],
+        arguments: callArguments(replacements, options),
+        default: recordOf(options, 'default'),
+        kind: 'views',
+        views: replacements,
     };
 }
-/** 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 authoring call one results-lane call was made through. */
+function resultCallName(call) {
+    return call.kind === 'value' ? 'result' : call.kind;
+}
+/** The finding for one results-lane call on the Command at `path`, marking one of its arguments. */
+function resultFinding(path, call, mark) {
+    const finding = { arguments: call.arguments, call: resultCallName(call), mark: mark.at, path };
+    return mark.note === undefined ? finding : { ...finding, note: mark.note };
+}
+/** Where one views entry sits among its call's arguments: in `views` for a declaration, or first. */
+function entryMark(call, key) {
+    return call.kind === 'views' ? `0.${key}` : `0.views.${key}`;
+}
+/** 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'),
+        children: state.children,
+        hasAction: state.action !== undefined,
+        name: state.name,
+        path: pathOf(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;
+/** The path one child sits at under its parent. */
+function childPath(parent, child) {
+    return [...parent.path, child];
+}
+/** The call that attached one child, noted with the child's name. */
+function childFinding(entry) {
+    return { ...entry.placement, note: `child "${entry.name}"` };
+}
+/**
+ * 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;
+    const aliased = (entry, alias) => aliasFinding({ aliases: entry.node.declared.aliases, path: childPath(parent, entry.name) }, alias, `alias of child "${entry.name}"`);
+    const correction = 'Rename or remove one.';
+    const twin = children.find((entry) => entry.name === child.name);
+    if (twin) {
+        throw new DeclarationError(siblingNameTaken, {
+            correction,
+            findings: [childFinding(twin), childFinding(child)],
+            sentence: `${sentence} attaches two children named "${child.name}".`,
+        });
     }
-    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.`);
+    for (const alias of child.node.declared.aliases) {
+        const holder = children.find((entry) => entry.name === alias);
+        if (holder) {
+            throw new DeclarationError(siblingNameTaken, {
+                correction,
+                findings: [childFinding(holder), aliased(child, alias)],
+                sentence: `${sentence} attaches child "${child.name}" with alias "${alias}", which is also the name of child "${alias}".`,
+            });
+        }
+        const owner = children.find((entry) => entry.node.declared.aliases.includes(alias));
+        if (owner) {
+            throw new DeclarationError(siblingNameTaken, {
+                correction,
+                findings: [aliased(owner, alias), aliased(child, alias)],
+                sentence: `${sentence} attaches child "${child.name}" with alias "${alias}", which is also an alias of child "${owner.name}".`,
+            });
+        }
     }
-    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().`);
+    const owner = children.find((entry) => entry.node.declared.aliases.includes(child.name));
+    if (owner) {
+        throw new DeclarationError(siblingNameTaken, {
+            correction,
+            findings: [aliased(owner, child.name), childFinding(child)],
+            sentence: `${sentence} attaches child "${owner.name}" with alias "${child.name}", which is also the name of child "${child.name}".`,
+        });
+    }
+}
+/**
+ * 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(nestingDepth, {
+            correction: `Nest Commands at most ${nestingCap.words} levels below the root.`,
+            findings: [{ ...child.placement, note: 'has children of its own' }],
+            sentence: `${commandSentence(parent)} attaches child "${child.name}", which has children of its own.`,
+        });
     }
-    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, place) {
+    const { name } = state;
+    if (state.children.length === 0) {
+        const { placement } = place;
+        throw new DeclarationError(commandWithoutAction, {
+            correction: 'Register an action.',
+            findings: placement === undefined ? [] : [{ ...placement, note: 'no action and no children' }],
+            sentence: `${commandSentence(name)} has no 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(groupOption, {
+            correction: 'Register an action or remove the option.',
+            findings: [inputFinding(place.path, option, 'no action reads it')],
+            sentence: `${commandSentence(name)} declares option "${option.name}" but registers no action to receive it.`,
+        });
     }
-    // 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, place) {
+    const result = buildResult(declared, hasAction, place.path);
+    if (!hasAction) {
+        checkGroup(declared, place);
     }
-    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. The placement is the call that attached it, which a
+ * finding about the child as a whole marks.
  */
-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, placement) {
+    const { name } = node;
+    const child = { name, node, placement };
+    if (parent.hasAction) {
+        throw new DeclarationError(declaredAfterAction, {
+            correction: 'Attach children before action().',
+            findings: [{ ...placement, note: 'after action()' }],
+            sentence: `${commandSentence(parent.name)} attaches child "${name}" after its action.`,
+        });
     }
-    return aliases;
+    if (parent.argument !== undefined) {
+        throw placementFault(parent, parent.argument, child);
+    }
+    checkFinished(node.declared, node.hasAction, { path: childPath(parent, name), placement });
+    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(notACommand, {
+            correction: 'Attach the value returned by new Command(name).',
+            findings: [{ arguments: [child], call: 'command', mark: '0', path: pathOf(parent) }],
+            sentence: `${commandSentence(parent)} attaches a value that is not a Command.`,
+        });
+    }
+    return node;
+}
+/** Attaching is a declaration call too, so the receiver keeps the children it already had. */
+function attachChild(state, child) {
+    const node = childNode(state.name, child);
+    const attached = attach(parentOf(state), node, commandPlacement(pathOf(state.name), node.name));
+    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, placement } = child;
+    checkNesting(parent.name, child, level);
+    const owner = scope.owners.get(node);
+    if (owner) {
+        throw new DeclarationError(commandAttachedTwice, {
+            correction: 'Attach a Command value at one point; create a new Command for each placement.',
+            findings: [
+                { ...owner.placement, note: 'the first placement' },
+                { ...placement, note: 'the second placement' },
+            ],
+            sentence: `${commandSentence(parent.name)} attaches child "${name}", which ${commandSubject(owner.name)} also attaches.`,
+        });
+    }
+    scope.owners.set(node, { name: parent.name, placement });
+    for (const [key, descriptor] of node.declared.descriptors) {
+        registerDescriptor(scope.descriptors, descriptor, { identity: key });
+    }
+    const path = childPath(parent, name);
+    checkLocalOptions(optionsOf(node.declared.inputs), scope.table, localScope(name, path));
+    for (const entry of node.declared.children) {
+        // A nested child's own placement knew its parent alone, so the walk places it under the root.
+        const rooted = { ...entry, placement: commandPlacement(path, entry.name) };
+        joinSubtree(scope, rooted, { level: level + 1, parent: { name, path } });
+    }
 }
 /**
- * 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, child, scope) {
+    const parent = parentOf(state);
+    const attached = attach(parent, child.node, child.placement);
+    joinSubtree(scope, attached, { level: parentLevel(state.name) + 1, parent });
+    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, parent, children) {
+    for (const { name, node } of children) {
+        const path = childPath(parent, name);
+        checkLocalOptions(optionsOf(node.declared.inputs), table, localScope(name, path));
+        checkAttachedOptions(table, { name, path }, 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) {
+    const place = { name: state.name, path: pathOf(state.name) };
+    checkLocalOptions(optionsOf(state.inputs), table, localScope(place.name, place.path));
+    checkAttachedOptions(table, place, state.children);
 }
 /** A variadic or optional slot ends the positional list, so nothing may follow either one. */
-function checkSlotOrder(slot, next, subject) {
+function checkSlotOrder(slot, next, command) {
+    const { path, subject } = command;
+    const after = inputFinding(path, next.input, 'the argument after it');
     if (slot.variadic) {
-        throw new DeclarationError(`Argument "${slot.input.name}" is variadic and precedes argument "${next.input.name}" on ${subject}. Declare the variadic argument last.`);
+        throw new DeclarationError(variadicArgumentLast, {
+            correction: 'Declare the variadic argument last.',
+            findings: [inputFinding(path, slot.input, 'the variadic argument'), after],
+            sentence: `Argument "${slot.input.name}" is variadic and precedes argument "${next.input.name}" on ${subject}.`,
+        });
     }
     if (!slot.required) {
-        throw new DeclarationError(next.required
-            ? `Argument "${slot.input.name}" is optional and precedes required argument "${next.input.name}" on ${subject}. Declare optional arguments after required ones.`
-            : `Argument "${next.input.name}" follows optional argument "${slot.input.name}" on ${subject}. Declare an optional argument last.`);
+        const findings = [inputFinding(path, slot.input, 'the optional argument'), after];
+        throw new DeclarationError(optionalArgumentLast, next.required
+            ? {
+                correction: 'Declare optional arguments after required ones.',
+                findings,
+                sentence: `Argument "${slot.input.name}" is optional and precedes required argument "${next.input.name}" on ${subject}.`,
+            }
+            : {
+                correction: 'Declare an optional argument last.',
+                findings,
+                sentence: `Argument "${next.input.name}" follows optional argument "${slot.input.name}" on ${subject}.`,
+            });
     }
 }
-function collectArguments(state, subject) {
+/**
+ * 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, command) {
     const slots = [];
-    const seen = new Set();
+    const declared = [];
+    const judged = { ...command, subject: commandSubject(command.name) };
     for (const input of state.inputs.filter((entry) => entry.kind === 'argument')) {
-        if (!isDeclaredName(input.name)) {
-            throw new DeclarationError(`${commandSentence(state.name)} declares an argument named "${String(input.name)}". Use a nonempty name without a leading hyphen, whitespace, or "=".`);
-        }
-        if (seen.has(input.name)) {
-            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,
-        });
+        checkArgumentName(judged, declared, input);
+        declared.push(input);
+        slots.push(slotOf(input));
     }
     for (let index = 0; index + 1 < slots.length; index += 1) {
         const slot = slots[index];
         const next = slots[index + 1];
         if (slot && next) {
-            checkSlotOrder(slot, next, subject);
+            checkSlotOrder(slot, next, judged);
         }
     }
     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);
@@ -367,71 +836,126 @@ function recordEntries(record) {
  * One `views` entry under the unit its declaration named, read back as the shape its own functions
  * name. The two shapes are exclusive, and a row view answers a rows declaration alone.
  */
-function resultView(declaration, name, entry) {
-    const { kind, sentence } = declaration;
+function resultView(kind, site, entry) {
+    const { call, key, path, sentence } = site;
+    const findings = [resultFinding(path, call, { at: entryMark(call, key) })];
     const whole = isWholeView(entry);
     const row = isRowView(entry);
     if (whole && row) {
-        throw new DeclarationError(`${sentence} names view "${name}" with render and row. Supply one of the two.`);
+        throw new DeclarationError(viewShape, {
+            correction: 'Supply one of the two.',
+            findings,
+            sentence: `${sentence} names view ${quoted(key)} with render and row.`,
+        });
     }
     if (row) {
         if (kind === 'value') {
-            throw new DeclarationError(`${sentence} names row view "${name}" on a value result. Supply a view with render, or declare the result with rows().`);
+            throw new DeclarationError(rowViewOnValue, {
+                correction: 'Supply a view with render, or declare the result with rows().',
+                findings,
+                sentence: `${sentence} names row view ${quoted(key)} on a value result.`,
+            });
         }
         return entry;
     }
     if (whole) {
         return 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.`);
+    throw new DeclarationError(viewShape, {
+        correction: 'Supply a view with render or a row view with row.',
+        findings,
+        sentence: `${sentence} names view ${quoted(key)} with a value that is not a view.`,
+    });
 }
 /**
- * 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');
-    if (declarations.length > 1) {
-        throw new DeclarationError(`${sentence} declares two results. Declare one result() or rows() call.`);
+function mergeResult(command, results) {
+    const { path } = command;
+    const sentence = commandSentence(command.name);
+    const declarations = results.filter((call) => call.kind !== 'views');
+    const [declaration, second] = declarations;
+    if (declaration && second) {
+        throw new DeclarationError(multipleResults, {
+            correction: 'Declare one result() or rows() call.',
+            findings: [
+                resultFinding(path, declaration, { at: '0', note: 'the first result' }),
+                resultFinding(path, second, { at: '0', note: 'the second result' }),
+            ],
+            sentence: `${sentence} declares two results.`,
+        });
     }
-    const declaration = declarations[0];
     // 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) {
-            throw new DeclarationError(`${sentence} reshapes its views and declares no result. Declare result() or rows() before action().`);
+        const [reshape] = results;
+        if (reshape) {
+            throw new DeclarationError(viewsWithoutResult, {
+                correction: 'Declare result() or rows() before action().',
+                findings: [resultFinding(path, reshape, { at: '0' })],
+                sentence: `${sentence} reshapes its views and declares no result.`,
+            });
         }
         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(declaration.kind, { call, key, path, sentence }, entry);
+            if (!isViewName(key)) {
+                throw new DeclarationError(viewName, {
+                    correction: 'Use a nonempty name without whitespace, a leading hyphen, or "=", and not a number.',
+                    findings: [resultFinding(path, call, { at: entryMark(call, key) })],
+                    sentence: `${sentence} names view ${quoted(key)}.`,
+                });
             }
-            views.set(name, view);
+            views.set(key, view);
         }
-        if (call.kind === 'views') {
-            selected = selectedKey(call.default) ?? selected;
+        const key = call.kind === 'views' ? selectedKey(call.default) : undefined;
+        if (key !== undefined) {
+            selected = { call, key };
         }
     }
+    return { declaration, 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, path) {
+    const merged = mergeResult({ name: declared.name, path }, declared.results);
+    if (!merged) {
+        return undefined;
+    }
+    const sentence = commandSentence(declared.name);
+    const { declaration, selected, views } = merged;
+    if (!hasAction) {
+        throw new DeclarationError(resultWithoutAction, {
+            correction: 'Register an action or remove the result.',
+            findings: [resultFinding(path, declaration, { at: '0' })],
+            sentence: `${sentence} declares a result and no action.`,
+        });
+    }
     const first = views.keys().next();
     if (first.done === true) {
-        throw new DeclarationError(`${sentence} declares a result with no views. Name at least one view.`);
+        throw new DeclarationError(resultWithoutViews, {
+            correction: 'Name at least one view.',
+            findings: [resultFinding(path, declaration, { at: '0.views' })],
+            sentence: `${sentence} declares a result with no views.`,
+        });
     }
-    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.`);
+    if (selected !== undefined && !views.has(selected.key)) {
+        throw new DeclarationError(unknownDefaultView, {
+            correction: 'Name the view or select a named one.',
+            findings: [resultFinding(path, selected.call, { at: '1.default' })],
+            sentence: `${sentence} selects default view ${quoted(selected.key)}, which it does not name.`,
+        });
     }
-    return { default: selected ?? first.value, kind: declaration.kind, views };
+    return { default: selected?.key ?? 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();
@@ -454,7 +978,7 @@ class AttachedCommandValue {
     #result;
     constructor(state) {
         this.#state = state;
-        this.#result = resultNode(buildResult(state.declared, state.hasAction));
+        this.#result = resultNode(buildResult(state.declared, state.hasAction, state.path));
         attachments.set(this, state);
         Object.freeze(this);
     }
@@ -481,17 +1005,13 @@ class AttachedCommandValue {
         return publishStore(this.#state.extensions);
     }
     argument(name, config) {
-        return this.#declare({ config: captureConfig(config), kind: 'argument', name });
+        return this.#declare({ config, kind: 'argument', name });
     }
     option(name, config) {
-        return this.#declare({ config: captureConfig(config), kind: 'option', name });
+        return this.#declare({ config, kind: 'option', name });
     }
     views(replacements, options) {
-        const call = {
-            default: recordOf(options, 'default'),
-            kind: 'views',
-            views: replacements,
-        };
+        const call = viewsCall(replacements, options);
         const { declared } = this.#state;
         return this.#derive({ call, kind: 'views' }, { ...declared, results: [...declared.results, call] });
     }
@@ -505,6 +1025,7 @@ class AttachedCommandValue {
         const layer = validateLayer({
             declared: values,
             descriptors: registry,
+            site: { at: '', declaration: { arguments: values, call: 'extend', path: state.path } },
             subject: state.subject,
             target: 'command',
         });
@@ -515,8 +1036,22 @@ class AttachedCommandValue {
         });
     }
     /** One input the running hook declared, which the Command's own names now hold. */
-    #declare(input) {
+    #declare(raw) {
         const { declared, identity } = this.#state;
+        const { path } = this.#state;
+        // The name is judged before the config, as Command and Application judge it.
+        if (raw.kind === 'argument') {
+            const { name } = declared;
+            checkArgumentName({ name, path, subject: commandSubject(name) }, [], raw);
+        }
+        else {
+            checkOptionName(raw.name, inputSite(declared.name, path, raw));
+        }
+        checkInputConfig(raw, { call: raw.kind, path });
+        // Each kind captures its own config, so the input keeps the pairing its kind declares.
+        const input = raw.kind === 'argument'
+            ? { ...raw, config: captureConfig(raw.config) }
+            : { ...raw, config: captureConfig(raw.config) };
         return this.#derive({ identity, input, kind: 'input' }, { ...declared, inputs: [...declared.inputs, input] });
     }
     #derive(call, declared) {
@@ -525,9 +1060,13 @@ class AttachedCommandValue {
     }
 }
 _a = AttachedCommandValue;
-/** The reason one failed hook reports, which is the thrown value's own message. */
-function attachReason(error) {
-    return error instanceof Error ? error.message : String(error);
+/** The finding for the hook one plugin declared, as `plugin(identity, { onCommandAttach })`. */
+function hookFinding(identity, hook) {
+    return {
+        arguments: [identity, { onCommandAttach: hook }],
+        call: 'plugin',
+        mark: '1.onCommandAttach',
+    };
 }
 /** One hook's own call, whose failure is the plugin's, and whose own report is its own. */
 function callHook(value, hook, named) {
@@ -539,7 +1078,11 @@ function callHook(value, hook, named) {
         if (error instanceof DeclarationError) {
             throw error;
         }
-        throw new DeclarationError(`Plugin "${named.identity}" failed in onCommandAttach for ${named.subject}: ${attachReason(error)}.`);
+        throw new DeclarationError(brokenAttachHook, {
+            correction: 'Return the value the hook received or a value derived from it, and throw only a DeclarationError from the hook.',
+            findings: [hookFinding(named.identity, hook)],
+            sentence: `Plugin ${quoted(named.identity)} failed in onCommandAttach for ${named.subject}: ${asSentence(reasonOf(error))}`,
+        }, { cause: error });
     }
 }
 /**
@@ -550,7 +1093,11 @@ function callHook(value, hook, named) {
 function attachOnce(value, hook, named) {
     const state = attachments.get(callHook(value, hook, named));
     if (!state || state.lineage !== named.lineage) {
-        throw new DeclarationError(`Plugin "${named.identity}" returned a value that is not the attached Command from onCommandAttach for ${named.subject}. Return the value it received or a value derived from it.`);
+        throw new DeclarationError(brokenAttachHook, {
+            correction: 'Return the value it received or a value derived from it.',
+            findings: [hookFinding(named.identity, hook)],
+            sentence: `Plugin ${quoted(named.identity)} returned a value that is not the attached Command from onCommandAttach for ${named.subject}.`,
+        });
     }
     return state;
 }
@@ -581,8 +1128,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;
@@ -608,10 +1155,28 @@ function applyAttachCalls(state, calls) {
     }
     return next;
 }
+/**
+ * The reason rule one name collision breaks.
+ * Two options or two arguments break the rule the application's own collision of the pair breaks.
+ * An argument and an option under one name break name-shared-across-kinds, which only a hook reaches.
+ */
+function nameCollisionRule(declared, held) {
+    if (declared !== held) {
+        return nameSharedAcrossKinds;
+    }
+    return declared === 'option' ? optionDeclaredTwice : argumentDeclaredTwice;
+}
+/** The note a finding for one hook-declared input carries. */
+function hookNote(identity) {
+    return `declared by plugin ${quoted(identity)}`;
+}
 /** The clause and the remedy an input another plugin's hook already declared earns. */
-function hookClause(kind, identity) {
+function hookClause(earlier, path) {
+    const { identity, input } = earlier;
     return {
-        clause: `an ${kind} plugin "${identity}" declared through onCommandAttach`,
+        clause: `an ${input.kind} plugin ${quoted(identity)} declared through onCommandAttach`,
+        held: inputFinding(path, input, hookNote(identity)),
+        kind: input.kind,
         remedy: 'Install one of them.',
     };
 }
@@ -633,6 +1198,25 @@ function attachedRemedy(target) {
     }
     return 'Install one of them.';
 }
+/** The collision with one option the globals table holds, a global or a plugin's own option. */
+function tableCollision(entry) {
+    const { owner, site } = entry;
+    if (owner.kind === 'plugin') {
+        const clause = `an option of plugin ${quoted(owner.identity)}`;
+        return {
+            clause,
+            held: siteFinding(site, site.named, clause),
+            kind: 'option',
+            remedy: attachedRemedy('plugin'),
+        };
+    }
+    return {
+        clause: 'a global option',
+        held: siteFinding(site, site.named, 'the global option'),
+        kind: 'option',
+        remedy: attachedRemedy('global'),
+    };
+}
 /**
  * What one name a hook-declared input of either kind collides with, in the order the scopes are
  * reported: an earlier hook's option, an earlier hook's argument, a local option, a global or
@@ -641,32 +1225,36 @@ function attachedRemedy(target) {
  */
 function attachedCollision(input, held) {
     const { name } = input;
-    const hook = held.hooks.get(name);
+    const { path } = held;
+    const hook = held.hooks.get(name) ?? held.hookArguments.get(name);
     if (hook !== undefined) {
-        return hookClause('option', hook);
+        return hookClause(hook, path);
     }
-    const hooked = held.hookArguments.get(name);
-    if (hooked !== undefined) {
-        return hookClause('argument', hooked);
-    }
-    if (held.locals.has(name)) {
-        return { clause: 'a local option', remedy: attachedRemedy('local') };
+    const local = held.locals.get(name);
+    if (local !== undefined) {
+        return {
+            clause: 'a local option',
+            held: inputFinding(path, local, 'the local option'),
+            kind: 'option',
+            remedy: attachedRemedy('local'),
+        };
     }
-    const claimed = held.globals.names.get(name);
-    if (claimed) {
-        const target = claimed.kind === 'plugin' ? 'plugin' : 'global';
-        const clause = claimed.kind === 'plugin' ? `an option of plugin "${claimed.identity}"` : 'a global option';
-        return { clause, remedy: attachedRemedy(target) };
+    const entry = held.globals.names.get(name);
+    if (entry) {
+        return tableCollision(entry);
     }
-    return held.arguments.has(name)
-        ? { clause: 'an argument', remedy: attachedRemedy('argument') }
-        : undefined;
+    const argument = held.arguments.get(name);
+    return argument === undefined
+        ? undefined
+        : {
+            clause: 'an argument',
+            held: inputFinding(path, argument, 'the argument'),
+            kind: 'argument',
+            remedy: attachedRemedy('argument'),
+        };
 }
-/**
- * The spellings one compiled table holds, each under the form its own option is named by, which is
- * its long form where it declares one and the colliding spelling itself where it declares none.
- */
-function readSpellings(table, claimed) {
+/** The spellings one compiled table holds, each with its form and the place that declared it. */
+function readSpellings(table, claimed, placeOf) {
     const longs = new Map();
     for (const [spelling, option] of table) {
         if (option.role === 'long') {
@@ -675,69 +1263,129 @@ function readSpellings(table, claimed) {
     }
     for (const [spelling, option] of table) {
         if (!claimed.has(spelling)) {
-            claimed.set(spelling, longs.get(option.name) ?? spelling);
+            const form = longs.get(option.name) ?? spelling;
+            claimed.set(spelling, { finding: placeOf(option.name, option.role), form });
         }
     }
 }
+/** The place one input's spelling sits: the key of its call that yields the spelling. */
+function spellingPlace(site, role, note) {
+    return siteFinding(site, spellingMark(site, role), note);
+}
 /** One hook-declared option's spellings, against every spelling the table already claims. */
 function checkAttachedSpelling(declared, named) {
-    const { claimed, subject } = named;
-    const table = compileOptions([declared.input], subject);
-    for (const [spelling] of table) {
+    const { claimed, scope } = named;
+    const { identity, input } = declared;
+    const { subject } = scope;
+    const site = scope.siteOf(input);
+    const table = compileOptions([input], scope);
+    for (const [spelling, option] of table) {
         const used = claimed.get(spelling);
         if (used !== undefined) {
-            throw new DeclarationError(`Plugin "${declared.identity}" declares option "${declared.input.name}" with spelling "${spelling}" on ${subject}, which "${used}" already uses.`);
+            throw new DeclarationError(spellingTaken, {
+                correction: 'Change one of the two spellings or omit the plugin.',
+                findings: [
+                    spellingPlace(site, option.role, hookNote(identity)),
+                    ...(used.finding === undefined ? [] : [used.finding]),
+                ],
+                sentence: `Plugin ${quoted(identity)} declares option ${quoted(input.name)} with spelling ${quoted(spelling)} on ${subject}, which ${quoted(used.form)} already uses.`,
+            });
         }
     }
-    readSpellings(table, claimed);
+    readSpellings(table, claimed, (_name, role) => spellingPlace(site, role, hookNote(identity)));
+}
+/** The declarations of one kind, keyed by name, the first of each name winning. */
+function byName(inputs) {
+    const named = new Map();
+    for (const input of inputs) {
+        if (!named.has(input.name)) {
+            named.set(input.name, input);
+        }
+    }
+    return named;
+}
+/** Where the globals table's options declared their spellings, a global or a plugin's option. */
+function tableSpellings(globals) {
+    return (name, role) => {
+        const entry = globals.names.get(name);
+        if (!entry) {
+            return undefined;
+        }
+        const { owner, site } = entry;
+        const note = owner.kind === 'plugin'
+            ? `an option of plugin ${quoted(owner.identity)}`
+            : `the global option "${name}"`;
+        return spellingPlace(site, role, note);
+    };
 }
 /**
  * Every input a hook declared, against the names and spellings the Command, the globals table, and
  * an earlier hook already hold. It runs before the Command's own inputs compile, so a hook-declared
- * input reports as the plugin's fault and never as the author's.
+ * input reports as the plugin's fault and never as the author's. A collision carries a finding for
+ * the hook's input and one for the declaration that already holds the name or spelling.
  */
-function checkAttachedInputs(declared, attached, globals) {
-    const subject = commandSubject(declared.name);
+function checkAttachedInputs(declared, attached, place) {
+    const { globals, path } = place;
+    const scope = localScope(declared.name, path);
+    const { subject } = scope;
     const hooked = new Set(attached.map((entry) => entry.input));
     const authored = declared.inputs.filter((input) => !hooked.has(input));
     const options = authored.filter((input) => input.kind === 'option');
+    const locals = byName(options);
     const held = {
-        arguments: new Set(authored.filter((input) => input.kind === 'argument').map((input) => input.name)),
+        arguments: byName(authored.filter((input) => input.kind === 'argument')),
         globals,
         hookArguments: new Map(),
         hooks: new Map(),
-        locals: new Set(options.map((input) => input.name)),
+        locals,
+        path,
     };
     const claimed = new Map();
-    readSpellings(globals.options, claimed);
-    readSpellings(compileOptions(options, subject), claimed);
-    for (const { identity, input } of attached) {
+    readSpellings(globals.options, claimed, tableSpellings(globals));
+    readSpellings(compileOptions(options, scope), claimed, (name, role) => {
+        const local = locals.get(name);
+        return local === undefined || local.kind !== 'option'
+            ? undefined
+            : spellingPlace(scope.siteOf(local), role, `the local option "${name}"`);
+    });
+    for (const entry of attached) {
+        const { identity, input } = entry;
         const collision = attachedCollision(input, held);
         if (collision) {
-            throw new DeclarationError(`Plugin "${identity}" declares ${input.kind} "${input.name}" on ${subject}, which is already declared as ${collision.clause}. ${collision.remedy}`);
+            throw new DeclarationError(nameCollisionRule(input.kind, collision.kind), {
+                correction: collision.remedy,
+                findings: [inputFinding(path, input, hookNote(identity)), collision.held],
+                sentence: `Plugin ${quoted(identity)} declares ${input.kind} ${quoted(input.name)} on ${subject}, which is already declared as ${collision.clause}.`,
+            });
         }
         if (input.kind === 'option') {
-            checkAttachedSpelling({ identity, input }, { claimed, subject });
-            held.hooks.set(input.name, identity);
+            checkAttachedSpelling({ identity, input }, { claimed, scope });
+            held.hooks.set(input.name, entry);
         }
         else {
-            held.hookArguments.set(input.name, identity);
+            held.hookArguments.set(input.name, entry);
         }
     }
 }
 /** 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,69 +1395,64 @@ 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) {
-        const sentence = `${commandSentence(name)} ${input.kind} "${input.name}"`;
-        checkDescription(sentence, input.config.description);
+        const site = inputSite(name, context.path, input);
+        const sentence = site.subject;
+        checkDescription(site, input.config.description);
         if (input.kind === 'argument') {
-            checkNoListingFacts(sentence, input.config);
+            checkNoListingFacts(site, input.config);
+            checkNoArgumentBinding(site, input.config);
         }
         else {
-            checkHidden(sentence, input.config.hidden);
-            checkDeprecated(sentence, input.config.deprecated);
+            checkHidden(site, input.config.hidden);
+            checkDeprecated(site, input.config.deprecated);
+            checkEnvBinding(site, input.config);
         }
         context.extensions.set(input, buildExtensions({
             declared: input.config.extensions,
             descriptors: context.descriptors,
+            site: { ...site, at: '1.extensions' },
             subject: { phrase: `on ${subject} ${input.kind} "${input.name}"`, sentence },
             target: input.kind,
         }));
     }
 }
 /** One Command declares arguments or attaches children, whichever declaration made each of them. */
-function checkArgumentPlacement(name, slot, child) {
+function checkArgumentPlacement(command, 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(command, slot.input, child);
     }
 }
-/** 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 action = actions[0];
+    const layer = layerOf(name);
+    for (const [input, record] of state.records) {
+        context.extensions.set(input, record);
+    }
+    const place = { name, path: context.path };
+    const declaredSlots = collectArguments(state, place);
     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) {
@@ -820,38 +1463,37 @@ export function buildCommand(state, context) {
     checkInputFacts(hookInputs.map((call) => call.input), { name, subject }, 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.
+    checkAttachedInputs(hooked, hookInputs, { globals, path: context.path });
+    // 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);
+    const slots = hookInputs.length > 0 ? collectArguments(hooked, place) : declaredSlots;
+    checkArgumentPlacement(place, slots[0], state.children[0]);
+    const result = checkFinished(hooked, hasAction, { path: context.path });
+    const options = checkLocalOptions(optionsOf(hooked.inputs), globals, localScope(name, context.path));
+    // A hook's erased calls answer the declaration rules an authored call answers at the call.
+    checkDeclarations(hookInputs.map(({ input }) => ({ input, site: inputSite(name, context.path, 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,105 +1501,101 @@ 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 = {
-            config: captureConfig(config),
+            config,
             kind: 'argument',
             name,
         };
-        return this.derive(declareArgument(this.#state, input));
+        return this.#derive(declareArgument(this.#state, input));
     }
     option(name, config) {
         const input = {
-            config: captureConfig(config),
+            config,
             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. */
@@ -970,21 +1608,54 @@ export function collectInputs(command) {
     ];
 }
 /**
- * The names a routing failure offers: the canonical names of the visible children, in authoring
- * order. A candidate list is a listing, so a hidden child is absent from it, and a parent whose
- * children are all hidden offers none.
+ * Where every input of one graph was declared: each global option at its `globalOption()` call,
+ * and each Command's own inputs at their calls on the Command, under its path from the root.
+ */
+export function inputPlaces(graph) {
+    const places = new Map();
+    for (const input of graph.globals.inputs) {
+        places.set(input, inputPlace(input, { global: true, path: [] }));
+    }
+    const walk = (command, path) => {
+        for (const input of command.inputs) {
+            places.set(input, inputPlace(input, { global: false, path }));
+        }
+        for (const [name, child] of command.children) {
+            walk(child, [...path, name]);
+        }
+    };
+    walk(graph.root, []);
+    return places;
+}
+/**
+ * The names a routing failure offers: the canonical names of the visible, current children, in
+ * authoring order. A candidate list is a listing, so a hidden or a deprecated child is absent from
+ * it, as completion leaves them out, and a parent whose children are all hidden or deprecated
+ * offers none. A deprecated child typed in full still routes.
  */
 function candidatesOf(command) {
-    return [...command.children].filter(([, child]) => !child.hidden).map(([name]) => name);
+    return [...command.children]
+        .filter(([, child]) => !child.hidden && child.deprecated === undefined)
+        .map(([name]) => name);
 }
-/** Bare tokens, names or aliases, select children until a Command has none; a hyphen commits. */
-export function route(root, tokens) {
+/**
+ * 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.
+ * `walked` receives the path after each name routes, so an unknown Command leaves its caller
+ * holding the partial path walked before it.
+ */
+export function route(root, tokens, walked) {
     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);
@@ -994,6 +1665,7 @@ export function route(root, tokens) {
         // An alias routes like the canonical name, and the path it walks reports that name alone.
         command = child.command;
         path.push(child.name);
+        walked?.(Object.freeze([...path]));
         index += 1;
     }
     return { command, path, tokens: tokens.slice(index) };
@@ -1005,33 +1677,40 @@ 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;
 }
-/** Consumes the globals table, then routes the remaining bare tokens to a Command. */
-export function routeInvocation(graph, argv) {
+/**
+ * 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. `walked`
+ * receives the path as routing extends it, the partial path of an unknown Command included.
+ */
+export function routeInvocation(graph, argv, walked) {
     const scan = extractGlobals(graph.globals.options, [...argv]);
-    const routed = route(graph.root, scan.rest);
+    const routed = route(graph.root, scan.rest, walked);
     return {
         command: routed.command,
         path: routed.path,
@@ -1060,37 +1739,104 @@ 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,
+        };
     }
-    const parsed = parseInputs(command.options, routed.tokens);
-    const args = bindArguments(command, path, parsed.positionals);
+    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 graphMismatch(`Option "${place.name}" is not in the inspected graph.`);
+    }
+    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,
+        offer: invocation.offer,
+        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 +1858,43 @@ 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 };
+        // The fault is held as a failure, so a throw from reading a validator's output is never offered.
+        return held(toFailure(error));
     }
 }