@loomcli/core 0.4.0 → 0.6.0

package/dist/application.js

@@ -1,17 +1,26 @@
 import { runInvocation } from './chain.js';
-import { attachChild, buildGraph, collectInputs, declareAction, declareExtensions, declareArgument, declareOption, declareResult, declareResultViews, freshState, recordGlobalOption, } from './command.js';
-import { DeclarationError, InternalError, reasonOf, toFailure } from './errors.js';
-import { checkDescription, checkNoListingFacts, checkVersion, isPlainObject } from './facts.js';
-import { declareGlobalOption, emptyGlobals } from './globals.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 { DeclarationError, exitCodeOf, InternalError, quoted, reasonOf, toFailure, } from './errors.js';
+import { storeCommandLayers } from './extension.js';
+import { checkDescription, checkNoListingFacts, checkVersion, partFinding, slotSite, } from './facts.js';
+import { declareGlobalOption, emptyGlobals, globalSite, globalTable } from './globals.js';
+import { destinationReport, reportFailure } from './hints.js';
 import { captureHost } from './host.js';
+import { globalOptionAfterCommand } from './input-rules.js';
 import { inspectGraph } from './inspect.js';
 import { coreViews } from './lanes.js';
 import { Output, reportPlainly } from './output.js';
-import { buildPlugins, installPlugins, ownedSignals, pluginSentence } from './plugin.js';
+import { isPlainObject } 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 { captureConfig, checkDeclarations, prepareInputs } from './validation.js';
-import { buildViews, describeFailure, viewIdentities } from './view.js';
+import { readTranslations, translateThrow } from './translators.js';
+import { checkDeclarations, prepareInputs } 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 = [];
 /**
@@ -26,6 +35,16 @@ function silenced(thrown, signal, cancelled) {
  * `undefined` is itself throwable, so the absence is spelled here rather than borrowed from it.
  */
 const noPrimary = Symbol('no primary');
+/**
+ * The write state a run reports by. A destination whose write failure the action let propagate,
+ * and a translator answered, is reported as that translated failure, so its failure is no longer
+ * the destination fault that forces 1.
+ */
+function answeredWrite(writes, answered) {
+    return writes.kind === 'failed' && answered !== undefined && writes.error === answered
+        ? { kind: 'ok' }
+        : writes;
+}
 /**
  * Whether the primary outcome carries one recorded cause already: the value itself, or a failure
  * that wraps it at any depth, which an action that caught a source failure and rethrew its own
@@ -53,10 +72,31 @@ function checkSignal(signal) {
         return undefined;
     }
     if (!(signal instanceof AbortSignal)) {
-        throw new InternalError('run() received a signal that is not an AbortSignal. Supply the signal of an AbortController.', undefined);
+        throw new InternalError(runOptions, {
+            cause: undefined,
+            correction: 'Supply the signal of an AbortController.',
+            sentence: 'run() received a signal that is not an AbortSignal.',
+        });
     }
     return signal;
 }
+/**
+ * Whether a throw in a cancelled run echoes its cancellation, so no translator is offered it. A
+ * value that cannot be read, such as an Error whose `name` getter throws, counts as an echo, so
+ * it keeps its cancellation code and no translator replaces it.
+ */
+function echoesCancellation(thrown, controller) {
+    const { signal } = controller;
+    if (!signal.aborted) {
+        return false;
+    }
+    try {
+        return isCancellationEcho(thrown, signal.reason);
+    }
+    catch {
+        return true;
+    }
+}
 /**
  * The Application holds the unnamed root's declaration state and applies the same transitions a
  * Command does, so each declaration call has one typed implementation and no builder to recover.
@@ -64,31 +104,20 @@ function checkSignal(signal) {
 class ApplicationBuilder {
     #name;
     #root;
-    // The override list the constructor read out of the options slot, unexamined until build.
-    #views;
-    #plugins;
     #globals;
-    // The constructor's raw options argument, kept for the slot's own shape rules.
-    // The options-slot rules answer at the same point every other authoring fault does:
-    // `inspect()` and `run()`.
-    #options;
-    // The facts the constructor read out of that slot, unexamined until build.
-    #declared;
-    constructor(name, root, config) {
-        this.#declared = config.declared;
-        this.#views = config.views;
+    #config;
+    constructor(name, declared) {
         this.#name = name;
-        this.#options = config.options;
-        this.#plugins = config.plugins;
-        this.#globals = config.globals;
-        this.#root = root;
+        this.#config = declared.config;
+        this.#globals = declared.globals;
+        this.#root = declared.root;
     }
     get name() {
         return this.#name;
     }
     argument(name, config) {
         const input = {
-            config: captureConfig(config),
+            config,
             kind: 'argument',
             name,
         };
@@ -96,33 +125,49 @@ class ApplicationBuilder {
     }
     option(name, config) {
         const input = {
-            config: captureConfig(config),
+            config,
             kind: 'option',
             name,
         };
-        return this.derive(declareOption(this.#root, input));
+        return this.derive(declareOption(this.#root, input, this.table()));
     }
     globalOption(name, config) {
+        // The plugins' Commands attach at construction, so only the application's own calls close 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: [] },
+                ],
+                sentence: `The Application declares global option ${quoted(name)} after command() or action().`,
+            });
+        }
         const input = {
-            config: captureConfig(config),
+            config,
             kind: 'option',
             name,
         };
-        return new ApplicationBuilder(this.#name, recordGlobalOption(this.#root, name), {
-            declared: this.#declared,
-            globals: declareGlobalOption(this.#globals, input),
-            options: this.#options,
-            plugins: this.#plugins,
-            views: this.#views,
-        });
+        const descriptors = new Map(this.#root.descriptors);
+        const { input: captured, state: globals } = declareGlobalOption(this.#globals, input, descriptors);
+        const root = { ...this.#root, descriptors };
+        checkDeclaredOptions(root, globalTable(globals.inputs, this.#config.plugins));
+        checkDeclarations([{ input: captured, site: globalSite(captured) }]);
+        return new ApplicationBuilder(this.#name, { config: this.#config, globals, root });
     }
     /** Registering the action closes input authoring; extension configuration remains available. */
     action(handler) {
-        return this.derive(declareAction(this.#root, handler));
+        return this.derive(declareAction(this.#root, handler), { composed: true });
     }
     /** A child arrives in any type state, because its own action is the call that finished it. */
     command(child) {
-        return this.derive(attachChild(this.#root, child));
+        const scope = {
+            descriptors: new Map(this.#root.descriptors),
+            owners: new Map(this.#config.owners),
+            table: this.table(),
+        };
+        const node = childNode(null, child);
+        const root = attachToRoot(this.#root, { node, placement: commandPlacement([], node.name) }, scope);
+        return this.derive(root, { composed: true, owners: scope.owners });
     }
     /**
      * The value the root action produces for its consumer. The type argument is stated by the
@@ -142,50 +187,38 @@ class ApplicationBuilder {
     extend(...values) {
         return this.derive(declareExtensions(this.#root, values));
     }
+    /** The globals table the root's options and every joining subtree meet. */
+    table() {
+        return globalTable(this.#globals.inputs, this.#config.plugins);
+    }
     /**
-     * Root declaration calls preserve the Application configuration. The next state
-     * travels through this call: each method names its transition in its return type, and the
-     * wrapper publishes the same runtime value in exactly that state.
+     * Root declaration calls preserve the Application configuration, with the parts a call changed.
+     * The next state travels through this call: each method names its transition in its return type,
+     * and the wrapper publishes the same runtime value in exactly that state.
      */
-    derive(root) {
-        return new ApplicationBuilder(this.#name, root, {
-            declared: this.#declared,
-            globals: this.#globals,
-            options: this.#options,
-            plugins: this.#plugins,
-            views: this.#views,
-        });
+    derive(root, changed = {}) {
+        return new ApplicationBuilder(this.#name, { config: { ...this.#config, ...changed }, globals: this.#globals, root });
     }
     /**
-     * Every rule that reads the declarations alone, in the order `run()` reads them: the
-     * application's own view overrides, the options slot, the installed list, each plugin's
-     * declarations, then the whole Command graph. The application's overrides are read and published
-     * first, because they need core's identities and nothing else, so every later declaration error
-     * reaches them, while a fault in that list itself reports through core's own text. The merged
-     * registry is published once the whole build has succeeded, so a build-time fault never resolves
-     * through a plugin's overrides, which build has not yet validated.
+     * The graph build, which applies the rules no earlier moment could know: the root's
+     * finished-Command rules and every lifecycle hook's contribution. The application's own overrides
+     * are published first, so a build fault reports through them. The merged registry is published
+     * once the build has succeeded, so a build fault never resolves through a plugin's overrides.
      */
     prepare(stage) {
-        const identities = viewIdentities(coreViews);
-        const application = buildViews({ declares: false, sentence: 'The Application' }, this.#views, identities);
-        stage.views([application]);
-        stage.rendering(renderingPolicy(this.#declared.rendering));
-        const facts = checkOptions(this.#options, this.#declared);
-        const installed = installPlugins(this.#plugins ?? []);
-        const install = { descriptors: new Map(), extensions: new Map() };
-        const plugins = buildPlugins(installed, install);
+        const { contributors, facts, plugins, rendering, views } = this.#config;
+        stage.views([views]);
+        stage.rendering(rendering);
         stage.plugins(plugins);
-        const contributors = plugins.map((entry) => buildViews({ declares: true, sentence: pluginSentence(entry.identity) }, entry.views, identities));
-        const graph = buildGraph(this.#root, this.#globals, { ...install, plugins });
-        checkDeclarations([...graph.globals.inputs, ...collectInputs(graph.root)]);
-        stage.views([application, ...contributors]);
+        const graph = buildGraph(this.#root, this.#globals, plugins);
+        stage.views([views, ...contributors]);
         return { facts, graph, plugins };
     }
     /**
-     * The built graph as plain, frozen data. It applies every rule `run()` applies without a schema,
-     * in the order `run()` applies them, and throws `DeclarationError` when one fails. Validating a
-     * declared default through its schema can be asynchronous, so that one rule stays in `run()`.
-     * Nothing is cached: each call builds the graph anew.
+     * The built graph as plain, frozen data. It builds the graph as `run()` does and throws
+     * `DeclarationError` for the same build faults. Validating a declared default through its schema
+     * can be asynchronous, so that one rule stays in `run()`. Nothing is cached: each call builds the
+     * graph anew.
      */
     inspect() {
         const built = this.prepare({
@@ -193,7 +226,10 @@ class ApplicationBuilder {
             rendering: () => undefined,
             views: () => undefined,
         });
-        return inspectGraph(this.#name, built.graph, built.facts);
+        return inspectGraph(this.#name, built.graph, {
+            ...built.facts,
+            development: this.#config.development,
+        });
     }
     async run(options) {
         let stderr = process.stderr;
@@ -206,6 +242,27 @@ class ApplicationBuilder {
         const faults = [];
         // The failure this run reports as its primary outcome, so nothing reports it a second time.
         let primary = noPrimary;
+        // Each failure a translator answered, keyed to the foreign throw it replaced.
+        const translatedFrom = new Map();
+        // Where a failure happened: the path routing walked, and what the hooks read once the graph built.
+        let walked = Object.freeze([]);
+        let reached = undefined;
+        // The host a failure's report reads, once it is captured; before that, the process's own.
+        let reportHost = undefined;
+        const scene = () => ({
+            application: this.#name,
+            built: reached,
+            host: (reportHost ??= captureHost(undefined, stderr)),
+            path: walked,
+        });
+        // What this run's build decides about its reports, shared by every report the run writes.
+        const build = {
+            development: this.#config.development,
+            generic: false,
+            reported: false,
+        };
+        // What broke the run's reporting: a destination's write error, or a throw while reporting.
+        let reportingCause = undefined;
         // One private controller per run, subscribed to the caller's signal at run entry.
         const controller = new AbortController();
         /**
@@ -220,6 +277,20 @@ class ApplicationBuilder {
             const reason = graphBuilt ? signals?.reason() : undefined;
             return reason ? cancellationCode(reason) : undefined;
         };
+        /**
+         * Offers one throw from the application's work to the translators. A view's failure and a
+         * cancellation echo are never offered, because each already names what it is.
+         */
+        const offer = (thrown) => {
+            if (output?.raisedByView(thrown) === true || echoesCancellation(thrown, controller)) {
+                return undefined;
+            }
+            const failure = translateThrow(this.#config.translators, thrown);
+            if (failure !== undefined) {
+                translatedFrom.set(failure, thrown);
+            }
+            return failure;
+        };
         /**
          * Every exit path of the run leaves through the removal below, the one place it is written,
          * so no listener this run installed outlives it however the run ends.
@@ -229,10 +300,10 @@ class ApplicationBuilder {
                 const overrides = options?.host;
                 stderr = overrides?.stderr ?? stderr;
                 const host = captureHost(overrides, stderr);
+                reportHost = host;
                 const invocationOutput = new Output(host, controller.signal);
                 output = invocationOutput;
-                // The policy is read inside the build, after the application's own overrides are published.
-                // A faulty rendering declaration then reports through the view the application listed.
+                // The constructor validated the declared policy, which the build hands over after the overrides.
                 let policy = {};
                 signals = bracketRun(controller, checkSignal(options?.signal));
                 const built = this.prepare({
@@ -240,7 +311,8 @@ class ApplicationBuilder {
                         invocationOutput.configure(policy, plugins.find((entry) => entry.theme !== undefined)?.theme ?? new Map());
                     },
                     rendering: (declared) => {
-                        policy = { ...declared, ...renderingPolicy(options?.rendering) };
+                        const rendering = options?.rendering;
+                        policy = { ...declared, ...renderingPolicy(rendering, runRendering(rendering)) };
                         invocationOutput.configure(policy, new Map());
                     },
                     views: (value) => {
@@ -249,8 +321,17 @@ class ApplicationBuilder {
                     },
                 });
                 const { graph } = built;
+                // The graph `inspect()` returns, built at most once for the run, whoever reads it first.
+                let inspectedGraph = undefined;
+                const { development } = this.#config;
+                const inspected = () => (inspectedGraph ??= inspectGraph(this.#name, graph, { ...built.facts, development }));
+                reached = { inspected, plugins: built.plugins };
+                if (development) {
+                    // A development build asks every converter at build, so its check runs on every run.
+                    inspected();
+                }
                 const inputs = { globals: graph.globals.inputs, locals: collectInputs(graph.root) };
-                const defaults = await prepareInputs(inputs, host);
+                const defaults = await prepareInputs(inputs, host, inputPlaces(graph));
                 graphBuilt = true;
                 if (!controller.signal.aborted) {
                     /**
@@ -261,17 +342,19 @@ class ApplicationBuilder {
                     await runInvocation({
                         channel: (binding) => invocationOutput.channel(binding),
                         defaults,
-                        facts: built.facts,
                         graph,
                         host,
-                        name: this.#name,
+                        inspected,
+                        offer,
                         out: output.out,
                         plugins: built.plugins,
                         report: (fault) => faults.push(fault),
                         route: (path) => {
+                            walked = path;
                             invocationOutput.useRoute(path);
                         },
                         signal: controller.signal,
+                        sourceOut: output.sourceOut,
                         style: output.style,
                     });
                 }
@@ -281,80 +364,96 @@ class ApplicationBuilder {
                 const fault = output.fault;
                 if (fault) {
                     // The action returned, so the view failure is this invocation's own failure.
-                    throw new InternalError(`Rendering output failed: ${reasonOf(fault.cause)}`, fault.cause);
+                    throw new InternalError(brokenOutputView, {
+                        cause: fault.cause,
+                        correction: viewCorrection,
+                        sentence: `Rendering output failed: ${reasonOf(fault.cause)}`,
+                    });
                 }
             }
             catch (error) {
                 primary = error;
                 try {
                     const failure = toFailure(error);
-                    code = failure.exitCode;
+                    code = exitCodeOf(failure);
                     output ??= new Output(captureHost(undefined, stderr), controller.signal);
-                    const writes = await output.settle();
+                    const writes = answeredWrite(await output.settle(), translatedFrom.get(failure));
                     if (writes.kind === 'ok' && !silenced(error, controller.signal, cancellation())) {
-                        const report = describeFailure(registry ?? noViews, failure, output.context('stderr'));
-                        if (report.kind === 'rendered') {
-                            // The view owns the trailing newline; output resolves its marked text.
-                            await output.report(report.text);
-                        }
-                        else {
+                        // A broken failure view or onFailure hook forces 1 over the failure's own code.
+                        const sink = { build, output, registry: registry ?? noViews, stderr };
+                        if (await reportFailure(sink, failure, scene())) {
                             code = 1;
-                            // `report.text` is core's default text, which already ends in `\n`.
-                            await reportPlainly(stderr, `${report.text}Internal error: Rendering the failure failed: ${report.reason}\n`);
                         }
                     }
                 }
-                catch {
+                catch (reportError) {
                     code = 1;
                     reportingFailed = true;
+                    reportingCause = reportError;
                 }
             }
             /**
              * A sequence that stopped on its own source reports the same way: the call the action never
              * awaited observed nothing, and a failure the action let propagate is the primary outcome
-             * already, so the one it raised is not reported twice.
+             * already, so the one it raised is not reported twice. A throw a translator replaced is
+             * carried by the failure it became, whether or not that failure keeps it as its cause. A
+             * foreign throw that is not carried is a deferred fault, offered to the translators here,
+             * where core would otherwise wrap it as an internal error.
              */
+            // A primary no translator answered replaced nothing, so even a thrown `undefined` is reported.
+            const replaced = translatedFrom.get(primary) ?? noPrimary;
+            const deferred = new Set();
             for (const cause of output?.stopped ?? []) {
-                if (!carried(primary, cause)) {
-                    faults.push(toFailure(cause));
+                if (!carried(primary, cause) && cause !== replaced) {
+                    // A failure is never offered, so only a foreign throw can be translated here.
+                    const translated = offer(cause);
+                    if (translated !== undefined) {
+                        deferred.add(translated);
+                    }
+                    faults.push(translated ?? toFailure(cause));
                 }
             }
             // A plugin's own fault is reported after the primary outcome and turns a would-be 0 into 1.
+            // A deferred fault a translator answered turns it into that failure's own code instead.
             // The primary outcome keeps its code, the way a view failure leaves it alone.
             // It is reported the way the primary failure is, so an override answers its class.
             for (const fault of faults) {
                 if (!silenced(fault, controller.signal, cancellation())) {
-                    code = code === 0 ? 1 : code;
+                    const own = deferred.has(fault) ? exitCodeOf(fault) : 1;
+                    code = code === 0 ? own : code;
                     try {
-                        const report = describeFailure(registry ?? noViews, fault, output?.context('stderr'));
-                        if (report.kind === 'rendered') {
-                            await output?.report(report.text);
-                        }
-                        else {
+                        const sink = output && { build, output, registry: registry ?? noViews, stderr };
+                        if (sink && (await reportFailure(sink, fault, scene()))) {
                             code = 1;
-                            await reportPlainly(stderr, `${report.text}Internal error: Rendering the failure failed: ${report.reason}\n`);
                         }
                     }
-                    catch {
+                    catch (reportError) {
                         reportingFailed = true;
+                        reportingCause ??= reportError;
                     }
                 }
             }
             if (output) {
-                const writes = await output.settle();
+                const writes = answeredWrite(await output.settle(), translatedFrom.get(primary));
                 if (writes.kind === 'failed') {
                     code = 1;
                     reportingFailed = true;
+                    reportingCause ??= writes.error;
                 }
                 output.dispose();
             }
             if (reportingFailed) {
-                await reportPlainly(stderr, 'Internal error: Could not write invocation output.\n');
+                const { application, host } = scene();
+                const text = destinationReport(build, reportingCause, { application, host });
+                if (text !== '') {
+                    await reportPlainly(stderr, text);
+                }
             }
             /**
              * One rule orders every code: a cancelled run resolves its signal's code, and a broken
-             * failure view or destination in that run is reported as text without changing it. The
-             * signal decides the code whatever the action did afterward, so this reading comes last.
+             * failure view, onFailure hook, or destination in that run is reported as text without
+             * changing it. The signal decides the code whatever the action did afterward, so this
+             * reading comes last.
              */
             code = cancellation() ?? code;
             process.exitCode = code;
@@ -365,59 +464,167 @@ class ApplicationBuilder {
         }
     }
 }
+/** The retired Application options, in the order they are rejected, each with its fix. */
+const retired = [
+    ['globals', 'Declare them with globalOption(name, config).'],
+    ['failures', 'Declare view overrides under views with override(key, view).'],
+];
+/** Where one Application option sits, rebuilt as `new Application(name, { key })`. */
+function optionSite(name, key, value) {
+    return slotSite({ call: 'new Application', named: name, subject: 'The Application' }, key, value);
+}
+/** Where `run()`'s own rendering policy sits: the options object of the call on the Application. */
+function runRendering(rendering) {
+    return {
+        at: '0.rendering',
+        declaration: { arguments: [{ rendering }], call: 'run', path: [] },
+        subject: 'The run',
+    };
+}
 /** Reject obsolete wiring before silently losing options that invocations depend on. */
-function checkOptions(options, declared) {
-    if (options !== undefined) {
-        if (!isPlainObject(options)) {
-            throw new DeclarationError('The Application options must be an object. Supply an Application options object.');
-        }
-        if ('globals' in options) {
-            throw new DeclarationError('The Application options contain globals. Declare them with globalOption(name, config).');
-        }
-        if ('failures' in options) {
-            throw new DeclarationError('The Application options contain failures. Declare view overrides under views with override(key, view).');
+function checkOptions(name, options) {
+    const site = {
+        at: '1',
+        declaration: { arguments: callArguments(name, options), call: 'new Application' },
+        subject: 'The Application',
+    };
+    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));
+            throw new DeclarationError(retiredApplicationOption, {
+                correction,
+                findings: [partFinding(retiredSite, [])],
+                sentence: `The Application options contain ${key}.`,
+            });
         }
-        // The root is every page's entry point, so it carries neither listing fact.
-        // A key that may not be there is a fault of the slot, so it answers with the slot's shape.
-        checkNoListingFacts('The Application', options);
+    }
+    // The root is every page's entry point, so it carries neither listing fact.
+    // A key that may not be there is a fault of the slot, so it answers with the slot's shape.
+    checkNoListingFacts(site, options);
+    return {
+        description: checkDescription(site, options.description),
+        version: checkVersion(site, options.version),
+    };
+}
+/**
+ * Whether the packet an Application received reads `development`. No packet is distributed, so an
+ * application that never opted in cannot show an operator the author's detail. The build is read
+ * once, here, so a later change to the imported object changes no run.
+ */
+function readPacket(name, packet) {
+    if (packet === undefined) {
+        return false;
+    }
+    const site = optionSite(name, 'packet', packet);
+    if (!isPlainObject(packet)) {
+        throw new DeclarationError(invalidPacket, {
+            correction: 'Import loom.packet.json and pass it as packet.',
+            findings: [partFinding(site, [])],
+            sentence: 'The Application packet must be an object.',
+        });
+    }
+    const { build } = packet;
+    if (build === 'development' || build === 'distributed') {
+        return build === 'development';
+    }
+    const found = build === undefined
+        ? 'The packet has no build.'
+        : `The packet's build is ${typeof build === 'string' ? `"${escapeControlCharacters(build)}"` : 'not a string'}.`;
+    throw new DeclarationError(invalidPacket, {
+        correction: 'Set build to "development" or "distributed".',
+        findings: [partFinding(site, 'build' in packet ? ['build'] : [])],
+        sentence: found,
+    });
+}
+/**
+ * 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.
+ */
+function declareApplication(name, options) {
+    const slot = isPlainObject(options) ? options : undefined;
+    const identities = viewIdentities(coreViews);
+    const views = buildViews({
+        declares: false,
+        owner: { call: 'new Application', named: name },
+        sentence: 'The Application',
+    }, 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 development = readPacket(name, slot?.packet);
+    const installed = installPlugins(name, slot?.plugins ?? []);
+    const { plugins } = installed;
+    const contributors = plugins.map((entry) => buildViews(pluginViews(entry.identity), entry.views, identities));
+    const table = globalTable([], plugins);
+    const descriptors = installed.descriptors;
+    const extensions = storeCommandLayers({
+        descriptors,
+        layers: [slot?.extensions],
+        site: optionSite(name, 'extensions', slot?.extensions),
+        subject: layerOf(null),
+    });
+    // The Application checks its own facts, so the root carries none.
+    // Its diagnostics name the Application rather than the root Command.
+    let root = freshState({
+        descriptors,
+        extensions,
+        facts: { deprecated: undefined, description: undefined, hidden: false },
+        name: null,
+    });
+    const owners = new Map();
+    for (const command of plugins.flatMap((entry) => entry.commands)) {
+        root = attachToRoot(root, command, {
+            descriptors: new Map(root.descriptors),
+            owners,
+            table,
+        });
     }
     return {
-        description: checkDescription('The Application', declared.description),
-        version: checkVersion(declared.version),
+        config: {
+            composed: false,
+            contributors,
+            development,
+            facts,
+            owners,
+            plugins,
+            rendering,
+            translators: [translations, ...plugins.map((entry) => entry.translators)],
+            views,
+        },
+        globals: emptyGlobals(),
+        root,
     };
 }
+/** The application name is typed as a command at the prompt, so it answers to the portable rule. */
+function checkApplicationName(name) {
+    if (!isPortableName(name)) {
+        throw new DeclarationError(portableName, {
+            correction: portableNameCorrection,
+            findings: [{ arguments: [name], call: 'new Application', mark: '0' }],
+            sentence: `Application name ${quoted(name)} is invalid.`,
+        });
+    }
+    return name;
+}
 /** Constructor inference preserves the installed plugin tuple; globals start empty. */
 class ApplicationDeclaration extends ApplicationBuilder {
     constructor(name, options) {
-        // The options slot is read defensively, never inspected.
-        // An invalid value still yields `views` and the facts of some kind.
-        // `checkOptions` reports such a value at build.
-        // The root's own slot and core facts stay empty, because the Application checks its own slot.
-        // Its diagnostics name the Application rather than the root Command.
-        super(name, freshState({
-            deprecated: undefined,
-            description: undefined,
-            extensions: options?.extensions,
-            hidden: undefined,
-            name: null,
-            options: undefined,
-        }), {
-            declared: {
-                description: options?.description,
-                rendering: isPlainObject(options?.rendering)
-                    ? { ...options.rendering }
-                    : options?.rendering,
-                version: options?.version,
-            },
-            globals: emptyGlobals(),
-            options,
-            plugins: options?.plugins,
-            // The read is loose because the slot is reachable from JavaScript with any value at all.
-            // An Application value passed here answers `views` with its own authoring method.
-            // The public `ApplicationOptions.views` stays exactly `readonly ViewOverride[]`.
-            // An options slot that is no plain object carries no override list, and its own rule reports it.
-            views: isPlainObject(options) ? options.views : undefined,
-        });
+        // The arguments evaluate in order, so the name is checked before any option is read.
+        const checked = checkApplicationName(name);
+        super(checked, declareApplication(checked, options));
     }
 }
 export const Application = ApplicationDeclaration;