@crustjs/core 0.3.1 → 0.3.3

package/dist/context-Cud9frNp.d.ts

@@ -0,0 +1,2059 @@
+import { BaseValueType } from "@crustjs/utils/primitive";
+import { InferOutput, StandardSchema } from "@crustjs/utils/schema";
+import { JsonCompatible, JsonValue } from "@crustjs/utils/json";
+//#region src/identity.d.ts
+declare const brand: unique symbol;
+/** Stable identity shared by Extensions and documentation section renderers. */
+type ExtensionId = string & {
+  readonly [brand]: true;
+};
+/** Mint an Extension identity from any non-blank, trimmed string. */
+declare function defineExtensionId(id: string): ExtensionId;
+//#endregion
+//#region src/validation/shared.d.ts
+type Awaitable<T> = T | Promise<T>;
+type Simplify<T> = { [K in keyof T]: T[K]; };
+type MergeContext<A, B> = A & B;
+/** Provider replacement is last-write-wins; an open name may leave any earlier value in place. */
+type MergeProviders<A, B> = keyof A extends never ? B : keyof B extends never ? A : string extends keyof B ? Record<string, A[keyof A] | B[string]> : [keyof A & keyof B] extends [never] ? A & B : Omit<A, keyof B> & B;
+/**
+ * Extract the narrowed canonical `name` literal from a definition.
+ * Open name domains carry no spelling proof; attachment must retain
+ * their uncertainty rather than treating this absence as an empty namespace.
+ */
+type DefName<T> = T extends {
+  name: infer N extends string;
+} ? IsClosedName<N> extends true ? N : never : never;
+/**
+ * Statically known `name` members of a definition (or definition union), for spelling grammar.
+ * Filtered per variant: combining names first would let an open variant's `string` absorb
+ * a literal sibling before {@link ClosedMembers} can see it.
+ */
+type DefNameMembers<T> = T extends {
+  name: infer N extends string;
+} ? ClosedMembers<N> : never;
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
+type IsUnion<T> = [T] extends [UnionToIntersection<T>] ? false : true;
+/**
+ * `true` only for a single statically known fixed-length tuple whose members
+ * are not unions. A conditionally assembled collection (`cond ? [a] : [b]` or
+ * `[cond ? a : b]`) infers as a union at the tuple or member level, and a
+ * variable-length array (`const xs: (typeof a)[]`) may be empty or partially
+ * populated at runtime; such contributions must stay runtime-only.
+ */
+type IsStaticTuple<Cs extends readonly unknown[]> = number extends Cs["length"] ? false : IsUnion<Cs> extends true ? false : true extends { [I in keyof Cs]: IsUnion<Cs[I]>; }[number] ? false : true;
+/** Whether a fixed tuple has one closed canonical name per slot. */
+type HasClosedNames<Ds extends readonly unknown[]> = number extends Ds["length"] ? false : IsUnion<Ds> extends true ? false : false extends { [I in keyof Ds]: Ds[I] extends {
+  name: infer N extends string;
+} ? IsUnion<N> extends true ? false : IsClosedName<N> : false; }[number] ? false : true;
+/** Brand statically known spelling collisions while allowing open names. */
+type CollisionBrand<S extends string, Existing extends string, Key extends string, Before extends string, After extends string> = string extends S | Existing ? {} : [S & Existing] extends [never] ? {} : { readonly [K in Key]: `${Before}"${S & Existing}"${After}`; };
+/**
+ * The statically known members of a name union; open members stay runtime-owned.
+ * Only for local spelling grammar: a literal beside an open template is still
+ * independently invalid, but must never become key or collision evidence.
+ */
+type ClosedMembers<N extends string> = N extends unknown ? IsClosedName<N> extends true ? N : never : never;
+/** Brand a statically known empty literal member while allowing widened and generic names. */
+type EmptyLiteralNameBrand<Name extends string, Err> = "" extends ClosedMembers<Name> ? Err : {};
+/**
+ * Brand a definition whose custom parser can return a Promise — parse results
+ * are consumed synchronously during argv parsing. `Extract` keeps the check
+ * union-aware (a sometimes-async `cond ? Promise.resolve(x) : x` parser is
+ * caught) while `any`-returning parsers stay unbranded.
+ */
+type AsyncParseBrand<T> = T extends {
+  parse?: (...args: never[]) => infer R;
+} ? Extract<R, Promise<unknown>> extends never ? {} : {
+  readonly FIX_ASYNC_PARSE: "parse must be synchronous; do async work in run()";
+} : {};
+/** Brand literal defaults that fall outside a literal `choices` tuple. */
+type DefaultWithinChoicesBrand<T> = T extends {
+  choices: readonly (infer Choice extends string)[];
+  default: infer Default;
+} ? string extends Choice ? {} : Default extends readonly string[] ? string extends Default[number] ? {} : Exclude<Default[number], Choice> extends never ? {} : {
+  readonly FIX_DEFAULT_CHOICE: "default must be one of choices";
+} : Default extends string ? string extends Default ? {} : Exclude<Default, Choice> extends never ? {} : {
+  readonly FIX_DEFAULT_CHOICE: "default must be one of choices";
+} : {} : {};
+/** Finite literal domains have required record keys; infinite templates and branded strings do not.
+ * Distribute first so a finite union member cannot hide an open member's index signature.
+ */
+type IsClosedName<N extends string> = false extends (N extends unknown ? ({} extends Record<N, true> ? false : true) : never) ? false : true;
+/** Reject independently provable invalid local values, including members of uncertain definitions. */
+type LocalValueBrand<T> = UnionToIntersection<T extends unknown ? AsyncParseBrand<T> & DefaultWithinChoicesBrand<T> : never>;
+//#endregion
+//#region src/validation/args.brands.d.ts
+type ArgNames<A extends readonly object[]> = DefName<A[number]>;
+type DuplicateArgBrand<A, Existing extends string> = CollisionBrand<DefName<A>, Existing, "FIX_DUPLICATE_ARG", "Argument name ", " is already defined">;
+type EmptyArgNameError = {
+  readonly FIX_EMPTY_NAME: "Argument names must be non-empty";
+};
+/** Reject empty argument names, including empty members of a name union. */
+type EmptyArgNameBrand<Name extends string> = EmptyLiteralNameBrand<Name, EmptyArgNameError>;
+type EmptyArgDefinitionNameBrand<A> = EmptyArgNameBrand<DefNameMembers<A>>;
+type ArgChecks<A, Existing extends string> = A & DuplicateArgBrand<A, Existing> & LocalValueBrand<A> & EmptyArgDefinitionNameBrand<A>;
+/**
+ * Per-arg validation tuple type. Resolves to `A` when the constraints are
+ * satisfied: only the last arg is variadic, names are unique, and custom
+ * parsers are synchronous. Invalid definitions receive a branded property.
+ *
+ * Generalized to work with any ordered tuple of object-typed definitions.
+ * Uses `readonly object[]` to avoid TypeScript's weak type detection
+ * (all-optional constraint rejection).
+ *
+ * ```
+ * Property 'FIX_VARIADIC_POSITION' is missing in type '{ name: "files"; ... variadic: true }'
+ *   but required in type
+ *     '{ readonly FIX_VARIADIC_POSITION: "Only the last positional argument can be variadic" }'.
+ * ```
+ */
+type ValidateVariadicArgs<A extends readonly object[], Existing extends string = never> = A extends readonly [infer Head, ...infer Tail extends readonly object[]] ? Tail extends readonly [unknown, ...unknown[]] ? Head extends {
+  variadic: true;
+} ? readonly [ArgChecks<Head, Existing> & {
+  readonly FIX_VARIADIC_POSITION: "Only the last positional argument can be variadic";
+}, ...ValidateVariadicArgs<Tail, Existing | DefName<Head>>] : readonly [ArgChecks<Head, Existing>, ...ValidateVariadicArgs<Tail, Existing | DefName<Head>>] : readonly [ArgChecks<Head, Existing>] : { [I in keyof A]: ArgChecks<A[I], Existing>; };
+type BrandVariadicPosition<A extends readonly object[]> = { [I in keyof A]: A[I] & {
+  readonly FIX_VARIADIC_POSITION: "Only the last positional argument can be variadic";
+}; };
+type AppendArgsChecks<A extends ArgsDef, NewA extends ArgsDef> = A extends readonly [...unknown[], infer Last] ? Last extends {
+  variadic: true;
+} ? BrandVariadicPosition<ValidateVariadicArgs<NewA, ArgNames<A>>> : ValidateVariadicArgs<NewA, ArgNames<A>> : ValidateVariadicArgs<NewA>;
+/** Conditional collections and uncertain canonical identities cannot promise every alternative output key. */
+type AttachedArgs<A extends ArgsDef> = HasClosedNames<A> extends true ? A : ArgsDef;
+//#endregion
+//#region src/validation/commands.brands.d.ts
+/** Preserve configured aliases; only a genuinely absent field proves an empty set. */
+type AliasesOf<C> = C extends {
+  readonly aliases: infer A extends readonly string[];
+} ? A : "aliases" extends keyof C ? readonly string[] : readonly [];
+type NarrowAliases<A extends readonly string[]> = IsClosedName<A[number]> extends true ? A[number] : never;
+type AliasMembers<A extends readonly string[]> = ClosedMembers<A[number]>;
+type AliasShapeError<Name extends string, Alias extends string> = Alias extends "" ? `Subcommand "${Name}" has an invalid alias: must be a non-empty string` : Alias extends `${string} ${string}` | `${string}\t${string}` | `${string}\n${string}` | `${string}\r${string}` | `${string}\v${string}` | `${string}\f${string}` ? `Subcommand "${Name}" alias "${Alias}" must not contain whitespace` : Alias extends `-${string}` ? `Subcommand "${Name}" alias "${Alias}" must not start with "-" (reserved for flags)` : string extends Name ? never : Alias extends Name ? `Subcommand "${Name}" alias "${Alias}" must not equal its own canonical name` : never;
+type AliasShapeErrors<Name extends string, C> = AliasMembers<AliasesOf<C>> extends (infer Alias) ? Alias extends string ? AliasShapeError<Name, Alias> : never : never;
+type AliasShapeBrand<Name extends string, C> = [AliasShapeErrors<Name, C>] extends [never] ? {} : {
+  readonly FIX_ALIAS_SHAPE: AliasShapeErrors<Name, C>;
+};
+type RootVersionBrand<C> = "version" extends keyof C ? {
+  readonly FIX_ROOT_VERSION: "Command config \"version\" belongs on the root Crust constructor";
+} : {};
+/** Brand command config containing statically known invalid metadata. */
+type ValidateCommandConfig<Name extends string, C> = AliasShapeBrand<Name, C> & RootVersionBrand<C>;
+type EmptyNameError = {
+  readonly FIX_EMPTY_NAME: "Command name must be a non-empty string";
+};
+type TrimWhitespace = " " | "\t" | "\n" | "\r" | "\v" | "\f" | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | " " | "
" | "
" | " " | " " | "　" | "";
+type BlankName<Name extends string> = Name extends `${TrimWhitespace}${infer Tail}` ? BlankName<Tail> : Name extends "" ? true : false;
+/** Runtime checks own open members; every statically known member is validated, even beside an open one. */
+type CommandNameBrand<Name extends string> = true extends BlankName<ClosedMembers<Name>> ? EmptyNameError : "__proto__" extends ClosedMembers<Name> ? {
+  readonly FIX_RESERVED_NAME: "Command name \"__proto__\" is reserved";
+} : {};
+type DefinitionAliases<D> = CommandDefinitionData<D> extends {
+  readonly _aliases?: infer A extends readonly string[];
+} ? A : readonly string[];
+/** All statically known canonical and alias spellings carried by a command definition. */
+type CommandDefinitionSpellings<D> = D extends unknown ? D extends {
+  name: infer N extends string;
+} ? IsUnion<N> extends true ? never : DefName<D> extends (infer Name extends string) ? [Name] extends [never] ? never : Name | NarrowAliases<DefinitionAliases<D>> : never : never : never;
+type SelfAliasBrand<D> = UnionToIntersection<D extends unknown ? DefNameMembers<D> & AliasMembers<DefinitionAliases<D>> extends (infer Dup extends string) ? [Dup] extends [never] ? {} : {
+  readonly FIX_ALIAS_SHAPE: `Command "${Dup}" must not list its own canonical name as an alias`;
+} : never : never>;
+type CommandCollisionBrand<Spellings extends string, Existing extends string> = CollisionBrand<Spellings, Existing, "FIX_COMMAND_COLLISION", "Command name or alias ", " collides with a sibling command">;
+/**
+ * Validate definitions against existing siblings and definitions earlier in
+ * the same `.add()` call. Widened names opt out because their spellings are
+ * not statically knowable; their literal aliases opt out with them
+ * (see {@link CommandDefinitionSpellings}).
+ */
+type ValidateCommandDefinitions<Ds extends readonly unknown[], Existing extends string = never> = Ds extends readonly [infer Head, ...infer Tail] ? CommandDefinitionSpellings<Head> extends (infer Spellings extends string) ? readonly [Head & CommandCollisionBrand<Spellings, Existing> & CommandNameBrand<DefNameMembers<Head>> & SelfAliasBrand<Head>, ...ValidateCommandDefinitions<Tail, Existing | Spellings>] : never : Ds;
+type ExtensionCommandDefs<E> = [E] extends [never] ? readonly [] : DefiningOf<E> extends {
+  readonly commands?: infer Cs extends readonly unknown[];
+} ? Cs : readonly [];
+/** An uncertain command collection opens only the child namespace. */
+type ExtensionCommandSpellings<E> = AttachedCommandSpellings<ExtensionCommandDefs<E>>;
+type ExtensionsCommandSpellings<Es extends readonly unknown[]> = IsStaticTuple<Es> extends true ? { [I in keyof Es]: ExtensionCommandSpellings<Es[I]>; }[number] : ExtensionCommandDefs<Es[number]>[number] extends never ? never : string;
+type ExtensionCommandCollisionBrand<E, Existing extends string> = CollisionBrand<ExtensionCommandSpellings<E>, Existing, "FIX_COMMAND_COLLISION", "Extension command ", " collides with an existing command">;
+/**
+ * Validate each Extension's contributed command spellings against existing
+ * root commands and against Extensions earlier in the same `.extend()` call.
+ * Runtime preparation resolves collisions last-write-wins, so a statically
+ * known collision would silently retype `run()` against a command that
+ * dispatch replaces.
+ */
+type ValidateExtensionCommands<Es extends readonly unknown[], Existing extends string> = Es extends readonly [infer H, ...infer T extends readonly unknown[]] ? readonly [H & ExtensionCommandCollisionBrand<H, Existing>, ...ValidateExtensionCommands<T, Existing | ExtensionCommandSpellings<H>>] : Es;
+/** Local metadata checks; unrelated description/version/usage text has no grammar. */
+type SectionTextBrand<S> = S extends {
+  title: infer T extends string;
+  body: infer B extends string;
+} ? true extends BlankName<T> | BlankName<B> ? {
+  readonly FIX_SECTION_TEXT: "Section title/body must be nonblank";
+} : Extract<T, `${string}\r${string}` | `${string}\n${string}`> extends never ? {} : {
+  readonly FIX_SECTION_TEXT: "Section title must be a single line";
+} : {};
+type SectionAudienceBrand<S> = S extends {
+  only: readonly [];
+} | {
+  except: readonly [];
+} ? {
+  readonly FIX_SECTION_AUDIENCE: "Section audience must be nonempty";
+} : {};
+type LocalSectionsBrand<C> = "sections" extends keyof C ? C extends {
+  sections: infer S extends readonly unknown[];
+} ? {
+  readonly sections: { [I in keyof S]: S[I] & UnionToIntersection<SectionTextBrand<S[I]>> & UnionToIntersection<SectionAudienceBrand<S[I]>>; };
+} : {} : {};
+type LocalCommandConfigBrand<N extends string, C> = ValidateCommandConfig<N, C> & LocalSectionsBrand<C>;
+type AttachedCommandSpellings<Ds extends readonly unknown[]> = [Ds] extends [readonly []] ? never : IsStaticTuple<Ds> extends true ? HasClosedNames<Ds> extends true ? false extends { [I in keyof Ds]: IsClosedName<DefinitionAliases<Ds[I]>[number]>; }[number] ? string : CommandDefinitionSpellings<Ds[number]> : string : string;
+//#endregion
+//#region src/validation/contexts.brands.d.ts
+/** Canonical names claimed by more than one instance in the same `.provide()` call. */
+type DuplicateContextNames<Cs extends readonly AnyContextInstance[], Seen extends string = never> = Cs extends readonly [infer Head, ...infer Tail extends readonly AnyContextInstance[]] ? (DefName<Head> & Seen) | DuplicateContextNames<Tail, Seen | DefName<Head>> : never;
+type DuplicateContextBrand<C, Existing extends string> = CollisionBrand<DefName<C>, Existing, "FIX_DUPLICATE_CONTEXT", "Context ", " is already provided on this command path">;
+/**
+ * Brand instances whose name is already provided on this builder chain or
+ * repeated within the same `.provide()` call. The accumulated Context value
+ * map doubles as the name registry (its keys are the provided names), so no
+ * separate accumulator is needed. Wrappers generic over the builder type
+ * use `any`, which opts out via the
+ * `string extends keyof Ctx` guard instead of deferring. Widened names opt
+ * out via `DefName`; a parent-provided Context is not in the definition's
+ * `Ctx` and therefore cannot be checked at this call site.
+ */
+type ValidateContextNames<Ctx extends ContextMap, Cs extends readonly AnyContextInstance[], Existing extends string = string extends keyof Ctx ? never : keyof Ctx & string, Dups extends string = DuplicateContextNames<Cs>> = { [I in keyof Cs]: Cs[I] & DuplicateContextBrand<Cs[I], Existing | Dups>; };
+type InstanceNames<P extends readonly unknown[]> = P extends readonly [infer H, ...infer T extends readonly unknown[]] ? DefName<H> | InstanceNames<T> : never;
+/** Statically known names of an Extension's provided Contexts; widened Extensions opt out. */
+type ExtensionProvidedNames<E> = DefiningOf<E> extends {
+  readonly provides?: infer P extends readonly unknown[];
+} ? InstanceNames<P> : never;
+type ExtensionContextBrand<E, Existing extends string> = CollisionBrand<ExtensionProvidedNames<E>, Existing, "FIX_DUPLICATE_CONTEXT", "Extension-provided Context ", " is already provided on this command path">;
+type ValidateExtensionProvidesWorker<Es extends readonly unknown[], Existing extends string> = Es extends readonly [infer H, ...infer T extends readonly unknown[]] ? readonly [H & ExtensionContextBrand<H, Existing>, ...ValidateExtensionProvidesWorker<T, Existing | ExtensionProvidedNames<H>>] : Es;
+/**
+ * Brand Extensions whose provided Context names replace one already on the
+ * command path (or one provided by an earlier Extension in the same call).
+ * The resolver is last-write-wins, so a silent replacement would hand actions
+ * bound before `.extend()` a value of a different static type.
+ */
+type ValidateExtensionProvides<Es extends readonly unknown[], Ctx extends ContextMap> = ValidateExtensionProvidesWorker<Es, string extends keyof Ctx ? never : keyof Ctx & string>;
+type ProvidedDepsOf<C> = IsAny<C> extends true ? {} : IsAny<ContextDepsOf<C>> extends true ? {} : string extends keyof ContextDepsOf<C> ? {} : ContextDepsOf<C>;
+type MissingDependencyBrand<C, Known extends string> = Exclude<keyof ProvidedDepsOf<C> & string, Known> extends (infer Missing extends string) ? [Missing] extends [never] ? {} : {
+  readonly FIX_MISSING_DEPENDENCY: `Context "${DefName<C>}" uses Context "${Missing}" which is not provided on this command path`;
+} : never;
+type MismatchedDependencyNames<Deps, KnownValues> = keyof Deps extends never ? never : KnownValues extends unknown ? { [K in keyof Deps & keyof KnownValues & string]: IsAny<KnownValues[K]> extends true ? never : IsAny<Deps[K]> extends true ? never : [unknown, string] extends [KnownValues[K], keyof KnownValues] ? never : KnownValues[K] extends Deps[K] ? never : K; }[keyof Deps & keyof KnownValues & string] : never;
+type MismatchedDependencyBrand<C, KnownValues> = MismatchedDependencyNames<ProvidedDepsOf<C>, KnownValues> extends (infer Mismatched extends string) ? [Mismatched] extends [never] ? {} : {
+  readonly FIX_DEPENDENCY_TYPE: `Context "${DefName<C>}" uses Context "${Mismatched}" whose provided value does not satisfy the declared dependency type`;
+} : never;
+/** Brand provided instances whose transitive dependency closure is unsatisfied. */
+type ValidateContextDeps<Ctx extends ContextMap, Cs extends readonly AnyContextInstance[], Known extends string = (keyof Ctx & string) | DefName<Cs[number]>, KnownValues extends ContextMap = Ctx & ContextsOutput<Cs>> = { [I in keyof Cs]: Cs[I] & MissingDependencyBrand<Cs[I], Known> & MismatchedDependencyBrand<Cs[I], KnownValues>; };
+/** Dependency closure carried by command definitions and Extensions. */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type DeclaredDepsOf<T> = IsAny<T> extends true ? Record<string, ContextValue> : CommandDefinitionData<DefiningOf<T>> extends {
+  readonly _deps?: infer D extends ContextMap;
+} ? IsAny<D> extends true ? Record<string, ContextValue> : D : {};
+/** Missing-dependency brand shared by `ValidateDeclaredDeps` and inline `.command()`. */
+type MissingDeclaredDependencyBrand<T, Known extends string> = string extends keyof DeclaredDepsOf<T> ? {} : Exclude<keyof DeclaredDepsOf<T> & string, Known> extends (infer Missing extends string) ? [Missing] extends [never] ? {} : {
+  readonly FIX_MISSING_DEPENDENCY: `Uses Context "${Missing}" which is not provided`;
+} : never;
+/** Brand sealed units whose declared dependencies are absent at a composition site. */
+type ValidateDeclaredDeps<Ctx extends ContextMap, Items extends readonly unknown[]> = { [I in keyof Items]: Items[I] & MissingDeclaredDependencyBrand<Items[I], keyof Ctx & string> & DeclaredDependencyValuesBrand<DeclaredDepsOf<Items[I]>, Ctx>; };
+/** Callback values stay TypeScript-owned, including at dynamic composition. */
+type DeclaredDependencyValuesBrand<Deps, Values> = MismatchedDependencyNames<Deps, Values> extends (infer Names extends string) ? [Names] extends [never] ? {} : {
+  readonly FIX_DEPENDENCY_TYPE: `Provided Context "${Names}" does not satisfy its declared value type`;
+} : never;
+/** Structural provider copies retain their defining name. */
+type KnownContextInstances<Cs extends readonly AnyContextInstance[]> = { [I in keyof Cs]: Cs[I] & Pick<DefiningOf<Cs[I]>, "name">; };
+//#endregion
+//#region src/validation/flags.brands.d.ts
+/** Brand an incoming definition when one of its spellings is already claimed. */
+type ExistingFlagCollisionBrand<F, Existing extends string> = CollisionBrand<DefName<F> | ExtractAllAliases<F>, Existing, "FIX_ALIAS_COLLISION", "Flag spelling ", " collides with an existing flag">;
+/**
+ * Every statically known canonical, short, and long-alias member, including literals
+ * beside an open member. Spelling grammar only: collision evidence stays with
+ * {@link ExtractAllAliases}, which must not leak literals out of an open domain.
+ * Each field is filtered on its own so a `string`-typed field cannot absorb a
+ * sibling field's invalid literal before the filter runs.
+ */
+type SpellingMembers<F> = DefNameMembers<F> | ClosedMembers<F extends {
+  short: infer S extends string;
+} ? S : never> | ClosedMembers<F extends {
+  aliases: infer A extends readonly string[];
+} ? A[number] : never>;
+/** Reject `__proto__`, which mutates the prototype of plain-object flag registries. */
+type ReservedSpellingBrand<F> = "__proto__" extends SpellingMembers<F> ? {
+  readonly FIX_RESERVED_SPELLING: "Flag spelling \"__proto__\" is reserved";
+} : {};
+type EmptySpellingError = {
+  readonly FIX_EMPTY_SPELLING: "Flag names and aliases must be non-empty strings";
+};
+/** Reject empty flag names, including an empty member of a name union beside an open member. */
+type EmptyFlagSpellingBrand<Name extends string> = EmptyLiteralNameBrand<Name, EmptySpellingError>;
+/** Reject empty spellings: their CLI tokens (`--`, `-`) are unparseable, so the flag can never be supplied. */
+type EmptySpellingBrand<F> = "" extends SpellingMembers<F> ? EmptySpellingError : {};
+type RepeatedAliases<Aliases extends readonly string[], Seen extends string> = Aliases extends readonly [infer Head extends string, ...infer Tail extends readonly string[]] ? (Head & Seen) | RepeatedAliases<Tail, Seen | Head> : never;
+type OwnAliasesBrand<F> = F extends {
+  aliases: infer Aliases extends readonly string[];
+} ? RepeatedAliases<Aliases, ExtractShort<F>> extends (infer Duplicate extends string) ? [Duplicate] extends [never] ? {} : {
+  readonly FIX_ALIAS_COLLISION: "Flag repeats one of its own spellings";
+} : never : {};
+type InvalidShort<S extends string> = S extends `${infer _First}${infer Rest}` ? Rest extends "" ? never : S : S;
+type ShortLengthBrand<F> = F extends {
+  short: infer Short extends string;
+} ? string extends Short ? {} : [InvalidShort<Short>] extends [never] ? {} : {
+  readonly FIX_SHORT_LENGTH: "Short flags must be one character";
+} : {};
+/**
+ * Extract the `short` alias literal from a flag definition.
+ * Resolves to `never` when the field is absent or its spelling domain is open.
+ */
+type ExtractShort<F> = F extends {
+  short: infer S;
+} ? S extends string ? IsClosedName<S> extends true ? S : never : never : never;
+/**
+ * Extract alias string literals from the `aliases` array of a flag definition.
+ * Resolves to `never` when the field is absent or its element domain is open.
+ */
+type ExtractLongAliases<F> = F extends {
+  aliases: infer A;
+} ? A extends readonly string[] ? IsClosedName<A[number]> extends true ? A[number] : never : never : never;
+/**
+ * Extract all alias identifiers (short + long) from a flag definition.
+ *
+ * Generalized to work with any shape; values without `short`/`aliases`
+ * fields resolve to `never`.
+ *
+ * Closed-name proof excludes open domains from literal collision evidence.
+ * Attachment separately keeps their spelling namespace open.
+ */
+type ExtractAllAliases<F> = ExtractShort<F> | ExtractLongAliases<F>;
+/** All narrowed canonical, short, and long-alias spellings in a flags record. */
+type SpellingsOf<F extends FlagsDef> = string extends keyof F ? never : (keyof F & string) | { [K in keyof F & string]: ExtractAllAliases<F[K]>; }[keyof F & string];
+type NoPrefixBrand<S extends string> = [Extract<S, `no-${string}`>] extends [never] ? {} : {
+  readonly FIX_NO_PREFIX: "Names must not start with no-";
+};
+type ContextOwnedFlags<C> = C extends unknown ? DefiningOf<C> extends {
+  readonly _ownedFlags?: infer OF extends FlagsDef;
+} ? OF : {} : never;
+type ContextFlagCollisionBrand<C, Existing extends string> = CollisionBrand<LocalSpellingsOf<ContextOwnedFlags<C>>, Existing, "FIX_ALIAS_COLLISION", "Flag spelling ", " collides with an existing flag">;
+/** Declared flag literals carried by an Extension's `_flagDefs` phantom; widened Extensions opt out. */
+type ExtensionFlagDefsOf<E> = [E] extends [never] ? readonly [] : DefiningOf<E> extends {
+  readonly _flagDefs?: infer D extends readonly NamedFlagDef[];
+} ? D : readonly NamedFlagDef[];
+/** All statically known owned-flag spellings across a tuple of Context instances. */
+type ProvidedContextSpellings<P extends readonly unknown[]> = P extends readonly [infer H, ...infer T extends readonly unknown[]] ? LocalSpellingsOf<ContextOwnedFlags<H>> | ProvidedContextSpellings<T> : [P[number]] extends [never] ? never : LocalSpellingsOf<ContextOwnedFlags<P[number]>>;
+/** All statically known flag spellings an Extension contributes: declared flags plus provided Context-owned flags. */
+type ExtensionSpellings<E> = AttachedSpellings<ExtensionFlagDefsOf<E>> | ([E] extends [never] ? never : DefiningOf<E> extends {
+  readonly provides?: infer P extends readonly unknown[];
+} ? ProvidedContextSpellings<P> : never);
+type ExtensionFlagCollisionBrand<E, Existing extends string> = CollisionBrand<ExtensionSpellings<E>, Existing, "FIX_ALIAS_COLLISION", "Extension flag spelling ", " collides with an existing flag">;
+/**
+ * Validate each Extension's contributed flag spellings against accumulated
+ * existing spellings and against Extensions earlier in the same `.extend()`
+ * call. Extensions must not override application flags: a silent overwrite
+ * would retype an already-bound action's flag at parse time.
+ */
+type ValidateExtensionFlags<Es extends readonly unknown[], Existing extends string> = Es extends readonly [infer H, ...infer T extends readonly unknown[]] ? readonly [H & ExtensionFlagCollisionBrand<H, Existing>, ...ValidateExtensionFlags<T, Existing | ExtensionSpellings<H>>] : Es;
+type ShapeSpellings<S> = 0 extends 1 & S ? string : S extends {
+  readonly flags: infer F extends FlagsDef;
+  readonly children: infer C;
+} ? LocalSpellingsOf<F> | TreeSpellings<C> : never;
+/** Every flag spelling reachable in a compile-time command tree (`Record<spelling, CommandShape>`), recursively. */
+type TreeSpellings<Tree> = 0 extends 1 & Tree ? string : string extends keyof Tree ? string : Tree extends object ? { [K in keyof Tree]: ShapeSpellings<Tree[K]>; }[keyof Tree] : never;
+type DefinitionSpellings<D> = CommandDefinitionData<D> extends {
+  readonly _shape?: infer S;
+} ? ShapeSpellings<S> : never;
+/** Flag spellings contributed by a tuple of command definitions. */
+type DefinitionTreeSpellings<Ds extends readonly unknown[]> = DefinitionSpellings<Ds[number]>;
+/**
+ * Extension-collision brand over a built command shape. Shared by `.add()`
+ * (via {@link ValidateDefinitionFlags}) and inline `.command()`, whose recipe
+ * builder exposes a shape instead of a definition tuple.
+ */
+type ShapeFlagCollisionBrand<S, Ext extends string> = CollisionBrand<ShapeSpellings<S>, Ext, "FIX_ALIAS_COLLISION", "Flag spelling ", " collides with a registered Extension flag">;
+type DefinitionFlagCollisionBrand<D, Ext extends string> = CommandDefinitionData<D> extends {
+  readonly _shape?: infer S;
+} ? ShapeFlagCollisionBrand<S, Ext> : {};
+/**
+ * Validate an added definition tree's flag spellings against already-registered
+ * Extension flags. Recursive Extension flags inject into every node at prepare
+ * time, so a colliding local flag would be silently retyped for its action.
+ */
+type ValidateDefinitionFlags<Ds extends readonly unknown[], Ext extends string> = { [I in keyof Ds]: Ds[I] & DefinitionFlagCollisionBrand<Ds[I], Ext>; };
+/** Union of every statically known flag spelling contributed by a tuple of Extensions. */
+type ExtensionsSpellings<Es extends readonly unknown[]> = Es extends readonly [infer H, ...infer T extends readonly unknown[]] ? ExtensionSpellings<H> | ExtensionsSpellings<T> : ExtensionSpellings<Es[number]> extends never ? never : string;
+/**
+ * Validate Context-owned flags against accumulated existing spellings and
+ * against instances earlier in the same `.provide(a(), b())` call. Without
+ * the batch check a same-call collision silently resolves last-write-wins,
+ * and a required flag shadowed by a peer's alias becomes impossible to supply.
+ */
+type ProvideChecks<Sp extends string, Cs extends readonly unknown[]> = Cs extends readonly [infer H, ...infer T extends readonly unknown[]] ? readonly [H & ContextFlagCollisionBrand<H, Sp>, ...ProvideChecks<Sp | LocalSpellingsOf<ContextOwnedFlags<H>>, T>] : Cs;
+/** Whether canonical and alias spellings form a closed, fixed local namespace. */
+type HasClosedFlagSpellings<F> = F extends {
+  name: infer N extends string;
+} ? false extends IsClosedName<N> | ("short" extends keyof F ? F extends {
+  short: infer S extends string;
+} ? IsClosedName<S> : false : true) | ("aliases" extends keyof F ? F extends {
+  aliases: infer A extends readonly string[];
+} ? false extends IsStaticTuple<A> | IsClosedName<A[number]> ? false : true : false : true) ? false : true : false;
+type LocalFlagBrand<F> = UnionToIntersection<F extends unknown ? LocalFlagBranchBrand<F> : never>;
+type LocalFlagBranchBrand<F> = LocalValueBrand<F> & OwnAliasesBrand<F> & ShortLengthBrand<F> & ReservedSpellingBrand<F> & EmptySpellingBrand<F> & NoPrefixBrand<SpellingMembers<F>> & ([DefName<F> & ExtractAllAliases<F>] extends [never] ? {} : {
+  readonly FIX_ALIAS_COLLISION: "Flag repeats one of its own spellings";
+});
+/** Validate provable local fields and destination relations without inventing names for open inputs. */
+type ValidateLocalFlagDefs<Defs extends readonly NamedFlagDef[], Existing extends string> = Defs & UnionToIntersection<LocalFlagTupleChecks<Defs, Existing>>;
+type LocalFlagTupleChecks<Defs extends readonly NamedFlagDef[], Existing extends string, Errors = {}> = Defs extends readonly [infer Head extends NamedFlagDef, ...infer Tail extends readonly NamedFlagDef[]] ? LocalFlagTupleChecks<Tail, Existing | DefName<Head> | ExtractAllAliases<Head>, Errors & LocalFlagBrand<Head> & ExistingFlagCollisionBrand<Head, Existing>> : Defs extends readonly [] ? Errors : Errors & LocalFlagBrand<Defs[number]>;
+/** An open collection is not an empty or guaranteed-present flag record. */
+type KnownNamedFlag<D> = D extends NamedFlagDef ? HasClosedNames<readonly [D]> extends true ? D : never : never;
+type AttachedFlags<Defs extends readonly NamedFlagDef[]> = HasClosedNames<Defs> extends true ? NamedFlagsRecord<Defs> : IsStaticTuple<Defs> extends true ? FlagsDef & NamedFlagsRecord<readonly KnownNamedFlag<Defs[number]>[]> : FlagsDef;
+type AttachedSpellings<Defs extends readonly NamedFlagDef[]> = IsStaticTuple<Defs> extends true ? false extends { [I in keyof Defs]: HasClosedFlagSpellings<Defs[I]>; }[number] ? string : SpellingsOf<NamedFlagsRecord<Defs>> : string;
+type LocalFlagNameBrand<N extends string> = EmptyFlagSpellingBrand<N> & ReservedSpellingBrand<{
+  name: N;
+}> & NoPrefixBrand<N>;
+/** Broad structural builder holders must not default their spelling state to empty. */
+type LocalSpellingsOf<F extends FlagsDef> = string extends keyof F ? string : true extends { [K in keyof F]: HasClosedFlagSpellings<F[K] & {
+  name: K;
+}> extends false ? true : false; }[keyof F] ? string : SpellingsOf<F>;
+//#endregion
+//#region src/command/snapshot.d.ts
+/**
+ * Serializable projection of a positional argument definition.
+ *
+ * Carries everything help/man/tooling surfaces need; `parse` functions and
+ * schemas never cross the boundary.
+ *
+ * Fields with `undefined` values are dropped entirely (see `freezeCompact`),
+ * so absent means "not declared".
+ *
+ * @example
+ * For `{ name: "port", type: "number", default: 3000 }`:
+ * ```ts
+ * { name: "port", type: "number", default: 3000 }
+ * // `required`/`variadic` keys absent — not declared on the def
+ * ```
+ */
+interface ArgSnapshot {
+  /** Argument name as defined, e.g. `"file"`. */
+  readonly name: string;
+  /** Value type (`"string"`, `"number"`, …); absent for schema-backed args. */
+  readonly type?: ValueType;
+  /** Human-readable description for help text. */
+  readonly description?: string;
+  /** `true` when parsing fails if the argument is missing. */
+  readonly required?: boolean;
+  /** `true` when the argument collects all remaining positionals into an array. */
+  readonly variadic?: boolean;
+  /** Static enum of accepted values, e.g. `["json", "text"]`. */
+  readonly choices?: readonly string[];
+  /** Declared default value; `URL` defaults are serialized to their `href` string. */
+  readonly default?: unknown;
+}
+/**
+ * Serializable projection of a flag definition. The flag's canonical name is
+ * the key it sits under in {@link CommandSnapshot.flags}, not a field here.
+ *
+ * @example
+ * For `{ verbose: { type: "boolean", short: "v", default: false } }`:
+ * ```ts
+ * snapshot.flags.verbose
+ * // => { type: "boolean", short: "v", default: false, negatable: true }
+ * ```
+ */
+interface FlagSnapshot {
+  /** Value type, e.g. `"boolean"`, `"string"`, `"number"`. */
+  readonly type: ValueType;
+  /** Human-readable description for help text. */
+  readonly description?: string;
+  /** Single-character short alias without the dash, e.g. `"v"` for `-v`. */
+  readonly short?: string;
+  /** Additional aliases without dashes; one-character aliases accept one or two dashes. */
+  readonly aliases?: readonly string[];
+  /** `true` when parsing fails if the flag is not provided. */
+  readonly required?: boolean;
+  /** `true` when the flag can repeat and collects values into an array. */
+  readonly multiple?: boolean;
+  /** `true` when the flag accepts generated `--no-<name>` spellings. */
+  readonly negatable: boolean;
+  /** `true` when a boolean flag opted out of the `--no-<name>` spelling. */
+  readonly noNegate?: boolean;
+  /** Static enum of accepted values, e.g. `["debug", "info", "error"]`. */
+  readonly choices?: readonly string[];
+  /** Declared default value; `URL` defaults are serialized to their `href` string. */
+  readonly default?: unknown;
+}
+/**
+ * A readonly, serializable description of a command, exposed across public
+ * API boundaries (Command Action context, Extension hooks, and
+ * `COMMAND_NOT_FOUND` error details) instead of internal command nodes.
+ *
+ * `flags` contains the effective (Context-owned + local merged) flags — the same
+ * set the parser accepts for the command.
+ *
+ * @example
+ * ```ts
+ * defineCommand("add", (cmd) =>
+ *   cmd
+ *     .args({ name: "name", type: "string", required: true })
+ *     .flags({ name: "force", type: "boolean", short: "f" })
+ *     .action(() => {}),
+ * );
+ * // snapshots to:
+ * // {
+ * //   meta: { name: "add" },
+ * //   hasAction: true,
+ * //   args: [{ name: "name", type: "string", required: true }],
+ * //   flags: { force: { type: "boolean", short: "f", negatable: true } },
+ * //   subCommands: {},
+ * // }
+ * ```
+ */
+interface CommandSnapshot {
+  /** Command metadata, including routing and presentation options. */
+  readonly meta: Readonly<CommandMeta>;
+  /** Whether the command defines a Command Action */
+  readonly hasAction: boolean;
+  /** Positional argument snapshots in declaration order. */
+  readonly args: readonly ArgSnapshot[];
+  /** Effective flags keyed by canonical flag name. */
+  readonly flags: Readonly<Record<string, FlagSnapshot>>;
+  /** Direct subcommand snapshots keyed by canonical name (includes hidden ones). */
+  readonly subCommands: Readonly<Record<string, CommandSnapshot>>;
+}
+//#endregion
+//#region src/command/crust.d.ts
+/**
+ * The runtime context object passed to the Command Action defined with
+ * `.action()`.
+ *
+ * Generic parameters:
+ * - `A` — positional argument definitions tuple
+ * - `F` — the effective (Context-owned + local merged) flag definitions
+ */
+interface CrustCommandContext<A extends ArgsDef = ArgsDef, F extends FlagsDef = FlagsDef, Ctx extends ContextMap = {}> extends InvocationIO {
+  /** Resolved positional arguments, keyed by arg name */
+  args: InferArgs<A>;
+  /** Resolved flags, keyed by flag name */
+  flags: InferFlags<F>;
+  /** Lazy Context values available on this command path. */
+  ctx: ContextBag<Ctx>;
+  /** Raw arguments that appeared after the `--` separator */
+  rawArgs: string[];
+  /** Readonly, serializable snapshot of the resolved command */
+  command: CommandSnapshot;
+  /** Readonly snapshot of the application root, including Extension contributions */
+  rootCommand: CommandSnapshot;
+}
+declare const commandProviders: unique symbol;
+/** Compile-time description of one command's programmatic input and action result. */
+interface CommandShape<A extends ArgsDef = ArgsDef, F extends FlagsDef = FlagsDef, Children extends object = {}, Result = unknown, Providers extends Record<string, ContextValue> = Record<string, ContextValue>> {
+  readonly [commandProviders]?: Providers;
+  readonly args: A;
+  readonly flags: F;
+  readonly children: Children;
+  readonly result: Result;
+}
+/** Captured invocation after lifecycle cleanup. */
+type RunOutcome<Result> = {
+  readonly stdout: string;
+  readonly stderr: string;
+} & ({
+  readonly status: "completed";
+  readonly result: Result;
+} | {
+  readonly status: "finished";
+  readonly by: ExtensionId;
+} | {
+  readonly status: "failed";
+  readonly error: unknown;
+});
+/** Compile-time command tree accumulated by `.add()`. */
+type CommandTree = Record<string, CommandShape>;
+/** Every valid path through a command tree, including the root path (`[]`). */
+type CommandPath<Tree extends object, Depth extends readonly unknown[] = readonly []> = Depth["length"] extends 15 ? readonly string[] : string extends keyof Tree ? readonly string[] : readonly [] | { [K in keyof Tree & string]: Tree[K] extends CommandShape ? readonly [K, ...CommandPath<Tree[K]["children"], readonly [...Depth, unknown]>] : never; }[keyof Tree & string];
+type KnownCommandPath<Path extends readonly string[], Tree> = string extends keyof Tree ? Path : IsStaticTuple<Path> extends true ? string extends Path[number] ? never : Path : never;
+/** Resolve the command shape at a typed path. */
+type CommandShapeAt<Shape extends CommandShape, Path extends readonly string[]> = Path extends readonly [infer Head, ...infer Tail extends readonly string[]] ? Head extends keyof Shape["children"] ? Shape["children"][Head] extends (infer Child extends CommandShape) ? CommandShapeAt<Child, Tail> : never : string extends Head ? CommandShape : never : Path extends readonly [] ? Shape : CommandShape;
+type RunSection<Name extends string, Values> = keyof Values extends never ? { [K in Name]?: never; } : {} extends Values ? { [K in Name]?: Values; } : { [K in Name]: Values; };
+/** Structured values bound directly against the selected command's definitions; no argv is produced. */
+type RunInput<Shape extends CommandShape> = RunSection<"args", ArgsDef extends Shape["args"] ? NonNullable<RunInputPayload["args"]> : InputArgs<Shape["args"]>> & RunSection<"flags", FlagsDef extends Shape["flags"] ? NonNullable<RunInputPayload["flags"]> : InputFlags<Shape["flags"]>> & {
+  readonly raw?: readonly string[];
+};
+type CompatibleRunValue<Expected, Actual> = Actual extends Expected ? Actual extends object ? Expected extends unknown ? Actual extends Expected ? Actual & { [K in Exclude<keyof Actual, keyof Expected>]: never; } & { [K in keyof Actual & keyof Expected]: CompatibleRunValue<Expected[K], Actual[K]>; } : never : never : Actual : JsonValue extends Expected ? Actual extends JsonCompatible<Actual> ? Actual : never : Expected extends unknown ? CompatibleRunBranch<Expected, Actual> : never;
+type CompatibleRunBranch<Expected, Actual> = Actual extends Expected ? Actual : Expected extends readonly (infer Item)[] ? JsonValue extends Item ? Actual extends (Expected extends readonly [unknown, ...unknown[]] ? readonly [unknown, ...unknown[]] : readonly unknown[]) ? Actual extends JsonCompatible<Actual> ? Actual : never : never : never : Actual extends object ? string extends keyof Expected ? { [K in keyof Actual]: CompatibleRunValue<Exclude<Expected[K & keyof Expected], undefined>, Actual[K]>; } : { [K in keyof Expected]: K extends keyof Actual ? CompatibleRunValue<Exclude<Expected[K], undefined>, Actual[K]> : Expected[K]; } & { [K in Exclude<keyof Actual, keyof Expected>]: never; } : never;
+type CompatibleRunInput<Shape extends CommandShape, Input> = CompatibleRunValue<RunInput<Shape>, Input>;
+type RunInputArguments<Shape extends CommandShape> = {} extends RunInput<Shape> ? readonly [input?: RunInput<Shape>] : readonly [input: RunInput<Shape>];
+type RunArguments<Shape extends CommandShape> = readonly [...RunInputArguments<Shape>, io?: Partial<InvocationIO>];
+/**
+ * Typed invoker bound to one command in an app, returned by {@link Crust.at}.
+ *
+ * `run` accepts the same structured input and IO as `Crust.run` with the path
+ * already applied, so a handle can be re-exported as a plain typed function.
+ */
+interface CommandHandle<Shape extends CommandShape> {
+  /** The typed path this handle was created with (`[]` selects the root). */
+  readonly path: readonly string[];
+  run(...args: RunArguments<Shape>): Promise<RunOutcome<Shape["result"]>>;
+  run<const Input>(input: Input, ...validation: [Input] extends [CompatibleRunInput<Shape, Input>] ? readonly [io?: Partial<InvocationIO>] : readonly [invalidInput: never]): Promise<RunOutcome<Shape["result"]>>;
+}
+/** Static configuration for a reusable command definition. */
+interface CommandConfig extends Omit<CommandMeta, "name" | "sections" | "version"> {
+  /** Plain-text sections rendered after built-in command documentation. */
+  readonly sections?: readonly RuntimeCommandSectionInput[];
+}
+/** Static metadata accepted by the root command constructor. */
+type RootCommandMeta = Pick<CommandMeta, "description" | "version" | "usage"> & {
+  /** Plain-text sections rendered after built-in command documentation. */
+  readonly sections?: readonly RuntimeCommandSectionInput[];
+};
+type AnyCommandDefinitionBuilder = Crust<any, any, any, any, any, any, any, any, any, any, any, "recipe">;
+type CommandRecipe<Builder extends AnyCommandDefinitionBuilder = AnyCommandDefinitionBuilder> = (command: CommandDefinitionBuilder<{}, [], {}, never, never>) => Builder;
+declare const commandDefinitionInternal: unique symbol;
+interface CommandDefinitionInternal {
+  readonly name: string;
+  readonly recipe: (command: AnyCommandDefinitionBuilder) => AnyCommandDefinitionBuilder;
+  readonly meta: Omit<CommandMeta, "name">;
+}
+type CommandInputShape<S extends CommandShape> = {
+  readonly args: S["args"];
+  readonly flags: S["flags"];
+  readonly providers: S[typeof commandProviders];
+  readonly children: { [K in keyof S["children"]]: S["children"][K] extends CommandShape ? CommandInputShape<S["children"][K]> : never; };
+};
+interface CommandDefinition<Name extends string = string, Aliases extends readonly string[] = readonly string[], Shape extends CommandShape = CommandShape, Deps extends ContextMap = {}> {
+  /** The subcommand name this definition is added under */
+  readonly name: Name;
+  /** The same definition under a different name; configured aliases travel with it. */
+  as<const N extends string>(name: N & CommandNameBrand<N> & ValidateCommandConfig<N, {
+    aliases: Aliases;
+  }>): CommandDefinition<N, Aliases, Shape, Deps>;
+  /** @internal */
+  readonly [commandDefinitionInternal]: CommandDefinitionInternal & {
+    readonly _aliases?: Aliases;
+    readonly _shape?: Shape;
+    readonly _deps?: Deps;
+    readonly proof?: [Shape] extends [never] ? unknown : string extends keyof Shape["flags"] | keyof Deps ? unknown : (state: [CommandInputShape<Shape>, Deps]) => void;
+  };
+}
+/** @internal */
+type CommandDefinitionData<D> = D extends {
+  readonly [commandDefinitionInternal]: infer Data;
+} ? Data : D;
+type AppendedArgs<A extends ArgsDef, NewA extends ArgsDef> = readonly [...A, ...AttachedArgs<NewA>];
+/** Configure-only capability of {@link Crust} passed to command recipes. */
+type CommandDefinitionBuilder<Flags extends FlagsDef = {}, A extends ArgsDef = ArgsDef, Ctx extends ContextMap = {}, Sibs extends string = never, Sp extends string = LocalSpellingsOf<Flags>, Tree extends object = {}, CtxFlags extends FlagsDef = {}, Result = void, Deps extends ContextMap = {}, Providers extends Record<string, ContextValue> = {}> = Crust<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSpellings<never, never, {}, never, Deps, Providers>, Result, {}, string, "recipe">;
+type ShapeOfBuilder<B> = [B] extends [never] ? CommandShape<[], {}, {}, never, {}> : B extends {
+  readonly _recipeTypes: {
+    shape: infer S extends CommandShape;
+  };
+} ? S : never;
+type DepsOfBuilder<B> = UnionToIntersection<B extends {
+  readonly _recipeTypes: {
+    deps: infer Deps extends ContextMap;
+  };
+} ? Deps : {}> extends (infer Merged extends ContextMap) ? Merged : {};
+type DefinitionShapeForSpelling<D, Spelling extends string> = D extends unknown ? CommandDefinitionData<D> extends {
+  readonly _shape?: infer Shape extends CommandShape;
+} ? Spelling extends CommandDefinitionSpellings<D> ? Shape : never : never : never;
+type ShapeWithInheritedFlags<S, CF extends FlagsDef> = keyof CF extends never ? S : S extends CommandShape<infer SA, infer SF, infer SC, infer SR, infer P> ? CommandShape<SA, MergeFlags<CF, SF>, { [K in keyof SC]: ShapeWithInheritedFlags<SC[K], CF>; }, SR, P> : never;
+type DefinitionsTree<Ds extends readonly CommandDefinition<any, any, any, any>[], CtxFlags extends FlagsDef = {}> = string extends AttachedCommandSpellings<Ds> ? Record<string, CommandShape> & KnownDefinitionTree<Ds, CtxFlags> : { [K in CommandDefinitionSpellings<Ds[number]>]: ShapeWithInheritedFlags<DefinitionShapeForSpelling<Ds[number], K>, CtxFlags>; };
+type KnownDefinitionTree<Ds extends readonly unknown[], CF extends FlagsDef> = IsUnion<Ds> extends true ? {} : Ds extends readonly [infer H, ...infer T] ? (IsUnion<H> extends true ? {} : { [K in CommandDefinitionSpellings<H>]: ShapeWithInheritedFlags<DefinitionShapeForSpelling<H, K>, CF>; }) & KnownDefinitionTree<T, CF> : {};
+type ExtensionCheckAt<Checks, I> = I extends keyof Checks ? Checks[I] : never;
+type ExtensionCommands<Es extends readonly AnyExtension[]> = Es extends readonly [infer H, ...infer T extends readonly AnyExtension[]] ? readonly [...ExtensionCommandDefs<H>, ...ExtensionCommands<T>] : ExtensionCommandDefs<Es[number]>[number] extends never ? readonly [] : readonly CommandDefinition<any, any, any, any>[];
+type ExtensionProviders<E> = [E] extends [never] ? [] : DefiningOf<E> extends {
+  provides?: infer P extends readonly AnyContextInstance[];
+} ? P : [];
+type ExtensionOwnDefs<E> = [E] extends [never] ? [] : DefiningOf<E> extends {
+  _flagDefs?: infer F extends readonly NamedFlagDef[];
+} ? F : [];
+type ExtensionFlags<Es extends readonly AnyExtension[]> = Es extends readonly [infer H, ...infer T extends readonly AnyExtension[]] ? AttachedFlags<ExtensionOwnDefs<H>> & ContextsOwnedFlags<ExtensionProviders<H>> & ExtensionFlags<T> : ExtensionOwnDefs<Es[number]>[number] extends never ? keyof ContextsOwnedFlags<ExtensionProviders<Es[number]>> extends never ? {} : FlagsDef : FlagsDef;
+type RecursiveFlagsOf<E> = ExtensionOwnDefs<E>[number] extends never ? {} : true extends { [K in keyof ExtensionOwnDefs<E>]: ExtensionOwnDefs<E>[K] extends (infer D extends NamedFlagDef) ? D extends {
+  readonly recursive: false;
+} ? false : IsClosedName<D["name"]> extends false ? true : IsUnion<D["name"]> extends true ? true : D extends {
+  recursive: infer R;
+} ? boolean extends R ? true : false : false : false; }[number] ? FlagsDef : IsStaticTuple<ExtensionOwnDefs<E>> extends true ? { [D in ExtensionOwnDefs<E>[number] as D extends {
+  readonly recursive: infer R;
+} ? [R] extends [false] ? never : D["name"] : D["name"]]: Omit<D, "name">; } : FlagsDef;
+type RecursiveExtensionFlags<Es extends readonly AnyExtension[]> = Es extends readonly [infer H, ...infer T extends readonly AnyExtension[]] ? RecursiveFlagsOf<H> & ContextsOwnedFlags<ExtensionProviders<H>> & RecursiveExtensionFlags<T> : ExtensionFlags<Es>;
+type TreeWithInheritedFlags<Tree, F extends FlagsDef> = { [K in keyof Tree]: ShapeWithInheritedFlags<Tree[K], F>; };
+type ReplacementTree<Tree, D extends CommandDefinition<any, any, any, any>, CF extends FlagsDef> = CommandDefinitionData<D> extends {
+  readonly _aliases?: infer Aliases extends readonly string[];
+} ? IsClosedName<Aliases[number]> extends false ? Record<string, CommandShape> & { [K in D["name"]]: ShapeWithInheritedFlags<DefinitionShapeForSpelling<D, K>, CF>; } : Omit<Tree, CommandDefinitionSpellings<D>> & { [K in CommandDefinitionSpellings<D>]: K extends D["name"] ? ShapeWithInheritedFlags<DefinitionShapeForSpelling<D, K>, CF> : K extends keyof Tree ? CommandShape : ShapeWithInheritedFlags<DefinitionShapeForSpelling<D, K>, CF>; } : Record<string, CommandShape>;
+type ReplacedTree<Tree, Commands extends readonly unknown[], CF extends FlagsDef> = Commands extends readonly [infer H extends CommandDefinition<any, any, any, any>, ...infer T extends readonly unknown[]] ? ReplacedTree<IsClosedName<H["name"]> extends false ? Record<string, CommandShape> : true extends IsUnion<H> | IsUnion<H["name"]> ? Record<string, CommandShape> : ReplacementTree<Tree, H, CF>, T, CF> : number extends Commands["length"] ? Record<string, CommandShape> : Tree;
+type ReplacedExtensionTree<Tree, Es extends readonly AnyExtension[], CF extends FlagsDef> = Es extends readonly [infer H extends AnyExtension, ...infer T extends readonly AnyExtension[]] ? ReplacedExtensionTree<ReplacedTree<Tree, ExtensionCommandDefs<H>, CF>, T, CF> : ExtensionCommandDefs<Es[number]>[number] extends never ? Tree : Record<string, CommandShape>;
+type ExtendedTree<Tree, Es extends readonly AnyExtension[], RecursiveFlags extends FlagsDef, InheritedFlags extends FlagsDef> = keyof RecursiveFlags extends never ? ReplacedExtensionTree<Tree, Es, InheritedFlags> : TreeWithInheritedFlags<ReplacedExtensionTree<Tree, Es, InheritedFlags>, RecursiveFlags>;
+/**
+ * Define a reusable, inert command under a required name.
+ *
+ * The recipe runs once per `.add()`, receiving a fresh builder.
+ *
+ * Static metadata belongs in `config`. Use `.as(name)`
+ * to add one definition under a different name; configured aliases travel with it.
+ */
+declare function defineCommand<const Name extends string, Builder extends AnyCommandDefinitionBuilder>(name: Name & CommandNameBrand<Name>, recipe: CommandRecipe<Builder>): CommandDefinition<Name, readonly [], ShapeOfBuilder<Builder>, DepsOfBuilder<Builder>>;
+declare function defineCommand<const Name extends string, const C extends CommandConfig, Builder extends AnyCommandDefinitionBuilder>(name: Name & CommandNameBrand<Name>, config: C & LocalCommandConfigBrand<Name, C>, recipe: CommandRecipe<Builder>): CommandDefinition<Name, AliasesOf<C>, ShapeOfBuilder<Builder>, DepsOfBuilder<Builder>>;
+/**
+ * Chainable builder for defining CLI commands with full type inference.
+ *
+ * Generic parameters:
+ * - `Flags` — flags defined locally or installed by provided Contexts
+ * - `A` — positional argument definitions
+ * - `Ctx` — provided Context values
+ * - `Sibs` — sibling command names and aliases already registered
+ * - `Sp` — accumulated flag spellings used for collision checks
+ * - `Tree` — command shapes accumulated by `.add()` for typed `run()`
+ * - `CtxFlags` — Context-owned flags accumulated by `.provide()` and recursive
+ *   Extension flags accumulated by `.extend()`, inherited by the shapes of
+ *   definitions added afterwards
+ * - `Result` — awaited return type of this command's action
+ * - `Meta` — authored root metadata available to Extension requirements
+ * - `Caps` — root application or configure-only recipe capabilities
+ *
+ * @example
+ * ```ts
+ * const app = new Crust("my-cli")
+ *   .flags({ name: "verbose", type: "boolean", short: "v" })
+ *   .args({ name: "file", type: "string", required: true })
+ *   .action(({ args, flags }) => {
+ *     console.log(args.file, flags.verbose);
+ *   });
+ * ```
+ */
+type CollisionSpellings<Extensions extends string = never, Tree extends string = never, Demands extends ContextMap = {}, Pending extends string = never, RecipeDeps extends ContextMap = {}, Providers extends Record<string, ContextValue> = {}, ActionDeps extends ContextMap = {}> = {
+  readonly actionDeps: ActionDeps;
+  readonly pending: Pending;
+  readonly demands: Demands;
+  readonly extension: Extensions;
+  readonly tree: Tree;
+  readonly recipeDeps: RecipeDeps;
+  readonly providers: Providers;
+};
+type AnyCollisionSpellings = {
+  readonly actionDeps?: ContextMap;
+  readonly pending: string;
+  readonly demands: ContextMap;
+  readonly extension: string;
+  readonly tree: string;
+  readonly recipeDeps?: ContextMap;
+  readonly providers?: Record<string, ContextValue>;
+};
+type RecipeDepsOf<S extends AnyCollisionSpellings> = S extends {
+  readonly recipeDeps: infer Deps extends ContextMap;
+} ? Deps : {};
+type ProvidersOf<S extends AnyCollisionSpellings> = S extends {
+  readonly providers: infer Providers extends Record<string, ContextValue>;
+} ? Providers : {};
+/** Obligations of this node's stored action, never inherited by descendants. */
+type ActionDepsOf<S extends AnyCollisionSpellings> = S extends {
+  readonly actionDeps: infer Deps extends ContextMap;
+} ? Deps : {};
+type AfterFlags<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, Result, Defs extends readonly NamedFlagDef[], Meta extends RootCommandMeta | undefined, Caps extends "app" | "recipe"> = Crust<MergeFlags<Flags, AttachedFlags<Defs>>, A, Ctx, Sibs, Sp | AttachedSpellings<Defs>, Tree, CtxFlags, CollisionSp, Result, Meta, string, Caps>;
+type AfterArgs<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, Result, NewA extends ArgsDef, Meta extends RootCommandMeta | undefined, Caps extends "app" | "recipe"> = Crust<Flags, AppendedArgs<A, NewA>, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Meta, string, Caps>;
+type AfterUse<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, Result, Fs extends readonly AnyContextFactory[], Meta extends RootCommandMeta | undefined> = Crust<Flags, A, MergeContext<Ctx, ContextDependencies<Fs>>, Sibs, Sp, Tree, CtxFlags, CollisionSpellings<CollisionSp["extension"], CollisionSp["tree"], CollisionSp["demands"], CollisionSp["pending"], MergeContext<RecipeDepsOf<CollisionSp>, ContextDependencies<Fs>>, ProvidersOf<CollisionSp>, ActionDepsOf<CollisionSp>>, Result, Meta, string, "recipe">;
+type AfterProvide<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, Result, Cs extends readonly AnyContextInstance[], Meta extends RootCommandMeta | undefined, Caps extends "app" | "recipe"> = Crust<MergeFlags<Flags, ContextsOwnedFlags<Cs>>, A, MergeProviders<Ctx, ContextsOutput<Cs>>, Sibs, Sp | LocalSpellingsOf<ContextsOwnedFlags<Cs>>, Tree, MergeFlags<CtxFlags, ContextsOwnedFlags<Cs>>, CollisionSpellings<CollisionSp["extension"], CollisionSp["tree"], CollisionSp["demands"], CollisionSp["pending"], RecipeDepsOf<CollisionSp>, MergeProviders<ProvidersOf<CollisionSp>, ContextsOutput<Cs>>, ActionDepsOf<CollisionSp>>, Result, Meta, string, Caps>;
+type AfterAction<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, R, Meta extends RootCommandMeta | undefined, Caps extends "app" | "recipe"> = Crust<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, Omit<CollisionSp, "actionDeps"> & {
+  readonly actionDeps: Ctx;
+}, Awaited<R>, Meta, string, Caps>;
+type AfterExtend<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, Result, Es extends readonly AnyExtension[], Meta extends RootCommandMeta | undefined, Caps extends "app" | "recipe"> = Crust<MergeFlags<Flags, ExtensionFlags<Es>>, A, MergeProviders<Ctx, ExtensionsProvidesOutput<Es>>, Sibs | ExtensionsCommandSpellings<Es>, Sp | ExtensionsSpellings<Es>, ExtendedTree<Tree, Es, RecursiveExtensionFlags<Es>, CtxFlags>, MergeFlags<CtxFlags, RecursiveExtensionFlags<Es>>, CollisionSpellings<CollisionSp["extension"] | ExtensionsSpellings<Es>, CollisionSp["tree"] | DefinitionTreeSpellings<ExtensionCommands<Es>>, CollisionSp["demands"] & ExtensionDemandValues<Es>, CollisionSp["pending"] | DefinitionTreeSpellings<ExtensionCommands<Es>>, RecipeDepsOf<CollisionSp>, MergeProviders<ProvidersOf<CollisionSp>, ExtensionsProvidesOutput<Es>>, ActionDepsOf<CollisionSp>>, Result, Meta, string, Caps>;
+type AfterAdd<Flags extends FlagsDef, A extends ArgsDef, Ctx extends ContextMap, Sibs extends string, Sp extends string, Tree extends object, CtxFlags extends FlagsDef, CollisionSp extends AnyCollisionSpellings, Result, Ds extends readonly CommandDefinition<any, any, any, any>[], Meta extends RootCommandMeta | undefined, Caps extends "app" | "recipe"> = Crust<Flags, A, Ctx, Sibs | AttachedCommandSpellings<Ds>, Sp, Tree & DefinitionsTree<Ds, CtxFlags>, CtxFlags, CollisionSpellings<CollisionSp["extension"], CollisionSp["tree"] | DefinitionTreeSpellings<Ds>, CollisionSp["demands"], CollisionSp["pending"], RecipeDepsOf<CollisionSp>, ProvidersOf<CollisionSp>, ActionDepsOf<CollisionSp>>, Result, Meta, string, Caps>;
+type ExtensionDemandValues<Es extends readonly AnyExtension[]> = UnionToIntersection<DefiningOf<Es[number]> extends {
+  readonly _hookDeps?: infer H extends ContextMap;
+} ? H : Record<string, ContextValue>> extends (infer D extends ContextMap) ? D : {};
+type DescendantShapeValuesBrand<S, Deps> = S extends CommandShape ? DeclaredDependencyValuesBrand<Deps, NonNullable<S[typeof commandProviders]>> & DescendantValuesBrand<S["children"], Deps> : {};
+type DescendantValuesBrand<Tree, Deps> = keyof Deps extends never ? {} : UnionToIntersection<Tree extends unknown ? keyof Tree extends never ? {} : { [K in keyof Tree]: DescendantShapeValuesBrand<Tree[K], Deps>; }[keyof Tree] : never>;
+type DefinitionDescendantValuesBrand<Ds extends readonly CommandDefinition<any, any, any, any>[], Deps> = DescendantValuesBrand<DefinitionsTree<Ds>, Deps>;
+type ValidateInlineCommandDeps<Ctx extends ContextMap, B> = MissingDeclaredDependencyBrand<{
+  readonly _deps?: DepsOfBuilder<B>;
+}, keyof Ctx & string> & DeclaredDependencyValuesBrand<DepsOfBuilder<B>, Ctx>;
+/** Completed applications expose inspection and invocation, not authoring after erasure. */
+type AnyCrust = Pick<Crust<FlagsDef, ArgsDef, Record<string, ContextValue>, string, string, CommandTree, FlagsDef, AnyCollisionSpellings, unknown, RootCommandMeta>, "_types" | "run" | "execute" | "snapshot">;
+type DefinedRootMetaKeys<Meta extends RootCommandMeta | undefined> = { [K in RootMetaKey]: [Meta] extends [Required<Pick<RootCommandMeta, K>>] ? K : never; }[RootMetaKey];
+declare class Crust<Flags extends FlagsDef = {}, A extends ArgsDef = [], Ctx extends ContextMap = {}, Sibs extends string = never, Sp extends string = LocalSpellingsOf<Flags>, Tree extends object = {}, CtxFlags extends FlagsDef = {}, CollisionSp extends AnyCollisionSpellings = CollisionSpellings, Result = void, const out Meta extends RootCommandMeta | undefined = {}, const Name extends string = string, Caps extends "app" | "recipe" = "app"> {
+  private readonly _contextProof;
+  /** @internal — recipe state, without structural inference through builder methods. */
+  readonly _recipeTypes: {
+    readonly shape: CommandShape<A, Flags, Tree, Result, ProvidersOf<CollisionSp>>;
+    readonly deps: RecipeDepsOf<CollisionSp>;
+    readonly proof?: (state: [CommandInputShape<CommandShape<A, Flags, Tree, Result, ProvidersOf<CollisionSp>>>, RecipeDepsOf<CollisionSp>]) => void;
+  };
+  /** Supported type-level seam exposing the application's inferred command types. */
+  readonly _types: {
+    flags: Flags;
+    args: A;
+    ctx: Ctx;
+    tree: Tree;
+    shape: CommandShape<A, Flags, Tree, Result>;
+    readonly rootMeta: Meta;
+    readonly caps: Caps;
+  };
+  /** @internal */
+  _node: CommandNode;
+  /** @internal — Recipe-builder lineage anchor, unique per materialization and preserved by clones */
+  _ancestorOwnedFlags: FlagsDef;
+  /**
+   * Create a new root command builder.
+   *
+   * @param name - The command name.
+   * @param metadata - Optional root description, version, usage, and documentation sections.
+   */
+  constructor(nameInput: (Name & CommandNameBrand<Name>) & ({} extends Meta ? {} : {
+    readonly FIX_ROOT_META: "This root requires metadata";
+  }));
+  constructor(nameInput: Name & CommandNameBrand<Name>, meta: Meta & (undefined | (RootCommandMeta & LocalSectionsBrand<NoInfer<NonNullable<Meta>>> & { [K in Exclude<keyof Meta, RootMetaKey>]: never; })));
+  /** @internal — Clone this builder with a new node, preserving generics. */
+  _clone<Out = this>(nodeOverrides: Partial<CommandNode>): Out;
+  /**
+   * Define local flags for this command from named flag definitions
+   * (created with `defineFlag(name, def)` or written inline as
+   * `{ name: "dry-run", type: "boolean" }`).
+   *
+   * Repeated `.flags()` calls accumulate local flags. Returns a new builder
+   * with the combined local flag types. The original builder is not mutated.
+   *
+   * @param defs - Named flag definitions
+   * @returns A new `Crust` instance with the given flags
+   */
+  flags<const Defs extends readonly NamedFlagDef[], _Union extends this = never>(...defs: ValidateLocalFlagDefs<Defs, Sp>): AfterFlags<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Defs, Meta, Caps>;
+  /**
+   * Define positional arguments for this command; argument order is the
+   * order they are passed (created with `defineArg(name, def)` or written
+   * inline).
+   *
+   * Repeated `.args()` calls append in call order. Returns a new builder with
+   * the combined args types. The original builder is not mutated.
+   *
+   * @param defs - Positional argument definitions, in positional order
+   * @returns A new `Crust` instance with the combined args
+   */
+  args<const NewA extends ArgsDef, _Union extends this = never>(...defs: NewA & AppendArgsChecks<A, NewA>): AfterArgs<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, NewA, Meta, Caps>;
+  /**
+   * Declare Contexts this command consumes without supplying their values.
+   * Factory references are retained while setup stays lazy.
+   */
+  use<const Fs extends readonly [AnyContextFactory, ...AnyContextFactory[]] = never>(this: {
+    readonly _types: {
+      readonly caps: "recipe";
+    };
+  }, ...factories: Fs & DeclaredDependencyValuesBrand<ContextDependencies<Fs>, ProvidersOf<CollisionSp>>): AfterUse<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Fs, Meta>;
+  /**
+   * Attach Contexts — named command dependencies — to this command.
+   *
+   * Contexts are inherited by descendant commands and constructed lazily when
+   * their `ctx` property is accessed. Dependency order within one call does not
+   * affect construction. Disposable values are released in
+   * reverse construction order after post-run hooks. TypeScript rejects known Context-owned flag collisions, including pending
+   * Extension commands. Consuming operations throw `DEFINITION` for actual collisions.
+   *
+   */
+  provide<const Cs extends readonly AnyContextInstance[] = never>(...instances: KnownContextInstances<Cs> & ProvideChecks<Sp | CollisionSp["pending"], Cs> & ValidateContextNames<Caps extends "recipe" ? ProvidersOf<CollisionSp> : Ctx, Cs> & ValidateContextDeps<Ctx, Cs> & DeclaredDependencyValuesBrand<CollisionSp["demands"] & RecipeDepsOf<CollisionSp> & ActionDepsOf<CollisionSp>, ContextsOutput<NoInfer<Cs>>>): AfterProvide<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Cs, Meta, Caps>;
+  /**
+   * Define the Command Action — the function that implements this
+   * command's behavior after its inputs are ready.
+   *
+   * The action receives a {@link CrustCommandContext} with `args` typed from
+   * `.args()` and `flags` typed from the accumulated `Flags`.
+   *
+   * Calling `.action()` again replaces the command behavior and its Context obligations
+   * on the new builder. Later local providers must satisfy the bound Context value types;
+   * descendants may shadow independently. The original builder is not mutated.
+   *
+   * @param action - The Command Action function
+   * @returns A new `Crust` instance with the action registered
+   */
+  action<R>(action: (ctx: NoInfer<CrustCommandContext<A, Flags, Ctx>>) => R): AfterAction<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, R, Meta, Caps>;
+  /**
+   * Register one or more CLI Extensions on the application root.
+   *
+   * Extensions are application-wide: they own the flags and commands they
+   * contribute. Repeated calls accumulate Extensions in registration order,
+   * except that registering an `ExtensionId` again keeps only the last
+   * registration — its contributions and providers replace the earlier ones
+   * and its hooks run once, at the later position. ID deduplication is
+   * runtime-only, so removed paths can remain statically visible and reject
+   * with `COMMAND_NOT_FOUND`. Canonical replacements use the new
+   * shape; open replacements and ambiguous aliases have unknown results.
+   * Required root metadata keys are checked against the constructor's inferred
+   * metadata by TypeScript, not at runtime.
+   * Recipe builders cannot call this root-only method.
+   */
+  extend<const Es extends readonly Extension<any, any, any, any, DefinedRootMetaKeys<Meta>>[], _Union extends this = never>(this: {
+    readonly _types: {
+      readonly caps: "app";
+    };
+  }, ...extensions: Es & { [I in keyof Es]: (ExtensionCommandDefs<Es[I]> extends ValidateDefinitionFlags<ExtensionCommandDefs<Es[I]>, LocalSpellingsOf<CtxFlags>> ? {} : {
+    readonly FIX_ALIAS_COLLISION: "Extension command flags collide with inherited Context flags";
+  }) & ValidateDeclaredDeps<MergeProviders<Ctx, ExtensionsProvidesOutput<Es>>, Es>[I] & DeclaredDependencyValuesBrand<CollisionSp["demands"], MergeProviders<Ctx, ExtensionsProvidesOutput<Es>>> & DescendantValuesBrand<Tree, ExtensionDemandValues<Es>> & DefinitionDescendantValuesBrand<ExtensionCommands<Es>, CollisionSp["demands"] & ExtensionDemandValues<Es>> & ExtensionCheckAt<ValidateExtensionFlags<Es, Sp | CollisionSp["tree"] | DefinitionTreeSpellings<ExtensionCommands<Es>>>, I> & ExtensionCheckAt<ValidateExtensionCommands<Es, Sibs>, I> & ExtensionCheckAt<ValidateExtensionProvides<Es, Ctx>, I>; }): AfterExtend<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Es, Meta, Caps>;
+  /**
+   * Materialize and register inert reusable command definitions, each
+   * under its own carried name (use `.as(name)` to rename).
+   *
+   */
+  add<const Ds extends readonly CommandDefinition<any, any, any, any>[] = never>(...definitions: Ds & ValidateCommandDefinitions<Ds, Sibs> & ValidateDeclaredDeps<Ctx, Ds> & DefinitionDescendantValuesBrand<Ds, CollisionSp["demands"]> & ValidateDefinitionFlags<Ds, CollisionSp["extension"] | LocalSpellingsOf<CtxFlags>>): AfterAdd<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, Ds, Meta, Caps>;
+  /**
+   * Define an app-local leaf subcommand inline (root-only sugar for
+   * `.add(defineCommand(name, recipe))`).
+   *
+   * The recipe builder is seeded with the Contexts and Context-owned flags
+   * accumulated on this builder so far — the call site. Contexts provided
+   * after `.command()` are not visible to it, matching the positional runtime
+   * semantics of `.provide()`. Extract to `defineCommand` when a command needs
+   * its own file, reuse, or a package. Recipe builders cannot call this
+   * root-only method.
+   */
+  command<const N extends string, B extends AnyCommandDefinitionBuilder>(this: {
+    readonly _types: {
+      readonly caps: "app";
+    };
+  }, name: N & CommandNameBrand<N> & CommandCollisionBrand<N, Sibs>, recipe: ((command: CommandDefinitionBuilder<{}, [], Ctx, never, LocalSpellingsOf<CtxFlags>, {}, CtxFlags>) => B & ShapeFlagCollisionBrand<ShapeOfBuilder<B>, CollisionSp["extension"]> & ValidateInlineCommandDeps<Ctx, NoInfer<B>>) & NoInfer<DescendantValuesBrand<{
+    child: ShapeOfBuilder<B>;
+  }, CollisionSp["demands"]>>): AfterAdd<Flags, A, Ctx, Sibs, Sp, Tree, CtxFlags, CollisionSp, Result, readonly [CommandDefinition<N, readonly [], ShapeOfBuilder<B>, DepsOfBuilder<B>>], Meta, Caps>;
+  private _addDefinitions;
+  /**
+   * Prepare a frozen Command Snapshot for tooling such as man-page, skill,
+   * and build generators.
+   *
+   * Materializes Extension contributions and command definitions without
+   * calling Command Actions.
+   */
+  snapshot(this: {
+    readonly _types: {
+      readonly caps: "app";
+    };
+  }): Promise<CommandSnapshot>;
+  /**
+   * Programmatically invoke a typed command, quietly capturing its output.
+   * Returns completed, finished, or failed after cleanup without presenting errors.
+   * Use {@link execute} as the streaming terminal adapter.
+   *
+   * @param path - Typed path to the command to invoke (`[]` selects the root)
+   * @param input - Structured argument, flag, and raw values
+   * @param io - Optional `stdout(text)` / `stderr(text)` callbacks, also
+   *             exposed to Command Actions and Extensions
+   */
+  run<const Path extends CommandPath<Tree>>(this: {
+    readonly _types: {
+      readonly caps: "app";
+    };
+  }, path: Path & KnownCommandPath<Path, Tree>, ...args: RunArguments<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>>): Promise<RunOutcome<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>["result"]>>;
+  run<const Path extends CommandPath<Tree>, const Input>(this: {
+    readonly _types: {
+      readonly caps: "app";
+    };
+  }, path: Path & KnownCommandPath<Path, Tree>, input: Input, ...validation: [Input] extends [CompatibleRunInput<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, NoInfer<Path>>, Input>] ? readonly [io?: Partial<InvocationIO>] : readonly [invalidInput: never]): Promise<RunOutcome<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>["result"]>>;
+  /**
+   * Bind a typed command path into a reusable {@link CommandHandle}.
+   *
+   * Validates the path eagerly against the prepared command tree, so an
+   * unknown path throws `COMMAND_NOT_FOUND` here rather than on the first
+   * `handle.run()`. The handle is bound to this builder's tree; commands added
+   * afterwards belong to the new builder returned by `.add()`.
+   *
+   * @param path - Typed path to the command to bind (`[]` selects the root)
+   * @throws {CrustError} COMMAND_NOT_FOUND when the path does not name a command
+   */
+  at<const Path extends CommandPath<Tree>>(this: {
+    readonly _types: {
+      readonly caps: "app";
+    };
+  }, path: Path & KnownCommandPath<Path, Tree>): CommandHandle<CommandShapeAt<CommandShape<A, Flags, Tree, Result>, Path>>;
+  /**
+   * Parse `process.argv`, resolve subcommands, run Extension hooks, and
+   * execute the matched Command Action.
+   *
+   * This is the terminal CLI boundary — call it on the root builder. It
+   * renders a failure once (through Extension `onError` hooks, ending in
+   * Core's default renderer), sets `process.exitCode` (`1`, or
+   * `130` for an `AbortError` cancellation), and resolves to the exit code.
+   *
+   * @param options - Optional overrides (e.g. custom `argv` and captured
+   *                   `io` for in-process testing of exit codes and
+   *                   rendered failures)
+   * @returns The terminal exit code (`0`, `1`, or `130` for cancellation)
+   */
+  execute(this: {
+    readonly _types: {
+      readonly caps: "app";
+    };
+  }, options?: {
+    argv?: string[];
+    io?: Partial<InvocationIO>;
+  }): Promise<number>;
+}
+//#endregion
+//#region src/errors.d.ts
+/** A value thrown by user code crossing a Core error boundary. */
+type CaughtError = unknown;
+/** Details for a subcommand token that could not be resolved. */
+interface CommandNotFoundErrorDetails {
+  /** Unrecognized subcommand token. */
+  input: string;
+  /** Canonical names of visible available child commands. */
+  available: string[];
+  /** Canonical path to the command whose child could not be resolved. */
+  commandPath: string[];
+  /** Readonly, serializable snapshot of the parent command. */
+  parentCommand: CommandSnapshot;
+}
+/** Aggregated Standard Schema and required-value validation failures. */
+interface ValidationErrorDetails {
+  /** Issues normalized under `args.<name>` or `flags.<name>`. */
+  issues: readonly {
+    readonly message: string;
+    readonly path: string;
+  }[];
+}
+/** Details for argv syntax or built-in value parsing failures. */
+interface ParseErrorDetails {
+  readonly flag?: string;
+  readonly argument?: string;
+  /** Retained for compatibility; Core no longer populates this field. */
+  readonly value?: string;
+  readonly reason?: string;
+}
+/** Details for runtime recipe, Extension, Context, and documentation failures. */
+interface DefinitionErrorDetails {
+  readonly subject?: "command" | "context" | "extension" | "flag" | "argument";
+  readonly name?: string;
+  readonly reason?: string;
+}
+interface CrustErrorDetailsMap {
+  DEFINITION: DefinitionErrorDetails | undefined;
+  VALIDATION: ValidationErrorDetails | undefined;
+  PARSE: ParseErrorDetails | undefined;
+  COMMAND_NOT_FOUND: CommandNotFoundErrorDetails;
+}
+/**
+ * All possible error codes emitted by Crust.
+ *
+ * - `DEFINITION` — Runtime recipe, Extension, Context, or documentation definition failure
+ * - `VALIDATION` — Missing required arguments or flags
+ * - `PARSE` — Argv parsing failures (unknown flags, type coercion)
+ * - `COMMAND_NOT_FOUND` — Unrecognised subcommand at the current level
+ *
+ * @example
+ * ```ts
+ * const outcome = await app.run(path, input);
+ * if (outcome.status === "failed") {
+ *   const err = outcome.error;
+ *   if (err instanceof CrustError) {
+ *     switch (err.code) {
+ *       case "VALIDATION":
+ *         console.error(err.message);
+ *         showHelp(cmd);
+ *         break;
+ *       case "PARSE":
+ *         console.error(err.message);
+ *         break;
+ *     }
+ *   }
+ * }
+ * ```
+ */
+type CrustErrorCode = keyof CrustErrorDetailsMap;
+type CrustErrorDetails<C extends CrustErrorCode> = CrustErrorDetailsMap[C];
+interface CrustErrorJson<C extends CrustErrorCode> {
+  code: C;
+  message: string;
+  details: CrustErrorDetails<C>;
+}
+/**
+ * A typed error for runtime recipe, Extension, Context, documentation, argv, and validation failures.
+ *
+ * Every `CrustError` carries a {@link CrustErrorCode} that identifies the specific
+ * failure, enabling programmatic error handling without fragile message parsing.
+ *
+ * @example
+ * ```ts
+ * import { CrustError } from "@crustjs/core";
+ *
+ * const outcome = await app.run(["deploy"], { args: { target: "prod" } });
+ * if (outcome.status === "failed") {
+ *   const err = outcome.error;
+ *   if (err instanceof CrustError) {
+ *     console.error(`[${err.code}] ${err.message}`);
+ *   }
+ * }
+ * ```
+ */
+declare class CrustError<C extends CrustErrorCode = CrustErrorCode> extends Error {
+  /** Machine-readable error code for programmatic handling */
+  readonly code: C;
+  /** Structured payload for programmatic handling */
+  readonly details: CrustErrorDetails<C>;
+  /** Optional wrapped original error/value */
+  override cause?: unknown;
+  constructor(code: C, message: string, ...details: undefined extends CrustErrorDetails<C> ? [] | [CrustErrorDetails<C>] : [CrustErrorDetails<C>]);
+  is<T extends CrustErrorCode>(code: T): this is CrustError<T>;
+  withCause(cause: unknown): this;
+  toJSON(): CrustErrorJson<C>;
+}
+//#endregion
+//#region src/api/extension.d.ts
+declare const finishedBrand: unique symbol;
+/** Opaque token returned by {@link ExtensionContext.finish} to end an invocation successfully. */
+interface Finished {
+  readonly [finishedBrand]: true;
+}
+type InvocationOutcome = {
+  readonly status: "completed";
+} | {
+  readonly status: "finished";
+  readonly by: ExtensionId;
+} | {
+  readonly status: "failed";
+  readonly error: unknown;
+  readonly by?: ExtensionId;
+};
+/** Authored root metadata fields an Extension may require. */
+type RootMetaKey = keyof RootCommandMeta;
+type RootCommandSnapshot<K extends RootMetaKey> = CommandSnapshot & {
+  readonly meta: Readonly<Required<Pick<CommandMeta, K>>>;
+};
+/** One file a build hook produces; `path` is POSIX-relative to the build output directory. */
+interface BuildFile {
+  readonly path: string;
+  readonly content: string | Uint8Array;
+}
+/** Files returned by a build hook; build tooling writes them into the build output directory. */
+type BuildArtifacts = readonly BuildFile[];
+/** Files written for each Extension build hook, in hook execution order. */
+interface BuildReport {
+  readonly extensions: readonly {
+    readonly id: ExtensionId;
+    readonly files: readonly string[];
+  }[];
+}
+/**
+ * Build-time context passed to an Extension's artifact generator. It deliberately
+ * carries no output directory: build tooling owns that tree, so every shipped file
+ * is a returned {@link BuildFile} and the {@link BuildReport} is exact.
+ */
+interface ExtensionBuildContext<MetaKeys extends RootMetaKey = never> {
+  /**
+   * Frozen snapshot prepared before this hook starts. It does not include this hook's own
+   * outputs; later-registered hooks receive refreshed snapshots.
+   */
+  readonly snapshot: RootCommandSnapshot<MetaKeys>;
+}
+/**
+ * Readonly invocation view passed to Extension hooks.
+ *
+ * Commands cross this boundary as readonly, serializable
+ * {@link CommandSnapshot}s — never as internal command nodes.
+ *
+ * Examples below assume the `tool deploy api --trace -- --dry-run` invocation.
+ */
+interface ExtensionContext<Defs extends readonly NamedExtensionFlagDef[] = [], Deps extends ContextMap = {}, MetaKeys extends RootMetaKey = never> extends Readonly<InvocationIO> {
+  /**
+   * Complete argv passed to the application, including routed command names.
+   * For typed `run()` this is the command path only; structured values are never rendered as argv.
+   *
+   * @example `["deploy", "api", "--trace", "--", "--dry-run"]`
+   */
+  readonly argv: readonly string[];
+  /**
+   * Snapshot of the application root, including Extension-contributed flags/commands.
+   *
+   * @example
+   * ```ts
+   * ctx.rootCommand.meta.name; // "tool"
+   * Object.keys(ctx.rootCommand.subCommands); // ["deploy"]
+   * ```
+   */
+  readonly rootCommand: RootCommandSnapshot<MetaKeys>;
+  /**
+   * Snapshot of the resolved command (the root when routing failed).
+   *
+   * @example
+   * ```ts
+   * ctx.command.meta.name; // "deploy"
+   * ctx.command.args; // [{ name: "target", type: "string", required: true }]
+   * ```
+   */
+  readonly command: CommandSnapshot;
+  /**
+   * Canonical names from the application root through the resolved command.
+   *
+   * @example `["tool", "deploy"]`
+   */
+  readonly commandPath: readonly string[];
+  /**
+   * Bound positional values for the resolved command, before validation: parsed from
+   * argv tokens for `execute()`, taken as-is from the structured input for typed `run()`
+   * (URL/JSON values keep their identity).
+   *
+   * @example `{ target: "api" }`
+   */
+  readonly args: Readonly<Record<string, ParsedArgValue>>;
+  /**
+   * Bound own flags plus unknown flags from the resolved command, before validation;
+   * parsed from argv tokens for `execute()`, taken as-is from the structured input for typed `run()`.
+   *
+   * @example `{ trace: true }`
+   */
+  readonly flags: Readonly<InferExtensionFlags<Defs> & Record<string, ParsedFlagValue>>;
+  /**
+   * Positional values that appeared after the `--` separator, or the `raw` array passed to typed `run()`.
+   *
+   * @example `["--dry-run"]`
+   */
+  readonly rawArgs: readonly string[];
+  /** Declared Contexts, constructed lazily on first property access. */
+  readonly ctx: ContextBag<Deps>;
+  /**
+   * End the invocation successfully before validation, Context construction, and the action.
+   *
+   * @example
+   * ```ts
+   * preRun(ctx) {
+   *   if (ctx.flags.help === true) return ctx.finish();
+   * }
+   * ```
+   */
+  readonly finish: () => Finished;
+}
+interface ExtensionHooks<Defs extends readonly NamedExtensionFlagDef[] = [], Deps extends ContextMap = {}, MetaKeys extends RootMetaKey = never> {
+  /**
+   * Runs after routing and input binding (argv parsing for `execute()`, structured
+   * binding for typed `run()`), before validation, in `.extend()` order.
+   * Return `ctx.finish()` to end the invocation successfully; later pre-run hooks,
+   * validation, schemas, Contexts, and the Command Action do not run.
+   */
+  readonly preRun?: (ctx: ExtensionContext<Defs, Deps, MetaKeys>) => Awaitable<void | Finished>;
+  /**
+   * Runs after the invocation settles, in reverse `.extend()` order. This is the
+   * `finally` slot for cleanup and post-run side effects.
+   */
+  readonly postRun?: (ctx: ExtensionContext<Defs, Deps, MetaKeys>, outcome: InvocationOutcome) => Awaitable<void>;
+  /**
+   * Renders a failure in `execute()` only. Return true when rendered to stop the
+   * chain; falsy values delegate to the next Extension and then Core's renderer.
+   * A hook that throws ends the chain: remaining hooks are skipped and Core's
+   * default renderer reports the original failure.
+   *
+   * Receives the base context: routing or syntax-parse failures render with a
+   * fallback context whose `flags` are empty, so owned-flag inference would lie here.
+   */
+  readonly onError?: (error: CaughtError, ctx: ExtensionContext<[], Deps, MetaKeys>) => Awaitable<boolean | void>;
+}
+/**
+ * A flag owned by an Extension. `recursive` (default `true`) contributes the
+ * flag to every command in the application; set `false` for a root-only flag.
+ */
+type ExtensionFlagDef = FlagDef & {
+  readonly recursive?: boolean;
+};
+/** A named flag definition accepted by {@link defineExtension}. */
+type NamedExtensionFlagDef = NamedFlagDef & {
+  readonly recursive?: boolean;
+};
+type SchemaToken<F> = F extends {
+  type: "boolean";
+} ? boolean : string;
+type InferPreSchemaExtensionFlag<F extends ExtensionFlagDef> = F extends {
+  schema: unknown;
+} ? (F extends {
+  multiple: true;
+} ? never : SchemaToken<F>) | ("multiple" extends keyof F ? true extends F["multiple"] ? SchemaToken<F>[] : never : never) | undefined : F extends {
+  required: true;
+} ? F extends {
+  default: unknown;
+} ? InferFlags<{
+  value: F;
+}>["value"] : InferFlags<{
+  value: F;
+}>["value"] | undefined : InferFlags<{
+  value: F;
+}>["value"];
+type InferExtensionFlag<F> = F extends ExtensionFlagDef ? InferPreSchemaExtensionFlag<F> | ("recursive" extends keyof F ? (false extends F["recursive"] ? undefined : never) : never) : never;
+/** Infer pre-validation hook values; uncertain collections claim no typed ownership. */
+type InferExtensionFlags<Defs extends readonly NamedExtensionFlagDef[]> = IsStaticTuple<Defs> extends true ? HasClosedNames<Defs> extends true ? { [K in keyof NamedFlagsRecord<Defs>]: InferExtensionFlag<NamedFlagsRecord<Defs>[K]>; } : Record<string, ParsedFlagValue> : Record<string, ParsedFlagValue>;
+/** A documentation section an Extension contributes to one command path. */
+type ExtensionSectionContribution = RuntimeCommandSectionInput & {
+  readonly command: readonly string[];
+};
+type CommandDefinitionsDependencies<Commands extends readonly CommandDefinition<any, any, any, any>[]> = Commands extends readonly [infer H extends CommandDefinition<any, any, any, any>, ...infer T extends readonly CommandDefinition<any, any, any, any>[]] ? ([H] extends [never] ? {} : DeclaredDepsOf<H>) & CommandDefinitionsDependencies<T> : Commands extends readonly [] ? {} : Record<string, ContextValue>;
+interface ExtensionConfig<Defs extends readonly NamedExtensionFlagDef[] = readonly NamedExtensionFlagDef[], Uses extends readonly AnyContextFactory[] = readonly AnyContextFactory[], Provides extends readonly AnyContextInstance[] = readonly AnyContextInstance[], Commands extends readonly CommandDefinition<any, any, any, any>[] = readonly CommandDefinition<any, any, any, any>[], MetaKeys extends RootMetaKey = never> {
+  readonly flags?: Defs;
+  readonly commands?: Commands;
+  readonly uses?: Uses;
+  readonly provides?: Provides;
+  readonly sections?: (snapshot: RootCommandSnapshot<MetaKeys>) => readonly ExtensionSectionContribution[];
+  readonly build?: (ctx: ExtensionBuildContext<MetaKeys>) => Awaitable<BuildArtifacts>;
+  readonly hooks?: ExtensionHooks<Defs, ContextDependencies<Uses>, MetaKeys>;
+}
+type ValidateExtensionConfig<Defs extends readonly NamedExtensionFlagDef[], Provides extends readonly AnyContextInstance[], Commands extends readonly CommandDefinition<any, any, any, any>[], Uses extends readonly AnyContextFactory[]> = {
+  readonly uses?: Uses;
+  readonly commands?: ValidateCommandDefinitions<Commands>;
+  readonly flags?: ValidateLocalFlagDefs<Defs, ProvidedContextSpellings<Provides>>;
+  readonly provides?: KnownContextInstances<Provides> & ProvideChecks<never, Provides>;
+};
+declare const extensionHookProof: unique symbol;
+interface Extension<Deps extends ContextMap = ContextMap, Provides extends readonly AnyContextInstance[] = readonly AnyContextInstance[], FlagDefs extends readonly NamedExtensionFlagDef[] = readonly NamedExtensionFlagDef[], Commands extends readonly CommandDefinition<any, any, any, any>[] = readonly CommandDefinition<any, any, any, any>[], out MetaKeys extends RootMetaKey = never, HookDeps extends ContextMap = Deps> extends Defining<Extension<Deps, Provides, FlagDefs, Commands, MetaKeys, HookDeps>> {
+  /** @internal Hook demands are distinct from command/provider attachment dependencies. */
+  readonly _hookDeps?: HookDeps;
+  readonly [extensionHookProof]?: (deps: HookDeps) => void;
+  readonly id: ExtensionId;
+  readonly flags?: Readonly<Record<string, ExtensionFlagDef>>;
+  /** @internal — phantom carrying declared flag literals for extend-time collision checks */
+  readonly _flagDefs?: FlagDefs;
+  readonly commands?: Commands;
+  readonly uses: readonly AnyContextFactory[];
+  readonly provides?: Provides;
+  readonly sections?: (snapshot: RootCommandSnapshot<MetaKeys>) => readonly ExtensionSectionContribution[];
+  readonly build?: (ctx: ExtensionBuildContext<MetaKeys>) => Awaitable<BuildArtifacts>;
+  readonly hooks?: ExtensionHooks<any, Deps, MetaKeys>;
+  readonly _deps?: Deps;
+}
+/** @internal Broad Extension constraint; contravariance requires the full metadata key set. */
+type AnyExtension = Extension<any, any, any, any, RootMetaKey>;
+type ExtensionProvidesOutput<E> = DefiningOf<E> extends Extension<any, infer Provides, any, any, RootMetaKey> ? ContextsOutput<Provides> : {};
+type ExtensionsProvidesOutput<Es extends readonly AnyExtension[]> = Es extends readonly [infer H, ...infer T extends readonly AnyExtension[]] ? MergeProviders<ExtensionProvidesOutput<H>, ExtensionsProvidesOutput<T>> : Es extends readonly [] ? {} : Es[number] extends Extension<any, infer P, any, any, RootMetaKey> ? P[number] extends never ? {} : Record<string, ContextValue> : {};
+/**
+ * A callable Extension constructor whose identity is also a section consumer.
+ * Contribution parameters default to closed sets. Use `ContextMap`,
+ * `readonly AnyContextInstance[]`, `readonly NamedExtensionFlagDef[]`, or
+ * `readonly CommandDefinition<any, any, any, any>[]` to keep a namespace open.
+ */
+type ExtensionFactory<Args extends readonly unknown[] = [], Deps extends ContextMap = {}, Provides extends readonly AnyContextInstance[] = [], Defs extends readonly NamedExtensionFlagDef[] = [], Commands extends readonly CommandDefinition<any, any, any, any>[] = [], MetaKeys extends RootMetaKey = never, HookDeps extends ContextMap = Deps> = ((...args: Args) => Extension<Deps, Provides, Defs, Commands, MetaKeys, HookDeps>) & {
+  readonly id: ExtensionId;
+};
+/** Curried Extension definer: explicit metadata keys leave all other types inferred. */
+interface DefineExtensionWith<MetaKeys extends RootMetaKey> {
+  <Args extends readonly unknown[], const Defs extends readonly NamedExtensionFlagDef[] = [], const Uses extends readonly AnyContextFactory[] = [], const Provides extends readonly AnyContextInstance[] = [], const Commands extends readonly CommandDefinition<any, any, any, any>[] = []>(id: ExtensionId, factory: (...args: Args) => ExtensionConfig<Defs, Uses, Provides, Commands, MetaKeys> & ValidateExtensionConfig<Defs, Provides, Commands, Uses>): ExtensionFactory<Args, ContextDependencies<Uses> & ContextsDependencies<Provides> & CommandDefinitionsDependencies<Commands>, Provides, Defs, Commands, MetaKeys, ContextDependencies<Uses>>;
+  <const Defs extends readonly NamedExtensionFlagDef[] = [], const Uses extends readonly AnyContextFactory[] = [], const Provides extends readonly AnyContextInstance[] = [], const Commands extends readonly CommandDefinition<any, any, any, any>[] = []>(id: ExtensionId, config?: ExtensionConfig<Defs, Uses, Provides, Commands, MetaKeys> & ValidateExtensionConfig<Defs, Provides, Commands, Uses>): Extension<ContextDependencies<Uses> & ContextsDependencies<Provides> & CommandDefinitionsDependencies<Commands>, Provides, Defs, Commands, MetaKeys, ContextDependencies<Uses>>;
+}
+/**
+ * Define an Extension, or a factory that builds one from config on each call.
+ *
+ * Extensions apply to the whole application and own the flags and commands
+ * they contribute. Factories expose the same identity for section audiences.
+ * `defineExtension<"version">()(id, configOrFactory)` declares required root
+ * metadata keys without preventing inference of flags, Contexts, or commands.
+ */
+declare function defineExtension<MetaKeys extends RootMetaKey = never>(): DefineExtensionWith<MetaKeys>;
+declare function defineExtension<Args extends readonly unknown[], const Defs extends readonly NamedExtensionFlagDef[] = [], const Uses extends readonly AnyContextFactory[] = [], const Provides extends readonly AnyContextInstance[] = [], const Commands extends readonly CommandDefinition<any, any, any, any>[] = []>(id: ExtensionId, factory: (...args: Args) => ExtensionConfig<Defs, Uses, Provides, Commands> & ValidateExtensionConfig<Defs, Provides, Commands, Uses>): ExtensionFactory<Args, ContextDependencies<Uses> & ContextsDependencies<Provides> & CommandDefinitionsDependencies<Commands>, Provides, Defs, Commands, never, ContextDependencies<Uses>>;
+declare function defineExtension<const Defs extends readonly NamedExtensionFlagDef[] = [], const Uses extends readonly AnyContextFactory[] = [], const Provides extends readonly AnyContextInstance[] = [], const Commands extends readonly CommandDefinition<any, any, any, any>[] = []>(id: ExtensionId, config?: ExtensionConfig<Defs, Uses, Provides, Commands> & ValidateExtensionConfig<Defs, Provides, Commands, Uses>): Extension<ContextDependencies<Uses> & ContextsDependencies<Provides> & CommandDefinitionsDependencies<Commands>, Provides, Defs, Commands, never, ContextDependencies<Uses>>;
+//#endregion
+//#region src/parsing/spellings.d.ts
+interface FlagSpelling {
+  canonicalName: string;
+  def: FlagDef;
+  kind: "canonical" | "short" | "alias";
+  negatable: boolean;
+}
+//#endregion
+//#region src/command/node.d.ts
+/** Runtime-erased Command Action; typed builders and run() own the specific result contract. */
+type CommandAction = (ctx: CrustCommandContext) => unknown;
+interface CommandContext {
+  instance: AnyContextInstance;
+  extensionId?: ExtensionId;
+}
+/**
+ * Internal representation of a single node in the command tree.
+ *
+ * Built by the `Crust` builder class; not part of the public API.
+ * Each node carries its own local flags, the pre-computed effective
+ * (Context-owned + local merged) flags, positional args, subcommands,
+ * extensions, and the Command Action.
+ */
+interface CommandNode {
+  /** Command metadata (name, description, usage) */
+  meta: CommandMeta;
+  /** Flags defined directly on this command via `.flags()` */
+  localFlags: FlagsDef;
+  /** Accumulated flags owned by Contexts provided on this command path */
+  ownedFlags: FlagsDef;
+  /** Context-owned and local flags merged for parsing */
+  effectiveFlags: FlagsDef;
+  /** Cached canonical/short/alias table for the effective flags. */
+  flagSpellings: Map<string, FlagSpelling>;
+  /** Positional argument definitions */
+  args: ArgsDef;
+  /** Named subcommands keyed by name */
+  subCommands: Record<string, CommandNode>;
+  /** Contexts available to this command in provide order (construction order is pull-driven). */
+  contexts: CommandContext[];
+  /** Declared command demands; validated when recipes are materialized. */
+  demands: readonly AnyContextFactory[];
+  /** Extensions registered via `.extend()` (root builder only) */
+  extensions: Extension[];
+  /** The Command Action */
+  run?: CommandAction;
+}
+//#endregion
+//#region src/parsing/parser.d.ts
+type RunInputValue = URL | JsonValue | readonly RunInputValue[];
+interface RunInputPayload {
+  readonly args?: Readonly<Record<string, RunInputValue | undefined>>;
+  readonly flags?: Readonly<Record<string, RunInputValue | undefined>>;
+  readonly raw?: readonly string[];
+}
+//#endregion
+//#region src/types.d.ts
+/** Injectable output callbacks threaded through one invocation. */
+interface InvocationIO {
+  /** Write a line of standard output (injectable text callback) */
+  stdout: (text: string) => void;
+  /** Write a line of diagnostic output (injectable text callback) */
+  stderr: (text: string) => void;
+}
+/**
+ * Supported type literals for args and flags.
+ *
+ * Extends `BaseValueType` (`"string" | "number" | "boolean"`) with three
+ * formatted built-ins:
+ *
+ * - `"url"`  — the raw value is parsed via `new URL()` into a {@link URL}
+ * - `"path"` — the raw value is expanded (`~`) and resolved against
+ *              `process.cwd()` into an absolute `string`
+ * - `"json"` — the raw value is parsed via `JSON.parse()` into `unknown`
+ */
+type ValueType = BaseValueType | "url" | "path" | "json";
+/** Resolve a {@link ValueType} literal to its runtime TypeScript type. */
+type Resolve<T extends ValueType> = {
+  string: string;
+  number: number;
+  boolean: boolean;
+  url: URL;
+  path: string;
+  json: unknown;
+}[T];
+/**
+ * Resolve the inferred runtime type for a flag/arg definition.
+ *
+ * When the def declares a `parse` escape hatch (only allowed on `"string"`
+ * variants), the inferred type is `ReturnType<typeof parse>`. Optional parsers
+ * also retain the unparsed output branch. String defs
+ * with a literal `choices` tuple narrow to the union of those literals.
+ * Otherwise it delegates to {@link Resolve} on the declared `type`.
+ */
+type ResolveBaseType<F> = "parse" extends keyof F ? F["parse"] extends (infer Parse) ? Parse extends ((raw: string) => infer R) ? R : ResolveUnparsedType<F> : never : ResolveUnparsedType<F>;
+type ResolveUnparsedType<F> = F extends {
+  type: "string";
+  choices: readonly (infer C extends string)[];
+} ? C : F extends {
+  type: infer T extends ValueType;
+} ? Resolve<T> : never;
+/** Shared fields present on every positional argument definition */
+interface ArgDefBase {
+  /** The argument name (used as the key in the parsed result and in help text) */
+  name: string;
+  /** Human-readable description for help text */
+  description?: string;
+  /**
+   * When `true`, the parser throws if the argument is not provided.
+   *
+   * For variadic args without a default, the validated output is a nonempty tuple.
+   */
+  required?: true;
+  /** Not supported with core value options — see {@link SchemaArgDef} */
+  schema?: never;
+  /**
+   * When `true`, collects all remaining positional values into an array.
+   *
+   * The validated output is always an array, never `undefined`.
+   * Required core variadics without defaults infer `[T, ...T[]]` after
+   * required validation; other core variadics infer `T[]`.
+   */
+  variadic?: true;
+}
+/** A positional argument whose value is a string */
+interface StringArgDef<ParseOutput = unknown> extends ArgDefBase {
+  type: "string";
+  /** Default string value when the argument is not provided */
+  default?: string;
+  /**
+   * Static enum of valid values for this argument.
+   *
+   * Checked for argv and structured invocation input before `parse` runs.
+   * Typed input also proves membership statically. Passing a value outside
+   * `choices` throws `CrustError("PARSE", …)` before any `parse` transform
+   * is applied. Also consumed by shell-completion extensions
+   * (e.g. `@crustjs/extensions`) to emit value candidates.
+   *
+   * Only available on string-typed args; not supported on number/boolean.
+   *
+   * @example
+   * { name: "target", type: "string", choices: ["browser", "bun", "node"] }
+   */
+  choices?: readonly string[];
+  /**
+   * Custom synchronous parser for the raw argv string. Runs after `choices`
+   * validation and per element for variadic args. Its return type becomes the
+   * argument's inferred runtime type; declared defaults are parsed too.
+   *
+   * @example
+   * { name: "port", type: "string", parse: (s) => Number(s) }
+   */
+  parse?: (raw: string) => ParseOutput;
+}
+/** A positional argument whose value is a number */
+interface NumberArgDef extends ArgDefBase {
+  type: "number";
+  choices?: never;
+  /** Default number value when the argument is not provided */
+  default?: number;
+  /** Not supported on number args — use `type: "string"` with `parse`. */
+  parse?: never;
+}
+/** A positional argument whose value is a boolean */
+interface BooleanArgDef extends ArgDefBase {
+  type: "boolean";
+  choices?: never;
+  /** Default boolean value when the argument is not provided */
+  default?: boolean;
+  /** Not supported on boolean args — use `type: "string"` with `parse`. */
+  parse?: never;
+}
+/** A positional argument whose value is a {@link URL} */
+interface UrlArgDef extends ArgDefBase {
+  type: "url";
+  choices?: never;
+  /** Default URL value when the argument is not provided */
+  default?: URL;
+  /** Not supported on url args — use `type: "string"` with `parse`. */
+  parse?: never;
+}
+/** A positional argument whose value is an absolute filesystem path */
+interface PathArgDef extends ArgDefBase {
+  type: "path";
+  choices?: never;
+  /** Default path string when the argument is not provided */
+  default?: string;
+  /** Not supported on path args — use `type: "string"` with `parse`. */
+  parse?: never;
+}
+/** A positional argument whose value is JSON parsed to `unknown` */
+interface JsonArgDef extends ArgDefBase {
+  type: "json";
+  choices?: never;
+  /** Default parsed JSON value when the argument is not provided */
+  default?: unknown;
+  /** Not supported on json args — use `type: "string"` with `parse`. */
+  parse?: never;
+}
+/**
+ * A positional argument validated by a Standard Schema (exclusive mode).
+ *
+ * The schema receives the raw string token (`string | undefined` when the
+ * argument is absent; `string[]` for variadic args) and exclusively owns
+ * coercion, defaults, requiredness, choices, and validation. Its inferred
+ * output type reaches the Command Action. Core value options (`type`,
+ * `default`, `required`, `choices`, `parse`) cannot be mixed in.
+ */
+interface SchemaArgDef {
+  /** The argument name (used as the key in the parsed result and in help text) */
+  name: string;
+  /** Human-readable description for help text */
+  description?: string;
+  /** When `true`, collects all remaining raw tokens into a `string[]` for the schema */
+  variadic?: true;
+  /** Standard Schema that owns coercion, defaults, requiredness, and validation */
+  schema: StandardSchema;
+  type?: never;
+  required?: never;
+  default?: never;
+  choices?: never;
+  parse?: never;
+}
+/**
+ * Defines a single positional argument for a CLI command.
+ *
+ * Discriminated by `type` for type-safe `default` values. Boolean toggle
+ * fields (`required`, `variadic`) only accept `true`.
+ *
+ * @example
+ * ```ts
+ * const args = [
+ *   { name: "port", type: "number", description: "Port number", default: 3000 },
+ *   { name: "name", type: "string", required: true },
+ *   { name: "files", type: "string", variadic: true },
+ * ] as const satisfies ArgsDef;
+ * ```
+ */
+type ArgDef = StringArgDef | NumberArgDef | BooleanArgDef | UrlArgDef | PathArgDef | JsonArgDef | SchemaArgDef;
+/** Ordered tuple of positional argument definitions */
+type ArgsDef = readonly ArgDef[];
+/** Shared fields present on every flag definition */
+interface FlagDefBase {
+  /** Human-readable description for help text */
+  description?: string;
+  /** Single-character short alias (e.g. `"v"` → `-v`) */
+  short?: string;
+  /** Additional aliases (e.g. `["out"]` → `--out`); one-character aliases also accept one dash. */
+  aliases?: readonly string[];
+  /** When `true`, the parser throws if the flag is not provided */
+  required?: true;
+  /** Not supported with core value options — see {@link SchemaStringFlagDef} */
+  schema?: never;
+}
+/** Base for single-value flags — `multiple` must be omitted */
+interface SingleFlagBase extends FlagDefBase {
+  /** Must be omitted for single-value flags — set to `true` for multi-value */
+  multiple?: never;
+}
+/** Base for multi-value flags — `multiple` is required as `true` */
+interface MultiFlagBase extends FlagDefBase {
+  /** Collect repeated values into an array */
+  multiple: true;
+}
+type StringFlagFields<Default, ParseOutput> = {
+  /** Default string value, or string array for a multi-value flag. */
+  default?: Default;
+  /**
+   * Static enum of valid values for this flag.
+   *
+   * Checked for argv and structured invocation input before `parse` runs.
+   * Typed input also proves membership statically. Passing a value outside
+   * `choices` throws `CrustError("PARSE", …)` before any `parse` transform
+   * is applied. Also consumed by shell-completion extensions.
+   */
+  choices?: readonly string[];
+  /**
+   * Custom synchronous parser for the raw argv string. For multi-value
+   * flags it runs once per occurrence. The return type becomes the flag's
+   * inferred runtime value type.
+   */
+  parse?: (raw: string) => ParseOutput;
+  noNegate?: never;
+};
+type TypedFlagFields<T extends Exclude<ValueType, "string">, Default> = {
+  /** Default value, or value array for a multi-value flag. */
+  default?: Default;
+  choices?: never;
+  /** Only boolean flags support generated-negation opt-out. */
+  noNegate?: T extends "boolean" ? true : never;
+  /** Use `type: "string"` with `parse` for custom parsing. */
+  parse?: never;
+};
+type CoreFlagFields<T extends ValueType, Default, ParseOutput> = T extends "string" ? StringFlagFields<Default, ParseOutput> : T extends Exclude<ValueType, "string"> ? TypedFlagFields<T, Default> : never;
+/** A single-value core flag for the declared value type. */
+type TypedFlagDef<T extends ValueType, ParseOutput = unknown> = SingleFlagBase & {
+  type: T;
+} & CoreFlagFields<T, Resolve<T>, ParseOutput>;
+/** A repeatable core flag for the declared value type. */
+type TypedMultiFlagDef<T extends ValueType, ParseOutput = unknown> = MultiFlagBase & {
+  type: T;
+} & CoreFlagFields<T, readonly Resolve<T>[], ParseOutput>;
+/** Shared fields for schema-backed flags (exclusive mode) */
+interface SchemaFlagBase extends Omit<FlagDefBase, "schema" | "required"> {
+  /** Standard Schema that owns coercion, defaults, requiredness, and validation */
+  schema: StandardSchema;
+  required?: never;
+  default?: never;
+  choices?: never;
+  parse?: never;
+}
+/**
+ * A schema-backed flag that consumes a value token (`--flag value`).
+ * The schema receives the raw string (`string | undefined`, or
+ * `string[] | undefined` with `multiple: true`) and exclusively owns coercion,
+ * defaults, requiredness, and validation. `type` declares token consumption only.
+ */
+interface SchemaStringFlagDef extends SchemaFlagBase {
+  type: "string";
+  /** When `true`, the schema receives `string[]` when present, or `undefined` when omitted. */
+  multiple?: true;
+  noNegate?: never;
+}
+/**
+ * A schema-backed toggle flag (no value token). The schema receives the raw
+ * `boolean | undefined` (or `boolean[] | undefined` with `multiple: true`).
+ */
+interface SchemaBooleanFlagDef extends SchemaFlagBase {
+  type: "boolean";
+  /** When `true`, the schema receives `boolean[]` when present, or `undefined` when omitted. */
+  multiple?: true;
+  /** When `true`, reject `--no-{name}` (and negated aliases) at parse time and hide the generated help label */
+  noNegate?: true;
+}
+/**
+ * Defines a single named flag for a CLI command.
+ *
+ * Discriminated by `type` and `multiple` for type-safe `default` values.
+ * Boolean toggle fields (`required`, `multiple`) only accept `true`.
+ *
+ * @example
+ * ```ts
+ * const flags = {
+ *   verbose: { type: "boolean", description: "Enable verbose logging", short: "v" },
+ *   port: { type: "number", description: "Port number", default: 3000 },
+ *   files: { type: "string", multiple: true, default: ["index.ts"] },
+ * } satisfies FlagsDef;
+ * ```
+ */
+type FlagDef = { [T in ValueType]: TypedFlagDef<T> | TypedMultiFlagDef<T>; }[ValueType] | SchemaStringFlagDef | SchemaBooleanFlagDef;
+/** Record mapping flag names to their definitions */
+type FlagsDef = Record<string, FlagDef>;
+/**
+ * A flag definition that carries its own name — the authoring shape
+ * produced by `defineFlag(name, def)` or written inline as an object
+ * literal (`{ name: "dry-run", type: "boolean" }`) and attached with the
+ * variadic `.flags(...defs)`.
+ */
+type NamedFlagDef = FlagDef & {
+  readonly name: string;
+};
+/**
+ * Derive the internal `FlagsDef` record from a tuple of named flag
+ * definitions: each definition's `name` literal becomes a key, its value
+ * the definition without `name`.
+ *
+ * The `extends infer R extends FlagsDef` step defers evaluation so the
+ * result satisfies `FlagsDef` in generic positions.
+ */
+type FlagWithoutName<D> = D extends unknown ? Omit<D, "name"> : never;
+type NamedFlagsRecord<Defs extends readonly NamedFlagDef[]> = { [K in Defs[number]["name"]]: FlagWithoutName<Extract<Defs[number], {
+  name: K;
+}>>; } extends (infer R extends FlagsDef) ? R : never;
+/**
+ * Merges two flag sets as a flat intersection.
+ *
+ * Statically known shared keys are branded at compile time (`DuplicateNameBrand`,
+ * `ExistingFlagCollisionBrand`, `ProvideChecks`). A plain intersection stays
+ * flat in the checker — chained `.flags()`/`.provide()` calls cost constant
+ * instantiation depth, where per-call merge layers (mapped type or
+ * `Simplify<Omit & …>`) nested and hit TS2589 at ~47 / ~31 chained calls.
+ */
+type MergeFlags<Base extends FlagsDef, Override extends FlagsDef> = Base & Override;
+/**
+ * Infer the resolved type for a single ArgDef:
+ *
+ * - **variadic** → `[primitive, ...primitive[]]` when required without a default,
+ *   otherwise `primitive[]` (always an array, never `undefined`)
+ * - **required** or **has default** → `primitive` (non-optional)
+ * - otherwise → `primitive | undefined`
+ *
+ * Required core variadics without defaults resolve to nonempty tuples.
+ * Schema-backed and default-backed arguments retain their own output contracts.
+ */
+type InferArgValue<A extends ArgDef> = A extends {
+  schema: infer S extends StandardSchema;
+} ? InferOutput<S> : A extends {
+  variadic: true;
+} ? A extends {
+  required: true;
+  default?: never;
+} ? [ResolveBaseType<A>, ...ResolveBaseType<A>[]] : ResolveBaseType<A>[] : ("variadic" extends keyof A ? true extends A["variadic"] ? ResolveBaseType<A>[] : never : never) | (A extends {
+  required: true;
+} ? ResolveBaseType<A> : A extends {
+  default: infer Default;
+} ? undefined extends Default ? ResolveBaseType<A> | undefined : ResolveBaseType<A> : ResolveBaseType<A> | undefined);
+type DuplicateArgNames<A extends readonly ArgDef[], Seen extends string = never, Duplicates extends string = never> = A extends readonly [infer Head extends ArgDef, ...infer Tail extends readonly ArgDef[]] ? DuplicateArgNames<Tail, Seen | Head["name"], Duplicates | (Head["name"] & Seen)> : Duplicates;
+type InferDuplicateArgs<A extends readonly ArgDef[]> = A extends readonly [infer Head extends ArgDef, ...infer Tail extends readonly ArgDef[]] ? { [K in Head["name"]]: InferArgValue<Head>; } & InferDuplicateArgs<Tail> : {};
+/**
+ * Convert a literal ArgsDef tuple into resolved values keyed by argument name.
+ *
+ * Tuples with rest elements (`number extends A["length"]`) opt out to `{}`;
+ * the builder only produces fixed tuples. Unions of tuples distribute through
+ * `InferArgs`'s naked conditional, so each member is inferred separately.
+ */
+type InferArgsTuple<A extends readonly ArgDef[]> = number extends A["length"] ? {} : [DuplicateArgNames<A>] extends [never] ? { [D in A[number] as D["name"]]: InferArgValue<D>; } : InferDuplicateArgs<A>;
+/**
+ * Maps an ArgsDef tuple to resolved arg types keyed by each arg's `name`.
+ *
+ * @example
+ * ```ts
+ * type Result = InferArgs<readonly [
+ *   { name: "port"; type: "number"; default: 3000 },
+ *   { name: "name"; type: "string"; required: true },
+ *   { name: "files"; type: "string"; variadic: true },
+ * ]>;
+ * // Result = { port: number; name: string; files: string[] }
+ * ```
+ */
+type InferArgs<A> = A extends ArgsDef ? Simplify<InferArgsTuple<A>> : Record<string, never>;
+/**
+ * Infer the resolved type for a single FlagDef:
+ *
+ * - **multiple** → wraps the resolved type in an array
+ * - **required** or **has default** → `primitive` (non-optional)
+ * - otherwise → `primitive | undefined`
+ */
+type InferFlagValue<F extends FlagDef> = F extends {
+  schema: infer S extends StandardSchema;
+} ? InferOutput<S> : F extends {
+  multiple: true;
+} ? F extends {
+  required: true;
+} ? ResolveBaseType<F>[] : F extends {
+  default: readonly unknown[];
+} ? ResolveBaseType<F>[] : ResolveBaseType<F>[] | undefined : F extends {
+  required: true;
+} ? ResolveBaseType<F> : F extends {
+  default: infer Default;
+} ? undefined extends Default ? ResolveBaseType<F> | undefined : ResolveBaseType<F> : ResolveBaseType<F> | undefined;
+/**
+ * Maps a full FlagsDef record to resolved flag types.
+ *
+ * @example
+ * ```ts
+ * type Result = InferFlags<{
+ *   verbose: { type: "boolean" };
+ *   port: { type: "number", default: 3000 };
+ * }>;
+ * // Result = { verbose: boolean | undefined; port: number }
+ * ```
+ */
+type InferFlags<F> = F extends FlagsDef ? { [K in keyof F]: InferFlagValue<F[K]>; } : Record<string, never>;
+type InputBaseValue<D> = true extends IsUnion<D> | IsUnion<D[keyof D & "type"]> ? never : D extends {
+  type: "boolean";
+} ? "noNegate" extends keyof D ? true extends D["noNegate"] ? true : boolean : boolean : D extends {
+  schema: StandardSchema;
+} ? D extends {
+  type: "boolean";
+} ? boolean : string : D extends {
+  type: "json";
+} ? JsonValue : "choices" extends keyof D ? Exclude<D["choices"], undefined> extends (infer Choices extends readonly string[]) ? [Choices] extends [never] ? D extends {
+  type: infer T extends ValueType;
+} ? Resolve<T> : never : IsStaticTuple<Choices> extends true ? IsClosedName<Choices[number]> extends true ? Choices[number] : never : never : never : D extends {
+  parse: (raw: string) => infer _ParseOutput;
+} ? string : D extends {
+  type: infer T extends ValueType;
+} ? Resolve<T> : never;
+type InputArgValue<D extends ArgDef, Value = InputBaseValue<D>> = [Value] extends [never] ? never : D extends {
+  variadic: true;
+} ? RequiredArgNames<[D]> extends never ? Value[] : [Value, ...Value[]] : "variadic" extends keyof D ? true extends D["variadic"] ? never : Value : Value;
+type InputFlagValue<D, Value = InputBaseValue<D>> = [Value] extends [never] ? never : D extends {
+  multiple: true;
+} ? Value[] : "multiple" extends keyof D ? true extends D["multiple"] ? never : Value : Value;
+type RequiredArgNames<A extends ArgsDef> = A[number] extends (infer D) ? D extends {
+  name: infer N extends string;
+} ? "required" extends keyof D ? true extends D["required"] ? D extends {
+  default: infer Default;
+} ? undefined extends Default ? N : never : N : never : never : never : never;
+type InputArgsPrefixes<Remaining extends ArgsDef, Supplied = {}, Prefixes = never> = Remaining extends readonly [infer Head extends ArgDef, ...infer Tail extends ArgsDef] ? InputArgsPrefixes<Tail, Supplied & { [K in Head["name"]]: InputArgValue<Head>; }, Prefixes | (RequiredArgNames<Remaining> extends never ? Simplify<Supplied & { [D in Remaining[number] as D["name"]]?: never; }> : never)> : Prefixes | Simplify<Supplied>;
+/** Supplied positional values form a prefix; defaults do not fill input gaps. */
+type InputArgs<A extends ArgsDef> = number extends A["length"] ? never : IsUnion<A> extends true ? never : IsClosedName<A[number]["name"]> extends true ? InputArgsPrefixes<A> : never;
+type RequiredFlagName<D, K> = D extends unknown ? "required" extends keyof D ? true extends D["required"] ? D extends {
+  default: infer Default;
+} ? undefined extends Default ? K : never : K : never : never : never;
+type RequiredFlagNames<F extends FlagsDef> = { [K in keyof F]-?: RequiredFlagName<F[K], K>; }[keyof F];
+/** Flag values accepted by typed programmatic invocation before parsing/validation. */
+type KnownFlags<F extends FlagsDef> = { [K in keyof F as string extends K ? never : K]: F[K]; };
+type InputFlags<F extends FlagsDef> = IsUnion<F> extends true ? never : Simplify<{ [K in RequiredFlagNames<KnownFlags<F>>]-?: InputFlagValue<KnownFlags<F>[K]>; } & { [K in Exclude<keyof KnownFlags<F>, RequiredFlagNames<KnownFlags<F>>>]?: InputFlagValue<KnownFlags<F>[K]>; }> & (string extends keyof F ? NonNullable<RunInputPayload["flags"]> : {});
+type SectionConsumer = ExtensionId | {
+  readonly id: ExtensionId;
+};
+type Audience<C> = {
+  readonly only: C;
+  readonly except?: never;
+} | {
+  readonly except: C;
+  readonly only?: never;
+} | {
+  readonly only?: never;
+  readonly except?: never;
+};
+type SectionAudience = Audience<readonly [SectionConsumer, ...SectionConsumer[]]>;
+type SectionContent = {
+  readonly title: string;
+  readonly body: string;
+};
+/** A plain-text documentation section accepted from command and Extension authors. */
+type CommandSectionInput = SectionContent & SectionAudience;
+/** Typed dynamic audiences may be empty until their consuming operation checks them. */
+type RuntimeCommandSectionInput = SectionContent & Audience<readonly SectionConsumer[]>;
+/** A validated documentation section rendered after built-in command documentation. */
+type CommandSection = SectionContent & Audience<readonly [ExtensionId, ...ExtensionId[]]>;
+/** Metadata describing a CLI command */
+interface CommandMeta {
+  /** The command name (used in help text and routing) */
+  name: string;
+  /** Human-readable description for help text */
+  description?: string;
+  /** Application version exposed to Extensions and tooling on the root command. */
+  version?: string;
+  /** Custom usage string (overrides auto-generated usage) */
+  usage?: string;
+  /** Plain-text sections rendered after built-in command documentation. */
+  sections?: readonly CommandSection[];
+  /**
+   * Alternative names that resolve to the same command.
+   *
+   * Each entry is a sibling-level alternative for `name`. For example,
+   * `defineCommand("issue", { aliases: ["issues", "i"] }, recipe)` makes
+   * `cli issue`, `cli issues`, and `cli i` all route to the same command node.
+   *
+   * **Conflict policy.** Alias strings must not collide with this command's
+   * own canonical `name`, with any sibling's `name`, or with any sibling's
+   * own alias. TypeScript reports statically known collisions. Each alias
+   * must also be a non-empty string with no
+   * whitespace and must not start with `-`.
+   *
+   * **Display contract.** Help output renders the canonical name with
+   * aliases inline as `name (a, b, c)`. The canonical `name` is what
+   * appears in `commandPath`, error messages, and suggestions from
+   * `didYouMean` — it does not depend on which alias the user typed.
+   *
+   * @example
+   * defineCommand("issue", { aliases: ["issues", "i"] }, recipe)
+   */
+  aliases?: readonly string[];
+  /**
+   * When `true`, omit this command from every tooling surface that
+   * enumerates the command tree for users:
+   *
+   * - `help` rendered output (subcommand list + USAGE token)
+   * - `@crustjs/man` generated man pages (`SUBCOMMANDS` section)
+   * - `completion` candidate lists (recursively — hidden
+   *   subcommands and their descendants never appear in generated
+   *   bash/zsh/fish scripts)
+   * - `didYouMean` typo suggestions and "Available commands"
+   *   list (so internal names never surface in error UX)
+   * - `skill` manifests
+   *
+   * The command is **only hidden from listings**: routing in
+   * `@crustjs/core` does not consult `meta.hidden`, so it stays fully
+   * invocable by direct name (or alias). The intended use case is
+   * internal/runtime commands like a `__complete` shell-completion
+   * entrypoint. Marking a user-facing command `hidden` is supported but
+   * unusual.
+   *
+   * **Scope: commands only.** There is no analogous `hidden` field on
+   * `FlagDef` or `ArgDef`; flags and positional arguments always surface
+   * in help, completion, and man output. If you need a flag that does
+   * not advertise itself, the workaround is to register it as an Extension
+   * flags entry without a description (omit `description`),
+   * which suppresses its description body but still lists the spelling
+   * — there is intentionally no full hide mechanism at the flag layer.
+   *
+   * Tooling contract: any renderer or generator that walks
+   * `subCommands` to produce a user-facing listing should skip nodes
+   * where `meta.hidden === true`.
+   *
+   * @example
+   * meta: { name: "__complete", hidden: true, description: "Internal" }
+   */
+  hidden?: boolean;
+}
+/** Raw token shapes a Standard Schema receives before it runs. */
+type RawSchemaFlagInput = string | boolean | readonly (string | boolean)[] | undefined;
+/** One flag value after syntax parsing and before required/schema validation. */
+type RawFlagValue<D extends FlagDef> = D extends {
+  schema: StandardSchema;
+} ? RawSchemaFlagInput : InferFlagValue<D> | undefined;
+/** Positional counterpart of {@link RawFlagValue}. */
+type RawArgValue<D extends ArgDef> = D extends {
+  schema: StandardSchema;
+} ? D extends {
+  variadic: true;
+} ? string[] : string | undefined : D extends {
+  variadic: true;
+} ? ResolveBaseType<D>[] | undefined : InferArgValue<D> | undefined;
+/** Runtime-erased syntax-parsed flag value. */
+type ParsedFlagValue = RawFlagValue<FlagDef>;
+/** Runtime-erased syntax-parsed positional value. */
+type ParsedArgValue = RawArgValue<ArgDef>;
+type RawParsedFlags<F extends FlagsDef> = { [K in keyof F]: RawFlagValue<F[K]>; };
+type RawParsedArgs<A extends ArgsDef> = number extends A["length"] ? Record<string, ParsedArgValue> : { [D in A[number] as D["name"]]: RawArgValue<D>; };
+/** A declared default on any argument or flag definition. */
+type DeclaredDefault = (ArgDef | FlagDef)["default"];
+/** Syntax-parsed input, before required and Standard Schema validation. */
+interface ParseResult<A extends ArgsDef = ArgsDef, F extends FlagsDef = FlagsDef> {
+  args: RawParsedArgs<A>;
+  flags: RawParsedFlags<F>;
+  /** Positionals before `--` that were not consumed by a declared argument. */
+  excessArgs: string[];
+  /** Arguments after the `--` separator. */
+  rawArgs: string[];
+}
+/** Fully validated input returned by the schema boundary. */
+interface ValidatedInput<A extends ArgsDef = ArgsDef, F extends FlagsDef = FlagsDef> {
+  args: InferArgs<A>;
+  flags: InferFlags<F>;
+}
+//#endregion
+//#region src/api/context.d.ts
+/** Upper bound for phantom name-to-value context maps. */
+type ContextMap = object;
+declare const defining: unique symbol;
+declare const contextProof: unique symbol;
+/** @internal Immutable defining data retained through public structural copies. */
+interface Defining<T> {
+  readonly [defining]: T;
+}
+/** @internal */
+type DefiningOf<T> = T extends Defining<unknown> ? T[typeof defining] : T;
+/**
+ * Adapter hook: the Context sources a bag was built from, exposed as a
+ * non-enumerable symbol property. Reading it never starts construction.
+ */
+declare const contextSources: unique symbol;
+/** Lazy, invocation-scoped Context values. Reading a property starts construction. */
+type ContextBag<Deps extends ContextMap = {}> = { readonly [K in keyof Deps]: Promise<Deps[K]>; } & {
+  readonly [contextSources]?: readonly (AnyContextFactory | AnyContextInstance)[];
+};
+interface ContextConfig {
+  readonly flags?: readonly NamedFlagDef[];
+  readonly uses?: readonly AnyContextFactory[];
+}
+type ValidateContextConfig<R extends ContextConfig> = {
+  readonly flags?: R["flags"] extends readonly NamedFlagDef[] ? ValidateLocalFlagDefs<R["flags"], never> : "flags" extends keyof R ? {} : never;
+  readonly uses?: R["uses"] extends readonly AnyContextFactory[] ? R["uses"] : "uses" extends keyof R ? {} : never;
+};
+interface ContextSetupInput<OF extends FlagsDef = FlagsDef> extends InvocationIO {
+  readonly flags: InferFlags<OF>;
+  readonly ctx: ContextBag<ContextMap>;
+  readonly defer: (cleanup: () => void | PromiseLike<void>) => void;
+}
+interface ContextInstance<Name extends string = string, Value = unknown, OF extends FlagsDef = FlagsDef, Deps extends ContextMap = Record<string, ContextValue>> extends Defining<ContextInstance<Name, Value, OF, Deps>> {
+  readonly [contextProof]?: string extends keyof OF | keyof Deps ? unknown : (state: [OF, Deps]) => void;
+  readonly name: Name;
+  readonly ownedFlags: FlagsDef;
+  /** @internal — declared direct dependency factories */
+  readonly uses: readonly AnyContextFactory[];
+  /** @internal defining factory, for adapters that identify Contexts by factory */
+  readonly factory: AnyContextFactory;
+  setup(input: ContextSetupInput<OF>): Awaitable<Value>;
+  readonly _ownedFlags?: OF;
+  /** @internal — phantom carrying the transitive dependency closure */
+  readonly _deps?: Deps;
+}
+/** @internal Existential registry constraint; never evidence for trusted attachment. */
+type AnyContextInstance = ContextInstance<string, unknown, any, any>;
+/** Whatever a Context setup produces, erased at the runtime registry. */
+type ContextValue = Awaited<ReturnType<AnyContextInstance["setup"]>>;
+interface ContextSetup<Options, OF extends FlagsDef = {}, Deps extends ContextMap = {}> extends InvocationIO {
+  readonly options: Options;
+  readonly flags: InferFlags<OF>;
+  readonly ctx: ContextBag<Deps>;
+  /**
+   * Registers cleanup on the invocation's disposal stack: callbacks run after
+   * post-run hooks in reverse registration order. Throws once setup has settled.
+   */
+  readonly defer: (cleanup: () => void | PromiseLike<void>) => void;
+}
+interface ContextFactory<Name extends string, Options, Value, OF extends FlagsDef = {}, Deps extends ContextMap = {}> extends Defining<ContextFactory<Name, Options, Value, OF, Deps>> {
+  (options: Options): ContextInstance<Name, Value, OF, Deps>;
+  readonly contextName: Name;
+  /** @internal — declared direct dependency factories */
+  readonly uses: readonly AnyContextFactory[];
+  of(value: Value): ContextInstance<Name, Value, OF, {}>;
+  readonly _deps?: Deps;
+}
+type AnyContextFactory = ContextFactory<string, any, any, any, any>;
+type NamedOutput<Name extends string, Value> = IsClosedName<Name> extends false ? Record<string, Awaited<Value>> : IsUnion<Name> extends true ? Record<string, Awaited<Value>> : { [K in Name]: Awaited<Value>; };
+type ContextOutput<C> = C extends AnyContextInstance ? DefiningOf<C> extends ContextInstance<infer Name, infer Value, any, any> ? NamedOutput<Name, Value> : never : never;
+type ContextsOutput<Cs extends readonly AnyContextInstance[]> = IsStaticTuple<Cs> extends true ? Cs extends readonly [infer H, ...infer T extends readonly AnyContextInstance[]] ? MergeProviders<ContextOutput<H>, ContextsOutput<T>> : {} : Cs[number] extends never ? {} : Record<string, ContextOutput<Cs[number]> extends (infer O) ? O extends unknown ? O[keyof O] : never : never>;
+type ContextsOwnedFlags<Cs extends readonly AnyContextInstance[]> = IsStaticTuple<Cs> extends true ? Cs extends readonly [infer H, ...infer T extends readonly AnyContextInstance[]] ? MergeFlags<ContextOwnedFlags<H>, ContextsOwnedFlags<T>> : {} : keyof UnionToIntersection<ContextOwnedFlags<Cs[number]>> extends never ? {} : FlagsDef;
+type FactoryOutput<F> = F extends AnyContextFactory ? DefiningOf<F> extends ContextFactory<infer Name, any, infer Value, any, any> ? NamedOutput<Name, Value> : never : never;
+type FactoriesOutput<Fs extends readonly AnyContextFactory[]> = Fs extends readonly [infer H, ...infer T extends readonly AnyContextFactory[]] ? FactoryOutput<H> & FactoriesOutput<T> : {};
+type FactoryDeps<F> = F extends AnyContextFactory ? DefiningOf<F> extends ContextFactory<any, any, any, any, infer Deps> ? Deps : {} : {};
+type FactoriesDeps<Fs extends readonly AnyContextFactory[]> = Fs extends readonly [infer H, ...infer T extends readonly AnyContextFactory[]] ? FactoryDeps<H> & FactoriesDeps<T> : {};
+type ContextDependencies<Uses extends readonly AnyContextFactory[]> = IsStaticTuple<Uses> extends true ? FactoriesOutput<Uses> & FactoriesDeps<Uses> : Record<string, ContextValue>;
+type ContextDepsOf<C> = C extends AnyContextInstance ? DefiningOf<C> extends {
+  readonly _deps?: infer Deps extends ContextMap;
+} ? Deps : {} : {};
+type ContextsDependencies<Cs extends readonly AnyContextInstance[]> = Cs extends readonly [infer H, ...infer T extends readonly AnyContextInstance[]] ? ContextDepsOf<H> & ContextsDependencies<T> : {};
+type OwnedFlagsOf<R extends ContextConfig> = R extends {
+  flags: infer F extends readonly NamedFlagDef[];
+} ? AttachedFlags<F> : "flags" extends keyof R ? FlagsDef : {};
+type UsesOf<R extends ContextConfig> = R extends {
+  uses: infer Uses extends readonly AnyContextFactory[];
+} ? Uses : "uses" extends keyof R ? readonly AnyContextFactory[] : readonly [];
+/** Define a named, lazy command dependency. Declared `uses` are exposed on `ctx`. */
+declare function defineContext<Name extends string, Value, Options = void>(name: Name, setup: (input: ContextSetup<Options>) => Awaitable<Value>): ContextFactory<Name, Options, Value>;
+declare function defineContext<Name extends string, const R extends ContextConfig, Value, Options = void>(name: Name, config: R & ValidateContextConfig<R> & ContextConfig, setup: (input: ContextSetup<Options, OwnedFlagsOf<R>, ContextDependencies<UsesOf<R>>>) => Awaitable<Value>): ContextFactory<Name, Options, Value, OwnedFlagsOf<R>, ContextDependencies<UsesOf<R>>>;
+type FactoryValueOf<F extends AnyContextFactory> = F extends ContextFactory<any, any, infer Value, any, any> ? Awaited<Value> : never;
+//#endregion
+export { CrustErrorDetailsMap as $, ValueType as A, defineExtensionId as At, ExtensionFlagDef as B, NamedFlagDef as C, FlagSnapshot as Ct, SectionAudience as D, LocalValueBrand as Dt, ParsedFlagValue as E, EmptyArgNameBrand as Et, Extension as F, InvocationOutcome as G, ExtensionSectionContribution as H, ExtensionBuildContext as I, defineExtension as J, NamedExtensionFlagDef as K, ExtensionConfig as L, BuildFile as M, BuildReport as N, SectionConsumer as O, MergeContext as Ot, DefineExtensionWith as P, CrustErrorDetails as Q, ExtensionContext as R, MergeFlags as S, CommandSnapshot as St, ParsedArgValue as T, LocalFlagNameBrand as Tt, Finished as U, ExtensionHooks as V, InferExtensionFlags as W, CrustError as X, CommandNotFoundErrorDetails as Y, CrustErrorCode as Z, FlagDef as _, RunInput as _t, ContextInstance as a, CommandConfig as at, InputFlags as b, defineCommand as bt, FactoryValueOf as c, CommandHandle as ct, ArgDef as d, CommandShapeAt as dt, CrustErrorJson as et, ArgsDef as f, CommandTree as ft, DeclaredDefault as g, RunArguments as gt, CommandSectionInput as h, RootCommandMeta as ht, ContextFactory as i, AnyCrust as it, BuildArtifacts as j, ValidatedInput as k, ExtensionId as kt, contextSources as l, CommandPath as lt, CommandSection as m, CrustCommandContext as mt, ContextBag as n, ParseErrorDetails as nt, ContextMap as o, CommandDefinition as ot, CommandMeta as p, Crust as pt, RootMetaKey as q, ContextConfig as r, ValidationErrorDetails as rt, ContextSetup as s, CommandDefinitionBuilder as st, AnyContextFactory as t, DefinitionErrorDetails as tt, defineContext as u, CommandShape as ut, FlagsDef as v, RunInputArguments as vt, ParseResult as w, LocalFlagBrand as wt, InvocationIO as x, ArgSnapshot as xt, InputArgs as y, RunOutcome as yt, ExtensionFactory as z };