@loomcli/core 0.3.0 → 0.4.0

package/dist/command.js

@@ -1,6 +1,6 @@
 var _a;
 import { commandSentence, commandSubject, DeclarationError, NonCallableCommandError, ResultError, UnexpectedArgumentError, UnknownCommandError, } from './errors.js';
-import { buildCommandExtensions, buildExtensions } from './extension.js';
+import { buildExtensions, extendStore, publishStore, storeCommandLayers, validateLayer, } from './extension.js';
 import { checkDeprecated, checkDescription, checkHidden, checkNoListingFacts, isPlainObject, } from './facts.js';
 import { buildGlobals, keyCollision, spellingCollision } from './globals.js';
 import { resultNode, snapshot } from './inspect.js';
@@ -476,6 +476,10 @@ class AttachedCommandValue {
     get result() {
         return this.#result;
     }
+    /** Published on first read and shared by every value whose store is unchanged. */
+    get extensions() {
+        return publishStore(this.#state.extensions);
+    }
     argument(name, config) {
         return this.#declare({ config: captureConfig(config), kind: 'argument', name });
     }
@@ -491,8 +495,24 @@ class AttachedCommandValue {
         const { declared } = this.#state;
         return this.#derive({ call, kind: 'views' }, { ...declared, results: [...declared.results, call] });
     }
+    /**
+     * The values are validated here, at the call, so the next read of `extensions` holds them and
+     * build never validates them again. A rejected value throws from the call and adds nothing.
+     */
     extend(...values) {
-        return this.#derive({ kind: 'extend', values }, this.#state.declared);
+        const state = this.#state;
+        const registry = new Map(state.registry);
+        const layer = validateLayer({
+            declared: values,
+            descriptors: registry,
+            subject: state.subject,
+            target: 'command',
+        });
+        return new _a({
+            ...state,
+            extensions: extendStore(state.extensions, layer),
+            registry,
+        });
     }
     /** One input the running hook declared, which the Command's own names now hold. */
     #declare(input) {
@@ -538,20 +558,26 @@ function attachOnce(value, hook, named) {
  * Every installed plugin's hook over one Command, in installation order, each receiving what the
  * previous returned. The calls they made travel back to the declaration the remaining rules read.
  */
-function runAttachHooks(declared, facts, plugins) {
+function runAttachHooks(start, facts, plugins) {
+    const { declared, extensions, layer, registry } = start;
     const subject = commandSubject(declared.name);
     const { lineage } = facts;
-    let progress = { calls: [], declared };
+    let progress = { calls: [], declared, extensions, registry };
     for (const installed of plugins) {
         const hook = installed.onCommandAttach;
         if (hook) {
             const identity = installed.identity;
-            const value = new AttachedCommandValue({ ...progress, ...facts, identity });
+            const value = new AttachedCommandValue({ ...progress, ...facts, identity, subject: layer });
             const state = attachOnce(value, hook, { identity, lineage, subject });
-            progress = { calls: state.calls, declared: state.declared };
+            progress = {
+                calls: state.calls,
+                declared: state.declared,
+                extensions: state.extensions,
+                registry: state.registry,
+            };
         }
     }
-    return progress.calls;
+    return progress;
 }
 /**
  * One input a hook declared. It joins the values an action reads at run time and the declaration's
@@ -575,15 +601,10 @@ function declareHookInput(state, input) {
 function applyAttachCalls(state, calls) {
     let next = state;
     for (const call of calls) {
-        if (call.kind === 'input') {
-            next = declareHookInput(next, call.input);
-        }
-        else if (call.kind === 'views') {
-            next = { ...next, results: [...next.results, call.call] };
-        }
-        else {
-            next = declareExtensions(next, call.values);
-        }
+        next =
+            call.kind === 'input'
+                ? declareHookInput(next, call.input)
+                : { ...next, results: [...next.results, call.call] };
     }
     return next;
 }
@@ -763,7 +784,8 @@ export function buildCommand(state, context) {
     const description = checkDescription(commandSentence(name), state.description);
     const hidden = checkHidden(commandSentence(name), state.hidden);
     const deprecated = checkDeprecated(commandSentence(name), state.deprecated);
-    const declaredExtensions = buildCommandExtensions({
+    // The author's layers validate before any hook runs on this Command, so a hook reads them.
+    const declaredExtensions = storeCommandLayers({
         descriptors: context.descriptors,
         layers: state.extensions,
         subject: layer,
@@ -787,20 +809,20 @@ export function buildCommand(state, context) {
      */
     // One token per Command per build, which binds a hook's return to the value it received.
     const lineage = {};
-    const calls = runAttachHooks(state, { hasAction, lineage, path: context.path }, context.plugins);
+    const progress = runAttachHooks({ declared: state, extensions: declaredExtensions, layer, registry: context.descriptors }, { hasAction, lineage, path: context.path }, context.plugins);
+    const { calls } = progress;
+    // The descriptors the returned value's extensions registered join the build's registry.
+    for (const [identity, descriptor] of progress.registry) {
+        context.descriptors.set(identity, descriptor);
+    }
     const hooked = applyAttachCalls(state, calls);
     const hookInputs = calls.filter((call) => call.kind === 'input');
     checkInputFacts(hookInputs.map((call) => call.input), { name, subject }, context);
     // The hook-declared names are checked first, so a collision reports in the plugin's voice.
     // A rule the author's own declaration voices never speaks for a name a hook declared.
     checkAttachedInputs(hooked, hookInputs, globals);
-    const extensions = calls.some((call) => call.kind === 'extend')
-        ? buildCommandExtensions({
-            descriptors: context.descriptors,
-            layers: hooked.extensions,
-            subject: layer,
-        })
-        : declaredExtensions;
+    // Every value was validated once, the author's above and each hook's at its `extend()` call.
+    const extensions = publishStore(progress.extensions);
     const slots = hookInputs.length > 0 ? collectArguments(hooked, subject) : declaredSlots;
     checkArgumentPlacement(name, slots[0], attached[0]);
     const result = calls.length > 0 ? buildResult(hooked, hasAction) : declaredResult;

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,52 @@ 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>;
 /** 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 +98,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 +112,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 { buildExtensions, extendStore, extension, isDescriptor, publishStore, readExtension, registerDescriptor, storeCommandLayers, validateLayer, };

package/dist/extension.js

@@ -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 = {
@@ -172,7 +176,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 +188,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) {
@@ -286,45 +314,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 { buildExtensions, extendStore, extension, isDescriptor, publishStore, readExtension, registerDescriptor, storeCommandLayers, validateLayer, };

package/dist/index.d.ts

@@ -11,7 +11,7 @@ export type { RenderingPolicy } from './rendering.js';
 export type { ViewContext } from './types.js';
 export { pad, style } from './style.js';
 export { issuePath } from './validation.js';
-export type { StandardSchemaV1 } from '@standard-schema/spec';
+export type { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec';
 export type { ApplicationMethod, ApplicationOptions } from './application.js';
 export type { ChainOutcome, MiddlewareContext } from './chain.js';
 export type { InputProblem, ResultFault } from './errors.js';

package/dist/inspect.d.ts

@@ -1,6 +1,11 @@
 import type { BuiltGraph } from './command.js';
 import type { DeclaredResult } from './types.js';
-/** One declared argument. `default` wraps the declared value, so an explicit `undefined` shows. */
+/** The plain JSON Schema a validated input publishes, or `null` where the graph holds no shape. */
+type InputSchema = Readonly<Record<string, unknown>> | null;
+/**
+ * One declared argument. `default` wraps the declared value, so an explicit `undefined` shows, and
+ * `schema` is the input schema its validator publishes through the Standard JSON Schema converter.
+ */
 interface ArgumentNode {
     readonly name: string;
     readonly description: string | undefined;
@@ -8,6 +13,7 @@ interface ArgumentNode {
     readonly variadic: boolean;
     readonly validated: boolean;
     readonly validateOmitted: boolean;
+    readonly schema: InputSchema;
     readonly default: {
         readonly value: unknown;
     } | undefined;
@@ -21,6 +27,9 @@ interface ArgumentNode {
  * `hidden` is `false` unless the declaration says `true`, and `deprecated` is the declared
  * migration message or `undefined`. A listing projection omits a hidden node and marks a
  * deprecated one; parsing binds without reading either.
+ * `schema` is the input schema the validator publishes. A Boolean option validates nothing, so its
+ * variant carries the field at `null`, and every projection built on the node holds if a later
+ * contract lets it validate.
  */
 type OptionNode = {
     readonly type: 'string';
@@ -35,6 +44,7 @@ type OptionNode = {
     readonly multiple: boolean;
     readonly validated: boolean;
     readonly validateOmitted: boolean;
+    readonly schema: InputSchema;
     readonly default: {
         readonly value: unknown;
     } | undefined;
@@ -50,6 +60,7 @@ type OptionNode = {
     readonly short: string | null;
     readonly negative: string | null;
     readonly polarity: 'positive' | 'negative' | 'both';
+    readonly schema: InputSchema;
     readonly extensions: Readonly<Record<string, unknown>>;
 };
 /**

package/dist/inspect.js

@@ -28,14 +28,60 @@ export function snapshot(value) {
         return Object.freeze(value.map((entry) => snapshot(entry)));
     }
     if (isPlainObject(value)) {
-        return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, snapshot(entry)])));
+        return snapshotRecord(value);
     }
     return value;
 }
+/** The snapshot of one plain object, under the record type the caller already established. */
+function snapshotRecord(value) {
+    return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, snapshot(entry)])));
+}
 /** A declared default is wrapped, so `default: undefined` reads apart from no default at all. */
 function declaredDefault(config) {
     return 'default' in config ? Object.freeze({ value: snapshot(config.default) }) : undefined;
 }
+/**
+ * The JSON Schema draft build asks every converter for, with no library options. Every converter
+ * receives this one object, so it is frozen against a library that writes to its argument.
+ */
+const schemaTarget = Object.freeze({ target: 'draft-2020-12' });
+/** Whether a validator declares the Standard JSON Schema converter, both sides, beside `validate`. */
+function publishesSchema(schema) {
+    const props = schema['~standard'];
+    return ('jsonSchema' in props &&
+        typeof props.jsonSchema === 'object' &&
+        props.jsonSchema !== null &&
+        'input' in props.jsonSchema &&
+        typeof props.jsonSchema.input === 'function' &&
+        'output' in props.jsonSchema &&
+        typeof props.jsonSchema.output === 'function');
+}
+/**
+ * The input-side schema a declaration's validator publishes, snapshotted the way a declared
+ * default is, or `null` where the graph holds no published shape: no validator, a validator with
+ * no converter, or a converter that throws or returns anything but a plain object. The contract of
+ * 2026-09-19 made that last case a declaration error `inspect()` alone reports; that diagnostic is
+ * held while the question of how a run tells development from a distributed application is
+ * decided, so it reads `null` on both paths.
+ */
+function inputSchema(config) {
+    const schema = 'validate' in config ? config.validate : undefined;
+    if (schema === undefined) {
+        return null;
+    }
+    // The converter is the library's code from the first property read.
+    // A throw on reaching it and a throw on calling it are one failure.
+    try {
+        if (!publishesSchema(schema)) {
+            return null;
+        }
+        const published = schema['~standard'].jsonSchema.input(schemaTarget);
+        return isPlainObject(published) ? snapshotRecord(published) : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** One declaration's extension record, which is the shared empty one when it carries no value. */
 function extensionsOf(records, declaration) {
     return records.get(declaration) ?? noExtensions;
@@ -54,6 +100,7 @@ function optionNode(input, { records, scope, table }) {
             name,
             negative,
             polarity: config.polarity ?? 'positive',
+            schema: null,
             scope,
             short,
             type: 'boolean',
@@ -69,6 +116,7 @@ function optionNode(input, { records, scope, table }) {
             multiple: config.multiple === true,
             name,
             required: config.required === true,
+            schema: inputSchema(config),
             scope,
             short,
             type: 'string',
@@ -86,6 +134,7 @@ function argumentNode(slot, records) {
         extensions: extensionsOf(records, slot.input),
         name,
         required: slot.required,
+        schema: inputSchema(config),
         validateOmitted: validatesOmission(slot.input),
         validated: config.validate !== undefined,
         variadic: slot.variadic,

package/dist/types.d.ts

@@ -211,6 +211,11 @@ export interface AttachedCommand {
     /** The declared local option names, in declaration order. */
     readonly options: readonly string[];
     readonly result: ResultNode | null;
+    /**
+     * The extension record `inspect()` would publish for this Command at this hook: the author's
+     * layers, then every value an earlier hook or this hook's earlier `extend()` calls added.
+     */
+    readonly extensions: Readonly<Record<string, unknown>>;
     argument(name: string, config: ArgumentConfig): AttachedCommand;
     option(name: string, config: OptionConfig): AttachedCommand;
     views(replacements: Readonly<Record<string, ResultView>>, options?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loomcli/core",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "The Loom CLI core package. Provides the scaffolding for creating new Loom CLI applications.",
   "license": "MIT",
   "repository": {