Interface OptionDefinition

Cardinality / onExcess / onShortage — see FieldDefinition.

Lifecycle effects this option applies to the dispatcher when the bound model value is truthy. Each entry names a phase from COMMAND_PHASES and an action (skip or replace). The dispatcher's phase walk consults the option set at every gated point and honors matching effects.

Concrete shapes (see the phase taxonomy at the top of this file):

look --peek: options: peek: type: boolean effects: - { phase: focus-update, action: skip }

Future --async: options: async: type: boolean effects: - { phase: dispatch, action: replace, with: deferred-dispatch }

Schema validates phase + handler names against the documented vocabulary at YAML load time; the dispatcher throws at runtime when an effect targets a phase or replacement handler that hasn't been wired into the substrate yet.

Field name to land on; defaults to the option's own name.

If true, repeated occurrences accumulate into an array. False (the default) means a second occurrence is a bind error.

Used by payload fields (the structured-form-only family) to declare that the client MUST attach this key. Enforced by assembleFromStructured against command.payload only — verb-scoped options ignore it (options are by convention optional).

Optional JSON Schema fragment — see FieldDefinition.schema.

MQL scope fragment(s) the dispatcher tries when resolving this option's value. Same precedence + expander rules as a positional's scope. Only meaningful for type: object / type: objects. Default when omitted: ['$focus'].

Same type taxonomy as positional fields. struct is structured-input-only — text-input rejects it with a clear error. object / objects run through the matcher's MQL resolution (see scope below); the controller receives an MqlOneResult / MqlManyResult wrapper, not the raw string.