@loomcli/core 0.4.0 → 0.6.0

package/dist/prototypes.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Every prototype in one value's chain, most derived first, or `undefined` when the chain cannot
+ * be read: a proxy trap throws, a link repeats, or the chain runs past `maxChainLinks` links. A
+ * value with a `null` prototype has an empty chain. Override resolution and translator resolution
+ * both walk the chain this returns.
+ */
+export declare function prototypeChain(value: object): object[] | undefined;

package/dist/prototypes.js

@@ -0,0 +1,29 @@
+/** The most links a prototype chain holds before core reads it as a chain that never ends. */
+const maxChainLinks = 1024;
+/** The walk behind `prototypeChain`, which throws where a proxy trap throws. */
+function walkChain(value) {
+    const chain = [];
+    const seen = new Set([value]);
+    for (let link = Reflect.getPrototypeOf(value); link !== null; link = Reflect.getPrototypeOf(link)) {
+        if (seen.has(link) || chain.length >= maxChainLinks) {
+            return undefined;
+        }
+        seen.add(link);
+        chain.push(link);
+    }
+    return chain;
+}
+/**
+ * Every prototype in one value's chain, most derived first, or `undefined` when the chain cannot
+ * be read: a proxy trap throws, a link repeats, or the chain runs past `maxChainLinks` links. A
+ * value with a `null` prototype has an empty chain. Override resolution and translator resolution
+ * both walk the chain this returns.
+ */
+export function prototypeChain(value) {
+    try {
+        return walkChain(value);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/rendering.d.ts

@@ -1,3 +1,4 @@
+import type { FactSite } from './facts.js';
 import type { Host } from './types.js';
 type SwitchPolicy = 'auto' | 'always' | 'never';
 interface RenderingPolicy {
@@ -14,7 +15,11 @@ interface Capabilities {
     depth: 16 | 256 | 'truecolor';
     mainGlyphs: boolean;
 }
-declare function renderingPolicy(value: unknown): RenderingPolicy;
+/**
+ * One declared rendering policy, checked against its closed sets. `site` is where it was declared,
+ * the Application's `rendering` option or `run()`'s, which a fault marks.
+ */
+declare function renderingPolicy(value: unknown, site: FactSite): RenderingPolicy;
 /** A run owns captured facts; stdout and stderr each resolve this one policy independently. */
 declare function capabilities(host: Host, destination: 'stdout' | 'stderr', policy: RenderingPolicy): Capabilities;
 export type { Capabilities, RenderingPolicy };

package/dist/rendering.js

@@ -1,17 +1,31 @@
 import { DeclarationError } from './errors.js';
-import { isPlainObject } from './facts.js';
-function renderingPolicy(value) {
+import { partFinding } from './facts.js';
+import { isPlainObject } from './plain.js';
+import { renderingPolicyRule } from './plugin-rules.js';
+/**
+ * One declared rendering policy, checked against its closed sets. `site` is where it was declared,
+ * the Application's `rendering` option or `run()`'s, which a fault marks.
+ */
+function renderingPolicy(value, site) {
     if (value === undefined) {
         return {};
     }
     if (!isPlainObject(value)) {
-        throw new DeclarationError('The rendering policy must be an object.');
+        throw new DeclarationError(renderingPolicyRule, {
+            correction: 'Supply an object, or omit rendering.',
+            findings: [partFinding(site, [])],
+            sentence: 'The rendering policy is not an object.',
+        });
     }
     const result = {};
     for (const field of ['color', 'modifiers', 'hyperlinks']) {
         const policy = value[field];
         if (policy !== undefined && policy !== 'auto' && policy !== 'always' && policy !== 'never') {
-            throw new DeclarationError(`Rendering ${field} must be auto, always, or never.`);
+            throw new DeclarationError(renderingPolicyRule, {
+                correction: `Supply one of the three, or omit ${field}.`,
+                findings: [partFinding(site, [field])],
+                sentence: `Rendering ${field} is not auto, always, or never.`,
+            });
         }
         if (policy !== undefined) {
             result[field] = policy;
@@ -19,7 +33,11 @@ function renderingPolicy(value) {
     }
     const controls = value.terminalControls;
     if (controls !== undefined && controls !== 'strip' && controls !== 'preserve') {
-        throw new DeclarationError('Rendering terminalControls must be strip or preserve.');
+        throw new DeclarationError(renderingPolicyRule, {
+            correction: 'Supply strip or preserve, or omit terminalControls.',
+            findings: [partFinding(site, ['terminalControls'])],
+            sentence: 'Rendering terminalControls is not strip or preserve.',
+        });
     }
     if (controls !== undefined) {
         result.terminalControls = controls;

package/dist/rules.d.ts

@@ -0,0 +1,51 @@
+/** A value thrown from an action, a middleware, or a source that no translator answered. */
+declare const foreignThrow: import("./diagnostic-text.js").DiagnosticRule;
+/** The fix every foreign throw shares. */
+declare const foreignThrowCorrection = "Catch the error where it is thrown and throw a failure class, such as FatalError, with a sentence the operator can act on.";
+/** A thrown value that inherits from a failure class without having been constructed by one. */
+declare const unconstructedFailure: import("./diagnostic-text.js").DiagnosticRule;
+/** A translator that threw or answered with something other than a failure. */
+declare const brokenTranslator: import("./diagnostic-text.js").DiagnosticRule;
+/** The fix every broken translator shares. */
+declare const brokenTranslatorCorrection = "Return a failure, or undefined to pass, and throw nothing from the translator.";
+/** A failure view that threw or returned a value that is not a string. */
+declare const brokenFailureView: import("./diagnostic-text.js").DiagnosticRule;
+/** An output or lane view that threw or returned a value that is not a string. */
+declare const brokenOutputView: import("./diagnostic-text.js").DiagnosticRule;
+/** The fix a broken failure view and a broken output view share. */
+declare const viewCorrection = "Return a string from the view's render function, and throw nothing from it.";
+/** An `onFailure` hook that threw or returned a value that is not hints. */
+declare const brokenFailureHook: import("./diagnostic-text.js").DiagnosticRule;
+/** A plugin's middleware or source loader that rejected or exported no default function. */
+declare const pluginLoaderFailed: import("./diagnostic-text.js").DiagnosticRule;
+/** A middleware that called `next()` twice, or after it returned. */
+declare const nextMisuse: import("./diagnostic-text.js").DiagnosticRule;
+/** An action or a plugin that broke the promise a declared result makes. */
+declare const resultContract: import("./diagnostic-text.js").DiagnosticRule;
+/** A validator that threw, rejected, or returned a malformed result. */
+declare const validatorFailed: import("./diagnostic-text.js").DiagnosticRule;
+/** A middleware that assigned `view` a name the routed Command's result cannot render. */
+declare const viewSelection: import("./diagnostic-text.js").DiagnosticRule;
+/** The fix every invalid view selection shares. */
+declare const viewSelectionCorrection = "Assign view one of the view names the routed Command's result declares, and only on a Command that declares a result.";
+/** A `run()` option that holds a value of the wrong kind. */
+declare const runOptions: import("./diagnostic-text.js").DiagnosticRule;
+/** A configuration source whose answers break the answers rule. */
+declare const sourceAnswers: import("./diagnostic-text.js").DiagnosticRule;
+/** The fix every source answers fault shares. */
+declare const sourceAnswersCorrection = "Return a record that maps each requested option's name to { value, label }, with a value of the option's raw type.";
+/** A graph that `inspect()` did not return, or whose nodes disagree with the build it came from. */
+declare const foreignGraph: import("./diagnostic-text.js").DiagnosticRule;
+/** The fix every foreign graph shares. */
+declare const foreignGraphCorrection = "Pass the graph inspect() returned, unchanged.";
+/** A host stream that failed a write the run owed it. */
+declare const brokenDestination: import("./diagnostic-text.js").DiagnosticRule;
+/** A failure class whose exit code is outside 1 through 125. */
+declare const failureExitCode: import("./diagnostic-text.js").DiagnosticRule;
+/** A diagnostic rule identity outside the `<package>[/<subpath>...]/<kebab-case-rule>` grammar. */
+declare const ruleIdentity: import("./diagnostic-text.js").DiagnosticRule;
+/** A diagnostic rule whose headline or explanation holds no prose. */
+declare const ruleProse: import("./diagnostic-text.js").DiagnosticRule;
+/** A diagnostic rule whose docs value is not a web address. */
+declare const ruleDocs: import("./diagnostic-text.js").DiagnosticRule;
+export { brokenDestination, brokenFailureHook, brokenFailureView, brokenOutputView, brokenTranslator, brokenTranslatorCorrection, failureExitCode, foreignGraph, foreignGraphCorrection, foreignThrow, foreignThrowCorrection, nextMisuse, pluginLoaderFailed, resultContract, ruleDocs, ruleIdentity, ruleProse, runOptions, sourceAnswers, sourceAnswersCorrection, unconstructedFailure, validatorFailed, viewCorrection, viewSelection, viewSelectionCorrection, };

package/dist/rules.js

@@ -0,0 +1,115 @@
+import { registerRule } from './diagnostic-text.js';
+/*
+ * Core's own rules for the defects it raises, the run-time declaration faults it finds, and the
+ * faults of the two things an author declares to describe a failure: a failure class's exit code
+ * and a diagnostic rule. Each is declared once here and shared by every site that raises it, as a
+ * plugin's rules are.
+ */
+/** A value thrown from an action, a middleware, or a source that no translator answered. */
+const foreignThrow = registerRule('@loomcli/core/foreign-throw', {
+    explanation: 'Core reports a value that an action, a middleware, or a configuration source threw, and that no translator answered, as a defect, because only the author knows what it means. A distributed build shows the operator one generic message in its place.',
+    headline: 'Unhandled exception',
+});
+/** The fix every foreign throw shares. */
+const foreignThrowCorrection = 'Catch the error where it is thrown and throw a failure class, such as FatalError, with a sentence the operator can act on.';
+/** A thrown value that inherits from a failure class without having been constructed by one. */
+const unconstructedFailure = registerRule('@loomcli/core/unconstructed-failure', {
+    explanation: 'A failure class records its exit code when a failure is constructed, so a value that only inherits from one, such as one made with Object.create(), carries no code core can trust.',
+    headline: 'Failure never constructed',
+});
+/** A translator that threw or answered with something other than a failure. */
+const brokenTranslator = registerRule('@loomcli/core/broken-translator', {
+    explanation: 'A translator turns a foreign throw into a failure synchronously. A throw, or any answer other than a failure or undefined, leaves core no failure to report, so it consults no later translator.',
+    headline: 'Broken translator',
+});
+/** The fix every broken translator shares. */
+const brokenTranslatorCorrection = 'Return a failure, or undefined to pass, and throw nothing from the translator.';
+/** A failure view that threw or returned a value that is not a string. */
+const brokenFailureView = registerRule('@loomcli/core/broken-failure-view', {
+    explanation: "A failure view turns a failure into the text the operator reads, synchronously and without throwing. Core wrote its own text for the failure in the view's place.",
+    headline: 'Broken failure view',
+});
+/** An output or lane view that threw or returned a value that is not a string. */
+const brokenOutputView = registerRule('@loomcli/core/broken-output-view', {
+    explanation: 'A view turns a value into text synchronously and without throwing. Core wrote nothing for the call whose view broke, and a run whose output is incomplete cannot succeed.',
+    headline: 'Broken output view',
+});
+/** The fix a broken failure view and a broken output view share. */
+const viewCorrection = "Return a string from the view's render function, and throw nothing from it.";
+/** An `onFailure` hook that threw or returned a value that is not hints. */
+const brokenFailureHook = registerRule('@loomcli/core/broken-failure-hook', {
+    explanation: "An onFailure hook adds hint lines under a failure, synchronously and without throwing. Core dropped this hook's hints and rendered the failure with every other plugin's.",
+    headline: 'Broken failure hook',
+});
+/** A plugin's middleware or source loader that rejected or exported no default function. */
+const pluginLoaderFailed = registerRule('@loomcli/core/plugin-loader-failed', {
+    explanation: "Core loads a plugin's middleware or source module the first time a run reaches it, and the module owes its function as its default export.",
+    headline: 'Plugin loader failed',
+});
+/** A middleware that called `next()` twice, or after it returned. */
+const nextMisuse = registerRule('@loomcli/core/next-misuse', {
+    explanation: 'next() continues the middleware chain once, while the middleware that received it runs. A second call, or a call after the middleware returned, has no chain left to continue.',
+    headline: 'next() misused',
+});
+/** An action or a plugin that broke the promise a declared result makes. */
+const resultContract = registerRule('@loomcli/core/result-contract', {
+    explanation: 'A Command that declares a result promises its consumer one value, or one sequence of rows, that its action emits once through out.results().',
+    headline: 'Result contract broken',
+});
+/** A validator that threw, rejected, or returned a malformed result. */
+const validatorFailed = registerRule('@loomcli/core/validator-failed', {
+    explanation: 'Only an issue a validator returns states a validation verdict. A validator that throws, rejects, or returns anything but a Standard Schema result leaves core no verdict to report, so validation stops and the action does not run.',
+    headline: 'Validator failed',
+});
+/** A middleware that assigned `view` a name the routed Command's result cannot render. */
+const viewSelection = registerRule('@loomcli/core/view-selection', {
+    explanation: "A middleware selects one of the views the routed Command's result declares, by name, before the action runs. A Command that declares no result has no view to select, and a name its result does not declare has no view to render.",
+    headline: 'Invalid view selection',
+});
+/** The fix every invalid view selection shares. */
+const viewSelectionCorrection = "Assign view one of the view names the routed Command's result declares, and only on a Command that declares a result.";
+/** A `run()` option that holds a value of the wrong kind. */
+const runOptions = registerRule('@loomcli/core/run-options', {
+    explanation: 'run() reads its options before it builds the graph. A caller that embeds the application, such as a test, passes them, and a value of the wrong kind leaves the run nothing to act on.',
+    headline: 'Invalid run options',
+});
+/** A configuration source whose answers break the answers rule. */
+const sourceAnswers = registerRule('@loomcli/core/source-answers', {
+    explanation: 'A configuration source answers with a record that maps each option core requested to { value, label }, where the value has the raw type the option takes and the label is one line of prose. Core fills no option from any other answer.',
+    headline: 'Invalid source answers',
+});
+/** The fix every source answers fault shares. */
+const sourceAnswersCorrection = "Return a record that maps each requested option's name to { value, label }, with a value of the option's raw type.";
+/** A graph that `inspect()` did not return, or whose nodes disagree with the build it came from. */
+const foreignGraph = registerRule('@loomcli/core/foreign-graph', {
+    explanation: 'Core reads a Command graph through the build inspect() rendered it from. A graph inspect() did not return, or one whose nodes do not match that build, leaves core no build to read, so the run stops rather than hand a plugin the wrong Command.',
+    headline: 'Graph not from inspect()',
+});
+/** The fix every foreign graph shares. */
+const foreignGraphCorrection = 'Pass the graph inspect() returned, unchanged.';
+/** A host stream that failed a write the run owed it. */
+const brokenDestination = registerRule('@loomcli/core/broken-destination', {
+    explanation: "Core writes the run's output and its failure reports to the host streams run() captured. A stream that fails a write loses whatever followed it, so the run cannot succeed.",
+    headline: 'Broken destination',
+});
+/** A failure class whose exit code is outside 1 through 125. */
+const failureExitCode = registerRule('@loomcli/core/failure-exit-code', {
+    explanation: "A failure's exit code tells the shell how the run ended: 0 means success, and 126 and above belong to the shell and to signals, so a failure exits with a code from 1 through 125. Core never clamps or replaces the code a failure class declares, so a code no failure may exit with is rejected where the class is first constructed.",
+    headline: 'Undeclarable exit code',
+});
+/** A diagnostic rule identity outside the `<package>[/<subpath>...]/<kebab-case-rule>` grammar. */
+const ruleIdentity = registerRule('@loomcli/core/rule-identity', {
+    explanation: "A rule's identity names the package that declares it and the rule inside it, so tooling keys on it and two packages never share one. It is an identity, a package name and any kebab-case subpath segments that name the part of the package that owns the rule, then a kebab-case rule name, joined by /.",
+    headline: 'Invalid rule identity',
+});
+/** A diagnostic rule whose headline or explanation holds no prose. */
+const ruleProse = registerRule('@loomcli/core/rule-prose', {
+    explanation: "A rule's banner prints its headline, and its explanation teaches why the rule exists, so each holds prose.",
+    headline: 'Empty rule text',
+});
+/** A diagnostic rule whose docs value is not a web address. */
+const ruleDocs = registerRule('@loomcli/core/rule-docs', {
+    explanation: "A diagnostic prints a rule's docs as a link the author follows, so it is an absolute http or https URL.",
+    headline: 'Invalid rule docs',
+});
+export { brokenDestination, brokenFailureHook, brokenFailureView, brokenOutputView, brokenTranslator, brokenTranslatorCorrection, failureExitCode, foreignGraph, foreignGraphCorrection, foreignThrow, foreignThrowCorrection, nextMisuse, pluginLoaderFailed, resultContract, ruleDocs, ruleIdentity, ruleProse, runOptions, sourceAnswers, sourceAnswersCorrection, unconstructedFailure, validatorFailed, viewCorrection, viewSelection, viewSelectionCorrection, };

package/dist/sequence.js

@@ -1,4 +1,5 @@
 import { InternalError, routedSubject } from './errors.js';
+import { resultContract } from './rules.js';
 /**
  * A failure the source raised, so the writer tells it apart from the view and write faults its own
  * pieces raise, which the output path has accounted for already.
@@ -44,7 +45,11 @@ function stepsOf(writer) {
         throw new SourceFault(error);
     }
     if (!steps) {
-        throw new SourceFault(new InternalError(`The result of ${routedSubject(writer.path)} is not iterable.`, undefined));
+        throw new SourceFault(new InternalError(resultContract, {
+            cause: undefined,
+            correction: 'Pass out.results() an iterable or an async iterable of rows.',
+            sentence: `The result of ${routedSubject(writer.path)} is not iterable.`,
+        }));
     }
     return steps;
 }

package/dist/sources.d.ts

@@ -0,0 +1,58 @@
+import { LoomError } from './errors.js';
+import type { ExtensionRecords } from './extension.js';
+import type { CommandGraph, OptionNode } from './inspect.js';
+import type { OptionValues } from './options.js';
+import type { BuiltPlugin } from './plugin.js';
+import type { ContextualStyle } from './style.js';
+import type { Host, Out } from './types.js';
+import type { OptionInput } from './validation.js';
+/**
+ * One scope the stage fills: its options in declaration order, and the values argv supplied them.
+ * The stage writes each fill into `values`, so the caller hands it the run's own copy.
+ */
+interface StageScope {
+    global: boolean;
+    inputs: readonly OptionInput[];
+    values: OptionValues;
+}
+/** Everything one input-source stage reads. */
+interface SourceStage {
+    extensions: ExtensionRecords;
+    /** The globals table: the application's global options, then each plugin's in install order. */
+    globals: StageScope;
+    host: Host;
+    /** The graph `inspect()` would return for the run, built on its first read. */
+    inspected: () => CommandGraph;
+    /** The routed Command's own options, or `undefined` while local parsing holds a fault. */
+    locals: StageScope | undefined;
+    /** Offers the resolver's foreign throw to the translators, ahead of the plugin-fault wrap. */
+    offer: (thrown: unknown) => LoomError | undefined;
+    /** The channel a source writes through, whose results call names the source. */
+    out: Out;
+    plugins: readonly BuiltPlugin[];
+    /** The `OptionNode` of one option, read from the graph `inspect()` would return for the run. */
+    request: (input: OptionInput, global: boolean) => OptionNode;
+    signal: AbortSignal;
+    /** The contextual style an action receives, so a source escapes raw data before it warns. */
+    style: ContextualStyle;
+}
+/**
+ * What the stage found beside the values it filled. `labels` names where each filled option's value
+ * came from, by option name, and `rejected` names the variable of each Boolean option whose value
+ * is outside the grammar. Both are internal to core's failure messages. `fault` is a configuration
+ * source's own fault, or the failure its resolver threw, which stops the stage and takes the place
+ * of every validation problem.
+ */
+interface SourceOutcome {
+    fault: LoomError | undefined;
+    labels: ReadonlyMap<string, string>;
+    rejected: ReadonlyMap<string, string>;
+}
+/**
+ * The input-source stage: the environment, then the configuration source, for every option in
+ * scope that argv left unfilled. When no option is left to ask, the source never loads. A source
+ * fault stops the stage and fills nothing more.
+ */
+declare function fillInputs(stage: SourceStage): Promise<SourceOutcome>;
+export type { SourceOutcome, SourceStage, StageScope };
+export { fillInputs };

package/dist/sources.js

@@ -0,0 +1,258 @@
+import { asSentence, foreignFailure, InternalError, LoomError, reasonOf } from './errors.js';
+import { isProseLine } from './facts.js';
+import { isSupplied } from './options.js';
+import { isPlainObject } from './plain.js';
+import { loadDefault, pluginSentence, pluginValues } from './plugin.js';
+import { foreignThrow, foreignThrowCorrection, sourceAnswers, sourceAnswersCorrection, } from './rules.js';
+/** The Boolean grammar a bound variable is read through: the whole value, case-insensitive. */
+const truths = new Map([
+    ['0', false],
+    ['1', true],
+    ['false', false],
+    ['true', true],
+]);
+/**
+ * Reads one option's bound variable. An empty variable is unset and falls through, a string option
+ * receives the raw string, and a Boolean option reads the whole value through the grammar, so the
+ * value states the option's value and not a spelling.
+ */
+function readVariable(input, env) {
+    const variable = input.config.env;
+    const raw = variable !== undefined && Object.hasOwn(env, variable) ? env[variable] : undefined;
+    if (raw === undefined || raw === '') {
+        return undefined;
+    }
+    if (input.config.type === 'string') {
+        return { kind: 'fill', value: raw };
+    }
+    const value = truths.get(raw.toLowerCase());
+    return value === undefined ? { kind: 'rejected' } : { kind: 'fill', value };
+}
+/** Writes one filled value where the option's own shape keeps it, a list as the run's own copy. */
+function fill(values, name, value) {
+    if (typeof value === 'boolean') {
+        values.booleans.set(name, value);
+    }
+    else if (typeof value === 'string') {
+        values.strings.set(name, value);
+    }
+    else {
+        values.lists.set(name, [...value]);
+    }
+}
+/** How a fault names the value an answer owed, by the shape the option takes. */
+const owed = {
+    boolean: 'a Boolean',
+    list: 'an array of strings',
+    string: 'a string',
+};
+function rawKind(input) {
+    if (input.config.type === 'boolean') {
+        return 'boolean';
+    }
+    return input.config.multiple === true ? 'list' : 'string';
+}
+/**
+ * The run's own copy of an answered list, or `undefined` when it is not a list of strings. Every
+ * index is read, so a hole fails the check as any entry that is not a string does.
+ */
+function stringList(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const list = [];
+    // Iteration visits a hole as undefined, where every() skips it.
+    for (const entry of value) {
+        if (typeof entry !== 'string') {
+            return undefined;
+        }
+        list.push(entry);
+    }
+    return list;
+}
+/** One answered value as the raw type its option takes, or `undefined` when it holds another. */
+function rawValue(kind, value) {
+    if (kind === 'list') {
+        return stringList(value);
+    }
+    if (kind === 'boolean') {
+        return typeof value === 'boolean' ? value : undefined;
+    }
+    return typeof value === 'string' ? value : undefined;
+}
+/**
+ * The faults the answers rule names. Reading the answers runs the plugin's own code, such as a
+ * getter, so a throw of any other kind while reading them is the plugin's failure.
+ */
+const ruleFaults = new WeakSet();
+/** A fault the answers rule names, recorded so that reading the answers rethrows it unframed. */
+function ruleFault(message) {
+    const fault = new InternalError(sourceAnswers, {
+        cause: undefined,
+        correction: sourceAnswersCorrection,
+        sentence: message,
+    });
+    ruleFaults.add(fault);
+    return fault;
+}
+/** One answer read under the answers rule: an object that holds a one-line label and a value. */
+function readAnswer(sentence, input, answer) {
+    const shape = isPlainObject(answer) ? answer : undefined;
+    const label = shape?.label;
+    if (!shape || !isProseLine(label)) {
+        throw ruleFault(`${sentence} answered option "${input.name}" with an answer that is not { value, label }.`);
+    }
+    const kind = rawKind(input);
+    const value = rawValue(kind, shape.value);
+    if (value === undefined) {
+        throw ruleFault(`${sentence} answered option "${input.name}" with a value that is not ${owed[kind]}.`);
+    }
+    return { label, value };
+}
+/**
+ * Every answer the resolver returned, read before any is filled, so an answer the rule rejects
+ * leaves every requested option unfilled. A key core did not request is the source's fault.
+ */
+function readAnswers(sentence, answers, requested) {
+    if (!isPlainObject(answers)) {
+        throw ruleFault(`${sentence} returned configuration answers that are not a record.`);
+    }
+    const byName = new Map(requested.map((target) => [target.input.name, target]));
+    return Object.entries(answers).map(([name, answer]) => {
+        const target = byName.get(name);
+        if (!target) {
+            throw ruleFault(`${sentence} answered option "${name}", which core did not request.`);
+        }
+        const { label, value } = readAnswer(sentence, target.input, answer);
+        return { label, target, value };
+    });
+}
+/**
+ * The default export a source loader must resolve to. A loaded module is data core never declared,
+ * so the check is the one runtime fact that decides it: the export is callable.
+ */
+function isResolverExport(value) {
+    return typeof value === 'function';
+}
+/** The fault of a source that threw, while it ran or while core read what it returned. */
+function sourceFailure(sentence, error) {
+    return new InternalError(foreignThrow, {
+        cause: error,
+        correction: foreignThrowCorrection,
+        sentence: `${sentence} failed in its configuration source: ${asSentence(reasonOf(error))}`,
+    });
+}
+/**
+ * Asks the one configuration source about every requested option, and answers with what it said.
+ * Core loads the source here and calls it once, awaiting it; one cancelled during the call awaits
+ * it. The run checks its signal and then reaches the load with no await between, so a run
+ * cancelled before the load starts neither step, and one cancelled during the load calls nothing.
+ * Core builds the context before the call, so a fault of its own is never the plugin's.
+ */
+async function askSource(stage, call) {
+    const { owner, requested } = call;
+    const resolver = await loadDefault(owner.identity, owner.source.load, {
+        guard: isResolverExport,
+        noun: 'source',
+    });
+    if (stage.signal.aborted) {
+        return [];
+    }
+    const sentence = pluginSentence(owner.identity);
+    const context = {
+        graph: stage.inspected(),
+        host: stage.host,
+        options: pluginValues(owner.inputs, stage.globals.values),
+        out: stage.out,
+        requests: requested.map(({ input, scope }) => stage.request(input, scope.global)),
+        style: stage.style,
+    };
+    let answers = undefined;
+    try {
+        answers = await resolver(context);
+    }
+    catch (error) {
+        // The resolver's own failure reports with its class's code, as an action's does.
+        // That covers an InputError, the FatalError out.fatal() throws, and its out.results() fault.
+        // A foreign throw is offered to the translators.
+        // One that no translator answers is the plugin's fault.
+        if (error instanceof LoomError) {
+            throw error;
+        }
+        throw stage.offer(error) ?? sourceFailure(sentence, error);
+    }
+    try {
+        return readAnswers(sentence, answers, requested);
+    }
+    catch (error) {
+        if (error instanceof InternalError && ruleFaults.has(error)) {
+            throw error;
+        }
+        throw sourceFailure(sentence, error);
+    }
+}
+/**
+ * The environment tier: each option in scope that argv left unfilled reads its bound variable. A
+ * filled option is labeled with its variable, and a Boolean one outside the grammar is recorded
+ * as rejected, which fills nothing.
+ */
+function fillFromEnvironment(scopes, env) {
+    const labels = new Map();
+    const rejected = new Map();
+    for (const scope of scopes) {
+        for (const input of scope.inputs) {
+            const reading = isSupplied(scope.values, input.name) ? undefined : readVariable(input, env);
+            const variable = input.config.env ?? '';
+            if (reading?.kind === 'fill') {
+                fill(scope.values, input.name, reading.value);
+                labels.set(input.name, variable);
+            }
+            else if (reading?.kind === 'rejected') {
+                rejected.set(input.name, variable);
+            }
+        }
+    }
+    return { labels, rejected };
+}
+/**
+ * The options the configuration source is asked about: those still unfilled that carry its
+ * binding and hold no environment fault, the globals table first and then the routed Command's own,
+ * each in declaration order.
+ */
+function requestedOf(scopes, excluded, bound) {
+    return scopes.flatMap((scope) => scope.inputs
+        .filter((input) => !isSupplied(scope.values, input.name) &&
+        !excluded.has(input.name) &&
+        Object.hasOwn(bound.extensions.get(input) ?? {}, bound.binding))
+        .map((input) => ({ input, scope })));
+}
+/**
+ * The input-source stage: the environment, then the configuration source, for every option in
+ * scope that argv left unfilled. When no option is left to ask, the source never loads. A source
+ * fault stops the stage and fills nothing more.
+ */
+async function fillInputs(stage) {
+    const scopes = stage.locals ? [stage.globals, stage.locals] : [stage.globals];
+    const { labels, rejected } = fillFromEnvironment(scopes, stage.host.env);
+    const owner = stage.plugins.find((installed) => installed.source !== undefined);
+    const requested = owner
+        ? requestedOf(scopes, rejected, { binding: owner.source.binding, extensions: stage.extensions })
+        : [];
+    if (!owner || requested.length === 0) {
+        return { fault: undefined, labels, rejected };
+    }
+    try {
+        for (const { label, target, value } of await askSource(stage, { owner, requested })) {
+            fill(target.scope.values, target.input.name, value);
+            labels.set(target.input.name, label);
+        }
+        return { fault: undefined, labels, rejected };
+    }
+    catch (error) {
+        // The resolver's own failure keeps its class, and so its code.
+        // Every other fault above is raised as an internal error, and anything else is wrapped the same way.
+        const fault = error instanceof LoomError ? error : foreignFailure(error);
+        return { fault, labels, rejected };
+    }
+}
+export { fillInputs };

package/dist/style-wire.js

@@ -1,5 +1,5 @@
-import { isPlainObject } from './facts.js';
 import { glyphForms } from './glyphs.generated.js';
+import { isPlainObject } from './plain.js';
 import { applyOperations, emptyAttributes } from './style-state.js';
 import { close, colorFallbacks, escape, headerEnd, isColorName, modifiers, open, tokens, } from './style.js';
 function isByte(value) {

package/dist/style.js

@@ -1,4 +1,4 @@
-import { isPlainObject } from './facts.js';
+import { isPlainObject } from './plain.js';
 /** Concrete terminal foregrounds; backgrounds use the same palette indices. */
 const colors = {
     black: 0,

package/dist/theme.d.ts

@@ -1,3 +1,7 @@
 import type { Palette } from './style-state.js';
+/**
+ * One plugin's theme, read as the palette core resolves semantic styles through. Each fault marks
+ * the theme, or the one entry at fault, in `plugin(identity, { theme })`.
+ */
 declare function buildTheme(value: unknown, identity: string): Palette;
 export { buildTheme };