Class MqlApi

Pick the effective target Stuff from a single-cardinality binding, considering both the direct match and any door attached to a via.exit. Returns the first Stuff (in that order) that satisfies predicate, or null when neither does.

The "direct first, door second" rule is what makes door-acting verbs (open, close, future knock / lock) work uniformly across the two ways MQL can land on a door: by keyword on the door itself (open oak) or by direction through the location (open north).

predicate is the standard MixinApi.isX shape — a type guard returning obj is Stuff & T. The narrowing flows through the return type, so callers don't need a follow-up cast.

Unwrap a YAML-bound field value into a flat Stuff[]. Accepts MqlOneResult (single, possibly null), MqlManyResult (plural, possibly empty), or a bare Stuff (legacy / structured-input path). Returns null for anything else — a wrong-shape binding — so validators can surface the right "must be an object" error.

Empty MQL results (stuff: null / stuff: []) return [] rather than null — empty is a normal outcome the controller decides about, not a wrong-shape error.

Resolve a query under multi intent. Returns the full match list sorted by score (highest first), plus a query-level via when every match arrived through the same sub-feature path; mixed paths produce via: undefined.

The dispatcher routes type: objects YAML fields through this surface.

Resolve a query under one-of-N intent. Returns the highest-scored match (or null when nothing matched), wrapped with any sub-feature attribution describing how the resolver got there (an Exit, a detail path, etc.).

The dispatcher routes type: object YAML fields through this surface. Direct callers wanting "first match wins" semantics also use this.