Struct Scope 

pub struct Scope<'a> { /* private fields */ }

The vocabulary one request is resolved against.

Borrows both halves; nothing here outlives the call that builds it.

Implementations

impl<'a> Scope<'a>

pub fn new(elements: &'a [Value], envelope: &'a Value) -> Self

Builds a scope over the elements and the envelope that carried them.

The synonym scope starts unset, which admits only the groups that hold for every command. That is the fail-safe half of the pair: a caller that never states which subcommand it is resolving for gets no mode-specific synonym, rather than the synonyms of some arbitrary mode.

pub fn with_command(self, command: Option<&'a str>) -> Self

GAP-SG-274: states which subcommand slug this scope resolves keys for.

Consumed by the synonym table alone. graph declares kind a spelling of the entity type; graph-ndjson does not, because there kind is the line discriminator and answering node to --select type would be a wrong value rather than a missing one.

pub fn is_empty(&self) -> bool

true when there are no elements to resolve a key against.

An empty result array carries no vocabulary, so it cannot tell a key that does not exist from a key that simply had no row to appear in.

pub fn classify(&self, key: &str) -> KeyOrigin

Where key lives, if anywhere.

An envelope with no elements can still answer KeyOrigin::EnvelopeOnly, which is what makes the scalar-envelope refusal precise instead of a blanket “no array here”.

pub fn effective_key(&self, key: &str) -> Option<String>

GAP-SG-230: the spelling this payload actually uses for key.

Returns key itself when the payload carries it, the synonym when the payload spells the same field differently, and None when no spelling in the group is present anywhere in scope.

Why this is a separate question from Self::classify

classify answers “may this request proceed”; this answers “which name do I look the value up under”. They only look like one question while both spellings are the same string. graph entities emits entity_type and graph --format json emits type for the very same column, so a caller that learned one name asks with it against both — and the four shaping knobs walk the path with the name the CALLER wrote, never with the verdict this scope reached. Answering only the first question would let a request pass the gate and then match nothing, which trades a refusal that names the fix for an empty set with exit 0.

Elements are consulted before the envelope, mirroring classify, so the answer describes the place a predicate or a projection will actually look.

pub fn suggestions(&self, key: &str) -> Vec<String>

Key names close enough to key to be worth offering as a correction.

Ordered by descending similarity and capped at K_VOCABULARY_MAX_SUGGESTIONS. An empty vector means nothing in the vocabulary resembled the request, which is itself informative: the caller is looking at the wrong command, not at a typo.

GAP-SG-230: a DECLARED synonym that the payload really carries is placed first and bypasses the similarity floor entirely. Similarity is a proxy for “you mistyped this”; a synonym is not a typo, it is the same field under the name a sibling surface chose, and the table says so as a fact. Leaving it to Jaro-Winkler was measured to lose exactly the case this exists for: entity_type against type shares no prefix, so the metric scores it below VOCABULARY_SUGGESTION_MIN_SIMILARITY and the caller who asked with the sibling spelling was told nothing resembled its key — while the field sat right there under another name.

pub fn vocabulary_is_partial(&self) -> bool

Distinct field names a correction could plausibly have meant.

Reads the elements when there are elements and the envelope when there are none, because that is the same split resolve_projection uses to decide what a key must address. Without the fallback the most useful refusal in the catalogue — --select body_length read, the case GAP-SG-202 was written from — named no alternative at all, since a read envelope carries no array to sample.

Borrowed, never cloned: the set holds &str into the payload, so a vocabulary of five hundred names costs five hundred pointers.

Whether the SUGGESTION vocabulary was built from less than everything.

Reported as vocabulary_partial so a caller reading an empty or thin suggestion list can tell “nothing resembled your key” from “the sampler stopped before it got there”. Only the suggestion path samples; Self::classify always scans every element, so a PARTIAL vocabulary never weakens a verdict — it only shortens the advice that follows one.