@loomcli/core 0.6.0 → 0.8.0

package/NOTICE

@@ -0,0 +1,34 @@
+@loomcli/core
+
+This package includes material from uucode and from the Unicode Character
+Database. Its license field reads "MIT AND Unicode-3.0": the Unicode tables
+named below stay under the Unicode License v3, and every other file is under
+the MIT License in LICENSE or, for the ported width iterator, in
+licenses/uucode-LICENSE.md. Neither license asks anything of an application
+that installs this package beyond keeping these notices with the files they
+cover.
+
+Unicode Character Database
+Copyright © 1991-2025 Unicode, Inc.
+Licensed under the Unicode License v3.
+A copy of the License is in licenses/unicode-LICENSE.txt, and at
+https://www.unicode.org/license.txt
+
+uucode
+Copyright (c) 2026 Tim Culverhouse
+Licensed under the MIT License.
+A copy of the License is in licenses/uucode-LICENSE.md.
+Source: @rockorager/uucode 2.2.1 on npm
+
+The Unicode tables core measures text with, in dist/unicode.generated.js, are
+generated by the Loom repository's scripts/generate-unicode-tables.mjs from
+the data files of @rockorager/uucode 2.2.1, which derive from Unicode 17 data.
+The generator writes the same values as a JavaScript module, so a bundle
+carries them.
+
+The grapheme width iterator in dist/style-width.js is ported from the
+@rockorager/uucode 2.2.1 width module. Changes made to it:
+
+- It is written in TypeScript and reads the generated tables module.
+- It yields each grapheme's start, end, and width, and no longer yields the
+  grapheme's text or offers clone, peek, or a standalone string width.

package/dist/application.d.ts

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

package/dist/application.js

@@ -1,7 +1,9 @@
+import { captureDeclaration, unreadableArgument } from './capture.js';
 import { runInvocation } from './chain.js';
 import { portableName } from './command-rules.js';
 import { attachToRoot, callArguments, childNode, buildGraph, checkDeclaredOptions, collectInputs, commandPlacement, inputPlaces, declareAction, declareExtensions, declareArgument, declareOption, declareResult, declareResultViews, freshState, isPortableName, layerOf, portableNameCorrection, } from './command.js';
 import { escapeControlCharacters } from './controls.js';
+import { elided, spelled } from './diagnostic-text.js';
 import { DeclarationError, exitCodeOf, InternalError, quoted, reasonOf, toFailure, } from './errors.js';
 import { storeCommandLayers } from './extension.js';
 import { checkDescription, checkNoListingFacts, checkVersion, partFinding, slotSite, } from './facts.js';
@@ -12,14 +14,14 @@ import { globalOptionAfterCommand } from './input-rules.js';
 import { inspectGraph } from './inspect.js';
 import { coreViews } from './lanes.js';
 import { Output, reportPlainly } from './output.js';
-import { isPlainObject } from './plain.js';
+import { declaring, isPlainObject, shallowList, shallowRecord } from './plain.js';
 import { invalidPacket, notAnObject, retiredApplicationOption } from './plugin-rules.js';
 import { installPlugins, ownedSignals, pluginViews } from './plugin.js';
 import { renderingPolicy } from './rendering.js';
 import { brokenOutputView, runOptions, viewCorrection } from './rules.js';
 import { bracketRun, cancellationCode, isCancellationEcho } from './signals.js';
 import { readTranslations, translateThrow } from './translators.js';
-import { checkDeclarations, prepareInputs } from './validation.js';
+import { checkDeclarations, prepareDeclaredValues } from './validation.js';
 import { buildViews, viewIdentities } from './view.js';
 /** The registry a failure is reported through when the application's own could not be built. */
 const noViews = [];
@@ -133,11 +135,17 @@ class ApplicationBuilder {
     }
     globalOption(name, config) {
         // The plugins' Commands attach at construction, so only the application's own calls close it.
+        // The config is judged after the order, so the finding prints it elided and reads none of it.
         if (this.#config.composed) {
             throw new DeclarationError(globalOptionAfterCommand, {
                 correction: 'Declare global options before attaching Commands or registering an action.',
                 findings: [
-                    { arguments: callArguments(name, config), call: 'globalOption', mark: '0', path: [] },
+                    {
+                        arguments: callArguments(name, config === undefined ? undefined : spelled(elided)),
+                        call: 'globalOption',
+                        mark: '0',
+                        path: [],
+                    },
                 ],
                 sentence: `The Application declares global option ${quoted(name)} after command() or action().`,
             });
@@ -331,7 +339,8 @@ class ApplicationBuilder {
                     inspected();
                 }
                 const inputs = { globals: graph.globals.inputs, locals: collectInputs(graph.root) };
-                const defaults = await prepareInputs(inputs, host, inputPlaces(graph));
+                const places = inputPlaces(graph);
+                const declaredValues = await prepareDeclaredValues(inputs, host, places);
                 graphBuilt = true;
                 if (!controller.signal.aborted) {
                     /**
@@ -341,12 +350,13 @@ class ApplicationBuilder {
                     signals.install(ownedSignals(built.plugins));
                     await runInvocation({
                         channel: (binding) => invocationOutput.channel(binding),
-                        defaults,
+                        declaredValues,
                         graph,
                         host,
                         inspected,
                         offer,
                         out: output.out,
+                        places,
                         plugins: built.plugins,
                         report: (fault) => faults.push(fault),
                         route: (path) => {
@@ -481,7 +491,10 @@ function runRendering(rendering) {
         subject: 'The run',
     };
 }
-/** Reject obsolete wiring before silently losing options that invocations depend on. */
+/**
+ * Reject obsolete wiring before silently losing options that invocations depend on. `options` is the
+ * copy `captureOptions` took, or `undefined` for an Application declared without options.
+ */
 function checkOptions(name, options) {
     const site = {
         at: '1',
@@ -491,13 +504,6 @@ function checkOptions(name, options) {
     if (options === undefined) {
         return { description: undefined, version: checkVersion(site, undefined) };
     }
-    if (!isPlainObject(options)) {
-        throw new DeclarationError(notAnObject, {
-            correction: 'Supply an Application options object.',
-            findings: [{ ...site.declaration, mark: '1' }],
-            sentence: 'The Application declares options that are not an object.',
-        });
-    }
     for (const [key, correction] of retired) {
         if (key in options) {
             const retiredSite = optionSite(name, key, Reflect.get(options, key));
@@ -546,15 +552,44 @@ function readPacket(name, packet) {
         sentence: found,
     });
 }
+/** The parts of the Application options that are lists, each copied with its entries as built. */
+const optionLists = ['plugins', 'views', 'translators', 'extensions'];
+/**
+ * The one copy of the options that `new Application(name, options)` reads: the options object, its
+ * packet and rendering policy, and each list it holds. An entry of a list is what its factory built
+ * and is not copied. A read that throws is the unreadable fault of the options, and a value that is
+ * not a plain object is the not-an-object fault. An Application declared without options has none
+ * to copy.
+ */
+function captureOptions(name, options) {
+    if (options === undefined) {
+        return undefined;
+    }
+    return captureDeclaration(options, (copy, read) => {
+        read.nested(copy, 'packet', shallowRecord);
+        read.nested(copy, 'rendering', shallowRecord);
+        for (const list of optionLists) {
+            read.nested(copy, list, shallowList);
+        }
+    }, {
+        notAnObject: () => new DeclarationError(notAnObject, {
+            correction: 'Supply an Application options object.',
+            findings: [{ arguments: [name, options], call: 'new Application', mark: '1' }],
+            sentence: 'The Application declares options that are not an object.',
+        }),
+        unreadable: unreadableArgument({ call: 'new Application', named: name, subject: 'The Application' }, 'options'),
+    });
+}
 /**
  * Every rule `new Application(name, options)` applies, in the order it reads the slot: the
  * application's own view overrides, its translations, the rendering policy, the options slot and
  * its facts, the installed list and every rule between two plugins, the root's extension values,
  * and then each plugin's Commands, which attach to the root first, in installation order and list
- * order.
+ * order. Each reads the one copy of the options `captureOptions` takes. The root's globals are
+ * the option values the declared `plugins` tuple contributes.
  */
-function declareApplication(name, options) {
-    const slot = isPlainObject(options) ? options : undefined;
+function declareApplication(name, declared) {
+    const slot = captureOptions(name, declared);
     const identities = viewIdentities(coreViews);
     const views = buildViews({
         declares: false,
@@ -563,7 +598,7 @@ function declareApplication(name, options) {
     }, slot?.views, identities);
     const translations = readTranslations(optionSite(name, 'translators', slot?.translators), slot?.translators);
     const rendering = renderingPolicy(slot?.rendering, optionSite(name, 'rendering', slot?.rendering));
-    const facts = checkOptions(name, options);
+    const facts = checkOptions(name, slot);
     const development = readPacket(name, slot?.packet);
     const installed = installPlugins(name, slot?.plugins ?? []);
     const { plugins } = installed;
@@ -619,12 +654,15 @@ function checkApplicationName(name) {
     }
     return name;
 }
-/** Constructor inference preserves the installed plugin tuple; globals start empty. */
+/**
+ * Constructor inference preserves the installed plugin tuple, and the globals start as the option
+ * values the installed plugins contribute.
+ */
 class ApplicationDeclaration extends ApplicationBuilder {
     constructor(name, options) {
         // The arguments evaluate in order, so the name is checked before any option is read.
         const checked = checkApplicationName(name);
-        super(checked, declareApplication(checked, options));
+        super(checked, declaring(() => declareApplication(checked, options)));
     }
 }
 export const Application = ApplicationDeclaration;

package/dist/capture.d.ts

@@ -0,0 +1,65 @@
+import type { Finding } from './diagnostic-text.js';
+import { DeclarationError } from './errors.js';
+/**
+ * One declaring call's read of the object an author passed it, under way. It remembers the slot it
+ * is reading, so a read that throws names the slot it threw in, or no slot when the object itself
+ * threw.
+ */
+declare class DeclarationRead {
+    /** The top-level key being read, or `undefined` while the object itself is read. */
+    slot: string | undefined;
+    /** The copy of every own string key of one object, each read under its own slot. */
+    record(declared: object): Record<string, unknown>;
+    /**
+     * Replaces the value one key of a copy holds with `copy` of it, read under that key's slot. An
+     * absent key stays absent, so a finding prints the copy with the keys the author wrote.
+     */
+    nested(captured: Record<string, unknown>, key: string, copy: (value: unknown) => unknown): void;
+}
+/** The two faults one declaring call raises when it cannot capture what it was given. */
+interface CaptureFaults {
+    /** The value is not a plain object, so it has no keys for core to read. */
+    readonly notAnObject: () => DeclarationError;
+    /** A read threw the value it receives, in the top-level slot it names, or in the object itself. */
+    readonly unreadable: (thrown: unknown, slot: string | undefined) => DeclarationError;
+}
+/**
+ * Authoring's one read of an object a declaring call receives, inside one try: the verdict on its
+ * prototype, the copy of every own string key, and the copies `nested` takes of the parts it holds,
+ * each judged plain once by `decidePlain`. Every later check, stored value, and finding reads that
+ * copy and never the author's object again, so a getter runs once and a read that threw is never
+ * repeated. A value that is not a plain object is the not-an-object fault, and a read that throws,
+ * from a getter or a proxy trap, is the unreadable fault, named by the slot it threw in.
+ */
+declare function captureDeclaration<Declared>(declared: Declared, nested: (copy: Record<string, unknown>, read: DeclarationRead) => void, faults: CaptureFaults): Declared & Record<string, unknown>;
+/**
+ * What a finding prints for a declaration whose read threw: the slot it threw in, elided, under the
+ * keys that lead to it, or the whole declaration elided. A read that threw is never repeated.
+ */
+declare function elidedRead(slot: string | undefined): {
+    keys: readonly string[];
+    shown: unknown;
+};
+/** What one unreadable declaration is: an input's config, a plugin's definition, or an options object. */
+type Unreadable = 'config' | 'definition' | 'options';
+/**
+ * The fault for a declaration whose read threw, named by `subject` and marked by `findings`. The
+ * thrown value's reason ends the sentence and the value itself is the fault's cause.
+ */
+declare function unreadableFault(report: {
+    readonly declared: Unreadable;
+    readonly findings: readonly Finding[];
+    readonly subject: string;
+}, thrown: unknown): DeclarationError;
+/**
+ * The unreadable fault of the object a `plugin()` call or a constructor receives as its second
+ * argument. Its finding marks the top-level slot whose read threw, or the whole argument when the
+ * object itself threw, and prints that part elided.
+ */
+declare function unreadableArgument(declaration: {
+    readonly call: string;
+    readonly named: unknown;
+    readonly subject: string;
+}, declared: 'definition' | 'options'): (thrown: unknown, slot: string | undefined) => DeclarationError;
+export type { CaptureFaults };
+export { captureDeclaration, elidedRead, unreadableArgument, unreadableFault };

package/dist/capture.js

@@ -0,0 +1,99 @@
+import { elided, spelled } from './diagnostic-text.js';
+import { asSentence, DeclarationError, reasonOf } from './errors.js';
+import { copyOwnKeys, decidePlain } from './plain.js';
+import { unreadableDeclaration } from './plugin-rules.js';
+/**
+ * One declaring call's read of the object an author passed it, under way. It remembers the slot it
+ * is reading, so a read that throws names the slot it threw in, or no slot when the object itself
+ * threw.
+ */
+class DeclarationRead {
+    /** The top-level key being read, or `undefined` while the object itself is read. */
+    slot = undefined;
+    /** The copy of every own string key of one object, each read under its own slot. */
+    record(declared) {
+        const copy = copyOwnKeys(declared, (key) => {
+            this.slot = key;
+        });
+        this.slot = undefined;
+        return copy;
+    }
+    /**
+     * Replaces the value one key of a copy holds with `copy` of it, read under that key's slot. An
+     * absent key stays absent, so a finding prints the copy with the keys the author wrote.
+     */
+    nested(captured, key, copy) {
+        if (Object.hasOwn(captured, key)) {
+            this.slot = key;
+            captured[key] = copy(captured[key]);
+            this.slot = undefined;
+        }
+    }
+}
+/**
+ * Authoring's one read of an object a declaring call receives, inside one try: the verdict on its
+ * prototype, the copy of every own string key, and the copies `nested` takes of the parts it holds,
+ * each judged plain once by `decidePlain`. Every later check, stored value, and finding reads that
+ * copy and never the author's object again, so a getter runs once and a read that threw is never
+ * repeated. A value that is not a plain object is the not-an-object fault, and a read that throws,
+ * from a getter or a proxy trap, is the unreadable fault, named by the slot it threw in.
+ */
+function captureDeclaration(declared, nested, faults) {
+    const read = new DeclarationRead();
+    let copy = undefined;
+    try {
+        if (decidePlain(declared)) {
+            copy = read.record(declared);
+            nested(copy, read);
+        }
+    }
+    catch (error) {
+        throw faults.unreadable(error, read.slot);
+    }
+    if (copy === undefined) {
+        throw faults.notAnObject();
+    }
+    // Last resort: no typed path exists.
+    // The copy is built key by key, so the compiler types it as a record of unknown values.
+    // A spread would keep the declared type, but it reads enumerable keys alone and names no slot.
+    // It holds because the copy holds every own string key of the declared plain object.
+    // Each holds the value read from it once, or that value's copy of the same kind.
+    // No declaration type declares a symbol key, and none reads its prototype.
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+    return copy;
+}
+/**
+ * What a finding prints for a declaration whose read threw: the slot it threw in, elided, under the
+ * keys that lead to it, or the whole declaration elided. A read that threw is never repeated.
+ */
+function elidedRead(slot) {
+    return slot === undefined
+        ? { keys: [], shown: spelled(elided) }
+        : { keys: [slot], shown: Object.fromEntries([[slot, spelled(elided)]]) };
+}
+/**
+ * The fault for a declaration whose read threw, named by `subject` and marked by `findings`. The
+ * thrown value's reason ends the sentence and the value itself is the fault's cause.
+ */
+function unreadableFault(report, thrown) {
+    const { declared, findings, subject } = report;
+    return new DeclarationError(unreadableDeclaration, {
+        correction: `Declare the ${declared} as a plain object literal whose properties read without throwing.`,
+        findings,
+        sentence: `${subject} ${declared} could not be read: ${asSentence(reasonOf(thrown))}`,
+    }, { cause: thrown });
+}
+/**
+ * The unreadable fault of the object a `plugin()` call or a constructor receives as its second
+ * argument. Its finding marks the top-level slot whose read threw, or the whole argument when the
+ * object itself threw, and prints that part elided.
+ */
+function unreadableArgument(declaration, declared) {
+    const { call, named, subject } = declaration;
+    return (thrown, slot) => {
+        const { keys, shown } = elidedRead(slot);
+        const finding = { arguments: [named, shown], call, mark: ['1', ...keys].join('.') };
+        return unreadableFault({ declared, findings: [finding], subject }, thrown);
+    };
+}
+export { captureDeclaration, elidedRead, unreadableArgument, unreadableFault };

package/dist/chain.d.ts

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

package/dist/chain.js

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

package/dist/command-rules.d.ts

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

package/dist/command-rules.js

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