@loomcli/core 0.3.0 → 0.5.0

package/dist/errors.d.ts

@@ -111,8 +111,8 @@ export declare class InternalError extends LoomError {
     readonly cause: unknown;
     constructor(message: string, cause: unknown);
 }
-/** The four ways the results lane is broken, each named where core meets it. */
-export type ResultFault = 'missing' | 'repeated' | 'undeclared' | 'middleware';
+/** The five ways the results lane is broken, each named where core meets it. */
+export type ResultFault = 'missing' | 'repeated' | 'undeclared' | 'middleware' | 'source';
 /**
  * Exit 1: the promise a declared result makes was not kept. It wraps no thrown value, so its
  * `cause` is `undefined`, and it extends `InternalError`, so an override of that class brands it
@@ -125,6 +125,11 @@ export declare class ResultError extends InternalError {
     readonly cause: undefined;
     constructor(kind: ResultFault, path: readonly string[]);
 }
+/**
+ * One message someone else wrote, as a sentence of its own. A schema or a plugin writes its message
+ * with or without a full stop, so a diagnostic supplies one only where the message carries none.
+ */
+export declare function asSentence(text: string): string;
 /** What a diagnostic says about an unexpected value, whether or not it was an Error. */
 export declare function reasonOf(thrown: unknown): string;
 /**

package/dist/errors.js

@@ -14,7 +14,8 @@ function resultMessage(kind, command) {
     if (kind === 'undeclared') {
         return `${routedSentence(command)} declares no result. Declare one with result() or rows() before action().`;
     }
-    return `A middleware called out.results() on ${routedSubject(command)}. Only the action emits a result.`;
+    const caller = kind === 'source' ? 'A configuration source' : 'A middleware';
+    return `${caller} called out.results() on ${routedSubject(command)}. Only the action emits a result.`;
 }
 /**
  * The clause that offers the candidates, which is absent when there are none: every child of the
@@ -210,6 +211,13 @@ export class ResultError extends InternalError {
         this.path = path;
     }
 }
+/**
+ * One message someone else wrote, as a sentence of its own. A schema or a plugin writes its message
+ * with or without a full stop, so a diagnostic supplies one only where the message carries none.
+ */
+export function asSentence(text) {
+    return text.endsWith('.') ? text : `${text}.`;
+}
 /** What a diagnostic says about an unexpected value, whether or not it was an Error. */
 export function reasonOf(thrown) {
     return thrown instanceof Error ? thrown.message : 'An unknown error occurred.';

package/dist/extension.d.ts

@@ -1,17 +1,22 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { ArgumentNode, CommandNode, OptionNode } from './inspect.js';
+import type { AttachedCommand } from './types.js';
 /** The three declaration kinds an extension can name, each with its own node in the graph. */
 type ExtensionTarget = 'argument' | 'command' | 'option';
 /**
- * The descriptor supertype a plugin's `extensions` list uses. It publishes the identity and the
- * target and erases both the schema and the factory call signature, because a schema-typed call
- * signature relates only by schema identity and a list cannot name one schema per element. A
- * descriptor is assignable to it; an extension value, which publishes its brand alone, is not.
+ * The descriptor supertype a plugin's `extensions` list uses. It publishes the identity, the
+ * target, and whether the extension collects, and erases both the schema and the factory call
+ * signature, because a schema-typed call signature relates only by schema identity and a list
+ * cannot name one schema per element. A descriptor is assignable to it; an extension value, which
+ * publishes its brand alone, is not.
  */
 interface AnyExtension {
     readonly identity: string;
     readonly target: ExtensionTarget;
+    readonly collect: boolean;
 }
+/** What a value must show to be taken for a descriptor before its `collect` flag is checked. */
+type DescriptorShape = Pick<AnyExtension, 'identity' | 'target'>;
 /** One carried value: the input its author supplied and the descriptor that produced it. */
 interface CarriedValue {
     descriptor: AnyExtension;
@@ -32,33 +37,54 @@ declare class ExtensionCarrier<Target extends ExtensionTarget> {
 type ExtensionValue<Target extends ExtensionTarget> = Pick<ExtensionCarrier<Target>, typeof extensionTarget>;
 /**
  * A descriptor that is also a factory: calling it with the schema's input returns the branded value
- * a declaration carries. The schema is public so a typed read recovers the output type.
+ * a declaration carries. The schema is public so a typed read recovers the output type, and
+ * `collect` says whether the values a declaration carries accumulate or replace each other.
  */
-interface Extension<Target extends ExtensionTarget = ExtensionTarget, Schema extends StandardSchemaV1 = StandardSchemaV1> extends AnyExtension {
+interface Extension<Target extends ExtensionTarget = ExtensionTarget, Schema extends StandardSchemaV1 = StandardSchemaV1, Collect extends boolean = false> extends AnyExtension {
     (input: StandardSchemaV1.InferInput<Schema>): ExtensionValue<Target>;
     readonly schema: Schema;
     readonly target: Target;
+    readonly collect: Collect;
 }
 /**
  * One typed fact a plugin defines for one target. The descriptor is compared by reference wherever
- * it appears, so one identity means one descriptor and a duplicated package copy is visible.
+ * it appears, so one identity means one descriptor and a duplicated package copy is visible. With
+ * `collect: true` it is a collecting extension, whose values accumulate on a declaration in order.
  */
 declare function extension<Target extends ExtensionTarget, Schema extends StandardSchemaV1>(identity: string, config: {
     schema: Schema;
     target: Target;
+    collect?: false | undefined;
 }): Extension<Target, Schema>;
-/** The node kind one descriptor's target names, so a read against another kind cannot compile. */
-type NodeFor<Target extends ExtensionTarget> = Target extends 'command' ? CommandNode : Target extends 'option' ? OptionNode : ArgumentNode;
+declare function extension<Target extends ExtensionTarget, Schema extends StandardSchemaV1>(identity: string, config: {
+    schema: Schema;
+    target: Target;
+    collect: true;
+}): Extension<Target, Schema, true>;
+/**
+ * The node kind one descriptor's target names, so a read against another kind cannot compile. A
+ * Command-target read also takes the value a lifecycle hook receives, which publishes the record
+ * as it stands at that hook.
+ */
+type NodeFor<Target extends ExtensionTarget> = Target extends 'command' ? CommandNode | AttachedCommand : Target extends 'option' ? OptionNode : ArgumentNode;
 /** Stored output is plain data the graph froze, so every read of it is read-only to any depth. */
 type DeepReadonly<Value> = Value extends readonly (infer Item)[] ? readonly DeepReadonly<Item>[] : Value extends object ? {
     readonly [Key in keyof Value]: DeepReadonly<Value[Key]>;
 } : Value;
+/**
+ * What one read answers, decided by the descriptor's own `collect` type: a collecting extension's
+ * outputs as a read-only list, or an ordinary extension's output or nothing.
+ */
+type ExtensionRead<Schema extends StandardSchemaV1, Collect extends boolean> = Collect extends true ? readonly DeepReadonly<StandardSchemaV1.InferOutput<Schema>>[] : DeepReadonly<StandardSchemaV1.InferOutput<Schema>> | undefined;
 /**
  * The typed read of one extension value. It takes the node kind the descriptor targets, returns the
  * stored output or `undefined`, compares the descriptor by reference with the one that produced the
- * value, and runs no schema.
+ * value, and runs no schema. Through a collecting descriptor it returns every collected output in
+ * collection order, and an empty list where the node carries none.
  */
-declare function readExtension<Target extends ExtensionTarget, Schema extends StandardSchemaV1>(node: NodeFor<Target>, descriptor: Extension<Target, Schema>): DeepReadonly<StandardSchemaV1.InferOutput<Schema>> | undefined;
+declare function readExtension<Target extends ExtensionTarget, Schema extends StandardSchemaV1, Collect extends boolean = false>(node: NodeFor<Target>, descriptor: Extension<Target, Schema, Collect>): ExtensionRead<Schema, Collect>;
+/** How a diagnostic names the declarations one target covers, such as "Commands". */
+declare function appliesTo(target: ExtensionTarget): string;
 /** The declaration one `extensions` slot belongs to, as its own diagnostics name it. */
 interface ExtensionSubject {
     /** The subject after a preposition, such as `on Command "get"`. */
@@ -74,10 +100,13 @@ type DescriptorRegistry = Map<string, AnyExtension>;
  * build alone and inspection reads them back with the nodes it renders.
  */
 type ExtensionRecords = Map<object, Readonly<Record<string, unknown>>>;
-/** Whether a value is a descriptor: a callable object carrying an identity and a declared target. */
-declare function isDescriptor(value: unknown): value is AnyExtension;
-/** One identity means one descriptor, wherever on the graph that descriptor appears. */
-declare function registerDescriptor(descriptors: DescriptorRegistry, descriptor: AnyExtension): void;
+/**
+ * Whether a value has a descriptor's shape: a callable object carrying an identity and a declared
+ * target. Its `collect` flag is checked where a build registers it.
+ */
+declare function isDescriptor(value: unknown): value is DescriptorShape;
+/** Admits one descriptor and records it, so a later descriptor of its identity is compared to it. */
+declare function registerDescriptor(descriptors: DescriptorRegistry, descriptor: DescriptorShape): void;
 /** Everything one `extensions` slot needs to answer: whose it is, and what it may carry. */
 interface ExtensionSlot {
     declared: unknown;
@@ -85,15 +114,44 @@ interface ExtensionSlot {
     subject: ExtensionSubject;
     target: ExtensionTarget;
 }
+/** One carried value, validated against its descriptor's schema and ready to store. */
+interface ValidatedValue {
+    descriptor: AnyExtension;
+    output: unknown;
+}
+/**
+ * One layer's values, each validated once, synchronously, in authoring order. A layer holds at
+ * most one value of an extension, collecting or not, so a second one is a declaration fault.
+ */
+declare function validateLayer(slot: ExtensionSlot): readonly ValidatedValue[];
+/**
+ * The values one declaration has validated so far, by identity in the order each first appeared:
+ * an ordinary extension's latest output alone, and a collecting extension's every output in
+ * collection order. A store is never changed; adding a layer answers a new one.
+ */
+interface ExtensionStore {
+    readonly entries: ReadonlyMap<string, {
+        readonly descriptor: AnyExtension;
+        readonly outputs: readonly unknown[];
+    }>;
+}
+/**
+ * The store with one more validated layer. An ordinary value replaces the earlier one in place, so
+ * a key keeps its first position, and a collecting value joins the values before it.
+ */
+declare function extendStore(store: ExtensionStore, layer: readonly ValidatedValue[]): ExtensionStore;
 /**
- * The frozen record one declaration publishes: each carried value validated once, synchronously,
- * and stored under its extension's identity. The descriptors that produced them are recorded beside
- * the record, so a typed read compares by reference without the graph carrying a reference.
+ * The frozen record a store publishes: each ordinary extension's output, and each collecting
+ * extension's frozen list of outputs, under its identity. The descriptors that produced them are
+ * recorded beside the record, so a typed read compares by reference without the graph carrying a
+ * reference.
  */
+declare function publishStore(store: ExtensionStore): Readonly<Record<string, unknown>>;
+/** The frozen record of one `extensions` slot, which is one layer. */
 declare function buildExtensions(slot: ExtensionSlot): Readonly<Record<string, unknown>>;
-/** Layers validate in authoring order; replacement updates existing keys without reinsertion. */
-declare function buildCommandExtensions(slot: Omit<ExtensionSlot, 'declared' | 'target'> & {
+/** A Command's author layers, validated in authoring order into the store its hooks extend. */
+declare function storeCommandLayers(slot: Omit<ExtensionSlot, 'declared' | 'target'> & {
     layers: readonly unknown[];
-}): Readonly<Record<string, unknown>>;
-export type { AnyExtension, DeepReadonly, DescriptorRegistry, Extension, ExtensionRecords, ExtensionSubject, ExtensionTarget, ExtensionValue, };
-export { buildCommandExtensions, buildExtensions, extension, isDescriptor, readExtension, registerDescriptor, };
+}): ExtensionStore;
+export type { AnyExtension, DeepReadonly, DescriptorRegistry, Extension, ExtensionRecords, ExtensionStore, ExtensionSubject, ExtensionTarget, ExtensionValue, };
+export { appliesTo, buildExtensions, extendStore, extension, isDescriptor, publishStore, readExtension, registerDescriptor, storeCommandLayers, validateLayer, };

package/dist/extension.js

@@ -1,4 +1,4 @@
-import { DeclarationError, reasonOf } from './errors.js';
+import { asSentence, DeclarationError, reasonOf } from './errors.js';
 import { isPlainObject } from './facts.js';
 /** Authored values register here, so the public brand publishes no state to reach or replace. */
 const values = new WeakMap();
@@ -19,16 +19,15 @@ class ExtensionCarrier {
         Object.freeze(this);
     }
 }
-/**
- * One typed fact a plugin defines for one target. The descriptor is compared by reference wherever
- * it appears, so one identity means one descriptor and a duplicated package copy is visible.
- */
 function extension(identity, config) {
     // `Object.assign` returns the same function object, so the value carries the descriptor itself.
     function create(input) {
         return new ExtensionCarrier({ descriptor, input });
     }
+    // An omitted or undefined `collect` publishes as false, and any other value as given.
+    // Build then rejects a JavaScript author's value that is neither Boolean.
     const descriptor = Object.assign(create, {
+        collect: config.collect === undefined ? false : config.collect,
         identity,
         schema: config.schema,
         target: config.target,
@@ -36,26 +35,31 @@ function extension(identity, config) {
     Object.freeze(descriptor);
     return descriptor;
 }
+/** The read of a collecting extension a declaration carries no value of, shared and frozen. */
+const noValues = Object.freeze([]);
 /**
  * The typed read of one extension value. It takes the node kind the descriptor targets, returns the
  * stored output or `undefined`, compares the descriptor by reference with the one that produced the
- * value, and runs no schema.
+ * value, and runs no schema. Through a collecting descriptor it returns every collected output in
+ * collection order, and an empty list where the node carries none.
  */
 function readExtension(node, descriptor) {
     const record = node.extensions;
     const owner = owners.get(record)?.get(descriptor.identity);
-    if (owner === undefined) {
-        return undefined;
-    }
-    if (owner !== descriptor) {
+    if (owner !== undefined && owner !== descriptor) {
         throw new DeclarationError(`Extension "${descriptor.identity}" was read through a descriptor that did not define the stored value. Install one copy of the package that defines it.`);
     }
-    // Last resort: no typed path exists. The graph stores every output under a string identity, so
-    // The record reads back as `unknown` and no key relates one entry to a descriptor's schema.
-    // It holds because the reference test above proves this descriptor produced this output, and
-    // Build stored exactly what that descriptor's own schema returned.
+    // A collecting extension a declaration carries no value of reads as an empty list.
+    const absent = descriptor.collect ? noValues : undefined;
+    const stored = owner === undefined ? absent : record[descriptor.identity];
+    // Last resort: no typed path exists.
+    // The graph stores every output under a string identity, so the record reads back as `unknown`.
+    // No key relates one entry to a descriptor's schema or to its runtime `collect` flag.
+    // It holds because the reference test above proves this descriptor produced this entry.
+    // Build stored exactly what its schema returned, a list when the descriptor collects.
+    // `Collect` is the literal `extension()` published as `collect`, which registration enforces.
     // oxlint-disable-next-line typescript/no-unsafe-type-assertion
-    return record[descriptor.identity];
+    return stored;
 }
 /** How a diagnostic names the declarations one target covers. */
 const applies = {
@@ -63,6 +67,10 @@ const applies = {
     command: 'Commands',
     option: 'options',
 };
+/** How a diagnostic names the declarations one target covers, such as "Commands". */
+function appliesTo(target) {
+    return applies[target];
+}
 /**
  * The children one container contributes, or nothing when its own shape is not plain data. An
  * accessor, a symbol key, and a non-enumerable own property are not plain data, and an `undefined`
@@ -172,7 +180,10 @@ function plainData(value) {
         }
     }
 }
-/** Whether a value is a descriptor: a callable object carrying an identity and a declared target. */
+/**
+ * Whether a value has a descriptor's shape: a callable object carrying an identity and a declared
+ * target. Its `collect` flag is checked where a build registers it.
+ */
 function isDescriptor(value) {
     return (value !== null &&
         (typeof value === 'object' || typeof value === 'function') &&
@@ -181,16 +192,37 @@ function isDescriptor(value) {
         'target' in value &&
         (value.target === 'argument' || value.target === 'command' || value.target === 'option'));
 }
-/** One identity means one descriptor, wherever on the graph that descriptor appears. */
-function registerDescriptor(descriptors, descriptor) {
+/** Whether a descriptor carries the `collect` flag every descriptor publishes, as a Boolean. */
+function hasCollectFlag(descriptor) {
+    return 'collect' in descriptor && typeof descriptor.collect === 'boolean';
+}
+/** Whether one registered descriptor collects, so its values accumulate instead of replacing. */
+function collects(descriptor) {
+    return descriptor.collect;
+}
+/**
+ * The descriptor a registry holds for one identity once this one is admitted. One identity means
+ * one descriptor, wherever on the graph that descriptor appears, and a descriptor is checked when
+ * a build first meets it: its `collect` flag is `true` or `false`, which the factory always
+ * publishes and a hand-built descriptor may not. It reads the registry and changes nothing.
+ */
+function admitDescriptor(descriptors, descriptor) {
     const known = descriptors.get(descriptor.identity);
     if (known === undefined) {
-        descriptors.set(descriptor.identity, descriptor);
-        return;
+        if (!hasCollectFlag(descriptor)) {
+            throw new DeclarationError(`Extension "${descriptor.identity}" declares collect that is not a Boolean. Supply true or false, or build the descriptor with extension(identity, config).`);
+        }
+        return descriptor;
     }
     if (known !== descriptor) {
         throw new DeclarationError(`Extension "${descriptor.identity}" is defined twice. Install one copy of the package that defines it.`);
     }
+    return known;
+}
+/** Admits one descriptor and records it, so a later descriptor of its identity is compared to it. */
+function registerDescriptor(descriptors, descriptor) {
+    const admitted = admitDescriptor(descriptors, descriptor);
+    descriptors.set(admitted.identity, admitted);
 }
 /** Whether a value answers the Standard Schema v1 contract this build calls synchronously. */
 function isSchema(value) {
@@ -203,13 +235,6 @@ function isSchema(value) {
         'validate' in standard &&
         typeof standard.validate === 'function');
 }
-/**
- * One schema message as a sentence of its own. A schema author writes the message with or without a
- * full stop, so the diagnostic supplies one only where the message carries none.
- */
-function sentence(text) {
-    return text.endsWith('.') ? text : `${text}.`;
-}
 /** The message one rejected value reports, with the placeholder a silent schema earns. */
 function issueText(issues) {
     const first = Array.isArray(issues) ? issues[0] : undefined;
@@ -244,7 +269,7 @@ function validated(subject, carried, schema) {
     }
     catch (error) {
         // A schema that throws rejected the value the only way it could, so it reads as a rejection.
-        throw new DeclarationError(`${subject.sentence} holds an invalid "${carried.descriptor.identity}" value: ${sentence(reasonOf(error))} Correct the value.`);
+        throw new DeclarationError(`${subject.sentence} holds an invalid "${carried.descriptor.identity}" value: ${asSentence(reasonOf(error))} Correct the value.`);
     }
 }
 /** Validates one carried value and answers the plain-data output the node stores under it. */
@@ -256,7 +281,7 @@ function validateValue(subject, carried) {
     }
     const issues = 'issues' in result ? result.issues : undefined;
     if (issues !== undefined) {
-        throw new DeclarationError(`${subject.sentence} holds an invalid "${identity}" value: ${sentence(issueText(issues))} Correct the value.`);
+        throw new DeclarationError(`${subject.sentence} holds an invalid "${identity}" value: ${asSentence(issueText(issues))} Correct the value.`);
     }
     const output = plainData('value' in result ? result.value : undefined);
     if (!output) {
@@ -286,45 +311,85 @@ function carriedValue(subject, target, entry) {
     return carried;
 }
 /**
- * The frozen record one declaration publishes: each carried value validated once, synchronously,
- * and stored under its extension's identity. The descriptors that produced them are recorded beside
- * the record, so a typed read compares by reference without the graph carrying a reference.
+ * One layer's values, each validated once, synchronously, in authoring order. A layer holds at
+ * most one value of an extension, collecting or not, so a second one is a declaration fault.
  */
-function buildExtensions(slot) {
+function validateLayer(slot) {
     const { subject } = slot;
-    const stored = [];
-    const defined = new Map();
+    const layer = [];
+    const seen = new Set();
+    // The layer's descriptors register together once every value is valid.
+    // A rejected layer, such as a hook's `extend()` call the hook catches, leaves the registry as it was.
+    const staged = new Map(slot.descriptors);
     for (const entry of readList(subject, slot.declared)) {
         const carried = carriedValue(subject, slot.target, entry);
         const { descriptor } = carried;
-        registerDescriptor(slot.descriptors, descriptor);
-        if (defined.has(descriptor.identity)) {
+        registerDescriptor(staged, descriptor);
+        if (seen.has(descriptor.identity)) {
             throw new DeclarationError(`${subject.sentence} holds extension "${descriptor.identity}" twice. Supply one value.`);
         }
-        defined.set(descriptor.identity, descriptor);
-        stored.push([descriptor.identity, validateValue(subject, carried)]);
+        seen.add(descriptor.identity);
+        layer.push({ descriptor, output: validateValue(subject, carried) });
+    }
+    for (const [identity, descriptor] of staged) {
+        slot.descriptors.set(identity, descriptor);
+    }
+    return layer;
+}
+/**
+ * The record each store published, so a store a hook left unchanged publishes the same record on
+ * every read and build does no second walk of it.
+ */
+const published = new WeakMap();
+/** The store of a declaration that carries no value yet. */
+const emptyStore = { entries: new Map() };
+/**
+ * The store with one more validated layer. An ordinary value replaces the earlier one in place, so
+ * a key keeps its first position, and a collecting value joins the values before it.
+ */
+function extendStore(store, layer) {
+    const entries = new Map(store.entries);
+    for (const { descriptor, output } of layer) {
+        const earlier = entries.get(descriptor.identity)?.outputs ?? [];
+        const outputs = collects(descriptor) ? [...earlier, output] : [output];
+        entries.set(descriptor.identity, { descriptor, outputs });
+    }
+    return { entries };
+}
+/**
+ * The frozen record a store publishes: each ordinary extension's output, and each collecting
+ * extension's frozen list of outputs, under its identity. The descriptors that produced them are
+ * recorded beside the record, so a typed read compares by reference without the graph carrying a
+ * reference.
+ */
+function publishStore(store) {
+    const cached = published.get(store);
+    if (cached) {
+        return cached;
+    }
+    const stored = [];
+    const defined = new Map();
+    for (const [identity, { descriptor, outputs }] of store.entries) {
+        stored.push([identity, collects(descriptor) ? Object.freeze([...outputs]) : outputs[0]]);
+        defined.set(identity, descriptor);
     }
     // `Object.fromEntries` defines each identity as an own data property, so an identity of
     // `__proto__` is a key of the record and the record keeps `Object.prototype`.
     const frozen = Object.freeze(Object.fromEntries(stored));
     owners.set(frozen, defined);
+    published.set(store, frozen);
     return frozen;
 }
-/** Layers validate in authoring order; replacement updates existing keys without reinsertion. */
-function buildCommandExtensions(slot) {
-    const stored = new Map();
-    const defined = new Map();
+/** The frozen record of one `extensions` slot, which is one layer. */
+function buildExtensions(slot) {
+    return publishStore(extendStore(emptyStore, validateLayer(slot)));
+}
+/** A Command's author layers, validated in authoring order into the store its hooks extend. */
+function storeCommandLayers(slot) {
+    let store = emptyStore;
     for (const declared of slot.layers) {
-        const layer = buildExtensions({ ...slot, declared, target: 'command' });
-        for (const [identity, value] of Object.entries(layer)) {
-            stored.set(identity, value);
-        }
-        for (const [identity, descriptor] of owners.get(layer) ?? []) {
-            defined.set(identity, descriptor);
-        }
+        store = extendStore(store, validateLayer({ ...slot, declared, target: 'command' }));
     }
-    const frozen = Object.freeze(Object.fromEntries(stored));
-    owners.set(frozen, defined);
-    return frozen;
+    return store;
 }
-export { buildCommandExtensions, buildExtensions, extension, isDescriptor, readExtension, registerDescriptor, };
+export { appliesTo, buildExtensions, extendStore, extension, isDescriptor, publishStore, readExtension, registerDescriptor, storeCommandLayers, validateLayer, };

package/dist/facts.d.ts

@@ -1,3 +1,8 @@
+/**
+ * One line of prose: a string that holds a character other than whitespace and no line terminator.
+ * Every one-line fact reads this rule, and so does the label a configuration source answers with.
+ */
+export declare function isProseLine(value: unknown): value is string;
 /**
  * The `description` core fact: one line of prose every projection reads. A value that is not a
  * string fails the same way a blank one does, because the author reads one rule for one fact.

package/dist/facts.js

@@ -10,6 +10,13 @@ const prose = /\P{White_Space}/u;
  * The seven are LF, VT, FF, CR, NEL, LS, and PS, each of them `White_Space` too.
  */
 const lineTerminator = /[\n\v\f\r\u0085\u2028\u2029]/u;
+/**
+ * One line of prose: a string that holds a character other than whitespace and no line terminator.
+ * Every one-line fact reads this rule, and so does the label a configuration source answers with.
+ */
+export function isProseLine(value) {
+    return typeof value === 'string' && prose.test(value) && !lineTerminator.test(value);
+}
 /**
  * The `description` core fact: one line of prose every projection reads. A value that is not a
  * string fails the same way a blank one does, because the author reads one rule for one fact.
@@ -19,7 +26,7 @@ export function checkDescription(subject, value) {
     if (value === undefined) {
         return undefined;
     }
-    if (typeof value !== 'string' || !prose.test(value) || lineTerminator.test(value)) {
+    if (!isProseLine(value)) {
         throw new DeclarationError(`${subject} description must hold a character other than whitespace and no line terminator. Supply a one-line summary.`);
     }
     return value;
@@ -48,7 +55,7 @@ export function checkDeprecated(subject, value) {
     if (value === undefined) {
         return undefined;
     }
-    if (typeof value !== 'string' || !prose.test(value) || lineTerminator.test(value)) {
+    if (!isProseLine(value)) {
         throw new DeclarationError(`${subject} deprecated message must hold a character other than whitespace and no line terminator. Supply a one-line migration path, such as "Use get instead.".`);
     }
     return value;
@@ -76,7 +83,7 @@ export function checkVersion(value) {
     if (value === undefined) {
         return '0.0.0';
     }
-    if (typeof value !== 'string' || !prose.test(value) || lineTerminator.test(value)) {
+    if (!isProseLine(value)) {
         throw new DeclarationError('The Application version must be a string that holds a character other than whitespace and no line terminator. Supply a string such as "1.2.0".');
     }
     return value;

package/dist/globals.d.ts

@@ -1,6 +1,8 @@
+import type { BoundOption } from './bindings.js';
 import { DeclarationError } from './errors.js';
+import type { DescriptorRegistry } from './extension.js';
 import { compileOptions } from './options.js';
-import type { BuiltPlugin, PluginBuild } from './plugin.js';
+import type { BuiltPlugin } from './plugin.js';
 import type { OptionConfig, OptionValue } from './types.js';
 import type { InputDeclaration, OptionInput, ValidatedInputs } from './validation.js';
 /**
@@ -28,30 +30,61 @@ declare function keyCollision(name: string, first: OptionOwner, second: OptionOw
 /** One spelling claimed twice, whichever two scopes claimed it. */
 declare function spellingCollision(spelling: string, first: OptionSite, second: OptionSite): DeclarationError;
 /**
- * The compiled global table: one spelling map shared by every Command in the graph. It holds the
+ * The globals table the pre-scan reads, with every rule that pairs two of its options settled: one
+ * spelling map, the scope that owns each key, and the variable each option binds. It holds the
  * application's global options and every installed plugin's options, because the pre-scan reads one
- * table. `inputs` holds the application's declarations alone, because a plugin option is never
- * validated and never reaches an action.
+ * table.
  */
-interface BuiltGlobals {
-    bind: (values: ValidatedInputs) => unknown;
-    inputs: readonly InputDeclaration[];
+interface GlobalTable {
     names: ReadonlyMap<string, OptionOwner>;
     options: ReturnType<typeof compileOptions>;
+    /** The variable each option in the table binds, under the phrase a duplicate names it by. */
+    variables: ReadonlyMap<string, string>;
+}
+/**
+ * The compiled table one graph build shares. `inputs` holds the application's declarations alone,
+ * because a plugin option is never validated and never reaches an action.
+ */
+interface BuiltGlobals extends GlobalTable {
+    bind: (values: ValidatedInputs) => unknown;
+    inputs: readonly OptionInput[];
     plugins: readonly BuiltPlugin[];
 }
-/** The Application's private global declarations and their schema-derived value binder. */
+/** The validated extension record of each declaration, keyed by the declaration itself. */
+type InputRecords = ReadonlyMap<InputDeclaration, Readonly<Record<string, unknown>>>;
+/**
+ * The Application's private global declarations, their schema-derived value binder, and the
+ * extension record each declaration's own call validated.
+ */
 interface GlobalsState<Globals = unknown> {
     bind: (values: ValidatedInputs) => Globals;
     inputs: readonly OptionInput[];
+    records: InputRecords;
 }
 declare function emptyGlobals(): GlobalsState<{}>;
-declare function declareGlobalOption<Globals, Name extends string, Config extends OptionConfig>(state: GlobalsState<Globals>, input: OptionInput<Name, Config>): GlobalsState<Globals & Record<Name, OptionValue<Config>>>;
+/**
+ * One global option's own facts, binding, and extension values, checked at its `globalOption()`
+ * call against the Application's descriptors. The rules that pair it with another option belong to
+ * the table, which the caller rebuilds with it.
+ */
+declare function declareGlobalOption<Globals, Name extends string, Config extends OptionConfig>(state: GlobalsState<Globals>, input: OptionInput<Name, Config>, descriptors: DescriptorRegistry): GlobalsState<Globals & Record<Name, OptionValue<Config>>>;
 /**
  * The one table the pre-scan reads: the application's global options in authoring order, then each
  * installed plugin's options in installation order. Every collision between the two scopes, by key
  * or by spelling, is reported here, so the pre-scan meets a table with one owner per name.
  */
-declare function buildGlobals(node: GlobalsState, plugins: readonly BuiltPlugin[], build: PluginBuild): BuiltGlobals;
-export type { BuiltGlobals, GlobalsState, OptionOwner, OptionSite };
-export { buildGlobals, declareGlobalOption, emptyGlobals, keyCollision, spellingCollision };
+declare function globalTable(inputs: readonly OptionInput[], plugins: readonly BuiltPlugin[]): GlobalTable;
+/** The table one graph build shares, which every earlier call already proved free of collisions. */
+declare function buildGlobals(node: GlobalsState, plugins: readonly BuiltPlugin[]): BuiltGlobals;
+/**
+ * One Command's own options against the globals table, compiled for dispatch. The table holds the
+ * application's globals and every plugin option, so a local collision reads the same sentence
+ * whichever scope on the other side claimed the name, the spelling, or the variable. One
+ * invocation's scope is this Command's own options and the table, so a variable binds one option
+ * there, while a sibling Command may bind it again.
+ */
+declare function checkLocalOptions(declarations: readonly OptionInput[], table: GlobalTable, subject: string): ReturnType<typeof compileOptions>;
+/** The options in one list that bind a variable, each named by the phrase its scope gives it. */
+declare function boundOptions(inputs: readonly OptionInput[], site: (name: string) => string): BoundOption[];
+export type { BuiltGlobals, GlobalsState, GlobalTable, InputRecords, OptionOwner, OptionSite };
+export { boundOptions, buildGlobals, checkLocalOptions, declareGlobalOption, emptyGlobals, globalTable, keyCollision, spellingCollision, };