@ykdz/template 0.0.41 → 0.1.0-experimental.0

package/node_modules/@ykdz/cli-contract/dist/cli-contract.d.ts

@@ -1,12 +1,12 @@
 import { type RuntimeAtomicVariant } from "#/atomic-variant-compiler";
 import type { CommandUsage } from "#/cli-invocation";
 import type { ContractSchema, ContractSchemaInput, ContractSchemaOutput, EmptyCliInput, JsonObject, JsonValue } from "#/contract-schema";
+import type { reservedFieldNames } from "#/field-identity";
 import type { AtomicTextPresenter, CompletionFact, CompletionTextPresenter, CompletionOutcome, DataFactUnion, DataOutcome, DataVariantDefinitions, FailureFactUnion, FailureOutcome, FailureVariantDefinitions, OutcomeFact, TextLine, TextLines, StreamOutcome, StreamTextPresenter, StreamRecordDefinitions, StreamRecordFactUnion, StreamSuccessFact } from "#/outcome-fact";
 import { type RuntimeStreamRecord, type StreamRecordManifest } from "#/stream-variant-compiler";
-export { createCompletionFact, createDataFact, createFailureFact, createStreamRecordFact, createStreamSuccessFact, isIssuedOutcomeFact, text, } from "#/outcome-fact";
-export type { CompletionFact, CompletionTextPresenter, CompletionOutcome, DataFact, DataFactUnion, DataOutcome, DataVariantDefinition, DataVariantDefinitions, FailureFact, FailureFactUnion, FailureOutcome, FailureVariantDefinition, FailureVariantDefinitions, OutcomeFact, StreamOutcome, StreamRecordDefinition, StreamRecordDefinitions, StreamRecordFact, StreamRecordFactUnion, StreamSuccessFact, StreamTextPresenter, SilentText, TextLine, TextLines, TextFragment, } from "#/outcome-fact";
+export { createCompletionFact, createDataFact, createFailureFact, createStreamRecordFact, createStreamSuccessFact, isIssuedOutcomeFact, TextValueError, text, } from "#/outcome-fact";
+export type { CompletionFact, CompletionTextPresenter, CompletionOutcome, DataFact, DataFactUnion, DataOutcome, DataVariantDefinition, DataVariantDefinitions, FailureFact, FailureFactUnion, FailureOutcome, FailureVariantDefinition, FailureVariantDefinitions, OutcomeFact, StreamOutcome, StreamRecordDefinition, StreamRecordDefinitions, StreamRecordFact, StreamRecordFactUnion, StreamSuccessFact, StreamTextPresenter, SilentText, TextLine, TextLines, TextValueErrorIssue, TextFragment, } from "#/outcome-fact";
 declare const cliContractType: unique symbol;
-declare const executableCommandType: unique symbol;
 declare const definitionPropertyKeys: {
     readonly cli: readonly ["root", "help", "version", "output", "usageFailureExitCode", "commands"];
     readonly group: readonly ["kind", "parent", "name", "aliases", "description", "helpSupplement", "handler"];
@@ -17,10 +17,14 @@ declare const definitionPropertyKeys: {
         readonly positional: readonly ["kind", "description"];
     };
     readonly usage: {
-        readonly requires: readonly ["kind", "field", "requires"];
-        readonly exclusive: readonly ["kind", "fields"];
-        readonly forbiddenCombination: readonly ["kind", "values"];
-        readonly value: readonly ["field", "value"];
+        readonly count: readonly ["kind", "fields", "min", "max"];
+        readonly when: readonly ["kind", "all", "onMatch", "otherwise"];
+        readonly effect: readonly ["require", "forbid"];
+        readonly forbiddenCombination: readonly ["kind", "all"];
+        readonly fact: {
+            readonly present: readonly ["kind", "field"];
+            readonly equals: readonly ["kind", "field", "value"];
+        };
     };
     readonly success: {
         readonly completion: readonly ["kind", "text"];
@@ -62,19 +66,93 @@ export interface HelpFactWording {
     readonly choices?: string;
     /** 字段或输出格式的默认 JSON 值，必须包含 `{value}`。 */
     readonly default?: string;
-    /** 字段依赖关系，必须包含 `{field}` 与 `{requires}`。 */
-    readonly requires?: string;
-    /** 互斥字段集合，必须包含 `{fields}`。 */
-    readonly exclusive?: string;
-    /** 禁止同时出现的字段和值，必须包含 `{values}`。 */
+    /** 有效的成立分支，必须包含 `{facts}` 与 `{onMatch}`。 */
+    readonly whenOnMatch?: string;
+    /** 有效的不成立分支，必须包含 `{facts}` 与 `{otherwise}`。 */
+    readonly whenOtherwise?: string;
+    /** 两侧均有效的条件分支，必须包含 `{facts}`、`{onMatch}` 与 `{otherwise}`。 */
+    readonly whenOnMatchOtherwise?: string;
+    /** 效果中的必需字段组，必须包含 `{fields}`。 */
+    readonly require?: string;
+    /** 效果中的禁止字段组，必须包含 `{fields}`。 */
+    readonly forbid?: string;
+    /** 字段出现事实，必须包含 `{field}`。 */
+    readonly present?: string;
+    /** 字段等值事实，必须包含 `{field}` 与 `{value}`。 */
+    readonly equals?: string;
+    /** 禁止同时成立的字段事实组，必须包含 `{facts}`。 */
     readonly forbiddenCombination?: string;
+    /** 字段数必须恰好为 `{count}`，包含 `{fields}`。 */
+    readonly countExactly?: string;
+    /** 字段数至少为 `{min}`，包含 `{fields}`。 */
+    readonly countAtLeast?: string;
+    /** 字段数至多为 `{max}`，包含 `{fields}`。 */
+    readonly countAtMost?: string;
+    /** 字段数位于 `{min}` 到 `{max}`，包含 `{fields}`。 */
+    readonly countBetween?: string;
 }
+/** 帮助事实槽位及其必需替换参数的唯一规格。 */
+export declare const helpTemplateSpecifications: {
+    readonly commandPlaceholder: {
+        readonly placeholders: readonly [];
+    };
+    readonly choices: {
+        readonly placeholders: readonly ["choices"];
+    };
+    readonly default: {
+        readonly placeholders: readonly ["value"];
+    };
+    readonly whenOnMatch: {
+        readonly placeholders: readonly ["facts", "onMatch"];
+    };
+    readonly whenOtherwise: {
+        readonly placeholders: readonly ["facts", "otherwise"];
+    };
+    readonly whenOnMatchOtherwise: {
+        readonly placeholders: readonly ["facts", "onMatch", "otherwise"];
+    };
+    readonly require: {
+        readonly placeholders: readonly ["fields"];
+    };
+    readonly forbid: {
+        readonly placeholders: readonly ["fields"];
+    };
+    readonly present: {
+        readonly placeholders: readonly ["field"];
+    };
+    readonly equals: {
+        readonly placeholders: readonly ["field", "value"];
+    };
+    readonly forbiddenCombination: {
+        readonly placeholders: readonly ["facts"];
+    };
+    readonly countExactly: {
+        readonly placeholders: readonly ["fields", "count"];
+    };
+    readonly countAtLeast: {
+        readonly placeholders: readonly ["fields", "min"];
+    };
+    readonly countAtMost: {
+        readonly placeholders: readonly ["fields", "max"];
+    };
+    readonly countBetween: {
+        readonly placeholders: readonly ["fields", "min", "max"];
+    };
+};
+/** 按帮助槽位推导的替换参数闭合形状。 */
+export type HelpFactTemplateParameters = {
+    readonly [Slot in keyof typeof helpTemplateSpecifications]: Readonly<Record<(typeof helpTemplateSpecifications)[Slot]["placeholders"][number], string>>;
+};
 /** 根契约一次装配的帮助配置；标题可省略，实际出现的事实必须有文案。 */
 export interface HelpCapabilityDefinition {
     readonly shortAlias?: "-h";
     readonly headings?: HelpHeadings;
     readonly wording?: HelpFactWording;
 }
+type HelpCapabilityDefinitionForTypeCheck = Omit<HelpCapabilityDefinition, "wording"> & {
+    /** 保留未知槽位的字面键，让局部闭合诊断提供可行动身份。 */
+    readonly wording?: object;
+};
 export interface VersionCapability {
     readonly kind: "versionCapability";
     readonly value: string;
@@ -138,36 +216,87 @@ export interface ValueOptionDefinition<LongOption extends `--${string}` = `--${s
     readonly description: string;
 }
 export type FieldDefinition = FlagDefinition | PositionalDefinition | RepeatableOptionDefinition | VariadicPositionalDefinition | ValueOptionDefinition;
+/**
+ * 字段键须符合 lowerCamelCase，且不能使用 constructor、hasOwnProperty、
+ * isPrototypeOf、propertyIsEnumerable、toString、valueOf 或 toLocaleString。
+ * 迁移字段键时同步模式 Input 键及引用，命令行拼写可保留。
+ */
 export type FieldDefinitions = Readonly<Record<string, FieldDefinition>>;
 /**
- * 由调用语法拥有、可同时投影到 parser 和 Draft 2020-12 的字段关系。
- * `requires` 与 `exclusive` 作用于可选 option；`forbiddenCombination`
- * 的离散值只作用于 flag 或 value option。动态声明在定义期检查这些前提。
+ * 可投影到 parser 和 Draft 2020-12 的有限字段关系：`count` 限制 raw 字段出现数，`when` 根据 raw 事实选择必需或禁止效果，
+ * `forbiddenCombination` 拒绝指定事实组合。字段必填、候选值与格式由输入模式表达；依赖实际值计算、时间或业务状态的规则由 handler 返回具名失败。
  */
-export type UsageConstraint<Fields extends FieldDefinitions = FieldDefinitions> = RequiresUsageConstraint<Extract<keyof Fields, string>> | ExclusiveUsageConstraint<Extract<keyof Fields, string>> | ForbiddenCombinationUsageConstraint<Fields>;
-export interface RequiresUsageConstraint<Field extends string = string> {
-    readonly kind: "requires";
-    readonly field: Field;
-    readonly requires: Field;
+export type UsageConstraint<Fields extends FieldDefinitions = FieldDefinitions, Input = unknown> = CountUsageConstraint<Fields> | WhenUsageConstraint<Fields, Input> | ForbiddenCombinationUsageConstraint<Fields, Input>;
+/**
+ * 限制当前命令中 `fields` 所列 raw 输入字段的出现数量；字段组必须非空且无重复。
+ * 规范化端点必须是有限整数，且满足 `0 <= min <= max <= fields.length`。每个 raw 自有属性只计一次，
+ * 因而 `false` 也算出现，repeatable 或 variadic 字段的多个值仍只计一项；
+ * 缺席的 variadic 字段没有属性，schema 默认值和转换结果也不会增加计数。
+ * 缺省 `min` 为 0，缺省 `max` 为字段组长度，至少显式提供一个端点。
+ * TypeScript 会拒绝静态可判定的错误；动态端点或字段成员在 CLI 定义时校验。
+ */
+export interface CountUsageConstraint<Fields extends FieldDefinitions = FieldDefinitions> {
+    readonly kind: "count";
+    readonly fields: readonly [
+        Extract<keyof Fields, string>,
+        ...Extract<keyof Fields, string>[]
+    ];
+    readonly min?: number;
+    readonly max?: number;
 }
-export interface ExclusiveUsageConstraint<Field extends string = string> {
-    readonly kind: "exclusive";
-    readonly fields: readonly [Field, Field, ...Field[]];
+/**
+ * 条件分支只描述 raw 输入 facts 全部成立或未全部成立时的效果；空效果不增加限制，
+ * 但整条规则至少需要一个非空分支。字段不会被赋值或补入默认值。
+ */
+export interface UsageConstraintEffect<Field extends string = string> {
+    readonly require?: readonly Field[];
+    readonly forbid?: readonly Field[];
+}
+/** 表示一个输入字段在 raw argv 解析结果中出现。 */
+export interface PresentUsageFact<Field extends string = string> {
+    readonly kind: "present";
+    readonly field: Field;
 }
-type DiscreteUsageValue<Field extends FieldDefinition> = Field extends FlagDefinition ? boolean : Field extends ValueOptionDefinition ? string : never;
-export type ForbiddenCombinationValue<Fields extends FieldDefinitions = FieldDefinitions> = {
-    [Field in keyof Fields & string]: DiscreteUsageValue<Fields[Field]> extends never ? never : Readonly<{
+type RawUsageFactValue<Field extends FieldDefinition> = Field extends Readonly<{
+    readonly kind: "flag";
+    readonly negatedLongOption: `--${string}`;
+}> ? boolean : Field extends FlagDefinition ? true : Field extends ValueOptionDefinition | PositionalDefinition ? string : never;
+type UsageFactInputValue<Input, Field extends string, RawValue> = IsAny<Input> extends true ? RawValue : unknown extends Input ? RawValue : Field extends keyof Input ? Extract<Exclude<Input[Field], undefined>, RawValue> : never;
+/** 从字段的 raw 标量和 schema Input 交集中推导可比较值。 */
+export type UsageFactValue<Fields extends FieldDefinitions, Input, Field extends keyof Fields & string> = UsageFactInputValue<Input, Field, RawUsageFactValue<Fields[Field]>>;
+/** 将字段身份关联到其可接受的 raw 等值操作数。 */
+export type EqualsUsageFact<Fields extends FieldDefinitions = FieldDefinitions, Input = unknown> = {
+    [Field in keyof Fields & string]: UsageFactValue<Fields, Input, Field> extends never ? never : Readonly<{
+        readonly kind: "equals";
         readonly field: Field;
-        readonly value: DiscreteUsageValue<Fields[Field]>;
+        readonly value: UsageFactValue<Fields, Input, Field>;
     }>;
 }[keyof Fields & string];
-export interface ForbiddenCombinationUsageConstraint<Fields extends FieldDefinitions = FieldDefinitions> {
+/** 字段出现或单值等值事实的闭合联合。 */
+export type UsageFact<Fields extends FieldDefinitions = FieldDefinitions, Input = unknown> = string extends keyof Fields ? PresentUsageFact<string> | Readonly<{
+    readonly kind: "equals";
+    readonly field: string;
+    readonly value: boolean | string;
+}> : PresentUsageFact<Extract<keyof Fields, string>> | EqualsUsageFact<Fields, Input>;
+/** 所列事实同时成立时拒绝调用；`all` 保留非空顺序和重复项。 */
+export interface ForbiddenCombinationUsageConstraint<Fields extends FieldDefinitions = FieldDefinitions, Input = unknown> {
     readonly kind: "forbiddenCombination";
-    readonly values: readonly [
-        ForbiddenCombinationValue<Fields>,
-        ForbiddenCombinationValue<Fields>,
-        ...ForbiddenCombinationValue<Fields>[]
+    readonly all: readonly [
+        UsageFact<Fields, Input>,
+        ...UsageFact<Fields, Input>[]
+    ];
+}
+/**
+ * 平面 facts 合取选择成立或不成立分支。观察与效果都依据模式验证、默认和转换前的 raw input。
+ */
+export interface WhenUsageConstraint<Fields extends FieldDefinitions = FieldDefinitions, Input = unknown> {
+    readonly kind: "when";
+    readonly all: readonly [
+        UsageFact<Fields, Input>,
+        ...UsageFact<Fields, Input>[]
     ];
+    readonly onMatch?: UsageConstraintEffect<Extract<keyof Fields, string>>;
+    readonly otherwise?: UsageConstraintEffect<Extract<keyof Fields, string>>;
 }
 export type ValueOptionDefinitions = Readonly<Record<string, ValueOptionDefinition>>;
 type RawFieldValue<Field extends FieldDefinition> = Field extends {
@@ -186,22 +315,30 @@ export type FieldDefinitionsForInput<Input> = Readonly<{
 export type ValueOptionDefinitionsForInput<Input> = Readonly<{
     [Field in Extract<keyof Input, string>]: ValueOptionDefinition;
 }>;
-type CheckedFieldDefinition<Field extends FieldDefinition, Key> = Field extends PositionalDefinition ? Field : Field extends VariadicPositionalDefinition ? Field : Field extends FlagDefinition<infer LongOption, infer ShortAlias> ? CheckedNegatedFlagDefinition<Field, Key, LongOption, ShortAlias> : Field extends RepeatableOptionDefinition<infer LongOption, infer ShortAlias> ? CheckedOptionDefinition<Field, Key, LongOption, ShortAlias> : Field extends ValueOptionDefinition<infer LongOption, infer ShortAlias> ? CheckedOptionDefinition<Field, Key, LongOption, ShortAlias> : never;
-type CheckedNegatedFlagDefinition<Field, Key, LongOption extends `--${string}`, ShortAlias extends `-${string}` | undefined> = CheckedOptionDefinition<Field, Key, LongOption, ShortAlias> extends Field ? Field extends {
-    readonly negatedLongOption: infer NegatedLongOption extends `--${string}`;
-} ? NegatedLongOption extends CanonicalLongOption<NegatedLongOption> ? Field : ContractTypeError<"invalidNegatedLongOption", Readonly<{
-    readonly field: Key;
-    readonly received: NegatedLongOption;
-}>> : Field : CheckedOptionDefinition<Field, Key, LongOption, ShortAlias>;
-type CheckedOptionDefinition<Field, Key, LongOption extends `--${string}`, ShortAlias extends `-${string}` | undefined> = LongOption extends CanonicalLongOption<LongOption> ? ShortAlias extends undefined ? Field : ShortAlias extends ShortOptionAlias<Extract<ShortAlias, string>> ? Field : ContractTypeError<"invalidShortOptionAlias", Readonly<{
-    readonly field: Key;
-    readonly received: ShortAlias;
-}>> : ContractTypeError<"invalidCanonicalLongOption", Readonly<{
-    readonly field: Key;
+type InvalidCanonicalLongOptionIssue<Command extends string, Key, LongOption extends `--${string}`> = LongOption extends CanonicalLongOption<LongOption> ? never : ContractTypeError<"invalidFieldLongOption", Readonly<{
+    readonly command: Command;
+    readonly field: Extract<Key, string>;
     readonly received: LongOption;
 }>>;
-type CheckedFieldDefinitions<Fields extends FieldDefinitions> = {
-    readonly [Field in keyof Fields]: CheckedFieldDefinition<Fields[Field], Field> & RejectUnknownProperties<Fields[Field], AllowedFieldProperties<Fields[Field]>>;
+type InvalidShortOptionAliasIssue<Field, Command extends string, Key> = Field extends Readonly<{
+    readonly shortAlias: infer ShortAlias extends `-${string}`;
+}> ? ShortAlias extends ShortOptionAlias<ShortAlias> ? never : ContractTypeError<"invalidFieldShortAlias", Readonly<{
+    readonly command: Command;
+    readonly field: Extract<Key, string>;
+    readonly received: ShortAlias;
+}>> : never;
+type InvalidNegatedLongOptionIssue<Field, Key, Command extends string> = Field extends Readonly<{
+    readonly negatedLongOption: infer NegatedLongOption extends `--${string}`;
+}> ? NegatedLongOption extends CanonicalLongOption<NegatedLongOption> ? never : ContractTypeError<"invalidFieldLongOption", Readonly<{
+    readonly command: Command;
+    readonly field: Extract<Key, string>;
+    readonly received: NegatedLongOption;
+}>> : never;
+type CheckedFieldDefinition<Field extends FieldDefinition, Key, Command extends string> = Field extends PositionalDefinition ? Field : Field extends VariadicPositionalDefinition ? Field : Field extends FlagDefinition<infer LongOption> ? CheckedNegatedFlagDefinition<Field, Key, LongOption, Command> : Field extends RepeatableOptionDefinition<infer LongOption> ? CheckedOptionDefinition<Field, Key, LongOption, Command> : Field extends ValueOptionDefinition<infer LongOption> ? CheckedOptionDefinition<Field, Key, LongOption, Command> : never;
+type CheckedNegatedFlagDefinition<Field, Key, LongOption extends `--${string}`, Command extends string> = [InvalidCanonicalLongOptionIssue<Command, Key, LongOption>] extends [never] ? [InvalidShortOptionAliasIssue<Field, Command, Key>] extends [never] ? [InvalidNegatedLongOptionIssue<Field, Key, Command>] extends [never] ? Field : InvalidNegatedLongOptionIssue<Field, Key, Command> : InvalidShortOptionAliasIssue<Field, Command, Key> : InvalidCanonicalLongOptionIssue<Command, Key, LongOption>;
+type CheckedOptionDefinition<Field, Key, LongOption extends `--${string}`, Command extends string> = [InvalidCanonicalLongOptionIssue<Command, Key, LongOption>] extends [never] ? [InvalidShortOptionAliasIssue<Field, Command, Key>] extends [never] ? Field : InvalidShortOptionAliasIssue<Field, Command, Key> : InvalidCanonicalLongOptionIssue<Command, Key, LongOption>;
+type CheckedFieldDefinitions<Fields extends FieldDefinitions, Command extends string> = {
+    readonly [Field in keyof Fields]: CheckedFieldDefinition<Fields[Field], Field, Command> & RejectUnknownProperties<Fields[Field], AllowedFieldProperties<Fields[Field]>>;
 };
 type RejectUnknownProperties<Value, Allowed extends PropertyKey> = Readonly<{
     [Property in Exclude<keyof Value, Allowed>]?: never;
@@ -219,19 +356,36 @@ type ClosedStreamRecords<Records> = ClosedVariantDefinitions<Records, (typeof de
 type ClosedFieldDefinitions<Fields> = Readonly<{
     [Field in keyof Fields]: RejectUnknownProperties<Fields[Field], AllowedFieldProperties<Fields[Field]>>;
 }>;
+type ClosedUsageFact<Fact> = Fact extends Readonly<{
+    readonly kind: "present";
+}> ? RejectUnknownProperties<Fact, (typeof definitionPropertyKeys.usage.fact.present)[number]> : Fact extends Readonly<{
+    readonly kind: "equals";
+}> ? RejectUnknownProperties<Fact, (typeof definitionPropertyKeys.usage.fact.equals)[number]> : unknown;
+type ClosedUsageFacts<Facts extends readonly unknown[]> = {
+    readonly [Index in keyof Facts]: ClosedUsageFact<Facts[Index]>;
+};
+type ClosedUsageEffect<Effect> = Effect extends object ? RejectUnknownProperties<Effect, (typeof definitionPropertyKeys.usage.effect)[number]> : Effect;
 type ClosedUsageConstraint<Constraint> = Constraint extends Readonly<{
-    readonly kind: "requires";
-}> ? RejectUnknownProperties<Constraint, (typeof definitionPropertyKeys.usage.requires)[number]> : Constraint extends Readonly<{
-    readonly kind: "exclusive";
-}> ? RejectUnknownProperties<Constraint, (typeof definitionPropertyKeys.usage.exclusive)[number]> : Constraint extends Readonly<{
+    readonly kind: "when";
+    readonly all: infer Facts extends readonly unknown[];
+}> ? RejectUnknownProperties<Constraint, (typeof definitionPropertyKeys.usage.when)[number]> & Readonly<{
+    readonly all: ClosedUsageFacts<Facts>;
+}> & (Constraint extends Readonly<{
+    readonly onMatch?: infer OnMatch;
+}> ? Readonly<{
+    readonly onMatch?: ClosedUsageEffect<OnMatch>;
+}> : unknown) & (Constraint extends Readonly<{
+    readonly otherwise?: infer Otherwise;
+}> ? Readonly<{
+    readonly otherwise?: ClosedUsageEffect<Otherwise>;
+}> : unknown) : Constraint extends Readonly<{
+    readonly kind: "count";
+}> ? RejectUnknownProperties<Constraint, (typeof definitionPropertyKeys.usage.count)[number]> : Constraint extends Readonly<{
     readonly kind: "forbiddenCombination";
-    readonly values: infer Values extends readonly unknown[];
-}> ? RejectUnknownProperties<Constraint, (typeof definitionPropertyKeys.usage.forbiddenCombination)[number]> & Readonly<{
-    readonly values: {
-        [Index in keyof Values]: Values[Index] & RejectUnknownProperties<Values[Index], (typeof definitionPropertyKeys.usage.value)[number]>;
-    };
-}> : unknown;
-type ClosedUsageConstraints<Constraints> = Constraints extends readonly (infer Constraint)[] ? readonly (Constraint & ClosedUsageConstraint<Constraint>)[] : unknown;
+}> ? unknown : unknown;
+type ClosedUsageConstraints<Command extends string, Constraints> = Constraints extends readonly unknown[] ? InvalidClosedUsageConstraintProperties<Command, Constraints[number]> extends infer Issue ? [Issue] extends [never] ? {
+    readonly [Index in keyof Constraints]: Constraints[Index] & ClosedUsageConstraint<Constraints[Index]>;
+} : Issue : never : unknown;
 type ClosedSuccessDefinition<Success> = Success extends Readonly<{
     readonly kind: "data";
     readonly variants: infer Variants;
@@ -243,7 +397,7 @@ type ClosedSuccessDefinition<Success> = Success extends Readonly<{
 }> ? RejectUnknownProperties<Success, (typeof definitionPropertyKeys.success.stream)[number]> & Readonly<{
     readonly records: ClosedStreamRecords<Records>;
 }> : RejectUnknownProperties<Success, (typeof definitionPropertyKeys.success.completion)[number]>;
-type ClosedCommandDefinition<Definition> = RejectUnknownProperties<Definition, (typeof definitionPropertyKeys.command)[number] | typeof executableCommandType> & (Definition extends Readonly<{
+type ClosedCommandDefinition<Definition, Command extends string = string> = RejectUnknownProperties<Definition, (typeof definitionPropertyKeys.command)[number]> & (Definition extends Readonly<{
     readonly success: infer Success;
 }> ? Readonly<{
     readonly success: ClosedSuccessDefinition<Success>;
@@ -258,12 +412,12 @@ type ClosedCommandDefinition<Definition> = RejectUnknownProperties<Definition, (
 }> : unknown) & (Definition extends Readonly<{
     readonly usageConstraints: infer Constraints;
 }> ? Readonly<{
-    readonly usageConstraints: ClosedUsageConstraints<Constraints>;
+    readonly usageConstraints: ClosedUsageConstraints<Command, Constraints>;
 }> : unknown);
 type ClosedRootCommands<Commands> = Readonly<{
     [Command in keyof Commands]: Commands[Command] extends Readonly<{
         readonly kind: "command" | "rootCommand";
-    }> ? ClosedCommandDefinition<Commands[Command]> : RejectUnknownProperties<Commands[Command], (typeof definitionPropertyKeys.group)[number]>;
+    }> ? ClosedCommandDefinition<Commands[Command], Extract<Command, string>> : RejectUnknownProperties<Commands[Command], (typeof definitionPropertyKeys.group)[number]>;
 }>;
 type ClosedRootDefinition<Definition> = RejectUnknownProperties<Definition, (typeof definitionPropertyKeys.cli)[number]> & (Definition extends Readonly<{
     readonly commands: infer Commands;
@@ -273,8 +427,11 @@ type ClosedRootDefinition<Definition> = RejectUnknownProperties<Definition, (typ
 type InvalidFieldIdentities<Fields extends FieldDefinitions> = {
     [Field in keyof Fields & string]: IsLowerCamelCase<Field> extends true ? never : Field;
 }[keyof Fields & string];
-type FieldIdentityContract<Fields extends FieldDefinitions> = string extends keyof Fields ? unknown : InvalidFieldIdentities<Fields> extends never ? unknown : ContractTypeError<"fieldMustBeLowerCamelCase", Readonly<{
-    readonly fields: InvalidFieldIdentities<Fields>;
+type FieldIdentityContract<Command extends string, Fields extends FieldDefinitions> = string extends keyof Fields ? unknown : InvalidFieldIdentities<Fields> | Extract<keyof Fields, (typeof reservedFieldNames)[number]> extends never ? unknown : ContractTypeError<"invalidFieldIdentity", Readonly<{
+    readonly command: Command;
+    readonly field: InvalidFieldIdentities<Fields> extends never ? Extract<keyof Fields, (typeof reservedFieldNames)[number]> : InvalidFieldIdentities<Fields>;
+    readonly reason: InvalidFieldIdentities<Fields> extends never ? "reservedName" : "lowerCamelCase";
+    readonly hint: InvalidFieldIdentities<Fields> extends never ? "更换字段键，同步模式 Input 键及引用；CLI 拼写可保留" : "小写字母开头，仅含字母和数字";
 }>>;
 export type RawValueOptionInputForSchema<InputSchema extends ContractSchema> = Readonly<{
     [Field in Extract<keyof ContractSchemaInput<InputSchema>, string>]?: string;
@@ -284,6 +441,42 @@ export interface ContractTypeError<Code extends string, Evidence> {
         readonly code: Code;
     } & Evidence>;
 }
+type HelpFactTemplateAllowedPlaceholder<Slot extends keyof HelpFactWording> = (typeof helpTemplateSpecifications)[Slot]["placeholders"][number];
+type ParsedHelpFactTemplate<Template extends string, Allowed extends string, Seen extends string = never> = Template extends `${infer Prefix}{${infer Tail}` ? Prefix extends `${string}}${string}` ? false : Tail extends `${infer Placeholder}}${infer Rest}` ? Placeholder extends Allowed ? ParsedHelpFactTemplate<Rest, Allowed, Seen | Placeholder> : false : false : Template extends `${string}}${string}` ? false : Exclude<Allowed, Seen> extends never ? true : false;
+type HelpTemplateWhitespace = " " | "\t" | "\v" | "\f" | "\u00a0" | "\u1680" | "\u2000" | "\u2001" | "\u2002" | "\u2003" | "\u2004" | "\u2005" | "\u2006" | "\u2007" | "\u2008" | "\u2009" | "\u200a" | "\u2028" | "\u2029" | "\u202f" | "\u205f" | "\u3000" | "\ufeff";
+type TrimHelpTemplateWhitespace<Template extends string> = Template extends `${HelpTemplateWhitespace}${infer Rest}` ? TrimHelpTemplateWhitespace<Rest> : Template extends `${infer Rest}${HelpTemplateWhitespace}` ? TrimHelpTemplateWhitespace<Rest> : Template;
+type HelpFactTemplateFailureReason<Slot extends keyof HelpFactWording, Template extends string> = Template extends `${string}\r${string}` | `${string}\n${string}` | `${string}\0${string}` ? "singleLine" : TrimHelpTemplateWhitespace<Template> extends "" ? "empty" : Slot extends "commandPlaceholder" ? Template extends `${string}<${string}` | `${string}>${string}` ? "placeholder" : ParsedHelpFactTemplate<Template, HelpFactTemplateAllowedPlaceholder<Slot>> extends true ? never : "placeholder" : ParsedHelpFactTemplate<Template, HelpFactTemplateAllowedPlaceholder<Slot>> extends true ? never : "placeholder";
+type IsValidStaticHelpFactTemplate<Slot extends keyof HelpFactWording, Template extends string> = HelpFactTemplateFailureReason<Slot, Template> extends never ? true : false;
+type HelpFactTemplateValueContract<Slot extends keyof HelpFactWording, Value> = [Exclude<Value, undefined>] extends [never] ? never : [Exclude<Value, undefined>] extends [string] ? string extends Exclude<Value, undefined> ? never : IsValidStaticHelpFactTemplate<Slot, Extract<Exclude<Value, undefined>, string>> extends true ? never : ContractTypeError<"invalidHelpFactTemplate", Readonly<{
+    readonly slot: Slot;
+    readonly received: Extract<Exclude<Value, undefined>, string>;
+    readonly reason: HelpFactTemplateFailureReason<Slot, Extract<Exclude<Value, undefined>, string>>;
+}>> : ContractTypeError<"invalidHelpFactTemplate", Readonly<{
+    readonly slot: Slot;
+    readonly received: Value;
+    readonly reason: "singleLine";
+}>>;
+type HelpFactWordingMemberIssues<Wording> = {
+    [Slot in keyof Wording & keyof HelpFactWording]: HelpFactTemplateValueContract<Slot, Wording[Slot]>;
+}[keyof Wording & keyof HelpFactWording] | HelpFactWordingUnknownPropertyIssues<Wording>;
+type HelpFactWordingIssues<Wording> = Wording extends unknown ? HelpFactWordingMemberIssues<Wording> : never;
+type HelpFactWordingUnknownPropertyIssues<Wording> = {
+    [Property in Exclude<Extract<keyof Wording, string>, keyof HelpFactWording>]: ContractTypeError<"unknownDefinitionProperty", Readonly<{
+        readonly path: readonly ["help", "wording", Property];
+        readonly property: Property;
+    }>>;
+}[Exclude<Extract<keyof Wording, string>, keyof HelpFactWording>];
+type HelpFactWordingContract<Wording> = [
+    HelpFactWordingIssues<Wording>
+] extends [never] ? unknown : HelpFactWordingIssues<Wording>;
+type HelpCapabilityWording<Definition> = Definition extends unknown ? Definition extends Readonly<{
+    readonly wording?: infer Wording;
+}> ? Exclude<Wording, undefined> : never : never;
+type HelpCapabilityTemplateContract<Definition> = [
+    HelpCapabilityWording<Definition>
+] extends [never] ? unknown : [
+    Extract<HelpCapabilityWording<Definition>, (...arguments_: never[]) => unknown>
+] extends [never] ? HelpFactWordingContract<HelpCapabilityWording<Definition>> : never;
 type InputStringKeys<Input> = Extract<keyof Input, string>;
 type IsAny<Value> = 0 extends 1 & Value ? true : false;
 type IsUnion<Value, Whole = Value> = IsAny<Value> extends true ? false : Value extends unknown ? [Whole] extends [Value] ? false : true : never;
@@ -300,12 +493,18 @@ type InvalidVariantNames<Variants> = {
     [Variant in keyof Variants & string]: IsLowerCamelCase<Variant> extends true ? never : Variant;
 }[keyof Variants & string];
 type InvalidDataVariantNames<Variants> = InvalidVariantNames<Variants>;
-type DataVariantNameContract<Variants> = InvalidDataVariantNames<Variants> extends never ? unknown : ContractTypeError<"dataVariantMustBeLowerCamelCase", Readonly<{
-    readonly variants: InvalidDataVariantNames<Variants>;
+type DataVariantNameContract<Command extends string, Variants> = InvalidDataVariantNames<Variants> extends never ? unknown : ContractTypeError<"invalidVariantName", Readonly<{
+    readonly command: Command;
+    readonly location: "data";
+    readonly variant: InvalidDataVariantNames<Variants>;
+    readonly reason: "lowerCamelCase";
 }>>;
 type InvalidFailureVariantNames<Failures> = InvalidVariantNames<Failures>;
-type FailureVariantNameContract<Failures> = InvalidFailureVariantNames<Failures> extends never ? unknown : ContractTypeError<"failureVariantMustBeLowerCamelCase", Readonly<{
-    readonly variants: InvalidFailureVariantNames<Failures>;
+type FailureVariantNameContract<Command extends string, Failures> = InvalidFailureVariantNames<Failures> extends never ? unknown : ContractTypeError<"invalidVariantName", Readonly<{
+    readonly command: Command;
+    readonly location: "failure";
+    readonly variant: InvalidFailureVariantNames<Failures>;
+    readonly reason: "lowerCamelCase";
 }>>;
 export interface CompletionHandlerContext<Command extends string, Dependencies, Failures extends FailureVariantDefinitions, Input = EmptyCliInput> {
     readonly input: Input;
@@ -373,8 +572,11 @@ type FailureVariantDefinitionsForSchemas<Schemas extends VariantSchemaMap, TextE
 }>;
 type FailureVariantTextContract<Command extends string, Failures, TextEnabled extends boolean> = NamedVariantTextContract<Command, "failure", Failures, TextEnabled, FailureVariantDefinitions<false>>;
 type StreamRecordTextContract<Command extends string, Records, TextEnabled extends boolean> = NamedVariantTextContract<Command, "record", Records, TextEnabled, StreamRecordDefinitions<false>>;
-type StreamRecordNameContract<Records> = InvalidVariantNames<Records> extends never ? unknown : ContractTypeError<"streamRecordMustBeLowerCamelCase", Readonly<{
-    readonly records: InvalidVariantNames<Records>;
+type StreamRecordNameContract<Command extends string, Records> = InvalidVariantNames<Records> extends never ? unknown : ContractTypeError<"invalidVariantName", Readonly<{
+    readonly command: Command;
+    readonly location: "record";
+    readonly variant: InvalidVariantNames<Records>;
+    readonly reason: "lowerCamelCase";
 }>>;
 type StreamRecordDefinitionForSchema<Schema extends ContractSchema, TextEnabled extends boolean> = Readonly<{
     readonly description: string;
@@ -392,11 +594,10 @@ export interface CompletionRootCommandDefinition<Command extends string, Depende
     readonly name: string;
     readonly description: string;
     readonly helpSupplement?: TextLines;
-    readonly usageConstraints?: readonly UsageConstraint<Fields>[];
-    readonly fields?: CheckedFieldDefinitions<Fields> & FieldDefinitionsForInput<ContractSchemaInput<InputSchema>> & FieldIdentityContract<Fields>;
+    readonly fields?: CheckedFieldDefinitions<Fields, Command> & FieldDefinitionsForInput<ContractSchemaInput<InputSchema>> & FieldIdentityContract<Command, Fields>;
     readonly input: InputSchema & RawFieldInputContract<Command, Fields, InputSchema>;
     readonly success: CompletionSuccessDefinition<Command, TextEnabled>;
-    readonly failures: Failures & ClosedAtomicVariants<Failures> & FailureVariantNameContract<Failures> & FailureVariantTextContract<Command, Failures, TextEnabled>;
+    readonly failures: Failures & ClosedAtomicVariants<Failures> & FailureVariantNameContract<Command, Failures> & FailureVariantTextContract<Command, Failures, TextEnabled>;
     readonly handler: (context: CompletionHandlerContext<Command, Dependencies, Failures, ContractSchemaOutput<InputSchema>>) => CompletionFact<Command> | FailureFactUnion<Command, Failures> | Promise<CompletionFact<Command> | FailureFactUnion<Command, Failures>>;
 }
 export interface DataRootCommandDefinition<Command extends string, Dependencies, Fields extends FieldDefinitions, InputSchema extends ContractSchema, Variants extends DataVariantDefinitions, Failures extends FailureVariantDefinitions> {
@@ -404,14 +605,13 @@ export interface DataRootCommandDefinition<Command extends string, Dependencies,
     readonly name: string;
     readonly description: string;
     readonly helpSupplement?: TextLines;
-    readonly usageConstraints?: readonly UsageConstraint<Fields>[];
-    readonly fields: CheckedFieldDefinitions<Fields> & FieldDefinitionsForInput<ContractSchemaInput<InputSchema>> & FieldIdentityContract<Fields>;
+    readonly fields: CheckedFieldDefinitions<Fields, Command> & FieldDefinitionsForInput<ContractSchemaInput<InputSchema>> & FieldIdentityContract<Command, Fields>;
     readonly input: InputSchema & RawFieldInputContract<Command, Fields, InputSchema>;
     readonly success: Readonly<{
         readonly kind: "data";
-        readonly variants: Variants & ClosedAtomicVariants<Variants> & DataVariantNameContract<Variants>;
+        readonly variants: Variants & ClosedAtomicVariants<Variants> & DataVariantNameContract<Command, Variants>;
     }>;
-    readonly failures: Failures & ClosedAtomicVariants<Failures> & FailureVariantNameContract<Failures>;
+    readonly failures: Failures & ClosedAtomicVariants<Failures> & FailureVariantNameContract<Command, Failures>;
     readonly handler: (context: DataHandlerContext<Command, Dependencies, ContractSchemaOutput<InputSchema>, Variants, Failures>) => DataFactUnion<Command, Variants> | FailureFactUnion<Command, Failures> | Promise<DataFactUnion<Command, Variants> | FailureFactUnion<Command, Failures>>;
 }
 export interface StreamRootCommandDefinition<Command extends string, Dependencies, Fields extends FieldDefinitions, InputSchema extends ContractSchema, Records extends StreamRecordDefinitions, Failures extends FailureVariantDefinitions, TextEnabled extends boolean = boolean> {
@@ -419,12 +619,11 @@ export interface StreamRootCommandDefinition<Command extends string, Dependencie
     readonly name: string;
     readonly description: string;
     readonly helpSupplement?: TextLines;
-    readonly usageConstraints?: readonly UsageConstraint<Fields>[];
-    readonly fields?: CheckedFieldDefinitions<Fields> & FieldDefinitionsForInput<ContractSchemaInput<InputSchema>> & FieldIdentityContract<Fields>;
+    readonly fields?: CheckedFieldDefinitions<Fields, Command> & FieldDefinitionsForInput<ContractSchemaInput<InputSchema>> & FieldIdentityContract<Command, Fields>;
     readonly input: InputSchema & RawFieldInputContract<Command, Fields, InputSchema>;
     readonly success: Readonly<{
         readonly kind: "stream";
-        readonly records: Records & StreamRecordDefinitions<TextEnabled> & ClosedStreamRecords<Records> & StreamRecordNameContract<Records>;
+        readonly records: Records & StreamRecordDefinitions<TextEnabled> & ClosedStreamRecords<Records> & StreamRecordNameContract<Command, Records>;
     }> & (TextEnabled extends true ? Readonly<{
         readonly text: CompletionTextPresenter;
     }> : TextEnabled extends false ? Readonly<{
@@ -432,7 +631,7 @@ export interface StreamRootCommandDefinition<Command extends string, Dependencie
     }> : Readonly<{
         readonly text?: CompletionTextPresenter;
     }>);
-    readonly failures: Failures & ClosedAtomicVariants<Failures> & FailureVariantNameContract<Failures>;
+    readonly failures: Failures & ClosedAtomicVariants<Failures> & FailureVariantNameContract<Command, Failures>;
     readonly handler: (context: StreamHandlerContext<Command, Dependencies, ContractSchemaOutput<InputSchema>, Records, Failures>) => AsyncGenerator<StreamRecordFactUnion<Command, Records>, StreamSuccessFact<Command> | FailureFactUnion<Command, Failures>, void>;
 }
 export type RootCommandDefinition<Command extends string, Dependencies> = CompletionRootCommandDefinition<Command, Dependencies, FailureVariantDefinitions, FieldDefinitions, ContractSchema> | DataRootCommandDefinition<Command, Dependencies, FieldDefinitions, ContractSchema, DataVariantDefinitions, FailureVariantDefinitions> | StreamRootCommandDefinition<Command, Dependencies, FieldDefinitions, ContractSchema, StreamRecordDefinitions, FailureVariantDefinitions>;
@@ -454,13 +653,17 @@ export interface CommandGroupDefinition<Parent extends string = string> {
     readonly helpSupplement?: TextLines;
     readonly handler?: never;
 }
-type HierarchyCommandFacts<Parent extends string = string> = Readonly<{
+type HierarchyCommandFactsDefinition<Parent extends string = string> = Readonly<{
     readonly kind: "command";
     readonly parent: Parent;
     readonly aliases?: readonly string[];
     readonly helpSupplement?: TextLines;
-    readonly [executableCommandType]: true;
 }>;
+type HierarchyCommandFacts<Parent extends string = string> = HierarchyCommandFactsDefinition<Parent> & CommandCombinationBrand;
+export declare abstract class CommandCombinationBrand {
+    private readonly commandCombinationBrand;
+}
+export type CommandCombination<Command extends string, Definition extends object, Parent extends string = string> = Readonly<Record<Command, Definition & HierarchyCommandFacts<Parent>>>;
 export type ExecutableCommandDefinition<Command extends string = string, Dependencies = unknown> = (Omit<CompletionRootCommandDefinition<Command, Dependencies, FailureVariantDefinitions, FieldDefinitions, ContractSchema>, "kind"> & HierarchyCommandFacts) | (Omit<DataRootCommandDefinition<Command, Dependencies, FieldDefinitions, ContractSchema, DataVariantDefinitions, FailureVariantDefinitions>, "kind"> & HierarchyCommandFacts) | (Omit<StreamRootCommandDefinition<Command, Dependencies, FieldDefinitions, ContractSchema, StreamRecordDefinitions, FailureVariantDefinitions>, "kind"> & HierarchyCommandFacts);
 export type CommandNodeDefinition = CommandGroupDefinition | (HierarchyCommandFacts & Readonly<{
     readonly name: string;
@@ -538,82 +741,402 @@ type HierarchyInputIssues<Commands> = {
 type HierarchyUsageConstraints<Node> = Node extends Readonly<{
     readonly usageConstraints?: infer Constraints;
 }> ? Exclude<Constraints, undefined> : never;
-type UsageConstraintValueFields<Values> = Values extends readonly (infer Value)[] ? Value extends Readonly<{
+type ConditionalUsageConstraints<Constraints> = Constraints extends readonly (infer Constraint)[] ? Extract<Constraint, Readonly<{
+    readonly kind: "when";
+}>> : never;
+type UsageConstraintFactsForNode<Node> = ConditionalUsageConstraints<HierarchyUsageConstraints<Node>>;
+type HierarchyUsageConstraintFacts<Commands> = Readonly<{
+    [Command in keyof Commands]: UsageConstraintFactsForNode<Commands[Command]>;
+}>;
+type RootUsageConstraintFacts<Root extends string, Commands> = Readonly<{
+    [Command in Root]: RootNodeFromCommands<Root, Commands> extends infer Node ? UsageConstraintFactsForNode<Node> : never;
+}>;
+type UsageConstraintFactFields<Facts> = Facts extends readonly (infer Fact)[] ? Fact extends Readonly<{
     readonly field: infer Field extends string;
 }> ? Field : never : never;
-type InvalidForbiddenCombinationValue<Command extends string, Value, Fields extends FieldDefinitions> = Value extends Readonly<{
-    readonly field: infer Field extends keyof Fields & string;
+type LastRequiredTupleItem<Items extends readonly unknown[]> = Items extends readonly [...unknown[], infer Last] ? Last : never;
+type PopRequiredTupleItem<Items extends readonly unknown[]> = Items extends readonly [...infer Prefix, unknown] ? readonly [...Prefix] : never;
+type StaticallyKnownTupleSuffixItems<Items extends readonly unknown[]> = [
+    LastRequiredTupleItem<Items>
+] extends [never] ? never : string extends LastRequiredTupleItem<Items> ? StaticallyKnownTupleSuffixItems<PopRequiredTupleItem<Items>> : LastRequiredTupleItem<Items> | StaticallyKnownTupleSuffixItems<PopRequiredTupleItem<Items>>;
+type StaticallyKnownUsageFact<Fact> = Fact extends Readonly<{
+    readonly field: infer Field extends string;
+}> ? string extends Field ? never : IsUnion<Field> extends true ? never : Fact : never;
+type StaticallyKnownUsageTupleFacts<Facts extends readonly unknown[]> = Facts extends readonly [infer Fact, ...infer Remaining] ? StaticallyKnownUsageFact<Fact> | StaticallyKnownUsageTupleFacts<Remaining> : StaticallyKnownTupleSuffixItems<Facts> extends infer Fact ? StaticallyKnownUsageFact<Fact> : never;
+type IsNarrowUsageFactValue<Value> = [Value] extends [string | boolean] ? string extends Value ? false : boolean extends Value ? false : true : false;
+type AreDisjointKnownUsageFactValues<Left, Right> = IsNarrowUsageFactValue<Left> extends true ? IsNarrowUsageFactValue<Right> extends true ? [Left & Right] extends [never] ? true : false : false : false;
+type ConflictingEqualsUsageFactFields<First, Others> = First extends Readonly<{
+    readonly kind: "equals";
+    readonly field: infer Field extends string;
+    readonly value: infer Value;
+}> ? Extract<Others, Readonly<{
+    readonly kind: "equals";
+    readonly field: Field;
+}>> extends infer SameFieldFacts ? SameFieldFacts extends Readonly<{
+    readonly kind: "equals";
+    readonly value: infer OtherValue;
+}> ? AreDisjointKnownUsageFactValues<Value, OtherValue> extends true ? Field : never : never : never : never;
+type ContradictoryUsageFactUnionFields<Fact, Facts = Fact> = Fact extends unknown ? ConflictingEqualsUsageFactFields<Fact, Exclude<Facts, Fact>> : never;
+type ContradictoryUsageFactFields<Facts extends readonly unknown[]> = Facts extends unknown ? ContradictoryUsageFactUnionFields<StaticallyKnownUsageTupleFacts<Facts>> : never;
+type InvalidUsageFactForFields<Command extends string, Fact, Fields extends FieldDefinitions, Input, Constraint extends "when" | "forbiddenCombination" = "forbiddenCombination"> = Fact extends Readonly<{
+    readonly kind: "present";
+    readonly field: infer Field extends string;
+}> ? Exclude<Field, keyof Fields> extends never ? never : ContractTypeError<"unknownUsageConstraintField", Readonly<{
+    readonly command: Command;
+    readonly constraint: Constraint;
+    readonly member: "all.field";
+    readonly field: Exclude<Field, keyof Fields>;
+}>> : Fact extends Readonly<{
+    readonly kind: "equals";
+    readonly field: infer Field extends string;
     readonly value: infer Actual;
-}> ? Fields[Field] extends FlagDefinition ? Actual extends boolean ? never : ContractTypeError<"invalidUsageConstraintValue", Readonly<{
+}> ? Exclude<Field, keyof Fields> extends never ? Field extends keyof Fields & string ? [UsageFactValue<Fields, Input, Field>] extends [never] ? ContractTypeError<"inapplicableUsageConstraintField", Readonly<{
     readonly command: Command;
-    readonly constraint: "forbiddenCombination";
-    readonly member: "values.value";
+    readonly constraint: Constraint;
+    readonly member: "all.field";
     readonly field: Field;
-    readonly actual: Actual;
-    readonly expected: boolean;
-}>> : Fields[Field] extends ValueOptionDefinition ? Actual extends string ? never : ContractTypeError<"invalidUsageConstraintValue", Readonly<{
+    readonly kind: Fields[Field]["kind"];
+}>> : [Actual] extends [UsageFactValue<Fields, Input, Field>] ? never : ContractTypeError<"invalidUsageConstraintValue", Readonly<{
     readonly command: Command;
-    readonly constraint: "forbiddenCombination";
-    readonly member: "values.value";
+    readonly constraint: Constraint;
+    readonly member: "all.value";
     readonly field: Field;
     readonly actual: Actual;
-    readonly expected: string;
-}>> : ContractTypeError<"inapplicableUsageConstraintField", Readonly<{
+    readonly expected: UsageFactValue<Fields, Input, Field>;
+}>> : never : ContractTypeError<"unknownUsageConstraintField", Readonly<{
+    readonly command: Command;
+    readonly constraint: Constraint;
+    readonly member: "all.field";
+    readonly field: Exclude<Field, keyof Fields>;
+}>> : ContractTypeError<"invalidUsageConstraint", Readonly<{
+    readonly command: Command;
+    readonly constraint: Constraint;
+    readonly member: "all";
+}>>;
+type InvalidForbiddenCombinationFacts<Command extends string, Facts extends readonly unknown[], Fields extends FieldDefinitions, Input> = Facts extends readonly [infer Fact, ...infer Remaining] ? [InvalidUsageFactForFields<Command, Fact, Fields, Input>] extends [never] ? InvalidForbiddenCombinationFacts<Command, Remaining, Fields, Input> : InvalidUsageFactForFields<Command, Fact, Fields, Input> : InvalidUsageFactForFields<Command, StaticallyKnownUsageTupleFacts<Facts>, Fields, Input>;
+type InvalidWhenFacts<Command extends string, Facts extends readonly unknown[], Fields extends FieldDefinitions, Input> = Facts extends readonly [infer Fact, ...infer Remaining] ? [InvalidUsageFactForFields<Command, Fact, Fields, Input, "when">] extends [
+    never
+] ? InvalidWhenFacts<Command, Remaining, Fields, Input> : InvalidUsageFactForFields<Command, Fact, Fields, Input, "when"> : InvalidUsageFactForFields<Command, StaticallyKnownUsageTupleFacts<Facts>, Fields, Input, "when">;
+type UnknownUsageFactProperty<Fact> = Fact extends Readonly<{
+    readonly kind: "present";
+}> ? Exclude<keyof Fact, (typeof definitionPropertyKeys.usage.fact.present)[number]> : Fact extends Readonly<{
+    readonly kind: "equals";
+}> ? Exclude<keyof Fact, (typeof definitionPropertyKeys.usage.fact.equals)[number]> : never;
+type UnknownUsageFactProperties<Facts extends readonly unknown[]> = UnknownUsageFactProperty<Facts[number]>;
+type UnknownForbiddenCombinationConstraintProperties<Constraint> = Exclude<keyof Constraint, (typeof definitionPropertyKeys.usage.forbiddenCombination)[number]>;
+type UnknownForbiddenCombinationFactProperties<Facts> = Facts extends readonly unknown[] ? UnknownUsageFactProperties<Facts> : never;
+type InvalidForbiddenCombinationShape<Command extends string, Constraint, Facts> = ([UnknownForbiddenCombinationConstraintProperties<Constraint>] extends [
+    never
+] ? never : ContractTypeError<"unknownDefinitionProperty", Readonly<{
     readonly command: Command;
     readonly constraint: "forbiddenCombination";
-    readonly member: "values.field";
-    readonly field: Field;
-    readonly kind: Fields[Field]["kind"];
+    readonly member: "forbiddenCombination";
+    readonly property: UnknownForbiddenCombinationConstraintProperties<Constraint>;
+}>>) | ([UnknownForbiddenCombinationFactProperties<Facts>] extends [never] ? never : ContractTypeError<"unknownDefinitionProperty", Readonly<{
+    readonly command: Command;
+    readonly constraint: "forbiddenCombination";
+    readonly member: "all";
+    readonly property: UnknownForbiddenCombinationFactProperties<Facts>;
+}>>);
+type UnknownWhenEffectProperty<Effect> = Effect extends object ? Exclude<keyof Effect, (typeof definitionPropertyKeys.usage.effect)[number]> : never;
+type UnknownWhenConstraintProperty<Constraint> = Constraint extends object ? Exclude<keyof Constraint, (typeof definitionPropertyKeys.usage.when)[number]> : never;
+type InvalidWhenEffectProperties<Command extends string, Branch, Effect> = Effect extends object ? [UnknownWhenEffectProperty<Effect>] extends [never] ? never : ContractTypeError<"unknownDefinitionProperty", Readonly<{
+    readonly command: Command;
+    readonly constraint: "when";
+    readonly member: Branch;
+    readonly property: UnknownWhenEffectProperty<Effect>;
 }>> : never;
-type InvalidForbiddenCombinationValues<Command extends string, Values extends readonly unknown[], Fields extends FieldDefinitions> = InvalidForbiddenCombinationValue<Command, Values[number], Fields>;
-type InvalidUsageConstraintForFields<Command extends string, Constraint, Fields extends FieldDefinitions> = Constraint extends Readonly<{
-    readonly kind: "requires";
-    readonly field: infer Field extends string;
-    readonly requires: infer Required extends string;
-}> ? Exclude<Field, keyof Fields> extends never ? Exclude<Required, keyof Fields> extends never ? never : ContractTypeError<"unknownUsageConstraintField", Readonly<{
+type InvalidWhenProperties<Command extends string, Constraint, Facts> = ([UnknownWhenConstraintProperty<Constraint>] extends [never] ? never : ContractTypeError<"unknownDefinitionProperty", Readonly<{
     readonly command: Command;
-    readonly constraint: "requires";
-    readonly member: "requires";
-    readonly field: Exclude<Required, keyof Fields>;
-}>> : ContractTypeError<"unknownUsageConstraintField", Readonly<{
+    readonly constraint: "when";
+    readonly member: "when";
+    readonly property: UnknownWhenConstraintProperty<Constraint>;
+}>>) | (Facts extends readonly unknown[] ? [UnknownUsageFactProperties<Facts>] extends [never] ? never : ContractTypeError<"unknownDefinitionProperty", Readonly<{
     readonly command: Command;
-    readonly constraint: "requires";
-    readonly member: "field";
-    readonly field: Exclude<Field, keyof Fields>;
-}>> : Constraint extends Readonly<{
-    readonly kind: "exclusive";
-    readonly fields: readonly (infer Field extends string)[];
-}> ? Exclude<Field, keyof Fields> extends never ? never : ContractTypeError<"unknownUsageConstraintField", Readonly<{
+    readonly constraint: "when";
+    readonly member: "all";
+    readonly property: UnknownUsageFactProperties<Facts>;
+}>> : never) | (Constraint extends Readonly<{
+    readonly onMatch?: infer OnMatch;
+}> ? InvalidWhenEffectProperties<Command, "onMatch", OnMatch> : never) | (Constraint extends Readonly<{
+    readonly otherwise?: infer Otherwise;
+}> ? InvalidWhenEffectProperties<Command, "otherwise", Otherwise> : never);
+type InvalidClosedUsageConstraintProperties<Command extends string, Constraint> = Constraint extends Readonly<{
+    readonly kind: "when";
+    readonly all: infer Facts;
+}> ? InvalidWhenProperties<Command, Constraint, Facts> : Constraint extends Readonly<{
+    readonly kind: "forbiddenCombination";
+    readonly all: infer Facts;
+}> ? InvalidForbiddenCombinationShape<Command, Constraint, Facts> : Constraint extends Readonly<{
+    readonly kind: "count";
+}> ? [
+    Exclude<keyof Constraint, (typeof definitionPropertyKeys.usage.count)[number]>
+] extends [never] ? never : ContractTypeError<"unknownDefinitionProperty", Readonly<{
+    readonly command: Command;
+    readonly constraint: "count";
+    readonly member: "count";
+    readonly property: Exclude<keyof Constraint, (typeof definitionPropertyKeys.usage.count)[number]>;
+}>> : never;
+type CountDigit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+type CountDigitTuple = {
+    readonly "0": readonly [];
+    readonly "1": readonly [unknown];
+    readonly "2": readonly [unknown, unknown];
+    readonly "3": readonly [unknown, unknown, unknown];
+    readonly "4": readonly [unknown, unknown, unknown, unknown];
+    readonly "5": readonly [unknown, unknown, unknown, unknown, unknown];
+    readonly "6": readonly [unknown, unknown, unknown, unknown, unknown, unknown];
+    readonly "7": readonly [
+        unknown,
+        unknown,
+        unknown,
+        unknown,
+        unknown,
+        unknown,
+        unknown
+    ];
+    readonly "8": readonly [
+        unknown,
+        unknown,
+        unknown,
+        unknown,
+        unknown,
+        unknown,
+        unknown,
+        unknown
+    ];
+    readonly "9": readonly [
+        unknown,
+        unknown,
+        unknown,
+        unknown,
+        unknown,
+        unknown,
+        unknown,
+        unknown,
+        unknown
+    ];
+};
+type CountStringLength<Value extends string, Cursor extends readonly unknown[] = []> = Value extends `${infer _Character}${infer Remaining}` ? CountStringLength<Remaining, [...Cursor, unknown]> : Cursor;
+type CompareCountDigit<Left extends CountDigit, Right extends CountDigit> = Left extends Right ? "equal" : CountDigitTuple[Left] extends readonly [
+    ...CountDigitTuple[Right],
+    unknown,
+    ...unknown[]
+] ? "greater" : "less";
+type CompareCountDigitStrings<Left extends string, Right extends string> = Left extends `${infer LeftDigit extends CountDigit}${infer LeftRest}` ? Right extends `${infer RightDigit extends CountDigit}${infer RightRest}` ? CompareCountDigit<LeftDigit, RightDigit> extends infer Comparison ? Comparison extends "equal" ? CompareCountDigitStrings<LeftRest, RightRest> : Comparison : never : "greater" : Right extends "" ? "equal" : "less";
+type CompareCountStringLengths<Left extends string, Right extends string> = CountStringLength<Left> extends readonly [
+    ...CountStringLength<Right>,
+    ...infer Remaining
+] ? Remaining extends readonly [] ? "equal" : "greater" : "less";
+type CompareCountUnsignedIntegers<Left extends string, Right extends string> = CompareCountStringLengths<Left, Right> extends infer LengthOrder ? LengthOrder extends "equal" ? CompareCountDigitStrings<Left, Right> : LengthOrder : never;
+type CompareCountFractions<Left extends string, Right extends string> = Left extends `${infer LeftDigit extends CountDigit}${infer LeftRest}` ? Right extends `${infer RightDigit extends CountDigit}${infer RightRest}` ? CompareCountDigit<LeftDigit, RightDigit> extends infer Comparison ? Comparison extends "equal" ? CompareCountFractions<LeftRest, RightRest> : Comparison : never : CompareCountDigit<LeftDigit, "0"> extends infer Comparison ? Comparison extends "equal" ? CompareCountFractions<LeftRest, ""> : Comparison : never : Right extends `${infer RightDigit extends CountDigit}${infer RightRest}` ? CompareCountDigit<"0", RightDigit> extends infer Comparison ? Comparison extends "equal" ? CompareCountFractions<"", RightRest> : Comparison : never : "equal";
+type CompareCountCoefficients<Left extends string, Right extends string> = Left extends `${infer LeftWhole extends CountDigit}.${infer LeftFraction}` ? Right extends `${infer RightWhole extends CountDigit}.${infer RightFraction}` ? CompareCountDigit<LeftWhole, RightWhole> extends infer Comparison ? Comparison extends "equal" ? CompareCountFractions<LeftFraction, RightFraction> : Comparison : never : never : never;
+type NormalizeCountCoefficient<Coefficient extends string> = Coefficient extends `${string}.${string}` ? Coefficient : `${Coefficient}.0`;
+type CountScientificParts<Value extends number> = `${Value}` extends `${infer Coefficient}e+${infer Exponent}` ? Readonly<{
+    readonly exponent: Exponent;
+    readonly coefficient: NormalizeCountCoefficient<Coefficient>;
+}> : `${Value}` extends `${infer First extends CountDigit}${infer Remaining}` ? Readonly<{
+    readonly exponent: CountStringLength<`${Value}`> extends readonly [
+        ...infer RemainingDigits,
+        unknown
+    ] ? `${RemainingDigits["length"]}` : "0";
+    readonly coefficient: `${First}.${Remaining extends "" ? "0" : Remaining}`;
+}> : never;
+type CompareCountNumbers<Left extends number, Right extends number> = CountScientificParts<Left> extends Readonly<{
+    readonly exponent: infer LeftExponent extends string;
+    readonly coefficient: infer LeftCoefficient extends string;
+}> ? CountScientificParts<Right> extends Readonly<{
+    readonly exponent: infer RightExponent extends string;
+    readonly coefficient: infer RightCoefficient extends string;
+}> ? CompareCountUnsignedIntegers<LeftExponent, RightExponent> extends infer ExponentOrder ? ExponentOrder extends "equal" ? CompareCountCoefficients<LeftCoefficient, RightCoefficient> : ExponentOrder : never : never : never;
+type IsCountIntegerLiteral<Value extends number> = `${Value}` extends `${bigint}` ? true : `${Value}` extends `${infer Coefficient}e+${infer Exponent}` ? Coefficient extends `${bigint}` ? true : Coefficient extends `${string}.${infer Fraction}` ? CompareCountUnsignedIntegers<Exponent, `${CountStringLength<Fraction>["length"]}`> extends "less" ? false : true : false : false;
+type CountFieldRange<Fields extends readonly unknown[], Cursor extends readonly unknown[] = []> = number extends Fields["length"] ? number : Cursor["length"] extends Fields["length"] ? Cursor["length"] : Cursor["length"] | CountFieldRange<Fields, [...Cursor, unknown]>;
+type CountFieldMaximum<Fields extends readonly unknown[]> = Fields["length"];
+type CountFieldDuplicates<Fields extends readonly unknown[], Seen = never> = Fields extends readonly [infer Field, ...infer Remaining] ? string extends Field ? CountFieldDuplicates<Remaining, Seen> : IsUnion<Field> extends true ? CountFieldDuplicates<Remaining, Seen> : Field extends Seen ? Field : CountFieldDuplicates<Remaining, Seen | Field> : CountFieldSuffixDuplicates<Fields, Seen>;
+type CountFieldSuffixDuplicates<Fields extends readonly unknown[], Seen> = [
+    LastRequiredTupleItem<Fields>
+] extends [never] ? never : LastRequiredTupleItem<Fields> extends infer Field ? string extends Field ? CountFieldSuffixDuplicates<PopRequiredTupleItem<Fields>, Seen> : IsUnion<Field> extends true ? CountFieldSuffixDuplicates<PopRequiredTupleItem<Fields>, Seen> : Field extends Seen ? Field | CountFieldSuffixDuplicates<PopRequiredTupleItem<Fields>, Seen | Field> : CountFieldSuffixDuplicates<PopRequiredTupleItem<Fields>, Seen | Field> : never;
+type CountEndpoint<Constraint, Member extends "min" | "max"> = Member extends keyof Constraint ? Exclude<Constraint[Member], undefined> : never;
+type CountEndpointIssue<Command extends string, Member extends "min" | "max", Value, Allowed extends number, Maximum extends number> = IsAny<Value> extends true ? never : number extends Value ? never : Value extends number ? `${Value}` extends `-${string}` ? ContractTypeError<"invalidCountConstraint", Readonly<{
+    readonly command: Command;
+    readonly constraint: "count";
+    readonly member: Member;
+    readonly reason: "nonNegative";
+    readonly actual: Value;
+}>> : IsCountIntegerLiteral<Value> extends true ? Exclude<Value, Allowed> extends infer Outside extends number ? [Outside] extends [never] ? never : ContractTypeError<"invalidCountConstraint", Readonly<{
+    readonly command: Command;
+    readonly constraint: "count";
+    readonly member: Member;
+    readonly reason: "fieldCount";
+    readonly actual: Outside;
+    readonly maximum: Maximum;
+}>> : never : ContractTypeError<"invalidCountConstraint", Readonly<{
+    readonly command: Command;
+    readonly constraint: "count";
+    readonly member: Member;
+    readonly reason: "integer";
+    readonly actual: Value;
+}>> : never;
+type CountEndpointValidationIssue<Command extends string, Constraint, Fields extends readonly unknown[], Member extends "min" | "max"> = CountEndpointIssue<Command, Member, CountEndpoint<Constraint, Member>, CountFieldRange<Fields>, CountFieldMaximum<Fields>>;
+type CountRangeOrderIssue<Command extends string, Minimum, Maximum> = Minimum extends number ? Maximum extends number ? CompareCountNumbers<Minimum, Maximum> extends "greater" ? ContractTypeError<"invalidCountConstraint", Readonly<{
+    readonly command: Command;
+    readonly constraint: "count";
+    readonly member: "min";
+    readonly reason: "ordered";
+    readonly actual: Minimum;
+    readonly maximum: Maximum;
+}>> : never : never : never;
+type StaticallyKnownCountTupleFields<Fields extends readonly unknown[]> = Fields extends readonly [infer Field, ...infer Remaining] ? string extends Field ? StaticallyKnownCountTupleFields<Remaining> : Field | StaticallyKnownCountTupleFields<Remaining> : StaticallyKnownTupleSuffixItems<Fields>;
+type CountUnknownFieldIssue<Command extends string, Fields extends FieldDefinitions, CountFields extends readonly unknown[]> = Exclude<StaticallyKnownCountTupleFields<CountFields>, keyof Fields> extends infer UnknownField ? [UnknownField] extends [never] ? never : ContractTypeError<"unknownUsageConstraintField", Readonly<{
     readonly command: Command;
-    readonly constraint: "exclusive";
+    readonly constraint: "count";
     readonly member: "fields";
+    readonly field: Extract<UnknownField, string>;
+}>> : never;
+type CountDuplicateFieldIssue<Command extends string, CountFields extends readonly unknown[]> = [CountFieldDuplicates<CountFields>] extends [never] ? never : ContractTypeError<"invalidCountConstraint", Readonly<{
+    readonly command: Command;
+    readonly constraint: "count";
+    readonly member: "fields";
+    readonly reason: "duplicateFields";
+    readonly fields: CountFieldDuplicates<CountFields>;
+}>>;
+type CountEndpointRangeIssue<Command extends string, Constraint, CountFields extends readonly unknown[]> = [
+    CountEndpoint<Constraint, "min"> | CountEndpoint<Constraint, "max">
+] extends [never] ? ContractTypeError<"invalidCountConstraint", Readonly<{
+    readonly command: Command;
+    readonly constraint: "count";
+    readonly member: "min";
+    readonly reason: "endpointRequired";
+}>> : [
+    CountEndpointValidationIssue<Command, Constraint, CountFields, "min">
+] extends [never] ? [
+    CountEndpointValidationIssue<Command, Constraint, CountFields, "max">
+] extends [never] ? number extends CountEndpoint<Constraint, "min"> | CountEndpoint<Constraint, "max"> ? never : CountRangeOrderIssue<Command, CountEndpoint<Constraint, "min">, CountEndpoint<Constraint, "max">> : CountEndpointValidationIssue<Command, Constraint, CountFields, "max"> : CountEndpointValidationIssue<Command, Constraint, CountFields, "min">;
+type InvalidCountConstraintForFields<Command extends string, Constraint, Fields extends FieldDefinitions> = Constraint extends Readonly<{
+    readonly fields: infer CountFields extends readonly unknown[];
+}> ? [CountUnknownFieldIssue<Command, Fields, CountFields>] extends [never] ? [CountFields["length"]] extends [0] ? ContractTypeError<"invalidCountConstraint", Readonly<{
+    readonly command: Command;
+    readonly constraint: "count";
+    readonly member: "fields";
+    readonly reason: "nonEmpty";
+}>> : [CountDuplicateFieldIssue<Command, CountFields>] extends [never] ? CountEndpointRangeIssue<Command, Constraint, CountFields> : CountDuplicateFieldIssue<Command, CountFields> : CountUnknownFieldIssue<Command, Fields, CountFields> : ContractTypeError<"invalidCountConstraint", Readonly<{
+    readonly command: Command;
+    readonly constraint: "count";
+    readonly member: "fields";
+    readonly reason: "nonEmpty";
+}>>;
+type UsageEffectFields<Effect, Member extends "require" | "forbid"> = Effect extends Readonly<Record<Member, readonly unknown[]>> ? StaticallyKnownCountTupleFields<Extract<Effect[Member], readonly unknown[]>> : never;
+type UsageEffectFieldArrays<Effect, Member extends "require" | "forbid"> = Effect extends object ? Member extends keyof Effect ? {} extends Pick<Effect, Member> ? never : Extract<Effect[Member], readonly unknown[]> : never : never;
+type StaticallyGuaranteedUsageTupleFields<Fields extends readonly unknown[]> = Fields extends readonly [infer Field, ...infer Remaining] ? string extends Field ? StaticallyGuaranteedUsageTupleFields<Remaining> : IsUnion<Field> extends true ? StaticallyGuaranteedUsageTupleFields<Remaining> : Field extends string ? Field | StaticallyGuaranteedUsageTupleFields<Remaining> : StaticallyGuaranteedUsageTupleFields<Remaining> : StaticallyGuaranteedUsageTupleSuffixFields<Fields>;
+type StaticallyGuaranteedUsageTupleSuffixFields<Fields extends readonly unknown[]> = [LastRequiredTupleItem<Fields>] extends [never] ? never : LastRequiredTupleItem<Fields> extends infer Field ? string extends Field ? StaticallyGuaranteedUsageTupleSuffixFields<PopRequiredTupleItem<Fields>> : IsUnion<Field> extends true ? StaticallyGuaranteedUsageTupleSuffixFields<PopRequiredTupleItem<Fields>> : Field extends string ? Field | StaticallyGuaranteedUsageTupleSuffixFields<PopRequiredTupleItem<Fields>> : StaticallyGuaranteedUsageTupleSuffixFields<PopRequiredTupleItem<Fields>> : never;
+type UsageArrayBranchesMissingGuaranteedField<Arrays, Field extends string> = Arrays extends readonly unknown[] ? Field extends StaticallyGuaranteedUsageTupleFields<Arrays> ? never : Arrays : never;
+type GuaranteedUsageFieldsAcrossArrays<Arrays> = StaticallyKnownCountTupleFields<Extract<Arrays, readonly unknown[]>> extends infer Candidate ? Candidate extends string ? [UsageArrayBranchesMissingGuaranteedField<Arrays, Candidate>] extends [
+    never
+] ? Candidate : never : never : never;
+type GuaranteedUsageEffectFields<Effect, Member extends "require" | "forbid"> = GuaranteedUsageFieldsAcrossArrays<UsageEffectFieldArrays<Effect, Member>>;
+type UnknownUsageEffectFields<Command extends string, Branch extends "onMatch" | "otherwise", Member extends "require" | "forbid", Effect, Fields extends FieldDefinitions> = UsageEffectFields<Effect, Member> extends infer Field extends string ? string extends Field ? never : Exclude<Field, keyof Fields> extends never ? never : ContractTypeError<"unknownUsageConstraintField", Readonly<{
+    readonly command: Command;
+    readonly constraint: "when";
+    readonly member: `${Branch}.${Member}`;
     readonly field: Exclude<Field, keyof Fields>;
-}>> : Constraint extends Readonly<{
+}>> : never;
+type DefinitelyEmptyUsageEffectMember<Effect, Member extends "require" | "forbid"> = Effect extends undefined ? true : Effect extends object ? Member extends keyof Effect ? [Exclude<Effect[Member], undefined>] extends [never] ? true : Exclude<Effect[Member], undefined> extends readonly [] ? true : false : true : true;
+type DefinitelyEmptyUsageEffect<Effect> = DefinitelyEmptyUsageEffectMember<Effect, "require"> extends true ? DefinitelyEmptyUsageEffectMember<Effect, "forbid"> extends true ? true : false : false;
+type ContradictoryUsageEffectFields<Effect> = Effect extends unknown ? Extract<GuaranteedUsageEffectFields<Effect, "require">, GuaranteedUsageEffectFields<Effect, "forbid">> : never;
+type InvalidUsageEffectForFields<Command extends string, Branch extends "onMatch" | "otherwise", Effect, Fields extends FieldDefinitions> = UnknownUsageEffectFields<Command, Branch, "require", Effect, Fields> | UnknownUsageEffectFields<Command, Branch, "forbid", Effect, Fields> | ([ContradictoryUsageEffectFields<Effect>] extends [never] ? never : ContractTypeError<"contradictoryUsageConstraint", Readonly<{
+    readonly command: Command;
+    readonly constraint: "when";
+    readonly member: Branch;
+    readonly fields: ContradictoryUsageEffectFields<Effect>;
+}>>);
+type WhenEffectForConstraint<Constraint, Branch extends "onMatch" | "otherwise"> = Constraint extends object ? Branch extends keyof Constraint ? Exclude<Constraint[Branch], undefined> : undefined : undefined;
+type InvalidWhenHasNoEffects<Command extends string, Constraint> = Constraint extends unknown ? [
+    DefinitelyEmptyUsageEffect<WhenEffectForConstraint<Constraint, "onMatch">>
+] extends [true] ? [
+    DefinitelyEmptyUsageEffect<WhenEffectForConstraint<Constraint, "otherwise">>
+] extends [true] ? ContractTypeError<"invalidUsageConstraint", Readonly<{
+    readonly command: Command;
+    readonly constraint: "when";
+    readonly member: "effects";
+}>> : never : never : never;
+type InvalidUsageConstraintForFields<Command extends string, Constraint, Fields extends FieldDefinitions, Input> = Constraint extends Readonly<{
+    readonly kind: "when";
+    readonly all: infer Facts extends readonly unknown[];
+}> ? [InvalidWhenProperties<Command, Constraint, Facts>] extends [never] ? Facts extends readonly [] ? ContractTypeError<"invalidUsageConstraint", Readonly<{
+    readonly command: Command;
+    readonly constraint: "when";
+    readonly member: "all";
+}>> : [InvalidWhenFacts<Command, Facts, Fields, Input>] extends [never] ? Exclude<UsageConstraintFactFields<Facts>, keyof Fields> extends never ? [ContradictoryUsageFactFields<Facts>] extends [never] ? [
+    InvalidUsageEffectForFields<Command, "onMatch", Constraint extends Readonly<{
+        readonly onMatch?: infer OnMatch;
+    }> ? OnMatch : undefined, Fields>
+] extends [never] ? [
+    InvalidUsageEffectForFields<Command, "otherwise", Constraint extends Readonly<{
+        readonly otherwise?: infer Otherwise;
+    }> ? Otherwise : undefined, Fields>
+] extends [never] ? [InvalidWhenHasNoEffects<Command, Constraint>] extends [
+    never
+] ? Constraint extends WhenUsageConstraint<Fields, Input> ? never : ContractTypeError<"invalidUsageConstraint", Readonly<{
+    readonly command: Command;
+    readonly constraint: "when";
+    readonly member: "when";
+}>> : InvalidWhenHasNoEffects<Command, Constraint> : InvalidUsageEffectForFields<Command, "otherwise", Constraint extends Readonly<{
+    readonly otherwise?: infer Otherwise;
+}> ? Otherwise : undefined, Fields> : InvalidUsageEffectForFields<Command, "onMatch", Constraint extends Readonly<{
+    readonly onMatch?: infer OnMatch;
+}> ? OnMatch : undefined, Fields> : ContractTypeError<"contradictoryUsageConstraint", Readonly<{
+    readonly command: Command;
+    readonly constraint: "when";
+    readonly member: "all";
+    readonly fields: ContradictoryUsageFactFields<Facts>;
+}>> : ContractTypeError<"unknownUsageConstraintField", Readonly<{
+    readonly command: Command;
+    readonly constraint: "when";
+    readonly member: "all.field";
+    readonly field: Exclude<UsageConstraintFactFields<Facts>, keyof Fields>;
+}>> : InvalidWhenFacts<Command, Facts, Fields, Input> : InvalidWhenProperties<Command, Constraint, Facts> : Constraint extends Readonly<{
+    readonly kind: "count";
+}> ? InvalidCountConstraintForFields<Command, Constraint, Fields> : Constraint extends Readonly<{
     readonly kind: "forbiddenCombination";
-    readonly values: infer Values extends readonly unknown[];
-}> ? Exclude<UsageConstraintValueFields<Values>, keyof Fields> extends never ? [
-    InvalidForbiddenCombinationValues<Command, Values, Fields>
-] extends [never] ? Constraint extends ForbiddenCombinationUsageConstraint<Fields> ? never : ContractTypeError<"invalidUsageConstraint", Readonly<{
+    readonly all: infer Facts extends readonly unknown[];
+}> ? [
+    InvalidForbiddenCombinationShape<Command, Constraint, Facts>
+] extends [never] ? Exclude<UsageConstraintFactFields<Facts>, keyof Fields> extends never ? [
+    InvalidForbiddenCombinationFacts<Command, Facts, Fields, Input>
+] extends [never] ? [ContradictoryUsageFactFields<Facts>] extends [never] ? Constraint extends ForbiddenCombinationUsageConstraint<Fields, Input> ? never : ContractTypeError<"invalidUsageConstraint", Readonly<{
+    readonly command: Command;
+    readonly constraint: "forbiddenCombination";
+    readonly member: "all";
+}>> : ContractTypeError<"contradictoryUsageConstraint", Readonly<{
+    readonly command: Command;
+    readonly constraint: "forbiddenCombination";
+    readonly member: "all";
+    readonly fields: ContradictoryUsageFactFields<Facts>;
+}>> : InvalidForbiddenCombinationFacts<Command, Facts, Fields, Input> : ContractTypeError<"unknownUsageConstraintField", Readonly<{
     readonly command: Command;
     readonly constraint: "forbiddenCombination";
-    readonly member: "values";
-}>> : InvalidForbiddenCombinationValues<Command, Values, Fields> : ContractTypeError<"unknownUsageConstraintField", Readonly<{
+    readonly member: "all.field";
+    readonly field: Exclude<UsageConstraintFactFields<Facts>, keyof Fields>;
+}>> : ContractTypeError<"invalidUsageConstraint", Readonly<{
     readonly command: Command;
     readonly constraint: "forbiddenCombination";
-    readonly member: "values.field";
-    readonly field: Exclude<UsageConstraintValueFields<Values>, keyof Fields>;
+    readonly member: "all";
 }>> : ContractTypeError<"invalidEffectiveUsageConstraint", Readonly<{
     readonly command: Command;
 }>>;
 type InvalidCommandUsageConstraintIssues<Commands> = {
     [Command in keyof Commands & string]: Commands[Command] extends Readonly<{
         readonly kind: "command" | "rootCommand";
-    }> ? HierarchyUsageConstraints<Commands[Command]> extends never ? never : HierarchyUsageConstraints<Commands[Command]> extends readonly (infer Constraint)[] ? InvalidUsageConstraintForFields<Command, Constraint, HierarchyCommandFields<Commands[Command]>> extends never ? never : InvalidUsageConstraintForFields<Command, Constraint, HierarchyCommandFields<Commands[Command]>> : ContractTypeError<"invalidEffectiveUsageConstraint", Readonly<{
+    }> ? HierarchyUsageConstraints<Commands[Command]> extends never ? never : HierarchyUsageConstraints<Commands[Command]> extends readonly (infer Constraint)[] ? InvalidUsageConstraintForFields<Command, Constraint, HierarchyCommandFields<Commands[Command]>, HierarchyCommandInputSchema<Commands[Command]>> extends never ? never : InvalidUsageConstraintForFields<Command, Constraint, HierarchyCommandFields<Commands[Command]>, HierarchyCommandInputSchema<Commands[Command]>> : ContractTypeError<"invalidEffectiveUsageConstraint", Readonly<{
         readonly command: Command;
     }>> : never;
 }[keyof Commands & string];
-type RootIdentityContract<Root extends string> = string extends Root ? unknown : IsLowerCamelCase<Root> extends true ? unknown : ContractTypeError<"commandMustBeLowerCamelCase", Readonly<{
+type HierarchyCommandInputSchema<Node> = Node extends Readonly<{
+    readonly input: infer InputSchema extends ContractSchema;
+}> ? ContractSchemaInput<InputSchema> : unknown;
+type RootIdentityContract<Root extends string> = string extends Root ? unknown : IsLowerCamelCase<Root> extends true ? unknown : ContractTypeError<"invalidCommandIdentity", Readonly<{
     readonly command: Root;
+    readonly reason: "lowerCamelCase";
 }>>;
 type RootCliDefinitionBase<Root extends string> = RootIdentityContract<Root> & {
     readonly root: Root;
@@ -771,9 +1294,22 @@ export interface ExecutableCommandManifest extends Omit<RootCommandManifest, "ki
     readonly aliases: readonly string[];
     readonly helpSupplement?: readonly string[];
 }
-export type UsageConstraintGrammar = RequiresUsageConstraint | ExclusiveUsageConstraint | ForbiddenCombinationUsageConstraint;
+export type UsageConstraintGrammar = CountUsageConstraintGrammar | WhenUsageConstraint | ForbiddenCombinationUsageConstraint;
+/** 已校验并补全默认端点的数量约束。 */
+export interface CountUsageConstraintGrammar {
+    readonly kind: "count";
+    readonly fields: readonly [string, ...string[]];
+    readonly min: number;
+    readonly max: number;
+}
+type CountHelpFact = Readonly<{
+    readonly slot: "countExactly" | "countAtLeast" | "countAtMost" | "countBetween";
+    readonly values: Readonly<Record<string, string>>;
+}>;
+/** 选择 count 事实实际使用的帮助模板及其占位符值。 */
+export declare function countHelpFactForConstraint(constraint: CountUsageConstraintGrammar): CountHelpFact;
 export interface CliManifest<Root extends string, RootKind extends CliRootKind = CliRootKind> {
-    readonly schemaVersion: "3";
+    readonly schemaVersion: "4";
     readonly root: Root;
     readonly commands: RootKind extends "rootGroup" ? Readonly<Record<string, CommandGroupManifest | ExecutableCommandManifest>> : Readonly<Record<Root, RootCommandManifest>>;
     readonly controls: CliGrammar<Root, RootKind>["controls"];
@@ -835,7 +1371,7 @@ type HierarchyExecutableKeys<Commands> = {
     }> ? Command : never;
 }[keyof Commands];
 export interface HierarchyCliManifest<Root extends string, Commands> {
-    readonly schemaVersion: "3";
+    readonly schemaVersion: "4";
     readonly root: Root;
     readonly commands: Readonly<{
         [Command in keyof Commands]: HierarchyManifestNode<Commands[Command]>;
@@ -849,7 +1385,7 @@ export interface HierarchyCliManifest<Root extends string, Commands> {
         [Command in HierarchyExecutableKeys<Commands>]: CommandWireManifest;
     }>;
 }
-export interface CliContract<Root extends string = string, Dependencies = unknown, RawInput = Readonly<Record<string, unknown>>, Result extends OutcomeFact = OutcomeFact, RootKind extends CliRootKind = CliRootKind, Commands = never> {
+export interface CliContract<Root extends string = string, Dependencies = unknown, RawInput = Readonly<Record<string, unknown>>, Result extends OutcomeFact = OutcomeFact, RootKind extends CliRootKind = CliRootKind, Commands = never, UsageFacts = Readonly<Record<string, unknown>>> {
     readonly grammar: [Commands] extends [never] ? CliGrammar<Root, RootKind> : HierarchyCliGrammar<Root, Commands>;
     readonly manifest: [Commands] extends [never] ? CliManifest<Root, RootKind> : HierarchyCliManifest<Root, Commands>;
     readonly [cliContractType]: Readonly<{
@@ -858,8 +1394,14 @@ export interface CliContract<Root extends string = string, Dependencies = unknow
         readonly result: Result;
         readonly root: Root;
         readonly commands: [Commands] extends [never] ? Root : keyof Commands;
+        readonly usageFacts: UsageFacts;
     }>;
 }
+export type CliContractUsageFacts<Contract> = Contract extends Readonly<{
+    readonly [cliContractType]: Readonly<{
+        readonly usageFacts: infer UsageFacts;
+    }>;
+}> ? UsageFacts : never;
 export type CliContractDependencies<Contract> = Contract extends CliContract<infer _Root, infer Dependencies, unknown, OutcomeFact, CliRootKind, infer _Commands> ? Dependencies : never;
 export type CliContractRawInput<Contract> = Contract extends CliContract<infer _Root, unknown, infer RawInput, OutcomeFact, CliRootKind, infer _Commands> ? RawInput : never;
 export type CliContractResult<Contract> = Contract extends CliContract<infer _Root, unknown, unknown, infer Result, CliRootKind, infer _Commands> ? Result : never;
@@ -971,28 +1513,27 @@ type RootFallbackCliDefinition<Root extends string, _Dependencies, Fields extend
             readonly name: string;
             readonly description: string;
             readonly helpSupplement?: TextLines;
-            readonly usageConstraints?: readonly UsageConstraint[];
         }> & Readonly<{
             readonly input: InputSchema & RootFallbackRawFieldInputContract<Command, Fields, InputSchema>;
-            readonly failures: Failures & FailureVariantDefinitionsForSchemas<FailureSchemas, boolean> & FailureVariantNameContract<Failures> & FailureVariantTextContract<Command, Failures, TextEnabled>;
+            readonly failures: Failures & FailureVariantDefinitionsForSchemas<FailureSchemas, boolean> & FailureVariantNameContract<Command, Failures> & FailureVariantTextContract<Command, Failures, TextEnabled>;
         }> & (Readonly<{
-            readonly fields: CheckedFieldDefinitions<Fields> & FieldDefinitionsForInput<ContractSchemaInput<InputSchema>> & FieldIdentityContract<Fields>;
+            readonly fields: CheckedFieldDefinitions<Fields, Command> & FieldDefinitionsForInput<ContractSchemaInput<InputSchema>> & FieldIdentityContract<Command, Fields>;
             readonly success: Readonly<{
                 readonly kind: "data";
-                readonly variants: Variants & DataVariantDefinitionsForSchemas<VariantSchemas, boolean> & DataVariantNameContract<Variants> & DataVariantTextContract<Command, Variants, TextEnabled>;
+                readonly variants: Variants & DataVariantDefinitionsForSchemas<VariantSchemas, boolean> & DataVariantNameContract<Command, Variants> & DataVariantTextContract<Command, Variants, TextEnabled>;
             }>;
         }> | Readonly<{
-            readonly fields?: CheckedFieldDefinitions<Fields> & FieldDefinitionsForInput<ContractSchemaInput<InputSchema>> & FieldIdentityContract<Fields>;
+            readonly fields?: CheckedFieldDefinitions<Fields, Command> & FieldDefinitionsForInput<ContractSchemaInput<InputSchema>> & FieldIdentityContract<Command, Fields>;
             readonly success: CompletionSuccessDefinition<Root, TextEnabled>;
         }> | Readonly<{
-            readonly fields?: CheckedFieldDefinitions<Fields> & FieldDefinitionsForInput<ContractSchemaInput<InputSchema>> & FieldIdentityContract<Fields>;
+            readonly fields?: CheckedFieldDefinitions<Fields, Command> & FieldDefinitionsForInput<ContractSchemaInput<InputSchema>> & FieldIdentityContract<Command, Fields>;
             readonly success: (Readonly<{
                 readonly kind: "stream";
-                readonly records: Records & StreamRecordDefinitionsForSchemas<RecordSchemas, boolean> & StreamRecordNameContract<Records>;
+                readonly records: Records & StreamRecordDefinitionsForSchemas<RecordSchemas, boolean> & StreamRecordNameContract<Command, Records>;
                 readonly text: CompletionTextPresenter;
             }> & StreamRecordTextContract<Command, Records, TextEnabled>) | (Readonly<{
                 readonly kind: "stream";
-                readonly records: Records & StreamRecordDefinitionsForSchemas<RecordSchemas, boolean> & StreamRecordNameContract<Records>;
+                readonly records: Records & StreamRecordDefinitionsForSchemas<RecordSchemas, boolean> & StreamRecordNameContract<Command, Records>;
                 readonly text?: never;
             }> & ([TextEnabled] extends [true] ? ContractTypeError<"missingTextPresenter", Readonly<{
                 readonly command: Command;
@@ -1032,56 +1573,23 @@ export interface DefineCli<Dependencies> {
         readonly kind: "rootGroup";
     }>> ? HierarchyCliDefinition<Root> & HierarchyContract<Commands, Output> : ValidationIntersection<HierarchyOutputValidation<Commands, Output>>)): Commands extends Readonly<Record<Root, {
         readonly kind: "rootGroup";
-    }>> ? CliContract<Root, Dependencies, HierarchyRawInput<Commands>, HierarchyResult<Commands>, "rootGroup", Commands> : CliContract<Root, Dependencies, RootCommandRawInput<Root, Commands>, RootCommandResult<Root, Commands>, "rootCommand">;
+    }>> ? CliContract<Root, Dependencies, HierarchyRawInput<Commands>, HierarchyResult<Commands>, "rootGroup", Commands, HierarchyUsageConstraintFacts<Commands>> : CliContract<Root, Dependencies, RootCommandRawInput<Root, Commands>, RootCommandResult<Root, Commands>, "rootCommand", never, RootUsageConstraintFacts<Root, Commands>>;
 }
-type HierarchyCommandInput<Definition> = Omit<Definition, "kind"> & Omit<HierarchyCommandFacts, typeof executableCommandType>;
-type HierarchyCompletionCommandDefinition<Command extends string, Dependencies, Failures extends FailureVariantDefinitions, Fields extends FieldDefinitions, InputSchema extends ContractSchema> = Omit<CompletionRootCommandDefinition<Command, Dependencies, Failures, Fields, InputSchema>, "fields" | "input" | "usageConstraints"> & Readonly<{
-    readonly fields?: CheckedFieldDefinitions<Fields> & FieldIdentityContract<Fields>;
-    readonly input: InputSchema;
-}>;
-type HierarchyDataCommandDefinition<Command extends string, Dependencies, Fields extends FieldDefinitions, InputSchema extends ContractSchema, Variants extends DataVariantDefinitions, Failures extends FailureVariantDefinitions> = Omit<DataRootCommandDefinition<Command, Dependencies, Fields, InputSchema, Variants, Failures>, "fields" | "input" | "usageConstraints"> & Readonly<{
-    readonly fields: CheckedFieldDefinitions<Fields> & FieldIdentityContract<Fields>;
-    readonly input: InputSchema;
-}>;
-type HierarchyStreamCommandDefinition<Command extends string, Dependencies, Fields extends FieldDefinitions, InputSchema extends ContractSchema, Records extends StreamRecordDefinitions, Failures extends FailureVariantDefinitions> = Omit<StreamRootCommandDefinition<Command, Dependencies, Fields, InputSchema, Records, Failures>, "fields" | "input" | "usageConstraints"> & Readonly<{
-    readonly fields: CheckedFieldDefinitions<Fields> & FieldIdentityContract<Fields>;
-    readonly input: InputSchema;
-}>;
-type UsageConstraintProperty<Constraints> = Constraints extends readonly unknown[] ? Readonly<{
-    readonly usageConstraints: Constraints;
-}> : unknown;
 type ActualFailureDefinitions<Failures> = Failures extends FailureVariantDefinitions ? Failures : never;
-type RootFallbackFieldsProperty<Fields extends FieldDefinitions, InputSchema extends ContractSchema> = Readonly<{
-    readonly fields: CheckedFieldDefinitions<Fields> & FieldDefinitionsForInput<ContractSchemaInput<InputSchema>> & FieldIdentityContract<Fields>;
+type RootFallbackFieldsProperty<Command extends string, Fields extends FieldDefinitions, InputSchema extends ContractSchema> = Readonly<{
+    readonly fields: CheckedFieldDefinitions<Fields, Command> & FieldDefinitionsForInput<ContractSchemaInput<InputSchema>> & FieldIdentityContract<Command, Fields>;
     readonly success: Readonly<{
         readonly kind: "data" | "stream";
     }>;
 }> | Readonly<{
-    readonly fields?: CheckedFieldDefinitions<Fields> & FieldDefinitionsForInput<ContractSchemaInput<InputSchema>> & FieldIdentityContract<Fields>;
+    readonly fields?: CheckedFieldDefinitions<Fields, Command> & FieldDefinitionsForInput<ContractSchemaInput<InputSchema>> & FieldIdentityContract<Command, Fields>;
     readonly success: Readonly<{
         readonly kind: "completion";
     }>;
 }>;
 /** 为具名叶命令生成可展开到根契约 `commands` 的定义。 */
 export interface DefineCommand<Command extends string, Dependencies> {
-    <const Definition extends object, const Parent extends string, const Fields extends FieldDefinitions, InputSchema extends ContractSchema, const VariantSchemas extends VariantSchemaMap, const Variants, const RecordSchemas extends VariantSchemaMap, const Records, const FailureSchemas extends VariantSchemaMap, const Failures, const Kind extends RootFallbackKind>(definition: Definition & ClosedCommandDefinition<Definition> & Omit<RootFallbackCliDefinition<Command, Dependencies, Fields, InputSchema, VariantSchemas, Variants, RecordSchemas, Records, FailureSchemas, Failures, boolean>["commands"][Command], "kind" | "fields"> & RootFallbackFieldsProperty<Fields, InputSchema> & RootFallbackHandlerDefinition<Command, Dependencies, InputSchema, DataVariantDefinitionsForSchemas<VariantSchemas, boolean>, StreamRecordDefinitionsForSchemas<RecordSchemas, boolean>, ActualFailureDefinitions<Failures>, Kind>["commands"][Command] & Omit<HierarchyCommandFacts<Parent>, typeof executableCommandType>): Readonly<Record<Command, Definition & HierarchyCommandFacts<Parent>>>;
-    <const Definition extends object, const Parent extends string, const Failures extends FailureVariantDefinitions, const Constraints extends readonly unknown[] | undefined = undefined>(definition: Definition & ClosedCommandDefinition<Definition> & HierarchyCommandInput<HierarchyCompletionCommandDefinition<Command, Dependencies, Failures, Readonly<Record<never, never>>, ContractSchema<EmptyCliInput>>> & Readonly<{
-        readonly parent: Parent;
-        readonly usageConstraints?: Constraints & readonly UsageConstraint[];
-    }>): Readonly<Record<Command, Definition & Omit<HierarchyCompletionCommandDefinition<Command, Dependencies, Failures, Readonly<Record<never, never>>, ContractSchema<EmptyCliInput>>, "kind" | "success" | "failures"> & UsageConstraintProperty<Constraints> & HierarchyCommandFacts<Parent>>>;
-    <const Definition extends object, const Fields extends FieldDefinitions, InputSchema extends ContractSchema, const Parent extends string, const Failures extends FailureVariantDefinitions, const Constraints extends readonly unknown[] | undefined = undefined>(definition: Definition & ClosedCommandDefinition<Definition> & HierarchyCommandInput<HierarchyCompletionCommandDefinition<Command, Dependencies, Failures, Fields, InputSchema>> & Readonly<{
-        readonly fields: Fields;
-        readonly parent: Parent;
-        readonly usageConstraints?: Constraints & readonly UsageConstraint[];
-    }>): Readonly<Record<Command, Definition & Omit<HierarchyCompletionCommandDefinition<Command, Dependencies, Failures, Fields, InputSchema>, "kind" | "success" | "failures"> & UsageConstraintProperty<Constraints> & HierarchyCommandFacts<Parent>>>;
-    <const Definition extends object, const Fields extends FieldDefinitions, InputSchema extends ContractSchema, const Parent extends string, const Variants extends DataVariantDefinitions, const Failures extends FailureVariantDefinitions, const Constraints extends readonly unknown[] | undefined = undefined>(definition: Definition & ClosedCommandDefinition<Definition> & HierarchyCommandInput<HierarchyDataCommandDefinition<Command, Dependencies, Fields, InputSchema, Variants, Failures>> & Readonly<{
-        readonly parent: Parent;
-        readonly usageConstraints?: Constraints & readonly UsageConstraint[];
-    }>): Readonly<Record<Command, Definition & Omit<HierarchyDataCommandDefinition<Command, Dependencies, Fields, InputSchema, Variants, Failures>, "kind" | "success" | "failures"> & UsageConstraintProperty<Constraints> & HierarchyCommandFacts<Parent>>>;
-    <const Definition extends object, const Fields extends FieldDefinitions, InputSchema extends ContractSchema, const Parent extends string, const Records extends StreamRecordDefinitions, const Failures extends FailureVariantDefinitions, const Constraints extends readonly unknown[] | undefined = undefined>(definition: Definition & ClosedCommandDefinition<Definition> & HierarchyCommandInput<HierarchyStreamCommandDefinition<Command, Dependencies, Fields, InputSchema, Records, Failures>> & Readonly<{
-        readonly parent: Parent;
-        readonly usageConstraints?: Constraints & readonly UsageConstraint[];
-    }>): Readonly<Record<Command, Definition & Omit<HierarchyStreamCommandDefinition<Command, Dependencies, Fields, InputSchema, Records, Failures>, "kind" | "success" | "failures"> & UsageConstraintProperty<Constraints> & HierarchyCommandFacts<Parent>>>;
+    <const Definition extends object, const Parent extends string, const Fields extends FieldDefinitions, InputSchema extends ContractSchema, const VariantSchemas extends VariantSchemaMap, const Variants, const RecordSchemas extends VariantSchemaMap, const Records, const FailureSchemas extends VariantSchemaMap, const Failures, const Kind extends RootFallbackKind>(definition: Definition & ClosedCommandDefinition<Definition, Command> & Omit<RootFallbackCliDefinition<Command, Dependencies, Fields, InputSchema, VariantSchemas, Variants, RecordSchemas, Records, FailureSchemas, Failures, boolean>["commands"][Command], "kind" | "fields"> & RootFallbackFieldsProperty<Command, Fields, InputSchema> & RootFallbackHandlerDefinition<Command, Dependencies, InputSchema, Variants extends DataVariantDefinitions ? Variants : never, Records extends StreamRecordDefinitions ? Records : never, ActualFailureDefinitions<Failures>, Kind>["commands"][Command] & HierarchyCommandFactsDefinition<Parent>): CommandCombination<Command, Definition, Parent>;
 }
 interface RuntimeCompiledCli {
     readonly contract: CliContract;
@@ -1127,16 +1635,11 @@ export declare function isCompiledExecutable(command: RuntimeCompiledCommand): c
  * 显式装配全树帮助。`headings` 是可选段落标题；`wording` 按实际帮助事实
  * 提供必要模板，由 defineCli 检查完整性；核心不生成默认自然语言。
  */
-export declare function helpCapability(definition?: undefined): HelpCapability;
-export declare function helpCapability<const Definition extends HelpCapabilityDefinition>(definition: Definition & RejectUnknownProperties<Definition, (typeof definitionPropertyKeys.capability.help)[number]> & (Definition extends Readonly<{
+export declare function helpCapability<const Definition extends HelpCapabilityDefinitionForTypeCheck = HelpCapabilityDefinition>(definition?: Definition & RejectUnknownProperties<Definition, (typeof definitionPropertyKeys.capability.help)[number]> & (Definition extends Readonly<{
     readonly headings: infer Headings;
 }> ? Readonly<{
     readonly headings: RejectUnknownProperties<Headings, keyof HelpHeadings>;
-}> : unknown) & (Definition extends Readonly<{
-    readonly wording: infer Wording;
-}> ? Readonly<{
-    readonly wording: RejectUnknownProperties<Wording, keyof HelpFactWording>;
-}> : unknown)): HelpCapability;
+}> : unknown) & HelpCapabilityTemplateContract<Definition>): HelpCapability;
 /**
  * 在根契约显式装配版本提前请求，并自动覆盖整棵命令树。`value` 与可选
  * `description` 均由消费者拥有；核心只注册固定 spelling、投影帮助并写出 value，
@@ -1152,8 +1655,10 @@ export declare function versionCapability<const Definition extends VersionCapabi
 export declare function outputCapability<const Definition extends OutputCapabilityDefinition>(definition: Definition & RejectUnknownProperties<Definition, (typeof definitionPropertyKeys.capability.output)[number]>): OutputCapability<OutputFormatsFor<Definition>>;
 /**
  * 定义一个闭合 CLI 契约。根级 help 与 output 能力在此处一次装配，并据此约束根命令的结果投影；
+ * 最终根装配会逐个检查整棵命令树的 completion、data/failure variant、stream record 与 stream success
+ * 是否满足 text 能力要求的同位 presenter；structured-only 禁止 presenter，`define.command()` 组合也在此检查。
  * 动态声明仍会在定义期报告 `ContractDefinitionError`，不能以它替代静态可判定声明的类型检查。
- * @see {@link https://github.com/YKDZ/cli-contract/tree/v0.2.1/packages/example | 端到端示例}
+ * @see {@link https://github.com/YKDZ/cli-contract/tree/v0.3.0/packages/example | 端到端示例}
  */
 export declare function defineCli<Dependencies = undefined>(): DefineCli<Dependencies>;
 export declare function getCompiledCli(contract: CliContract): RuntimeCompiledCli;