Skip to main content

tabnas/
parser.rs

1// Copyright (c) 2013-2026 Richard Rodger, MIT License
2
3use crate::builtins::run_builtin_action_with_info;
4use crate::context::{Context, ContextSeed, InstanceInfo};
5use crate::error::TabnasError;
6use crate::lexer::{compile_number_exclude, Lexer, RelexCheckpoint};
7use crate::options::Options;
8use crate::rule::{
9    resolved_action_order, resolved_alt_action_order, ActionBinding, AltActionBinding, AltMatch,
10    AltSpec, CompareOp, Condition, Rule, RuleDone, RuleDoneAlt, RuleName, RuleSnapshot, RuleSpec,
11    RuleState, StateAction,
12};
13use crate::token::{Tin, Token, TIN_AA, TIN_BD, TIN_ZZ};
14use crate::value::Value;
15use crate::{
16    Action, AltAction, ContextAction, LexSubscriber, ParseGuard, RuleDoneSubscriber,
17    RuleSubscriber, TokenSubscriber,
18};
19use indexmap::IndexMap;
20use std::borrow::Cow;
21use std::cell::RefCell;
22use std::collections::{BTreeSet, HashMap};
23use std::panic::{catch_unwind, AssertUnwindSafe};
24use std::rc::Rc;
25use std::sync::Arc;
26
27#[derive(Debug, Clone, PartialEq, Eq)]
28pub struct Continuations {
29    pub tins: Vec<Tin>,
30    pub tokens: Vec<String>,
31}
32
33#[derive(Debug, Clone)]
34pub struct ParseRecovery {
35    pub value: Option<Value>,
36    pub errors: Vec<TabnasError>,
37    pub fatal: Option<TabnasError>,
38}
39
40#[derive(Default)]
41struct ContinuationCapture {
42    at_end: BTreeSet<Tin>,
43    have_end: bool,
44    failure: Vec<Tin>,
45}
46
47struct ParseMode<'a> {
48    continuation: Option<&'a mut ContinuationCapture>,
49    recovering: bool,
50    errors: &'a mut Vec<TabnasError>,
51    partial: Option<PartialValue>,
52    /// Recovery gave up, and the error it gave up on is already accounted
53    /// for in `errors`: recorded there, or dropped as a cascade of the
54    /// fault before it. TypeScript records an error as it is constructed
55    /// and gives up by rethrowing the last one it recorded (`RuleSpec.bad`,
56    /// ts/src/rules.ts), or the bad token it has just recorded, coalesced
57    /// or dropped (the fetch in `parse_alts`), so the error that ends the
58    /// parse is never listed a second time. Every other terminal error is
59    /// listed once, where the parse ends.
60    gave_up: bool,
61}
62
63/// A recovery result that stays borrowed from the live parse until needed.
64///
65/// Holding a cloned `Value` while its container was still being built kept a
66/// second `Arc` handle alive. Every following append then made
67/// `Arc::make_mut` copy the whole prefix. A node cell follows TypeScript's
68/// recovery path instead: keep the live node and read it once when parsing
69/// ends. `Complete` is the already-finalized value retained for a post-loop
70/// trailing-content failure.
71enum PartialValue {
72    Node(Rc<RefCell<Value>>),
73    Complete(Value),
74}
75
76impl PartialValue {
77    fn into_value(self) -> Option<Value> {
78        match self {
79            Self::Complete(value) => Some(value),
80            Self::Node(node) => {
81                let value = node.borrow().clone();
82                (!matches!(value, Value::Undefined | Value::Null)).then(|| value.unwrap_undefined())
83            }
84        }
85    }
86}
87
88struct RelexUndo {
89    position: usize,
90    token: Token,
91    checkpoint: RelexCheckpoint,
92    tokens: Vec<Token>,
93}
94
95/// Who is asking [`Parser::ensure_lookahead`] for a token, which decides
96/// what a bad token does under recovery.
97#[derive(Clone, Copy, PartialEq, Eq)]
98enum Fetch {
99    /// A rule reading its lookahead, as TypeScript's `parse_alts` does:
100    /// under recovery a bad token is recorded and skipped, and the fetch
101    /// goes on.
102    Rule,
103    /// The check for content after the parse has finished, as
104    /// TypeScript's `Parser.start` makes it: a bad token ends the parse
105    /// with its own error, recovering or not.
106    Trailing,
107}
108
109#[derive(Clone, Copy)]
110struct ParseSite<'a> {
111    source: &'a str,
112    stack: &'a [Rule],
113    alts: &'a [AltSpec],
114}
115
116pub struct Parser {
117    /// Shared with the lexer, which never writes to them. Cloning a
118    /// whole `Options` was 22% of a small parse, and it was happening
119    /// twice.
120    pub options: Arc<Options>,
121    ignore_tins: Vec<Tin>,
122    /// `options.number.exclude` compiled once, here, and shared with
123    /// the lexer of every parse instead of compiled by each of them.
124    ///
125    /// `options` is public, so this is a cache whose source has a second
126    /// writer: a caller on the low-level API may replace the whole `Arc`
127    /// between parses, and before this was cached each lexer compiled
128    /// whatever pattern was in force. `exclude_pattern` is the pattern
129    /// this regex was built from, and a parse whose options no longer
130    /// carry it compiles the one they do carry instead -- the old cost,
131    /// paid only by the callers who change the pattern under the parser.
132    exclude_regex: Option<Arc<regex::Regex>>,
133    exclude_pattern: Option<String>,
134    /// Installed rules by name.
135    ///
136    /// Private, and read through [`Parser::rules`]. Two derived tables below
137    /// are keyed by the same names and are written only by `add_rule`; while
138    /// this was public an embedder could insert or replace a rule straight
139    /// into it, leaving those tables describing the rule that used to be
140    /// there. Lookahead would then gate the custom matchers on the previous
141    /// rule's token identities, or on none at all for a name that was never
142    /// installed, and a valid document could fail to parse. Before those
143    /// identities were derived once per rule instead of once per lookahead
144    /// there was nothing to go stale, so this hazard arrived with the table.
145    rules: IndexMap<String, Arc<RuleSpec>>,
146    /// The `rule.include` and `rule.exclude` every `PreparedAlt::groups`
147    /// was worked out against, and every `expected_tins` row collated
148    /// against. Both are public and a callback may write either between
149    /// one step and the next, so the step compares these two strings
150    /// before trusting the prepared answer, and `expected_match_tins`
151    /// before trusting the row -- the same shape of guard the compiled
152    /// `number.exclude` pattern carries, and for the same reason: a cache
153    /// derived from a public mutable field is a cache with a second
154    /// writer.
155    prepared_include: String,
156    prepared_exclude: String,
157    /// The token identities each rule can accept at each lookahead slot,
158    /// worked out once per installed rule rather than once per token, and
159    /// positional in `rules` the way `names` is: a rule carries the slot
160    /// it was installed at, so reaching its row costs an index rather than
161    /// a hash of its name on every token fetch.
162    expected_tins: Vec<ExpectedTins>,
163    /// One shared copy of each installed rule's name, so pushing a rule
164    /// clones a pointer rather than reallocating the name per push.
165    ///
166    /// Parallel to `rules`, indexed by position rather than keyed by the
167    /// name again: every route already has to find the rule's spec, and
168    /// `IndexMap::get_full` hands back that rule's index with it, so the
169    /// shared name costs an array index instead of a second hash of the
170    /// same bytes. `Parser::rules` is public and hands out the map itself,
171    /// which is why the handle lives beside the map rather than in it.
172    /// `add_rule` keeps the two in step; `IndexMap` gives a replaced key
173    /// back its existing index, so a replacement overwrites in place.
174    names: Vec<RuleName>,
175    /// Per-rule state worked out once, when the grammar is installed.
176    ///
177    /// Parallel to `rules` and `names`, and written only by `add_rule`,
178    /// which rebuilds the whole table -- a route may name a rule that is
179    /// installed later, so an entry is only right once every rule is in.
180    /// The loop reaches an entry by the `slot` the rule carries and checks
181    /// it against the rule's own spec and name before trusting it, so a
182    /// callback that rewrites either just falls back to the lookup.
183    prepared: Vec<PreparedRule>,
184    pub actions: HashMap<String, Action>,
185    pub context_actions: HashMap<String, ContextAction>,
186    pub matched_actions: HashMap<String, AltAction>,
187    pub state_actions: HashMap<String, StateAction>,
188    pub token_subscribers: Vec<TokenSubscriber>,
189    pub lex_subscribers: Vec<LexSubscriber>,
190    pub rule_subscribers: Vec<RuleSubscriber>,
191    pub rule_done_subscribers: Vec<RuleDoneSubscriber>,
192    pub parse_guards: Vec<ParseGuard>,
193    pub instance: InstanceInfo,
194}
195
196/// One installed rule, with what the parse loop can work out about it
197/// before a parse starts.
198///
199/// Routing, and the order the rule's actions run in. The order is a
200/// question about the spec alone -- which of the named, callback and
201/// state lists a binding came from, and where the three interleave -- and
202/// the spec behind the `Arc` this record is checked against cannot change
203/// while a parse runs, so it is answered once here instead of rebuilt into
204/// a fresh `Vec` on every rule step. What a *named* binding resolves to is
205/// a different question: it is looked up in `Parser::actions`,
206/// `matched_actions` and `state_actions`, all of them public maps an
207/// embedder may write after `add_rule` has run, so that lookup stays where
208/// it was, on the step -- a table derived from a field with a second
209/// writer goes stale in silence, which is the hazard `rules` was made
210/// private to close.
211struct PreparedRule {
212    /// The rule's shared name handle and the spec it was installed with.
213    ///
214    /// `spec` is what the loop borrows in place of the rule's own; `name`
215    /// is only ever compared. Together they are what says the rule in hand
216    /// is still the rule this record describes.
217    name: RuleName,
218    spec: Arc<RuleSpec>,
219    open: Vec<PreparedAlt>,
220    close: Vec<PreparedAlt>,
221    /// The alternates of each state indexed by the tin they can take at
222    /// position 0, so a step tries the candidates for the first
223    /// lookahead token rather than every alternate.
224    open_first: AltIndex,
225    close_first: AltIndex,
226    /// The four lifecycle action orders, in the same order the rule runs
227    /// them. Most grammars declare none of them, and an empty list here is
228    /// what lets a step skip the whole phase rather than walk an empty
229    /// one: `bind_spec` sets a rule's `bo`/`ao`/`bc`/`ac` true
230    /// unconditionally, so those flags say the phase is *enabled*, never
231    /// that it has anything to run.
232    bo: Vec<ActionBinding>,
233    ao: Vec<ActionBinding>,
234    bc: Vec<ActionBinding>,
235    ac: Vec<ActionBinding>,
236}
237
238impl PreparedRule {
239    /// The first-token index of the open or close alternates.
240    fn first(&self, is_open: bool) -> &AltIndex {
241        if is_open {
242            &self.open_first
243        } else {
244            &self.close_first
245        }
246    }
247
248    fn alt(&self, is_open: bool, idx: usize) -> Option<&PreparedAlt> {
249        if is_open {
250            self.open.get(idx)
251        } else {
252            self.close.get(idx)
253        }
254    }
255
256    /// The before-open or before-close action order.
257    fn before(&self, is_open: bool) -> &[ActionBinding] {
258        if is_open {
259            &self.bo
260        } else {
261            &self.bc
262        }
263    }
264
265    /// The after-open or after-close action order.
266    fn after(&self, is_open: bool) -> &[ActionBinding] {
267        if is_open {
268            &self.ao
269        } else {
270            &self.ac
271        }
272    }
273}
274
275/// One alternate's two routing channels and its action order, resolved at
276/// install time.
277struct PreparedAlt {
278    p: PreparedRoute,
279    r: PreparedRoute,
280    /// The alternate's action bindings in the order they run.
281    actions: Vec<AltActionBinding>,
282    /// Whether anything a step on this alternate runs can read the
283    /// `AltMatch` record, and so see the action list the engine publishes
284    /// into `matched.actions`.
285    ///
286    /// The list is published for the callbacks that receive the record --
287    /// the `c`/`e`/`p`/`r`/`b` matched hooks, the matched modifier, and a
288    /// matched action itself. When the alternate declares none of them
289    /// nothing in the step can tell whether the field was filled, so the
290    /// step runs these bindings straight from here: no `Vec` built, no
291    /// second copy taken to iterate, no reference counts touched. When it
292    /// declares any of them the step fills the record exactly as before.
293    ///
294    /// A `Named` binding may also resolve to a matched action, and that
295    /// cannot be settled here -- `add_matched_action` may be called after
296    /// `add_rule`, and `matched_actions` is public. `named` records only
297    /// that the question arises; the step asks it of the map it is asking
298    /// anyway.
299    observed: bool,
300    named: bool,
301    /// Whether `rule.include` and `rule.exclude` leave this alternate
302    /// active, worked out when the rule was installed.
303    ///
304    /// The question is about `alt.g` against two option strings, and the
305    /// answer cannot change during a parse unless a callback rewrites the
306    /// options -- so `prepared_include`/`prepared_exclude` on the parser
307    /// record what this was computed against, and the step checks those
308    /// two strings ONCE rather than re-deriving the answer per alternate.
309    groups: bool,
310    /// `alt.g` split into the tags the step publishes into `matched.g`,
311    /// split when the rule was installed rather than per rule step.
312    ///
313    /// Unlike `groups` this is derived from the alternate alone, so no
314    /// option string can stale it; the only alternate it cannot answer for
315    /// is one a modifier rewrote, which the step detects the same way it
316    /// does for the action order.
317    group_tags: Vec<String>,
318}
319
320enum PreparedRoute {
321    /// Nothing was resolved: the alternate declares no route on this
322    /// channel, or names a rule that is not installed, or routes through a
323    /// callback. All three take the same path they took before the table --
324    /// one lookup by name, which is also what raises `unknown_rule` for a
325    /// route naming no rule.
326    ByName,
327    Static {
328        slot: usize,
329        name: RuleName,
330        spec: Arc<RuleSpec>,
331    },
332}
333
334impl PreparedRoute {
335    /// The prepared answer, if the route the parse is actually taking is
336    /// still the one that was prepared.
337    ///
338    /// The test is byte-equality of the name, unconditionally, and not a
339    /// pointer comparison of the alternate: `h` rewrites the whole
340    /// `AltSpec` per step, `p_fn`/`r_fn` and `p_match`/`r_match` produce
341    /// the name at run time, and a matched action may write `matched.p` or
342    /// `matched.r` outright -- all supported routing channels. A route that
343    /// arrives at the same name resolves to the same rule whichever of them
344    /// produced it, so the bytes are the whole question.
345    fn resolved(&self, name: &str) -> Option<(usize, RuleName, &Arc<RuleSpec>)> {
346        match self {
347            PreparedRoute::Static {
348                slot,
349                name: prepared,
350                spec,
351            } if prepared.as_str() == name => Some((*slot, prepared.clone(), spec)),
352            _ => None,
353        }
354    }
355}
356
357/// Per-slot accepted token identities for one rule, in each state.
358///
359/// This used to be derived on every lookahead: a map lookup, a `BTreeSet`
360/// built from the alternates, and a `Vec` collected out of it, once per
361/// token. None of it can change while a parse runs, so it is derived once
362/// when the rule is installed.
363/// What the names on one slot resolve to against `options` now: a slot
364/// naming a token set takes the set's current members, and a slot naming a
365/// token takes that token. `None` leaves the slot with the tins it has, and
366/// is the answer for a slot with no names (an alternate built from tins
367/// directly, or a slot set by hand before a merge carried it, whose names
368/// the merge drops), a slot whose `s` was set by hand since it was
369/// installed (it no longer equals what the names last resolved to,
370/// `s_bound`: the edit wins over the names, as it did before the names
371/// were kept), and a slot naming something the options do not know (a
372/// parser build must not mint a token).
373pub(crate) fn resolved_slot(alt: &AltSpec, slot: usize, options: &Options) -> Option<Vec<Tin>> {
374    let names = alt.s_names.get(slot)?;
375    if names.is_empty() || alt.s.get(slot) != alt.s_bound.get(slot) {
376        return None;
377    }
378    let mut tins = Vec::with_capacity(names.len());
379    for name in names {
380        if let Some(set) = options.token_set.get(name.trim_start_matches('#')) {
381            tins.extend(set.iter().copied());
382        } else {
383            tins.push(options.token(name)?);
384        }
385    }
386    Some(tins)
387}
388
389/// Resolve every slot that was declared by name against `options`
390/// (`resolved_slot`).
391fn resolve_slot_names(spec: &mut RuleSpec, options: &Options) {
392    for alt in spec.open.iter_mut().chain(spec.close.iter_mut()) {
393        for slot in 0..alt.s.len() {
394            if let Some(tins) = resolved_slot(alt, slot, options) {
395                alt.s[slot] = tins;
396            }
397        }
398    }
399}
400
401/// Alternates indexed by the tin they can take at position 0.
402///
403/// `by_tin` maps each tin some alternate names at position 0 to the
404/// ascending indices of the alternates naming it; `wild` holds the
405/// alternates that constrain nothing at position 0 (an empty sequence,
406/// an empty slot, or a slot naming `#AA`, exactly the slots
407/// `slot_matches` accepts every tin for), which are candidates for every
408/// tin. The step walks the two lists together in index order, so the
409/// candidates for a tin are the original scan with the alternates that
410/// cannot take it left out, and first-match-wins is preserved. The lists
411/// stay separate rather than being merged per tin: a rule with W
412/// wildcard alternates and T distinct first tins would otherwise cost
413/// W×T entries.
414#[derive(Debug, Default)]
415struct AltIndex {
416    by_tin: HashMap<Tin, Vec<usize>>,
417    wild: Vec<usize>,
418}
419
420const NO_ALTS: &[usize] = &[];
421
422impl AltIndex {
423    fn of(alts: &[AltSpec]) -> Self {
424        let mut by_tin: HashMap<Tin, Vec<usize>> = HashMap::new();
425        let mut wild = Vec::new();
426        for (idx, alt) in alts.iter().enumerate() {
427            match alt.s.first() {
428                Some(slot) if !slot.is_empty() && !slot.contains(&TIN_AA) => {
429                    for tin in slot {
430                        let list = by_tin.entry(*tin).or_default();
431                        // A slot naming one tin twice must not try the
432                        // alternate twice: a condition could observe it.
433                        if list.last() != Some(&idx) {
434                            list.push(idx);
435                        }
436                    }
437                }
438                _ => wild.push(idx),
439            }
440        }
441        AltIndex { by_tin, wild }
442    }
443
444    /// The ascending alternates naming `tin` at position 0; the
445    /// wildcards are `wild`, walked beside them.
446    fn named(&self, tin: Tin) -> &[usize] {
447        self.by_tin.get(&tin).map_or(NO_ALTS, Vec::as_slice)
448    }
449}
450
451#[derive(Debug, Default)]
452struct ExpectedTins {
453    open: Vec<Vec<Tin>>,
454    close: Vec<Vec<Tin>>,
455}
456
457impl ExpectedTins {
458    /// Collated over the alternates `options` enable, as TypeScript's
459    /// `tcol` is: `filterRules` has removed the others from the spec
460    /// before `norm()` collates it. An excluded alternate is never tried,
461    /// so it must not decide which matchers run in the position-expected
462    /// pass either. It did until 0.12.4, and a grammar that excludes a
463    /// group while redefining a set that group's alternates name had the
464    /// set's members expected where the grammar never takes them (toml
465    /// excludes jsonic and sets `KEY` to `#ST #ID`, and its `val` came to
466    /// expect `#ID`, whose matcher then claimed every number).
467    ///
468    /// The filters are the ones in force at install, which the parser
469    /// records as `prepared_include` and `prepared_exclude`. Both are
470    /// public options a caller may rewrite afterwards, and the step then
471    /// chooses among the alternates the live filters enable, so
472    /// `Parser::expected_match_tins` reads this table only while the live
473    /// filters are still the recorded ones, and collates from them with
474    /// `live` otherwise.
475    fn of(spec: &RuleSpec, options: &Options) -> Self {
476        Self {
477            open: Self::by_slot(&spec.open, options),
478            close: Self::by_slot(&spec.close, options),
479        }
480    }
481
482    fn by_slot(alts: &[AltSpec], options: &Options) -> Vec<Vec<Tin>> {
483        let alts: Vec<&AltSpec> = alts
484            .iter()
485            .filter(|alt| groups_enabled(alt, options))
486            .collect();
487        let slots = alts.iter().map(|alt| alt.s.len()).max().unwrap_or(0);
488        (0..slots)
489            .map(|slot| Self::collate(alts.iter().copied(), slot))
490            .collect()
491    }
492
493    /// One slot's row, collated from the alternates `options` enable now
494    /// rather than the ones they enabled at install.
495    fn live(alts: &[AltSpec], options: &Options, slot: usize) -> Vec<Tin> {
496        Self::collate(alts.iter().filter(|alt| groups_enabled(alt, options)), slot)
497    }
498
499    fn collate<'a>(alts: impl Iterator<Item = &'a AltSpec>, slot: usize) -> Vec<Tin> {
500        let mut expected = BTreeSet::new();
501        for alt in alts {
502            if let Some(tins) = alt.s.get(slot) {
503                expected.extend(tins.iter().copied());
504            }
505        }
506        expected.into_iter().collect()
507    }
508
509    fn at(&self, is_open: bool, slot: usize) -> &[Tin] {
510        let slots = if is_open { &self.open } else { &self.close };
511        slots.get(slot).map(Vec::as_slice).unwrap_or_default()
512    }
513}
514
515impl Parser {
516    pub fn new(options: Options) -> Self {
517        let mut options = options;
518        options.sort_for_lexing();
519        Self::from_shared(Arc::new(options))
520    }
521
522    /// Parse against a configuration that is already prepared and
523    /// ordered, shared with every other parse of the same grammar.
524    pub fn from_shared(options: Arc<Options>) -> Self {
525        if let Err(error) = options.validate_comment_definitions() {
526            panic!("invalid options: {error}");
527        }
528        Parser {
529            ignore_tins: options.ignore_tins(),
530            exclude_regex: compile_number_exclude(&options),
531            exclude_pattern: options.number.exclude.clone(),
532            options,
533            rules: IndexMap::new(),
534            prepared_include: String::new(),
535            prepared_exclude: String::new(),
536            expected_tins: Vec::new(),
537            names: Vec::new(),
538            prepared: Vec::new(),
539            actions: HashMap::new(),
540            context_actions: HashMap::new(),
541            matched_actions: HashMap::new(),
542            state_actions: HashMap::new(),
543            token_subscribers: Vec::new(),
544            lex_subscribers: Vec::new(),
545            rule_subscribers: Vec::new(),
546            rule_done_subscribers: Vec::new(),
547            parse_guards: Vec::new(),
548            instance: InstanceInfo::default(),
549        }
550    }
551
552    /// The installed rules, in declaration order.
553    ///
554    /// Read-only: every write goes through [`Parser::add_rule`], which is
555    /// what keeps the derived tables in step with it.
556    pub fn rules(&self) -> &IndexMap<String, Arc<RuleSpec>> {
557        &self.rules
558    }
559
560    pub fn add_rule(&mut self, spec: RuleSpec) {
561        // A slot declared by name is resolved against the options this
562        // parser is built with, so a token set overridden after the rule
563        // was installed reaches it (tabnas/parser#217). The parser is
564        // rebuilt whenever the options change, which is what makes this
565        // the late binding TypeScript's `norm()` and Go's `altS` provide.
566        let mut spec = spec;
567        resolve_slot_names(&mut spec, &self.options);
568        // `rebuild_prepared` below records the live filters as the ones
569        // every accepted-token row was collated against, so a row collated
570        // under filters rewritten since then is collated again first. Only
571        // a rewrite between two installs reaches this.
572        if self.options.rule.include != self.prepared_include
573            || self.options.rule.exclude != self.prepared_exclude
574        {
575            for (row, installed) in self.expected_tins.iter_mut().zip(self.rules.values()) {
576                *row = ExpectedTins::of(installed, &self.options);
577            }
578        }
579        let expected = ExpectedTins::of(&spec, &self.options);
580        let shared = RuleName::from(spec.name.as_str());
581        let (index, _) = self.rules.insert_full(spec.name.clone(), Arc::new(spec));
582        // A replacement keeps the key's index, so it overwrites its own
583        // name handle; a new rule is appended and takes the next slot. The
584        // accepted-token table is positional for the same reason and is
585        // written here, not in `rebuild_prepared`: it is derived from one
586        // rule's spec alone, so rebuilding it for every rule on every
587        // install would be quadratic for no gain.
588        match self.names.get_mut(index) {
589            Some(existing) => *existing = shared,
590            None => self.names.push(shared),
591        }
592        match self.expected_tins.get_mut(index) {
593            Some(existing) => *existing = expected,
594            None => self.expected_tins.push(expected),
595        }
596        self.rebuild_prepared();
597    }
598
599    /// Rebuild the prepared table for every installed rule.
600    ///
601    /// Every rule, not just the one just installed: routes point across the
602    /// grammar, so a rule installed now can be the destination an earlier
603    /// rule named and could not resolve, and a replaced rule is a new
604    /// `Arc<RuleSpec>` that every route into it has to start handing out.
605    /// That makes installing a grammar quadratic in its size, which for the
606    /// grammars this engine runs -- tens of rules, installed once -- is
607    /// nothing next to a single parse, and it is the only shape that stays
608    /// right for a `Parser` that has rules added to it after it has already
609    /// parsed something.
610    fn rebuild_prepared(&mut self) {
611        let mut prepared = Vec::with_capacity(self.rules.len());
612        for (index, spec) in self.rules.values().enumerate() {
613            prepared.push(PreparedRule {
614                name: self.names[index].clone(),
615                spec: Arc::clone(spec),
616                open: Self::prepared_alts(&spec.open, &self.rules, &self.names, &self.options),
617                close: Self::prepared_alts(&spec.close, &self.rules, &self.names, &self.options),
618                open_first: AltIndex::of(&spec.open),
619                close_first: AltIndex::of(&spec.close),
620                bo: resolved_action_order(
621                    &spec.bo,
622                    &spec.bo_fns,
623                    &spec.bo_state_fns,
624                    &spec.bo_order,
625                ),
626                ao: resolved_action_order(
627                    &spec.ao,
628                    &spec.ao_fns,
629                    &spec.ao_state_fns,
630                    &spec.ao_order,
631                ),
632                bc: resolved_action_order(
633                    &spec.bc,
634                    &spec.bc_fns,
635                    &spec.bc_state_fns,
636                    &spec.bc_order,
637                ),
638                ac: resolved_action_order(
639                    &spec.ac,
640                    &spec.ac_fns,
641                    &spec.ac_state_fns,
642                    &spec.ac_order,
643                ),
644            });
645        }
646        self.prepared = prepared;
647        self.prepared_include.clone_from(&self.options.rule.include);
648        self.prepared_exclude.clone_from(&self.options.rule.exclude);
649    }
650
651    fn prepared_alts(
652        alts: &[AltSpec],
653        rules: &IndexMap<String, Arc<RuleSpec>>,
654        names: &[RuleName],
655        options: &Options,
656    ) -> Vec<PreparedAlt> {
657        alts.iter()
658            .map(|alt| {
659                // The same normalisation the step used to run: a grammar
660                // that appended to `a` or `action_fns` after the builder
661                // last touched `action_order` gets the fallback chain built
662                // for it here instead of there.
663                let actions = resolved_alt_action_order(
664                    &alt.a,
665                    &alt.action_fns,
666                    &alt.matched_action_fns,
667                    &alt.action_order,
668                );
669                let observed = alt.c_match.is_some()
670                    || alt.c_lex_match.is_some()
671                    || alt.e_match.is_some()
672                    || alt.p_match.is_some()
673                    || alt.r_match.is_some()
674                    || alt.b_match.is_some()
675                    || alt.h_match.is_some()
676                    || actions
677                        .iter()
678                        .any(|binding| matches!(binding, AltActionBinding::Matched(_)));
679                let named = actions
680                    .iter()
681                    .any(|binding| matches!(binding, AltActionBinding::Named(_)));
682                PreparedAlt {
683                    p: Self::prepared_route(alt.p.as_deref(), rules, names),
684                    r: Self::prepared_route(alt.r.as_deref(), rules, names),
685                    actions,
686                    observed,
687                    named,
688                    groups: groups_enabled(alt, options),
689                    group_tags: listed(&alt.g).map(str::to_owned).collect(),
690                }
691            })
692            .collect()
693    }
694
695    fn prepared_route(
696        route: Option<&str>,
697        rules: &IndexMap<String, Arc<RuleSpec>>,
698        names: &[RuleName],
699    ) -> PreparedRoute {
700        // An empty route name is "no route" at the transition, so it is not
701        // one here either.
702        let Some(route) = route.filter(|route| !route.is_empty()) else {
703            return PreparedRoute::ByName;
704        };
705        match rules.get_full(route) {
706            Some((slot, _, spec)) => PreparedRoute::Static {
707                slot,
708                name: names[slot].clone(),
709                spec: Arc::clone(spec),
710            },
711            None => PreparedRoute::ByName,
712        }
713    }
714
715    /// Resolve a rule name to the shared name handle and the installed
716    /// spec in one lookup.
717    ///
718    /// Every route into a rule needs both, and used to hash the same
719    /// three-byte name three times over to get them: once to ask whether
720    /// the rule existed, once for the shared handle, once for the spec.
721    /// `get_full` answers all three at once -- absence, the index the
722    /// handle sits at, and the spec. The index is also the rule's slot in
723    /// the prepared table, which the rule carries so that the next step can
724    /// find its state without asking again.
725    fn installed(&self, name: &str) -> Option<(usize, RuleName, &Arc<RuleSpec>)> {
726        let (index, _, spec) = self.rules.get_full(name)?;
727        Some((index, self.names[index].clone(), spec))
728    }
729
730    pub fn add_action(&mut self, name: String, action: Action) {
731        self.actions.insert(name, action);
732    }
733
734    pub fn add_context_action(&mut self, name: String, action: ContextAction) {
735        self.context_actions.insert(name, action);
736    }
737
738    pub fn add_matched_action(&mut self, name: String, action: AltAction) {
739        self.matched_actions.insert(name, action);
740    }
741
742    pub fn add_state_action(&mut self, name: String, action: StateAction) {
743        self.state_actions.insert(name, action);
744    }
745
746    pub fn add_token_subscriber(&mut self, subscriber: TokenSubscriber) {
747        self.token_subscribers.push(subscriber);
748    }
749
750    pub fn add_lex_subscriber(&mut self, subscriber: LexSubscriber) {
751        self.lex_subscribers.push(subscriber);
752    }
753
754    pub fn add_rule_subscriber(&mut self, subscriber: RuleSubscriber) {
755        self.rule_subscribers.push(subscriber);
756    }
757
758    pub fn add_parse_guard(&mut self, guard: ParseGuard) {
759        self.parse_guards.push(guard);
760    }
761
762    pub fn add_rule_done_subscriber(&mut self, subscriber: RuleDoneSubscriber) {
763        self.rule_done_subscribers.push(subscriber);
764    }
765
766    pub fn set_instance_info(&mut self, instance: InstanceInfo) {
767        self.instance = instance;
768    }
769
770    fn run_action(
771        &self,
772        name: &str,
773        rule: &mut Rule,
774        context: &mut Context,
775    ) -> Result<(), TabnasError> {
776        self.run_action_with_config(name, rule, context, None)
777    }
778
779    fn run_after_actions(
780        &self,
781        spec: &RuleSpec,
782        prepared: Option<&PreparedRule>,
783        is_open: bool,
784        rule: &mut Rule,
785        context: &mut Context,
786        site: ParseSite<'_>,
787    ) -> Result<(), TabnasError> {
788        if (is_open && !rule.ao) || (!is_open && !rule.ac) {
789            return Ok(());
790        }
791        // `ao`/`ac` above are run control, not presence: a rule carries
792        // them set whether or not it declares an after action. The order
793        // itself says whether there is anything to run, and when there is
794        // not the phase costs nothing -- not the list, and not the
795        // reference count on the next rule the state callbacks would have
796        // been handed.
797        let by_spec;
798        let bindings: &[ActionBinding] = match prepared {
799            Some(prepared) => prepared.after(is_open),
800            None => {
801                let (actions, callbacks, states, order) = if is_open {
802                    (&spec.ao, &spec.ao_fns, &spec.ao_state_fns, &spec.ao_order)
803                } else {
804                    (&spec.ac, &spec.ac_fns, &spec.ac_state_fns, &spec.ac_order)
805                };
806                by_spec = resolved_action_order(actions, callbacks, states, order);
807                &by_spec
808            }
809        };
810        if bindings.is_empty() {
811            return Ok(());
812        }
813        let next = rule.next_rule.clone();
814        let mut output = None;
815        for binding in bindings {
816            output = match binding {
817                ActionBinding::Named(action) => {
818                    if let Some(callback) = self.state_actions.get(action) {
819                        self.run_state_callback(
820                            "named lifecycle after action",
821                            callback,
822                            rule,
823                            context,
824                            next.as_deref(),
825                            output,
826                        )
827                        .map_err(|error| {
828                            self.attach_action_error(
829                                error,
830                                site.source,
831                                rule,
832                                site.stack,
833                                site.alts,
834                            )
835                        })?
836                    } else {
837                        self.run_action(action, rule, context).map_err(|error| {
838                            self.attach_action_error(
839                                error,
840                                site.source,
841                                rule,
842                                site.stack,
843                                site.alts,
844                            )
845                        })?;
846                        None
847                    }
848                }
849                ActionBinding::Callback(callback) => {
850                    self.run_context_callback("lifecycle after action", callback, rule, context)
851                        .map_err(|error| {
852                            self.attach_action_error(
853                                error,
854                                site.source,
855                                rule,
856                                site.stack,
857                                site.alts,
858                            )
859                        })?;
860                    None
861                }
862                ActionBinding::State(callback) => self
863                    .run_state_callback(
864                        "lifecycle after action",
865                        callback,
866                        rule,
867                        context,
868                        next.as_deref(),
869                        output,
870                    )
871                    .map_err(|error| {
872                        self.attach_action_error(error, site.source, rule, site.stack, site.alts)
873                    })?,
874            };
875            output = self.check_lifecycle_output(output, rule, site)?;
876        }
877        Ok(())
878    }
879
880    fn run_context_callback(
881        &self,
882        label: &str,
883        callback: &ContextAction,
884        rule: &mut Rule,
885        context: &mut Context,
886    ) -> Result<(), TabnasError> {
887        context.set_rule(rule);
888        match catch_unwind(AssertUnwindSafe(|| callback(rule, context))) {
889            Ok(result) => result.map_err(|action_error| {
890                let token = match rule.state {
891                    RuleState::Open => rule.o0().or_else(|| rule.c0()),
892                    RuleState::Close => rule.c0().or_else(|| rule.o0()),
893                };
894                let mut error = TabnasError::new(
895                    action_error.code,
896                    token.map_or("", |value| value.src.as_str()),
897                    "",
898                    token.map_or(0, |value| value.site.pos),
899                    token.map_or(1, |value| value.site.ri),
900                    token.map_or(1, |value| value.site.ci),
901                );
902                error.detail = action_error.detail;
903                error
904            }),
905            Err(payload) => Err(self.action_panic(payload, label, rule)),
906        }
907    }
908
909    fn run_state_callback(
910        &self,
911        label: &str,
912        callback: &StateAction,
913        rule: &mut Rule,
914        context: &mut Context,
915        next: Option<&RuleSnapshot>,
916        out: Option<Token>,
917    ) -> Result<Option<Token>, TabnasError> {
918        context.set_rule(rule);
919        match catch_unwind(AssertUnwindSafe(|| callback(rule, context, next, out))) {
920            Ok(result) => result.map_err(|action_error| {
921                let token = match rule.state {
922                    RuleState::Open => rule.o0().or_else(|| rule.c0()),
923                    RuleState::Close => rule.c0().or_else(|| rule.o0()),
924                };
925                let mut error = TabnasError::new(
926                    action_error.code,
927                    token.map_or("", |value| value.src.as_str()),
928                    "",
929                    token.map_or(0, |value| value.site.pos),
930                    token.map_or(1, |value| value.site.ri),
931                    token.map_or(1, |value| value.site.ci),
932                );
933                error.detail = action_error.detail;
934                error
935            }),
936            Err(payload) => Err(self.action_panic(payload, label, rule)),
937        }
938    }
939
940    fn check_lifecycle_output(
941        &self,
942        output: Option<Token>,
943        rule: &Rule,
944        site: ParseSite<'_>,
945    ) -> Result<Option<Token>, TabnasError> {
946        let Some(token) = output.as_ref().filter(|token| !token.err.is_empty()) else {
947            return Ok(output);
948        };
949        Err(self.raised_token_error(token, rule, site))
950    }
951
952    fn raised_token_error(&self, token: &Token, rule: &Rule, site: ParseSite<'_>) -> TabnasError {
953        let error = TabnasError::new(
954            raised_error_code(token),
955            token.src.clone(),
956            site.source,
957            token.site.pos,
958            token.site.ri,
959            token.site.ci,
960        );
961        self.attach_error(error, rule, site.stack, site.alts, Some(token))
962    }
963
964    fn attach_action_error(
965        &self,
966        mut error: TabnasError,
967        src: &str,
968        rule: &Rule,
969        stack: &[Rule],
970        alts: &[AltSpec],
971    ) -> TabnasError {
972        error.full_source = src.into();
973        let token = match rule.state {
974            RuleState::Open => rule.o0().or_else(|| rule.c0()),
975            RuleState::Close => rule.c0().or_else(|| rule.o0()),
976        };
977        self.attach_error(error, rule, stack, alts, token)
978    }
979
980    fn run_action_with_config(
981        &self,
982        name: &str,
983        rule: &mut Rule,
984        context: &mut Context,
985        config: Option<&Value>,
986    ) -> Result<(), TabnasError> {
987        context.set_rule(rule);
988        match catch_unwind(AssertUnwindSafe(|| {
989            run_builtin_action_with_info(name, rule, context, config, &self.options.info)
990        })) {
991            Ok(true) => return Ok(()),
992            Ok(false) => {}
993            Err(payload) => return Err(self.action_panic(payload, name, rule)),
994        }
995        if let Some(action) = self.actions.get(name) {
996            return match catch_unwind(AssertUnwindSafe(|| action(rule))) {
997                Ok(()) => Ok(()),
998                Err(payload) => Err(self.action_panic(payload, name, rule)),
999            };
1000        }
1001        if let Some(action) = self.context_actions.get(name) {
1002            return self.run_context_callback(name, action, rule, context);
1003        }
1004        let token = match rule.state {
1005            RuleState::Open => rule.o0().or_else(|| rule.c0()),
1006            RuleState::Close => rule.c0().or_else(|| rule.o0()),
1007        };
1008        let mut error = TabnasError::new(
1009            "unknown",
1010            name,
1011            "",
1012            token.map_or(0, |value| value.site.pos),
1013            token.map_or(1, |value| value.site.ri),
1014            token.map_or(1, |value| value.site.ci),
1015        );
1016        error.detail = format!("unknown action: {name}");
1017        Err(error)
1018    }
1019
1020    fn action_panic(
1021        &self,
1022        payload: Box<dyn std::any::Any + Send>,
1023        name: &str,
1024        rule: &Rule,
1025    ) -> TabnasError {
1026        let token = match rule.state {
1027            RuleState::Open => rule.o0().or_else(|| rule.c0()),
1028            RuleState::Close => rule.c0().or_else(|| rule.o0()),
1029        };
1030        TabnasError::from_panic(
1031            payload,
1032            &format!("action {name}"),
1033            "",
1034            token.map_or(0, |value| value.site.pos),
1035            token.map_or(1, |value| value.site.ri),
1036            token.map_or(1, |value| value.site.ci),
1037            &self.options,
1038        )
1039    }
1040
1041    fn attach_error(
1042        &self,
1043        mut error: TabnasError,
1044        rule: &Rule,
1045        stack: &[Rule],
1046        alts: &[AltSpec],
1047        token: Option<&Token>,
1048    ) -> TabnasError {
1049        let mut rule_stack: Vec<String> = stack.iter().map(|item| item.name.to_string()).collect();
1050        rule_stack.push(rule.name.to_string());
1051        let expected = alts
1052            .iter()
1053            .filter_map(|alt| alt.s.first())
1054            .flat_map(|tins| tins.iter().copied())
1055            .map(|tin| self.options.token_name(tin))
1056            .collect();
1057        error.attach_context(
1058            &rule.name,
1059            if rule.state == RuleState::Open {
1060                "o"
1061            } else {
1062                "c"
1063            },
1064            rule_stack,
1065            token,
1066            expected,
1067        );
1068        self.decorate_error(&mut error);
1069        error
1070    }
1071
1072    fn decorate_error(&self, error: &mut TabnasError) {
1073        error.apply_options(&self.options);
1074        error.plugins = self.instance.plugins.clone();
1075    }
1076
1077    fn catch_callback<T>(
1078        &self,
1079        api: &str,
1080        src: &str,
1081        callback: impl FnOnce() -> T,
1082    ) -> Result<T, TabnasError> {
1083        catch_unwind(AssertUnwindSafe(callback))
1084            .map_err(|payload| TabnasError::from_panic(payload, api, src, 0, 1, 1, &self.options))
1085    }
1086
1087    /// The `cancel` error a budget or a guard stops the parse with, at the
1088    /// token about to be read.
1089    fn cancelled(&self, src: &str, context: &Context, rule: &Rule, stack: &[Rule]) -> TabnasError {
1090        let token = context.t.first();
1091        let pnt = token
1092            .map(|token| {
1093                (
1094                    token.src.as_str(),
1095                    token.site.pos,
1096                    token.site.ri,
1097                    token.site.ci,
1098                )
1099            })
1100            .unwrap_or(("", 0, 1, 1));
1101        let error = TabnasError::new("cancel", pnt.0, src, pnt.1, pnt.2, pnt.3);
1102        self.attach_active_error(error, rule, stack, token)
1103    }
1104
1105    fn attach_active_error(
1106        &self,
1107        mut error: TabnasError,
1108        rule: &Rule,
1109        stack: &[Rule],
1110        token: Option<&Token>,
1111    ) -> TabnasError {
1112        if let Some(spec) = self.rules.get(&*rule.name) {
1113            let alts = if rule.state == RuleState::Open {
1114                &spec.open
1115            } else {
1116                &spec.close
1117            };
1118            self.attach_error(error, rule, stack, alts, token)
1119        } else {
1120            self.decorate_error(&mut error);
1121            error
1122        }
1123    }
1124
1125    fn phase_token(rule: &Rule) -> Option<&Token> {
1126        match rule.state {
1127            RuleState::Open => rule.o0().or_else(|| rule.c0()),
1128            RuleState::Close => rule.c0().or_else(|| rule.o0()),
1129        }
1130    }
1131
1132    fn ancestors_for<'a>(rule: &Rule, stack: &'a [Rule]) -> &'a [Rule] {
1133        if stack.last().is_some_and(|ancestor| ancestor.i == rule.i) {
1134            &stack[..stack.len() - 1]
1135        } else {
1136            stack
1137        }
1138    }
1139
1140    /// A copy of the rule that just finished, when something will read it.
1141    ///
1142    /// [`Parser::notify_rule_done`] is its only reader, and that returns
1143    /// without looking when no `ruleDone` subscriber is installed. Cloning
1144    /// a `Rule` copies the value tree it has built with it, which is 3.3%
1145    /// of a 1 MB parse spent for nobody in a grammar that subscribes to
1146    /// nothing. This is the treatment `RuleDoneAlt` already gets at the
1147    /// transition arms, for the same reason.
1148    fn rule_done_copy(&self, rule: &Rule) -> Option<Rule> {
1149        (!self.rule_done_subscribers.is_empty()).then(|| rule.clone())
1150    }
1151
1152    #[allow(clippy::too_many_arguments)]
1153    fn notify_rule_done(
1154        &self,
1155        rule: &Rule,
1156        context: &Context,
1157        state: RuleState,
1158        alt: Option<RuleDoneAlt>,
1159        probe: bool,
1160        src: &str,
1161        stack: &[Rule],
1162    ) -> Result<(), TabnasError> {
1163        if self.rule_done_subscribers.is_empty() {
1164            return Ok(());
1165        }
1166        let done = RuleDone {
1167            state,
1168            alt,
1169            forced: false,
1170            probe,
1171        };
1172        let mut site_rule = rule.clone();
1173        site_rule.state = state;
1174        for subscriber in &self.rule_done_subscribers {
1175            let result = self.catch_callback("ruleDone subscriber", src, || {
1176                subscriber(rule, context, &done)
1177            });
1178            result.map_err(|error| {
1179                self.attach_active_error(
1180                    error,
1181                    &site_rule,
1182                    Self::ancestors_for(&site_rule, stack),
1183                    Self::phase_token(&site_rule),
1184                )
1185            })?;
1186        }
1187        Ok(())
1188    }
1189
1190    fn notify_forced_close(
1191        &self,
1192        rule: &Rule,
1193        context: &Context,
1194        probe: bool,
1195        src: &str,
1196        stack: &[Rule],
1197    ) -> Result<(), TabnasError> {
1198        if self.rule_done_subscribers.is_empty() {
1199            return Ok(());
1200        }
1201        let done = RuleDone {
1202            state: RuleState::Close,
1203            alt: None,
1204            forced: true,
1205            probe,
1206        };
1207        let mut site_rule = rule.clone();
1208        site_rule.state = RuleState::Close;
1209        for subscriber in &self.rule_done_subscribers {
1210            let result = self.catch_callback("ruleDone subscriber", src, || {
1211                subscriber(rule, context, &done)
1212            });
1213            result.map_err(|error| {
1214                self.attach_active_error(
1215                    error,
1216                    &site_rule,
1217                    Self::ancestors_for(&site_rule, stack),
1218                    Self::phase_token(&site_rule),
1219                )
1220            })?;
1221        }
1222        Ok(())
1223    }
1224
1225    fn attempt_recover(
1226        &self,
1227        error: TabnasError,
1228        current_rule: &mut Rule,
1229        stack: &mut Vec<Rule>,
1230        context: &mut Context,
1231        lexer: &mut Lexer,
1232        mode: &mut ParseMode<'_>,
1233    ) -> Result<bool, TabnasError> {
1234        let src = error.full_source.clone();
1235        let recover = &self.options.parse.recover;
1236
1237        // The order is TypeScript's `attemptRecover`: the error is recorded
1238        // as it is built, dropped again when it falls inside the suppress
1239        // window of the recovery before it, and only then is the cap read.
1240        // So a give-up leaves the error listed, once and without recovery
1241        // metadata, unless it was a cascade; and a cascade at the cap still
1242        // recovers, since dropping it keeps the list within the cap.
1243        let suppressed = context
1244            .recover_at
1245            .is_some_and(|at| context.v_abs.saturating_sub(at) < recover.suppress);
1246        let recorded = (!suppressed).then(|| {
1247            mode.errors.push(error.clone());
1248            context.errs.push(error.clone());
1249            mode.errors.len() - 1
1250        });
1251        if recover.max_recoveries < mode.errors.len() {
1252            return Ok(false);
1253        }
1254
1255        let no_progress = context.recover_at == Some(context.v_abs);
1256        let last_si = context.recover_si;
1257        context.recover_at = Some(context.v_abs);
1258
1259        let sync = compute_sync_tins(current_rule, stack, &self.rules, &self.options);
1260        let mut pending: std::collections::VecDeque<Token> = std::mem::take(&mut context.t).into();
1261        let mut skipped = 0usize;
1262
1263        let candidate = loop {
1264            let next = if let Some(token) = pending.pop_front() {
1265                Some(token)
1266            } else {
1267                loop {
1268                    let next_raw = self.catch_callback("lexer callback", &src, || {
1269                        lexer.next_raw_for_rule(current_rule, context)
1270                    });
1271                    let next_raw = next_raw.map_err(|error| {
1272                        self.attach_active_error(
1273                            error,
1274                            current_rule,
1275                            stack,
1276                            Self::phase_token(current_rule),
1277                        )
1278                    })?;
1279                    match next_raw {
1280                        Ok(mut token) => {
1281                            for subscriber in &self.lex_subscribers {
1282                                let result = self.catch_callback("lex subscriber", &src, || {
1283                                    subscriber(&mut token, current_rule, context)
1284                                });
1285                                result.map_err(|error| {
1286                                    self.attach_active_error(
1287                                        error,
1288                                        current_rule,
1289                                        stack,
1290                                        Some(&token),
1291                                    )
1292                                })?;
1293                            }
1294                            if self.ignore_tins.contains(&token.tin) {
1295                                continue;
1296                            }
1297                            for subscriber in &self.token_subscribers {
1298                                let result = self.catch_callback("token subscriber", &src, || {
1299                                    subscriber(&token)
1300                                });
1301                                result.map_err(|error| {
1302                                    self.attach_active_error(
1303                                        error,
1304                                        current_rule,
1305                                        stack,
1306                                        Some(&token),
1307                                    )
1308                                })?;
1309                            }
1310                            break Some(token);
1311                        }
1312                        Err(lex_error) => {
1313                            let mut token = error_token(&lex_error);
1314                            for subscriber in &self.lex_subscribers {
1315                                let result = self.catch_callback("lex subscriber", &src, || {
1316                                    subscriber(&mut token, current_rule, context)
1317                                });
1318                                result.map_err(|error| {
1319                                    self.attach_active_error(
1320                                        error,
1321                                        current_rule,
1322                                        stack,
1323                                        Some(&token),
1324                                    )
1325                                })?;
1326                            }
1327                            lexer.skip_bad(&token, mid_construct(&lex_error.code));
1328                            if skipped >= recover.max_skip {
1329                                break None;
1330                            }
1331                            skipped += 1;
1332                        }
1333                    }
1334                }
1335            };
1336            let Some(token) = next else {
1337                return Ok(false);
1338            };
1339            if token.tin == TIN_ZZ
1340                || (sync.contains(&token.tin)
1341                    && !(no_progress && last_si.is_some_and(|si| token.site.pos <= si)))
1342            {
1343                break token;
1344            }
1345            // A bad token is skipped like any other, but it did not move
1346            // the cursor when it was cut: a custom matcher's `Lexer::bad`
1347            // leaves it where it was, and so does one buffered under
1348            // relexing. Step past it, as TypeScript's `advanceLexPast` does,
1349            // or the next fetch would cut the same bad token again.
1350            if token.tin == TIN_BD {
1351                lexer.skip_bad(&token, mid_construct(&token.why));
1352            }
1353            if skipped >= recover.max_skip {
1354                return Ok(false);
1355            }
1356            skipped += 1;
1357        };
1358
1359        if candidate.tin == TIN_ZZ
1360            && no_progress
1361            && last_si.is_some_and(|si| candidate.site.pos <= si)
1362        {
1363            return Ok(false);
1364        }
1365        context.recover_si = Some(candidate.site.pos);
1366        if let Some(index) = recorded {
1367            let recovered = Some(crate::RecoveredAt {
1368                skipped,
1369                sync: Some(candidate.tin),
1370                bad: false,
1371            });
1372            if let Some(entry) = context.errs.get_mut(index) {
1373                entry.recovered.clone_from(&recovered);
1374            }
1375            if let Some(entry) = mode.errors.get_mut(index) {
1376                entry.recovered = recovered;
1377            }
1378        }
1379
1380        context.t.push(candidate.clone());
1381        context.t.extend(pending);
1382        context.bad_to = None;
1383        context.bad_error = None;
1384
1385        if !recover.pop_until_valid {
1386            // The only pop that resumes a parent WITHOUT accepting a
1387            // child node over the top of it, so the only one that would
1388            // see a parked `child_node`. `Rule::park_child_node` is
1389            // skipped for the whole parse when this option is off, so
1390            // nothing is parked to see.
1391            if let Some(parent) = stack.pop() {
1392                // The erroring rule is dropped: close the probes it opened.
1393                context.probe_abandon(current_rule);
1394                *current_rule = parent;
1395                return Ok(true);
1396            }
1397            return Ok(false);
1398        }
1399
1400        if accepts_close(current_rule, candidate.tin, &self.rules, &self.options) {
1401            if current_rule.state == RuleState::Open {
1402                current_rule.state = RuleState::Close;
1403            } else {
1404                current_rule.skip_befores = true;
1405            }
1406            return Ok(true);
1407        }
1408
1409        // Close the probes each abandoned rule opened, subscribed or not.
1410        let probe = context.probe_abandon(current_rule);
1411        self.notify_forced_close(current_rule, context, probe, &src, stack)?;
1412        while let Some(mut parent) = stack.pop() {
1413            parent.accept_child(current_rule);
1414            if accepts_close(&parent, candidate.tin, &self.rules, &self.options) {
1415                *current_rule = parent;
1416                return Ok(true);
1417            }
1418            let probe = context.probe_abandon(&parent);
1419            self.notify_forced_close(&parent, context, probe, &src, stack)?;
1420            *current_rule = parent;
1421        }
1422        Ok(false)
1423    }
1424
1425    #[allow(clippy::too_many_arguments)]
1426    fn recover_error_pass(
1427        &self,
1428        error: TabnasError,
1429        state: RuleState,
1430        mut alt: Option<RuleDoneAlt>,
1431        fallback_error_token: bool,
1432        src: &str,
1433        current_rule: &mut Rule,
1434        stack: &mut Vec<Rule>,
1435        context: &mut Context,
1436        lexer: &mut Lexer,
1437        mode: &mut ParseMode<'_>,
1438    ) -> Result<(), TabnasError> {
1439        // TypeScript's RuleSpec.bad performs recovery inside the rule pass;
1440        // the ordinary ruleDone event is dispatched only after that pass
1441        // returns. Preserve that ordering so any synthesized forced-close
1442        // events precede this final attempted-pass event.
1443        let event_rule = current_rule.clone();
1444        // The failing pass is the probe's if one is open where it failed,
1445        // even when the recovery below closes it before the pass is
1446        // reported.
1447        let probe_at_error = 0 < context.probe_depth();
1448        let recovered = mode.recovering
1449            && self.attempt_recover(error.clone(), current_rule, stack, context, lexer, mode)?;
1450        if !recovered && fallback_error_token {
1451            if let Some(alt) = alt.as_mut().filter(|alt| alt.err.is_none()) {
1452                let tin = self.options.token(&error.token.name).unwrap_or(TIN_BD);
1453                let mut token = Token::new(
1454                    error.token.name.clone(),
1455                    tin,
1456                    Value::Undefined,
1457                    error.token.src.clone(),
1458                    crate::Point {
1459                        len: error.len,
1460                        site: crate::Site {
1461                            si: error.pos,
1462                            pos: error.pos,
1463                            ri: error.row,
1464                            ci: error.col,
1465                        },
1466                    },
1467                );
1468                token.bad(&error.code);
1469                alt.err = Some(token);
1470            }
1471        }
1472        let probe = context.probe_take() || probe_at_error;
1473        self.notify_rule_done(&event_rule, context, state, alt, probe, src, stack)?;
1474        if recovered {
1475            Ok(())
1476        } else {
1477            // TypeScript's `RuleSpec.bad` gives up by rethrowing the last
1478            // error it recorded, which `attempt_recover` has just recorded
1479            // or dropped as a cascade, so the list is already complete. Only
1480            // an empty list makes it raise, and record, a fresh one.
1481            if mode.recovering && !mode.errors.is_empty() {
1482                mode.gave_up = true;
1483            }
1484            Err(error)
1485        }
1486    }
1487
1488    #[allow(clippy::too_many_arguments)]
1489    fn recover_after_actions(
1490        &self,
1491        result: Result<(), TabnasError>,
1492        state: RuleState,
1493        alt: Option<RuleDoneAlt>,
1494        src: &str,
1495        current_rule: &mut Rule,
1496        stack: &mut Vec<Rule>,
1497        context: &mut Context,
1498        lexer: &mut Lexer,
1499        mode: &mut ParseMode<'_>,
1500    ) -> Result<bool, TabnasError> {
1501        let Err(error) = result else {
1502            return Ok(false);
1503        };
1504        self.recover_error_pass(
1505            error,
1506            state,
1507            alt,
1508            true,
1509            src,
1510            current_rule,
1511            stack,
1512            context,
1513            lexer,
1514            mode,
1515        )?;
1516        Ok(true)
1517    }
1518
1519    pub fn parse(&self, src: &str) -> Result<Value, TabnasError> {
1520        self.parse_with_meta(src, Value::Undefined)
1521    }
1522
1523    pub fn parse_with_meta(&self, src: &str, meta: Value) -> Result<Value, TabnasError> {
1524        self.parse_with_owner(src, meta, None, None)
1525    }
1526
1527    pub(crate) fn parse_for(
1528        &self,
1529        owner: &crate::Tabnas,
1530        src: &str,
1531        meta: Value,
1532    ) -> Result<Value, TabnasError> {
1533        self.parse_with_owner(src, meta, Some(owner), None)
1534    }
1535
1536    pub(crate) fn parse_for_with_context(
1537        &self,
1538        owner: &crate::Tabnas,
1539        src: &str,
1540        meta: Value,
1541        parent: &ContextSeed,
1542    ) -> Result<Value, TabnasError> {
1543        self.parse_with_owner(src, meta, Some(owner), Some(parent))
1544    }
1545
1546    fn parse_with_owner(
1547        &self,
1548        src: &str,
1549        meta: Value,
1550        owner: Option<&crate::Tabnas>,
1551        parent: Option<&ContextSeed>,
1552    ) -> Result<Value, TabnasError> {
1553        match catch_unwind(AssertUnwindSafe(|| {
1554            self.parse_uncaught(src, meta, owner, parent)
1555        })) {
1556            Ok(result) => result,
1557            Err(payload) => {
1558                let mut error =
1559                    TabnasError::from_panic(payload, "Parser::parse", src, 0, 1, 1, &self.options);
1560                self.decorate_error(&mut error);
1561                Err(error)
1562            }
1563        }
1564    }
1565
1566    fn parse_uncaught(
1567        &self,
1568        src: &str,
1569        meta: Value,
1570        owner: Option<&crate::Tabnas>,
1571        parent: Option<&ContextSeed>,
1572    ) -> Result<Value, TabnasError> {
1573        if let Some(result) = self.run_parser_start(src, &meta, owner, parent) {
1574            return result.map_err(|mut error| {
1575                self.decorate_error(&mut error);
1576                error
1577            });
1578        }
1579        let mut errors = Vec::new();
1580        let recovering = self.options.parse.recover.enabled;
1581        let mut mode = ParseMode {
1582            continuation: None,
1583            recovering,
1584            errors: &mut errors,
1585            partial: None,
1586            gave_up: false,
1587        };
1588        let result = self
1589            .parse_inner(src, meta, owner, parent, &mut mode)
1590            .map_err(|mut error| {
1591                self.decorate_error(&mut error);
1592                error
1593            });
1594        match result {
1595            Err(_) if recovering => Ok(mode
1596                .partial
1597                .and_then(PartialValue::into_value)
1598                .unwrap_or(Value::Undefined)),
1599            other => other,
1600        }
1601    }
1602
1603    pub fn parse_recover(&self, src: &str) -> ParseRecovery {
1604        self.parse_recover_with_meta(src, Value::Undefined)
1605    }
1606
1607    pub fn parse_recover_with_meta(&self, src: &str, meta: Value) -> ParseRecovery {
1608        self.parse_recover_with_owner(src, meta, None, None)
1609    }
1610
1611    pub(crate) fn parse_recover_for(
1612        &self,
1613        owner: &crate::Tabnas,
1614        src: &str,
1615        meta: Value,
1616    ) -> ParseRecovery {
1617        self.parse_recover_with_owner(src, meta, Some(owner), None)
1618    }
1619
1620    pub(crate) fn parse_recover_for_with_context(
1621        &self,
1622        owner: &crate::Tabnas,
1623        src: &str,
1624        meta: Value,
1625        parent: &ContextSeed,
1626    ) -> ParseRecovery {
1627        self.parse_recover_with_owner(src, meta, Some(owner), Some(parent))
1628    }
1629
1630    fn parse_recover_with_owner(
1631        &self,
1632        src: &str,
1633        meta: Value,
1634        owner: Option<&crate::Tabnas>,
1635        parent: Option<&ContextSeed>,
1636    ) -> ParseRecovery {
1637        match catch_unwind(AssertUnwindSafe(|| {
1638            self.parse_recover_uncaught(src, meta, owner, parent)
1639        })) {
1640            Ok(result) => result,
1641            Err(payload) => {
1642                let mut error = TabnasError::from_panic(
1643                    payload,
1644                    "Parser::parse_recover",
1645                    src,
1646                    0,
1647                    1,
1648                    1,
1649                    &self.options,
1650                );
1651                self.decorate_error(&mut error);
1652                ParseRecovery {
1653                    value: None,
1654                    errors: Vec::new(),
1655                    fatal: Some(error),
1656                }
1657            }
1658        }
1659    }
1660
1661    fn parse_recover_uncaught(
1662        &self,
1663        src: &str,
1664        meta: Value,
1665        owner: Option<&crate::Tabnas>,
1666        parent: Option<&ContextSeed>,
1667    ) -> ParseRecovery {
1668        if let Some(result) = self.run_parser_start(src, &meta, owner, parent) {
1669            return match result {
1670                Ok(value) => ParseRecovery {
1671                    value: Some(value),
1672                    errors: Vec::new(),
1673                    fatal: None,
1674                },
1675                Err(mut error) => {
1676                    self.decorate_error(&mut error);
1677                    ParseRecovery {
1678                        value: None,
1679                        errors: Vec::new(),
1680                        fatal: Some(error),
1681                    }
1682                }
1683            };
1684        }
1685        let mut errors = Vec::new();
1686        let recovering = self.options.parse.recover.enabled;
1687        let (result, partial, gave_up) = {
1688            let mut mode = ParseMode {
1689                continuation: None,
1690                recovering,
1691                errors: &mut errors,
1692                partial: None,
1693                gave_up: false,
1694            };
1695            let result = self
1696                .parse_inner(src, meta, owner, parent, &mut mode)
1697                .map_err(|mut error| {
1698                    self.decorate_error(&mut error);
1699                    error
1700                });
1701            (
1702                result,
1703                mode.partial.and_then(PartialValue::into_value),
1704                mode.gave_up,
1705            )
1706        };
1707        for error in &mut errors {
1708            self.decorate_error(error);
1709        }
1710        match result {
1711            Ok(value) => ParseRecovery {
1712                value: Some(value),
1713                errors,
1714                fatal: None,
1715            },
1716            Err(error) => {
1717                // The error that ended the parse is listed once, where the
1718                // parse ended, as TypeScript's constructor lists it, unless
1719                // recovery gave up on an error it had already accounted for.
1720                if !gave_up {
1721                    errors.push(error.clone());
1722                }
1723                ParseRecovery {
1724                    value: recovering.then_some(partial).flatten(),
1725                    errors,
1726                    fatal: (!recovering).then_some(error),
1727                }
1728            }
1729        }
1730    }
1731
1732    fn run_parser_start(
1733        &self,
1734        src: &str,
1735        meta: &Value,
1736        owner: Option<&crate::Tabnas>,
1737        parent: Option<&ContextSeed>,
1738    ) -> Option<Result<Value, TabnasError>> {
1739        let result = if let Some(start) = self.options.parser.start_with_context.as_ref() {
1740            let Some(owner) = owner else {
1741                let mut error = TabnasError::new("internal", "", src, 0, 1, 1);
1742                error.detail =
1743                    "parser.start requires an owning Tabnas instance; call Tabnas::parse".into();
1744                self.decorate_error(&mut error);
1745                return Some(Err(error));
1746            };
1747            catch_unwind(AssertUnwindSafe(|| start(src, owner, meta, parent)))
1748        } else if let Some(start) = self.options.parser.start_with_instance.as_ref() {
1749            let Some(owner) = owner else {
1750                let mut error = TabnasError::new("internal", "", src, 0, 1, 1);
1751                error.detail =
1752                    "parser.start requires an owning Tabnas instance; call Tabnas::parse".into();
1753                self.decorate_error(&mut error);
1754                return Some(Err(error));
1755            };
1756            catch_unwind(AssertUnwindSafe(|| start(src, owner, meta)))
1757        } else {
1758            let start = self.options.parser.start.as_ref()?;
1759            catch_unwind(AssertUnwindSafe(|| start(src)))
1760        };
1761        Some(match result {
1762            Ok(result) => result.map_err(|error| *error),
1763            Err(payload) => Err(TabnasError::from_panic(
1764                payload,
1765                "parser.start",
1766                src,
1767                0,
1768                1,
1769                1,
1770                &self.options,
1771            )),
1772        })
1773    }
1774
1775    /// Return the token kinds that can legally follow `src` when it is
1776    /// treated as a prefix. The result is an intentional over-approximation:
1777    /// runtime conditions and counters may still reject a listed token.
1778    pub fn continuations(&self, src: &str) -> Continuations {
1779        self.continuations_with_owner(src, None)
1780    }
1781
1782    pub(crate) fn continuations_for(&self, owner: &crate::Tabnas, src: &str) -> Continuations {
1783        self.continuations_with_owner(src, Some(owner))
1784    }
1785
1786    fn continuations_with_owner(&self, src: &str, owner: Option<&crate::Tabnas>) -> Continuations {
1787        catch_unwind(AssertUnwindSafe(|| self.continuations_uncaught(src, owner)))
1788            .unwrap_or_else(|_| self.start_continuations())
1789    }
1790
1791    fn continuations_uncaught(&self, src: &str, owner: Option<&crate::Tabnas>) -> Continuations {
1792        let mut capture = ContinuationCapture::default();
1793        let mut errors = Vec::new();
1794        let result = {
1795            let mut mode = ParseMode {
1796                continuation: Some(&mut capture),
1797                recovering: false,
1798                errors: &mut errors,
1799                partial: None,
1800                gave_up: false,
1801            };
1802            self.parse_inner(src, Value::Undefined, owner, None, &mut mode)
1803        };
1804        let mut tins = if result.is_ok() {
1805            if capture.have_end {
1806                capture.at_end.insert(TIN_ZZ);
1807                capture.at_end.into_iter().collect()
1808            } else {
1809                self.start_openers()
1810            }
1811        } else if capture.failure.is_empty() {
1812            self.start_openers()
1813        } else {
1814            capture.failure
1815        };
1816        tins.sort_unstable();
1817        tins.dedup();
1818        let tokens = tins
1819            .iter()
1820            .map(|tin| self.options.token_name(*tin))
1821            .collect();
1822        Continuations { tins, tokens }
1823    }
1824
1825    fn start_continuations(&self) -> Continuations {
1826        let tins = self.start_openers();
1827        let tokens = tins
1828            .iter()
1829            .map(|tin| self.options.token_name(*tin))
1830            .collect();
1831        Continuations { tins, tokens }
1832    }
1833
1834    fn start_openers(&self) -> Vec<Tin> {
1835        let start = self.rules.get(&self.options.rule.start);
1836        let mut out = BTreeSet::new();
1837        if let Some(spec) = start {
1838            for alt in &spec.open {
1839                if groups_enabled(alt, &self.options) {
1840                    if let Some(slot) = alt.s.first() {
1841                        out.extend(completion_tins(slot));
1842                    }
1843                }
1844            }
1845        }
1846        out.into_iter().collect()
1847    }
1848
1849    /// The tins the rule can accept at `slot`, as the lexer's custom-matcher
1850    /// gate wants them, or nothing when there is no custom matcher to gate.
1851    ///
1852    /// Both consumers (the `fix_len` filter and the expected-first pass in
1853    /// `Lexer::next_raw_inner`) only read this list to decide WHICH of
1854    /// `options.match_tokens` may fire; with no match tokens the answer is
1855    /// the same for any list, and the walk over an empty table yields
1856    /// nothing either way. The empty slice is therefore exact, and it
1857    /// spares every token fetch the rule's accepted-token row entirely --
1858    /// the last work that sat on the fetch path of a grammar with no
1859    /// custom matcher at all. TS `makeMatchMatcher`
1860    /// returns null on an empty table and never asks (ts/src/lexer.ts).
1861    ///
1862    /// `options` is the one `Arc<Options>` the lexer reads too, so this
1863    /// guard consults the field its consumers consult and cannot drift
1864    /// from it.
1865    ///
1866    /// The table was collated over the alternates the group filters
1867    /// enabled at install. `rule.include` and `rule.exclude` are public and
1868    /// may have been rewritten since, and the step then chooses among the
1869    /// alternates the live filters enable (its `groups_prepared` guard),
1870    /// so the row is collated from the live filters too, rather than
1871    /// letting an alternate the step will not try decide which matcher
1872    /// runs first.
1873    fn expected_match_tins(&self, rule: &Rule, slot: usize) -> Cow<'_, [Tin]> {
1874        if self.options.match_tokens.is_empty() {
1875            return Cow::Borrowed(&[]);
1876        }
1877        // The table is the rule's, chosen by what the rule is called --
1878        // exactly as the name-keyed map this replaced chose it. The slot
1879        // is only a hint that skips the hash: `name` is public and a
1880        // callback may have written it, so the slot is trusted only while
1881        // the name installed there is still the rule's own, and anything
1882        // else falls back to the lookup by name. A slot never answers for
1883        // a name that is not at it.
1884        let index = match self.names.get(rule.slot) {
1885            Some(installed) if *installed == rule.name => rule.slot,
1886            _ => match self.rules.get_index_of(&*rule.name) {
1887                Some(index) => index,
1888                None => return Cow::Borrowed(&[]),
1889            },
1890        };
1891        let is_open = rule.state == RuleState::Open;
1892        if self.options.rule.include == self.prepared_include
1893            && self.options.rule.exclude == self.prepared_exclude
1894        {
1895            return Cow::Borrowed(self.expected_tins[index].at(is_open, slot));
1896        }
1897        let installed = &self.rules[index];
1898        let alts = if is_open {
1899            &installed.open
1900        } else {
1901            &installed.close
1902        };
1903        Cow::Owned(ExpectedTins::live(alts, &self.options, slot))
1904    }
1905
1906    /// Record, for `continuations()`, what could have followed where a
1907    /// fetch raised a bad token: the lexer's own fault, or a `#BD` token a
1908    /// custom matcher returned.
1909    ///
1910    /// TypeScript records nothing at such a fetch (`_contTins` is cleared
1911    /// when `parse_alts` begins and written only when every alternate has
1912    /// failed on a buffered token), so `Tabnas.continuations` computes the
1913    /// answer from the buffer for the rule that fetched, at position 0
1914    /// (`continuationTins(ctx, rule)`), or, when that rule is `NORULE`
1915    /// because the check for trailing content fetched, answers with the
1916    /// start rule's openers. Here a rule's fetch records the same set, and
1917    /// the trailing check records nothing, which `continuations_uncaught`
1918    /// turns into the start openers.
1919    fn capture_fetch_failure(
1920        &self,
1921        context: &Context,
1922        rule: &Rule,
1923        stack: &[Rule],
1924        mode: &mut ParseMode<'_>,
1925        fetch: Fetch,
1926    ) {
1927        if fetch != Fetch::Rule {
1928            return;
1929        }
1930        if let Some(capture) = mode.continuation.as_deref_mut() {
1931            capture.failure =
1932                continuation_tins(context, rule, stack, &self.rules, &self.options, 0, None);
1933        }
1934    }
1935
1936    #[allow(clippy::too_many_arguments)]
1937    fn ensure_lookahead(
1938        &self,
1939        lexer: &mut Lexer,
1940        context: &mut Context,
1941        rule: &mut Rule,
1942        count: usize,
1943        mode: &mut ParseMode<'_>,
1944        site: ParseSite<'_>,
1945        fetch: Fetch,
1946    ) -> Result<(), TabnasError> {
1947        while context.t.len() < count {
1948            if context.t.last().is_some_and(|token| token.tin == TIN_ZZ) {
1949                break;
1950            }
1951            let expected_match_tins = self.expected_match_tins(rule, context.t.len());
1952            let token = loop {
1953                let next = match context.next_replay() {
1954                    Some(token) => Ok(token),
1955                    None => {
1956                        let result = self.catch_callback("lexer callback", site.source, || {
1957                            lexer.next_rule_token(&expected_match_tins, rule, context)
1958                        });
1959                        result.map_err(|error| {
1960                            self.attach_active_error(
1961                                error,
1962                                rule,
1963                                site.stack,
1964                                Self::phase_token(rule),
1965                            )
1966                        })?
1967                    }
1968                };
1969                let mut token = match next {
1970                    Ok(token) => token,
1971                    // The lexer's own fault is a `#BD` token from here on,
1972                    // as it is in TypeScript, where `lex.next` builds the
1973                    // token, hands it to the lex subscribers and returns
1974                    // it, and `parse_alts` reads what came back. A
1975                    // subscriber may rewrite it, its code and position
1976                    // included, and the parse sees what it left: so the
1977                    // fault takes the path below, the one a `#BD` token a
1978                    // custom matcher returned takes, and the lexer's error
1979                    // itself goes no further than this token.
1980                    Err(error) => error_token(&error),
1981                };
1982                for subscriber in &self.lex_subscribers {
1983                    let result = self.catch_callback("lex subscriber", site.source, || {
1984                        subscriber(&mut token, rule, context)
1985                    });
1986                    result.map_err(|error| {
1987                        self.attach_active_error(error, rule, site.stack, Some(&token))
1988                    })?;
1989                }
1990                // A bad token a custom matcher returned (`Lexer::bad`,
1991                // `Lexer::bad_span`) is a lexer fault like any other, and
1992                // is handled here exactly as the lexer's own faults are
1993                // above, which is what TypeScript's fetch in `parse_alts`
1994                // does with every `#BD` token it is handed: raised at once,
1995                // with its own code at its own position, or under recovery
1996                // recorded, coalesced with the run it continues, and
1997                // stepped past. Only relexing leaves it in the lookahead,
1998                // for an alternate to re-cut. Buffered, it failed every
1999                // alternate it met, and the error named the first token of
2000                // the lookahead instead: `unexpected`, at the good token in
2001                // front of it.
2002                if token.tin == TIN_BD && !self.options.lex.relex {
2003                    let code = if token.why.is_empty() {
2004                        "unexpected"
2005                    } else {
2006                        token.why.as_str()
2007                    };
2008                    let error = TabnasError::new(
2009                        code,
2010                        token.src.clone(),
2011                        site.source,
2012                        token.site.pos,
2013                        token.site.ri,
2014                        token.site.ci,
2015                    );
2016                    let error = self.attach_error(error, rule, site.stack, site.alts, Some(&token));
2017                    if mode.recovering && fetch == Fetch::Rule {
2018                        if absorb_lex_error(&error, context, &self.options, mode.errors) {
2019                            lexer.skip_bad(&token, mid_construct(&error.code));
2020                            continue;
2021                        }
2022                        mode.gave_up = true;
2023                    }
2024                    self.capture_fetch_failure(context, rule, site.stack, mode, fetch);
2025                    return Err(error);
2026                }
2027                if token.tin == TIN_ZZ {
2028                    if let Some(capture) = mode.continuation.as_deref_mut() {
2029                        // The end is a legal continuation of a prefix that
2030                        // parses, whoever fetched it. What else is legal
2031                        // there is what the fetching rule's alternates could
2032                        // still take; the check for trailing content has no
2033                        // rule, and TypeScript's capture (the lex subscriber
2034                        // in `Tabnas.continuations`) answers it with nothing,
2035                        // since its `rule` is then `NORULE`.
2036                        capture.have_end = true;
2037                        if fetch == Fetch::Rule {
2038                            capture.at_end.extend(continuation_tins(
2039                                context,
2040                                rule,
2041                                site.stack,
2042                                &self.rules,
2043                                &self.options,
2044                                context.t.len(),
2045                                None,
2046                            ));
2047                        }
2048                    }
2049                }
2050                if !self.ignore_tins.contains(&token.tin) {
2051                    break token;
2052                }
2053            };
2054            for subscriber in &self.token_subscribers {
2055                let result =
2056                    self.catch_callback("token subscriber", site.source, || subscriber(&token));
2057                result.map_err(|error| {
2058                    self.attach_active_error(error, rule, site.stack, Some(&token))
2059                })?;
2060            }
2061            let is_end = token.tin == TIN_ZZ;
2062            context.t.push(token);
2063            if is_end {
2064                break;
2065            }
2066        }
2067        Ok(())
2068    }
2069
2070    fn parse_inner(
2071        &self,
2072        src: &str,
2073        meta: Value,
2074        owner: Option<&crate::Tabnas>,
2075        parent: Option<&ContextSeed>,
2076        mode: &mut ParseMode<'_>,
2077    ) -> Result<Value, TabnasError> {
2078        let input_meta = meta.clone();
2079        let mut context = Context::new(
2080            self.options.rewind.history,
2081            src,
2082            meta,
2083            Arc::clone(&self.options),
2084            self.instance.clone(),
2085        );
2086        if let Some(parent) = parent {
2087            context.apply_seed(parent);
2088        }
2089        for prepare in &self.options.parse.prepare {
2090            let outcome = self.catch_callback("parse.prepare", src, || {
2091                prepare.run(owner, &mut context, &input_meta)
2092            })?;
2093            if let Err(detail) = outcome {
2094                let mut error = TabnasError::new("internal", "", src, 0, 1, 1);
2095                error.detail = detail.into();
2096                return Err(error);
2097            }
2098        }
2099        for prepare in self.options.parse.named_prepare.values() {
2100            let outcome = self.catch_callback("parse.prepare", src, || {
2101                prepare.run(owner, &mut context, &input_meta)
2102            })?;
2103            if let Err(detail) = outcome {
2104                let mut error = TabnasError::new("internal", "", src, 0, 1, 1);
2105                error.detail = detail.into();
2106                return Err(error);
2107            }
2108        }
2109
2110        if src.is_empty() {
2111            return if self.options.lex.empty {
2112                Ok(self.options.lex.empty_result.clone())
2113            } else {
2114                Err(TabnasError::new("unexpected", "", src, 0, 1, 1))
2115            };
2116        }
2117
2118        // The cached regex is the one the parser was built with; use it
2119        // only while the options still carry the pattern it came from.
2120        let exclude_regex = if self.exclude_pattern == self.options.number.exclude {
2121            self.exclude_regex.clone()
2122        } else {
2123            compile_number_exclude(&self.options)
2124        };
2125        let mut lexer = Lexer::with_shared(src, Arc::clone(&self.options), exclude_regex);
2126
2127        // One lookup for the start rule: whether it exists, its shared
2128        // name handle and the spec to bind, which used to be three.
2129        let start_name = self.options.rule.start.as_str();
2130        let Some((start_slot, start_shared, start_spec)) = self.installed(start_name) else {
2131            return Ok(Value::Undefined);
2132        };
2133
2134        let mut current_rule = Rule::new(start_shared.clone(), Value::Undefined);
2135        current_rule.bind_spec(start_spec, start_shared, start_slot);
2136        // Instance 1, as in TypeScript, whose NORULE sentinel is made by
2137        // `makeRule` and takes 0; this engine's is made outside the count.
2138        current_rule.i = 1;
2139        let root_node = current_rule.node.clone();
2140        context.set_root(root_node.clone());
2141        let mut stack: Vec<Rule> = Vec::new();
2142        // Whether a pushed rule may let go of `child_node` while it is
2143        // buried. Read once: `self.options` is reached through `&self`,
2144        // so this cannot change under the parse, and the rule that parks
2145        // is the rule `attempt_recover` will resume.
2146        let park_child_nodes = self.options.parse.recover.pop_until_valid;
2147        let mut next_rule_id = 2;
2148        #[allow(unused_assignments)]
2149        let mut final_value = None;
2150
2151        let mut iterations = 0usize;
2152        let maxmul = if self.options.rule.maxmul == 0 {
2153            3
2154        } else {
2155            self.options.rule.maxmul
2156        };
2157        let max_iterations = self
2158            .rules
2159            .len()
2160            .saturating_mul(src.encode_utf16().count())
2161            .saturating_mul(4)
2162            .saturating_mul(maxmul)
2163            .max(100);
2164        let budget = &self.options.parse.budget;
2165
2166        // One match record for the whole parse, reset at the head of each
2167        // rule step. It used to be born twice per step -- a seed and a
2168        // per-alternate candidate -- and then moved twice more, at 320
2169        // bytes a move, to end up holding what one record could have held
2170        // all along. TypeScript keeps exactly one per context
2171        // (`ctx._palt`); a nested parse runs `parse_inner` again and so
2172        // gets its own, which is why this is a local and not a field.
2173        let mut matched = AltMatch::default();
2174
2175        'parse: loop {
2176            context.set_active(&current_rule, &stack);
2177            update_partial(mode, &root_node, &current_rule, &stack);
2178            iterations += 1;
2179            if iterations > max_iterations {
2180                let pnt = context
2181                    .t
2182                    .first()
2183                    .map(|t| (t.site.pos, t.site.ri, t.site.ci))
2184                    .unwrap_or((0, 1, 1));
2185                return Err(TabnasError::new("unexpected", "", src, pnt.0, pnt.1, pnt.2));
2186            }
2187            context.iteration = iterations - 1;
2188            // The guards run first, and at every step the budget can run
2189            // on: a grammar's bound holds whatever budget the caller set.
2190            if context.iteration > 0 {
2191                for guard in &self.parse_guards {
2192                    let result = self.catch_callback("parse guard", src, || guard(&context));
2193                    let keep_going = result.map_err(|error| {
2194                        self.attach_active_error(
2195                            error,
2196                            &current_rule,
2197                            &stack,
2198                            Self::phase_token(&current_rule).or_else(|| context.t.first()),
2199                        )
2200                    })?;
2201                    if !keep_going {
2202                        return Err(self.cancelled(src, &context, &current_rule, &stack));
2203                    }
2204                }
2205            }
2206            if budget.check_every_n > 0
2207                && context.iteration > 0
2208                && context.iteration % budget.check_every_n == 0
2209            {
2210                if let Some(check) = &budget.on_check {
2211                    let result =
2212                        self.catch_callback("parse.budget.onCheck", src, || check(&context));
2213                    let keep_going = result.map_err(|error| {
2214                        self.attach_active_error(
2215                            error,
2216                            &current_rule,
2217                            &stack,
2218                            Self::phase_token(&current_rule).or_else(|| context.t.first()),
2219                        )
2220                    })?;
2221                    if !keep_going {
2222                        return Err(self.cancelled(src, &context, &current_rule, &stack));
2223                    }
2224                }
2225            }
2226
2227            // The rule was bound to its prepared state when it was routed
2228            // to, and carries the slot that state sits at. Taking the spec
2229            // from there rather than from the rule costs an array index in
2230            // place of comparing the two names byte by byte, and hands out a
2231            // borrow of the parser instead of a reference count on the spec
2232            // -- the clone existed only to release the borrow on the rule
2233            // that the callbacks below need mutably, and the parser is not
2234            // mutable here at all.
2235            //
2236            // The record is a hint. `spec` and `name` are both public on a
2237            // rule and reachable from any callback, so the slot is trusted
2238            // only while the record still describes the rule in hand: same
2239            // spec by pointer, same name. Anything else falls back to the
2240            // rule's own spec, and to the lookup by name as the guard for a
2241            // rule that was never bound.
2242            let by_name;
2243            let (prepared, spec) = match self.prepared.get(current_rule.slot).filter(|prepared| {
2244                Arc::ptr_eq(&prepared.spec, &current_rule.spec)
2245                    && prepared.name == current_rule.name
2246            }) {
2247                Some(prepared) => (Some(prepared), &prepared.spec),
2248                None => {
2249                    by_name = if current_rule.spec.name == *current_rule.name {
2250                        Arc::clone(&current_rule.spec)
2251                    } else {
2252                        match self.rules.get(&*current_rule.name) {
2253                            Some(s) => s.clone(),
2254                            None => {
2255                                let pnt = context
2256                                    .t
2257                                    .first()
2258                                    .map(|t| (t.site.pos, t.site.ri, t.site.ci))
2259                                    .unwrap_or((0, 1, 1));
2260                                return Err(TabnasError::new(
2261                                    "unknown_rule",
2262                                    &*current_rule.name,
2263                                    src,
2264                                    pnt.0,
2265                                    pnt.1,
2266                                    pnt.2,
2267                                ));
2268                            }
2269                        }
2270                    };
2271                    (None, &by_name)
2272                }
2273            };
2274
2275            let is_open = current_rule.state == RuleState::Open;
2276            // A pass that begins inside a probe is the probe's, even when
2277            // error recovery closes the probe before the pass is reported.
2278            let probe_at_start = 0 < context.probe_depth();
2279            let alts = if is_open { &spec.open } else { &spec.close };
2280
2281            for subscriber in &self.rule_subscribers {
2282                let result = self.catch_callback("rule subscriber", src, || {
2283                    subscriber(&mut current_rule, &mut context)
2284                });
2285                result.map_err(|error| {
2286                    self.attach_error(
2287                        error,
2288                        &current_rule,
2289                        &stack,
2290                        alts,
2291                        Self::phase_token(&current_rule).or_else(|| context.t.first()),
2292                    )
2293                })?;
2294            }
2295            update_partial(mode, &root_node, &current_rule, &stack);
2296
2297            // 1. Run before-actions. Recovery can retry a failed close pass;
2298            // its before-close actions have already run and must not replay.
2299            let skip_befores = current_rule.skip_befores;
2300            current_rule.skip_befores = false;
2301            let before_enabled = if is_open {
2302                current_rule.bo
2303            } else {
2304                current_rule.bc
2305            };
2306            // `bo`/`bc` are run control, not presence -- see
2307            // `run_after_actions`. An empty order is the phase having
2308            // nothing to run, and skipping it here also skips the
2309            // snapshot the state callbacks would have been handed.
2310            let by_spec;
2311            let before_bindings: &[ActionBinding] = if skip_befores || !before_enabled {
2312                &[]
2313            } else {
2314                match prepared {
2315                    Some(prepared) => prepared.before(is_open),
2316                    None => {
2317                        let (actions, callbacks, states, order) = if is_open {
2318                            (&spec.bo, &spec.bo_fns, &spec.bo_state_fns, &spec.bo_order)
2319                        } else {
2320                            (&spec.bc, &spec.bc_fns, &spec.bc_state_fns, &spec.bc_order)
2321                        };
2322                        by_spec = resolved_action_order(actions, callbacks, states, order);
2323                        &by_spec
2324                    }
2325                }
2326            };
2327            if !before_bindings.is_empty() {
2328                let label = if is_open {
2329                    "before-open action"
2330                } else {
2331                    "before-close action"
2332                };
2333                let next = is_open.then(|| current_rule.snapshot());
2334                let site = ParseSite {
2335                    source: src,
2336                    stack: &stack,
2337                    alts,
2338                };
2339                let mut output = None;
2340                let mut lifecycle_error = None;
2341                for binding in before_bindings {
2342                    output = match binding {
2343                        ActionBinding::Named(action) => {
2344                            if let Some(callback) = self.state_actions.get(action) {
2345                                self.run_state_callback(
2346                                    label,
2347                                    callback,
2348                                    &mut current_rule,
2349                                    &mut context,
2350                                    next.as_deref(),
2351                                    output,
2352                                )
2353                                .map_err(|error| {
2354                                    self.attach_action_error(
2355                                        error,
2356                                        src,
2357                                        &current_rule,
2358                                        &stack,
2359                                        alts,
2360                                    )
2361                                })?
2362                            } else {
2363                                self.run_action(action, &mut current_rule, &mut context)
2364                                    .map_err(|error| {
2365                                        self.attach_action_error(
2366                                            error,
2367                                            src,
2368                                            &current_rule,
2369                                            &stack,
2370                                            alts,
2371                                        )
2372                                    })?;
2373                                None
2374                            }
2375                        }
2376                        ActionBinding::Callback(callback) => {
2377                            self.run_context_callback(
2378                                label,
2379                                callback,
2380                                &mut current_rule,
2381                                &mut context,
2382                            )
2383                            .map_err(|error| {
2384                                self.attach_action_error(error, src, &current_rule, &stack, alts)
2385                            })?;
2386                            None
2387                        }
2388                        ActionBinding::State(callback) => self
2389                            .run_state_callback(
2390                                label,
2391                                callback,
2392                                &mut current_rule,
2393                                &mut context,
2394                                next.as_deref(),
2395                                output,
2396                            )
2397                            .map_err(|error| {
2398                                self.attach_action_error(error, src, &current_rule, &stack, alts)
2399                            })?,
2400                    };
2401                    match self.check_lifecycle_output(output, &current_rule, site) {
2402                        Ok(next_output) => output = next_output,
2403                        Err(error) => {
2404                            lifecycle_error = Some(error);
2405                            break;
2406                        }
2407                    }
2408                }
2409                if let Some(error) = lifecycle_error {
2410                    update_partial(mode, &root_node, &current_rule, &stack);
2411                    self.recover_error_pass(
2412                        error,
2413                        if is_open {
2414                            RuleState::Open
2415                        } else {
2416                            RuleState::Close
2417                        },
2418                        None,
2419                        false,
2420                        src,
2421                        &mut current_rule,
2422                        &mut stack,
2423                        &mut context,
2424                        &mut lexer,
2425                        mode,
2426                    )?;
2427                    continue 'parse;
2428                }
2429            }
2430            update_partial(mode, &root_node, &current_rule, &stack);
2431
2432            // 2. Select alternates
2433            let mut matched_alt_idx: Option<usize> = None;
2434            let mut matched_count = 0;
2435            // Nothing has read the record since the last step ended, so
2436            // this is the only point it has to be clean by.
2437            matched.reset();
2438            // Set once either of the two condition callbacks that receive
2439            // the record has written into it, so a rejected alternate's
2440            // writes are wiped before the next alternate is tried. Rust
2441            // keeps the alternates isolated from each other here; only the
2442            // candidates that were actually offered a record pay for it.
2443            let mut record_written = false;
2444            // The winning alternate's matched tokens, when they are known to
2445            // still describe `context.t`. See the assignment below.
2446            let mut matched_tokens: Option<Rc<Vec<Token>>> = None;
2447
2448            // Asked once per step rather than once per alternate. When
2449            // the options still carry what the prepared answers were
2450            // worked out against, every alternate below reads a `bool`;
2451            // when a callback has rewritten either list, every alternate
2452            // falls back to deriving it, exactly as before.
2453            let groups_prepared = self.options.rule.include == self.prepared_include
2454                && self.options.rule.exclude == self.prepared_exclude;
2455
2456            // First-token index. Once the first lookahead token is in
2457            // hand, and the lexer is not renegotiating token identity
2458            // (under relex an alternate may re-cut a token it does not
2459            // name, so every alternate stays a candidate), only the
2460            // alternates that can take that token at position 0 are
2461            // tried, in their original order. Until the first fetch,
2462            // alternates are tried in order as before: the first
2463            // alternate with a sequence fetches the token.
2464            let first_index = if self.options.lex.relex {
2465                None
2466            } else {
2467                prepared.map(|prepared| prepared.first(is_open))
2468            };
2469            // The two candidate lists (alternates naming the first tin,
2470            // and the wildcards), walked together in index order once
2471            // selected, and the tin they were selected for.
2472            let mut lists: Option<(&[usize], &[usize])> = None;
2473            let mut key_tin = TIN_BD;
2474            let (mut ni, mut wi) = (0, 0);
2475            let mut next_idx = 0;
2476            loop {
2477                if lists.is_none() {
2478                    if let (Some(index), Some(t0)) = (first_index, context.t.first()) {
2479                        if t0.tin != TIN_BD {
2480                            key_tin = t0.tin;
2481                            let named = index.named(key_tin);
2482                            let wild = index.wild.as_slice();
2483                            (ni, wi) = (0, 0);
2484                            while ni < named.len() && named[ni] < next_idx {
2485                                ni += 1;
2486                            }
2487                            while wi < wild.len() && wild[wi] < next_idx {
2488                                wi += 1;
2489                            }
2490                            lists = Some((named, wild));
2491                        }
2492                    }
2493                }
2494                let idx = match lists {
2495                    Some((named, wild)) => {
2496                        let n = named.get(ni).copied().unwrap_or(alts.len());
2497                        let w = wild.get(wi).copied().unwrap_or(alts.len());
2498                        if alts.len() <= n && alts.len() <= w {
2499                            // No remaining alternate can take the first token.
2500                            break;
2501                        }
2502                        if n < w {
2503                            ni += 1;
2504                            n
2505                        } else {
2506                            wi += 1;
2507                            w
2508                        }
2509                    }
2510                    None => {
2511                        if alts.len() <= next_idx {
2512                            break;
2513                        }
2514                        next_idx += 1;
2515                        next_idx - 1
2516                    }
2517                };
2518                let alt = &alts[idx];
2519                let enabled = match prepared
2520                    .filter(|_| groups_prepared)
2521                    .and_then(|prepared| prepared.alt(is_open, idx))
2522                {
2523                    Some(prepared_alt) => prepared_alt.groups,
2524                    None => groups_enabled(alt, &self.options),
2525                };
2526                if !enabled {
2527                    continue;
2528                }
2529                let s_len = alt.s.len();
2530                let mut alt_matches = true;
2531                if record_written {
2532                    matched.reset();
2533                    record_written = false;
2534                }
2535                let mut relex_undo: Option<RelexUndo> = None;
2536                for (pos, pos_tins) in alt.s.iter().enumerate() {
2537                    if let Err(error) = self.ensure_lookahead(
2538                        &mut lexer,
2539                        &mut context,
2540                        &mut current_rule,
2541                        pos + 1,
2542                        mode,
2543                        ParseSite {
2544                            source: src,
2545                            stack: &stack,
2546                            alts,
2547                        },
2548                        Fetch::Rule,
2549                    ) {
2550                        return Err(self.attach_error(error, &current_rule, &stack, alts, None));
2551                    }
2552                    let Some(token) = context.t.get(pos).cloned() else {
2553                        alt_matches = false;
2554                        break;
2555                    };
2556                    if !slot_matches(pos_tins, token.tin) {
2557                        let recut = if self.options.lex.relex
2558                            && !token.src.is_empty()
2559                            && !pos_tins.is_empty()
2560                        {
2561                            let result = self.catch_callback("lexer relex callback", src, || {
2562                                lexer.relex(&token, pos_tins, &mut current_rule, &mut context)
2563                            });
2564                            result.map_err(|error| {
2565                                self.attach_error(error, &current_rule, &stack, alts, Some(&token))
2566                            })?
2567                        } else {
2568                            None
2569                        };
2570                        let Some((mut recut, checkpoint)) = recut else {
2571                            alt_matches = false;
2572                            break;
2573                        };
2574                        for subscriber in &self.lex_subscribers {
2575                            let result = self.catch_callback("lex subscriber", src, || {
2576                                subscriber(&mut recut, &mut current_rule, &mut context)
2577                            });
2578                            result.map_err(|error| {
2579                                self.attach_error(error, &current_rule, &stack, alts, Some(&recut))
2580                            })?;
2581                        }
2582                        if !pos_tins.contains(&recut.tin) {
2583                            lexer.unrelex(checkpoint, &mut context);
2584                            alt_matches = false;
2585                            break;
2586                        }
2587                        if relex_undo.is_none() {
2588                            relex_undo = Some(RelexUndo {
2589                                position: pos,
2590                                token,
2591                                checkpoint,
2592                                tokens: context.t.clone(),
2593                            });
2594                        }
2595                        context.t[pos] = recut;
2596                        context.t.truncate(pos + 1);
2597                    }
2598                }
2599
2600                if alt_matches {
2601                    let tokens: Rc<Vec<Token>> =
2602                        Rc::new(context.t.iter().take(s_len).cloned().collect());
2603                    // The declarative conditions are the only readers of a
2604                    // candidate rule; the callback tiers below run against
2605                    // `current_rule` itself, after its matched tokens are in
2606                    // place. Most alternates declare no declarative
2607                    // condition, and cloning a whole rule to answer a
2608                    // question nobody asks was the parse loop's largest
2609                    // single copy.
2610                    if alt.c_ref.is_some() || !alt.c.is_empty() {
2611                        let mut candidate = current_rule.clone();
2612                        if is_open {
2613                            candidate.o = Rc::clone(&tokens);
2614                        } else {
2615                            candidate.c = Rc::clone(&tokens);
2616                        }
2617                        if !builtin_condition_matches(alt.c_ref.as_deref(), &candidate)
2618                            || !conditions_match(&alt.c, &candidate, &stack)
2619                        {
2620                            alt_matches = false;
2621                        }
2622                    }
2623                    if alt_matches {
2624                        if is_open {
2625                            current_rule.o = Rc::clone(&tokens);
2626                        } else {
2627                            current_rule.c = Rc::clone(&tokens);
2628                        }
2629                        if let Some(condition) = &alt.c_fn {
2630                            context.set_rule(&current_rule);
2631                            let result = self.catch_callback("alternate condition", src, || {
2632                                condition(&mut current_rule, &mut context)
2633                            });
2634                            alt_matches = result.map_err(|error| {
2635                                self.attach_error(
2636                                    error,
2637                                    &current_rule,
2638                                    &stack,
2639                                    alts,
2640                                    Self::phase_token(&current_rule),
2641                                )
2642                            })?;
2643                        }
2644                        if alt_matches {
2645                            if let Some(condition) = &alt.c_match {
2646                                context.set_rule(&current_rule);
2647                                record_written = true;
2648                                let result =
2649                                    self.catch_callback("matched alternate condition", src, || {
2650                                        condition(&mut current_rule, &mut context, &mut matched)
2651                                    });
2652                                alt_matches = result.map_err(|error| {
2653                                    self.attach_error(
2654                                        error,
2655                                        &current_rule,
2656                                        &stack,
2657                                        alts,
2658                                        Self::phase_token(&current_rule),
2659                                    )
2660                                })?;
2661                            }
2662                        }
2663                        if alt_matches {
2664                            if let Some(condition) = &alt.c_lex_match {
2665                                context.set_rule(&current_rule);
2666                                record_written = true;
2667                                let result = self.catch_callback(
2668                                    "matched alternate lexer condition",
2669                                    src,
2670                                    || {
2671                                        condition(
2672                                            &mut current_rule,
2673                                            &mut context,
2674                                            &mut matched,
2675                                            &mut lexer,
2676                                        )
2677                                    },
2678                                );
2679                                alt_matches = result.map_err(|error| {
2680                                    self.attach_error(
2681                                        error,
2682                                        &current_rule,
2683                                        &stack,
2684                                        alts,
2685                                        Self::phase_token(&current_rule),
2686                                    )
2687                                })?;
2688                            }
2689                        }
2690                        if alt_matches {
2691                            if let Some(condition) = &alt.c_lex {
2692                                context.set_rule(&current_rule);
2693                                let result =
2694                                    self.catch_callback("alternate lexer condition", src, || {
2695                                        condition(&mut current_rule, &mut context, &mut lexer)
2696                                    });
2697                                alt_matches = result.map_err(|error| {
2698                                    self.attach_error(
2699                                        error,
2700                                        &current_rule,
2701                                        &stack,
2702                                        alts,
2703                                        Self::phase_token(&current_rule),
2704                                    )
2705                                })?;
2706                            }
2707                        }
2708                    }
2709                    if alt_matches {
2710                        matched_alt_idx = Some(idx);
2711                        matched_count = s_len;
2712                        // `tokens` is `context.t[..s_len]`, which is what the
2713                        // matched-token copy after this loop rebuilds from
2714                        // the same buffer. Between building it and here, the
2715                        // only things holding a `&mut Context` are the two
2716                        // condition callbacks, so without them the rebuild
2717                        // cannot differ and the vector below is reused
2718                        // instead of allocated and cloned a second time.
2719                        // `break` leaves the loop before the relex undo, so
2720                        // that cannot restore `context.t` underneath either.
2721                        if alt.c_fn.is_none() && alt.c_match.is_none() {
2722                            matched_tokens = Some(Rc::clone(&tokens));
2723                        }
2724                        break;
2725                    }
2726                }
2727                if let Some(undo) = relex_undo {
2728                    lexer.unrelex(undo.checkpoint, &mut context);
2729                    context.t = undo.tokens;
2730                    for subscriber in &self.lex_subscribers {
2731                        let mut restored = undo.token.clone();
2732                        let result = self.catch_callback("lex subscriber", src, || {
2733                            subscriber(&mut restored, &mut current_rule, &mut context)
2734                        });
2735                        result.map_err(|error| {
2736                            self.attach_error(error, &current_rule, &stack, alts, Some(&restored))
2737                        })?;
2738                    }
2739                    debug_assert_eq!(context.t.get(undo.position), Some(&undo.token));
2740                }
2741                // A condition can retag the first token, or replace it,
2742                // and then reject. The lists were selected for a tin the
2743                // token no longer has, and the plain scan would test every
2744                // later alternate against the token as it is now: resume
2745                // after this alternate, and select again at the top.
2746                if lists.is_some() && context.t.first().map(|t0| t0.tin) != Some(key_tin) {
2747                    lists = None;
2748                    next_idx = idx + 1;
2749                }
2750            }
2751
2752            if let Some(idx) = matched_alt_idx {
2753                // Copy matched tokens
2754                let matched_tokens = matched_tokens.unwrap_or_else(|| {
2755                    Rc::new(context.t.iter().take(matched_count).cloned().collect())
2756                });
2757                if is_open {
2758                    current_rule.o = matched_tokens;
2759                } else {
2760                    current_rule.c = matched_tokens;
2761                }
2762
2763                // Compatibility modifier for the original two-argument Rust
2764                // callback tier. It rewrites the source spec before dynamic
2765                // fields are resolved. The full `h_match` callback below runs
2766                // at the canonical point over the resolved AltMatch.
2767                //
2768                // Rewriting is the only thing here that needs an alternate of
2769                // its own; everything below reads one. A grammar that
2770                // declares no modifier — which is most of them, and both
2771                // benchmark grammars — now borrows the installed alternate
2772                // instead of copying it once per rule step.
2773                let rewritten: AltSpec;
2774                let alt: &AltSpec = if let Some(modifier) = alts[idx].h.clone() {
2775                    context.set_rule(&current_rule);
2776                    let source = alts[idx].clone();
2777                    let result = self.catch_callback("alternate modifier", src, || {
2778                        modifier(source, &mut current_rule, &mut context)
2779                    });
2780                    rewritten = result.map_err(|error| {
2781                        self.attach_error(
2782                            error,
2783                            &current_rule,
2784                            &stack,
2785                            alts,
2786                            Self::phase_token(&current_rule),
2787                        )
2788                    })?;
2789                    &rewritten
2790                } else {
2791                    &alts[idx]
2792                };
2793
2794                matched.h = alt.h_match.clone();
2795                if !alt.n.is_empty() {
2796                    matched.n = alt.n.clone();
2797                }
2798                if !alt.u.is_empty() {
2799                    matched.u = alt.u.clone();
2800                }
2801                if !alt.k.is_empty() {
2802                    matched.k = alt.k.clone();
2803                }
2804                // The alternate's group tags and action order, both worked
2805                // out when the rule was installed. A modifier rewrites the
2806                // whole `AltSpec` per step, so a rule that carries one is
2807                // resolved from what the modifier produced, not from the
2808                // record.
2809                let prepared_alt = if alts[idx].h.is_some() {
2810                    None
2811                } else {
2812                    prepared.and_then(|prepared| prepared.alt(is_open, idx))
2813                };
2814                match prepared_alt {
2815                    // `clone_from` writes into the list the last step left
2816                    // behind -- `AltMatch::reset` clears it without giving
2817                    // up its capacity -- rather than growing a fresh one.
2818                    Some(prepared_alt) => matched.g.clone_from(&prepared_alt.group_tags),
2819                    None if !alt.g.is_empty() => {
2820                        matched.g = listed(&alt.g).map(str::to_owned).collect();
2821                    }
2822                    None => {}
2823                }
2824                // Publishing the order into the record is only observable
2825                // when something this step runs receives the record. When
2826                // nothing does -- no matched condition, error, route,
2827                // backtrack, modifier or action, and no named binding that
2828                // could resolve to a matched action -- the step runs the
2829                // prepared order in place and the record keeps the empty
2830                // list it was born with. `matched_actions` is public and
2831                // may be written after `add_rule`, so whether a name can
2832                // reach it is asked here, per step, never cached.
2833                let prepared_alt = prepared_alt.filter(|prepared_alt| {
2834                    !prepared_alt.observed
2835                        && (!prepared_alt.named || self.matched_actions.is_empty())
2836                });
2837                if prepared_alt.is_none() {
2838                    let actions = resolved_alt_action_order(
2839                        &alt.a,
2840                        &alt.action_fns,
2841                        &alt.matched_action_fns,
2842                        &alt.action_order,
2843                    );
2844                    if !actions.is_empty() {
2845                        matched.actions = actions;
2846                    }
2847                }
2848                if !alt.action_configs.is_empty() {
2849                    matched.action_configs = alt.action_configs.clone();
2850                }
2851
2852                if let Some(route) = &alt.p_fn {
2853                    context.set_rule(&current_rule);
2854                    matched.p = self
2855                        .catch_callback("alternate push", src, || {
2856                            route(&mut current_rule, &mut context)
2857                        })
2858                        .map_err(|error| {
2859                            self.attach_error(
2860                                error,
2861                                &current_rule,
2862                                &stack,
2863                                alts,
2864                                Self::phase_token(&current_rule),
2865                            )
2866                        })?
2867                        .filter(|name| !name.is_empty());
2868                }
2869                if let Some(route) = &alt.p_match {
2870                    context.set_rule(&current_rule);
2871                    matched.p = self
2872                        .catch_callback("matched alternate push", src, || {
2873                            route(&mut current_rule, &mut context, &mut matched)
2874                        })
2875                        .map_err(|error| {
2876                            self.attach_error(
2877                                error,
2878                                &current_rule,
2879                                &stack,
2880                                alts,
2881                                Self::phase_token(&current_rule),
2882                            )
2883                        })?
2884                        .filter(|name| !name.is_empty());
2885                } else if alt.p_fn.is_none() {
2886                    if let Some(route) = alt.p.clone() {
2887                        matched.p = (!route.is_empty()).then_some(route);
2888                    }
2889                }
2890                if let Some(route) = &alt.r_fn {
2891                    context.set_rule(&current_rule);
2892                    matched.r = self
2893                        .catch_callback("alternate replace", src, || {
2894                            route(&mut current_rule, &mut context)
2895                        })
2896                        .map_err(|error| {
2897                            self.attach_error(
2898                                error,
2899                                &current_rule,
2900                                &stack,
2901                                alts,
2902                                Self::phase_token(&current_rule),
2903                            )
2904                        })?
2905                        .filter(|name| !name.is_empty());
2906                }
2907                if let Some(route) = &alt.r_match {
2908                    context.set_rule(&current_rule);
2909                    matched.r = self
2910                        .catch_callback("matched alternate replace", src, || {
2911                            route(&mut current_rule, &mut context, &mut matched)
2912                        })
2913                        .map_err(|error| {
2914                            self.attach_error(
2915                                error,
2916                                &current_rule,
2917                                &stack,
2918                                alts,
2919                                Self::phase_token(&current_rule),
2920                            )
2921                        })?
2922                        .filter(|name| !name.is_empty());
2923                } else if alt.r_fn.is_none() {
2924                    if let Some(route) = alt.r.clone() {
2925                        matched.r = (!route.is_empty()).then_some(route);
2926                    }
2927                }
2928                if let Some(backtrack) = &alt.b_fn {
2929                    context.set_rule(&current_rule);
2930                    matched.b = self
2931                        .catch_callback("alternate backtrack", src, || {
2932                            backtrack(&mut current_rule, &mut context)
2933                        })
2934                        .map_err(|error| {
2935                            self.attach_error(
2936                                error,
2937                                &current_rule,
2938                                &stack,
2939                                alts,
2940                                Self::phase_token(&current_rule),
2941                            )
2942                        })?;
2943                }
2944                if let Some(backtrack) = &alt.b_match {
2945                    context.set_rule(&current_rule);
2946                    matched.b = self
2947                        .catch_callback("matched alternate backtrack", src, || {
2948                            backtrack(&mut current_rule, &mut context, &mut matched)
2949                        })
2950                        .map_err(|error| {
2951                            self.attach_error(
2952                                error,
2953                                &current_rule,
2954                                &stack,
2955                                alts,
2956                                Self::phase_token(&current_rule),
2957                            )
2958                        })?;
2959                } else if alt.b_fn.is_none() && alt.b != 0 {
2960                    matched.b = alt.b;
2961                }
2962
2963                if let Some(modifier) = alt.h_match.clone() {
2964                    context.set_rule(&current_rule);
2965                    let next = is_open.then(|| current_rule.snapshot());
2966                    matched = self
2967                        .catch_callback("matched alternate modifier", src, || {
2968                            modifier(
2969                                std::mem::take(&mut matched),
2970                                &mut current_rule,
2971                                &mut context,
2972                                next.as_deref(),
2973                            )
2974                        })
2975                        .map_err(|error| {
2976                            self.attach_error(
2977                                error,
2978                                &current_rule,
2979                                &stack,
2980                                alts,
2981                                Self::phase_token(&current_rule),
2982                            )
2983                        })?;
2984                }
2985
2986                // The alternate's error hook runs AFTER the routing forms
2987                // have resolved and after both modifiers, and sees what the
2988                // modifier produced: routing, then modify, then check, in
2989                // every runtime (#154). It ran before the routing forms and
2990                // between the two modifiers here, which no grammar could
2991                // observe and no other port did.
2992                if let Some(error_hook) = alt.e.clone() {
2993                    context.set_rule(&current_rule);
2994                    let result = self.catch_callback("alternate error", src, || {
2995                        error_hook(&mut current_rule, &mut context)
2996                    });
2997                    matched.e = result
2998                        .map_err(|error| {
2999                            self.attach_error(
3000                                error,
3001                                &current_rule,
3002                                &stack,
3003                                alts,
3004                                Self::phase_token(&current_rule),
3005                            )
3006                        })?
3007                        .map(Box::new);
3008                }
3009                if let Some(error_hook) = alt.e_match.clone() {
3010                    context.set_rule(&current_rule);
3011                    let result = self.catch_callback("matched alternate error", src, || {
3012                        error_hook(&mut current_rule, &mut context, &mut matched)
3013                    });
3014                    matched.e = result
3015                        .map_err(|error| {
3016                            self.attach_error(
3017                                error,
3018                                &current_rule,
3019                                &stack,
3020                                alts,
3021                                Self::phase_token(&current_rule),
3022                            )
3023                        })?
3024                        .map(Box::new);
3025                }
3026                // Function-valued alternate errors are raised at the match
3027                // site, before counters, actions and consumption.
3028                if let Some(token) = matched.e.clone() {
3029                    let code = raised_error_code(&token);
3030                    let error = TabnasError::new(
3031                        code,
3032                        token.src.clone(),
3033                        src,
3034                        token.site.pos,
3035                        token.site.ri,
3036                        token.site.ci,
3037                    );
3038                    let done_alt = (!self.rule_done_subscribers.is_empty()).then(|| RuleDoneAlt {
3039                        b: matched.b,
3040                        g: matched.g.clone(),
3041                        p: matched.p.clone().unwrap_or_default(),
3042                        r: matched.r.clone().unwrap_or_default(),
3043                        err: Some((*token).clone()),
3044                    });
3045                    let error = self.attach_error(error, &current_rule, &stack, alts, Some(&token));
3046                    self.recover_error_pass(
3047                        error,
3048                        if is_open {
3049                            RuleState::Open
3050                        } else {
3051                            RuleState::Close
3052                        },
3053                        done_alt,
3054                        false,
3055                        src,
3056                        &mut current_rule,
3057                        &mut stack,
3058                        &mut context,
3059                        &mut lexer,
3060                        mode,
3061                    )?;
3062                    continue;
3063                }
3064
3065                // Update counters n
3066                for (k, v) in &matched.n {
3067                    if *v == 0 {
3068                        current_rule.n_mut().insert(k.clone(), 0);
3069                    } else {
3070                        *current_rule.n_mut().entry(k.clone()).or_insert(0) += *v;
3071                    }
3072                }
3073
3074                // Update user props u
3075                for (k, v) in &matched.u {
3076                    current_rule.u_mut().insert(k.clone(), v.clone());
3077                }
3078
3079                // Update keep props k
3080                for (k, v) in &matched.k {
3081                    current_rule.k_mut().insert(k.clone(), v.clone());
3082                }
3083
3084                let backtrack = matched.b;
3085                let consumed = matched_count.saturating_sub(backtrack);
3086                context.record_consumed(consumed);
3087
3088                // Run action. A bad token returned by a canonical action is
3089                // raised through the same recovery path as alt.e and
3090                // lifecycle actions; later actions must not run.
3091                let mut matched_action_error = None;
3092                let mut matched_action_token = None;
3093                // The published list has to be copied to be walked -- an
3094                // action may write the record it is being read out of, and
3095                // appending to `matched.actions` from inside this loop has
3096                // never reached it. The prepared list is not the record, so
3097                // it is walked where it lies.
3098                let published;
3099                let bindings: &[AltActionBinding] = match prepared_alt {
3100                    Some(prepared_alt) => &prepared_alt.actions,
3101                    None => {
3102                        published = matched.actions.clone();
3103                        &published
3104                    }
3105                };
3106                for binding in bindings {
3107                    let act_name = match binding {
3108                        AltActionBinding::Context(callback) => {
3109                            self.run_context_callback(
3110                                "alternate action",
3111                                callback,
3112                                &mut current_rule,
3113                                &mut context,
3114                            )
3115                            .map_err(|error| {
3116                                self.attach_action_error(error, src, &current_rule, &stack, alts)
3117                            })?;
3118                            continue;
3119                        }
3120                        AltActionBinding::Matched(callback) => {
3121                            context.set_rule(&current_rule);
3122                            let result = self
3123                                .catch_callback("matched alternate action", src, || {
3124                                    callback(&mut current_rule, &mut context, &mut matched)
3125                                })
3126                                .map_err(|error| {
3127                                    self.attach_action_error(
3128                                        error,
3129                                        src,
3130                                        &current_rule,
3131                                        &stack,
3132                                        alts,
3133                                    )
3134                                })?;
3135                            let token = result.map_err(|action_error| {
3136                                self.attach_action_error(
3137                                    action_error.into(),
3138                                    src,
3139                                    &current_rule,
3140                                    &stack,
3141                                    alts,
3142                                )
3143                            })?;
3144                            if let Some(token) = token.filter(|token| !token.err.is_empty()) {
3145                                matched_action_error = Some(self.raised_token_error(
3146                                    &token,
3147                                    &current_rule,
3148                                    ParseSite {
3149                                        source: src,
3150                                        stack: &stack,
3151                                        alts,
3152                                    },
3153                                ));
3154                                matched_action_token = Some(token);
3155                                break;
3156                            }
3157                            continue;
3158                        }
3159                        AltActionBinding::Named(name) => name,
3160                    };
3161                    if let Some(callback) = self.matched_actions.get(act_name) {
3162                        context.set_rule(&current_rule);
3163                        let result = self
3164                            .catch_callback("named matched alternate action", src, || {
3165                                callback(&mut current_rule, &mut context, &mut matched)
3166                            })
3167                            .map_err(|error| {
3168                                self.attach_action_error(error, src, &current_rule, &stack, alts)
3169                            })?;
3170                        let token = result.map_err(|action_error| {
3171                            self.attach_action_error(
3172                                action_error.into(),
3173                                src,
3174                                &current_rule,
3175                                &stack,
3176                                alts,
3177                            )
3178                        })?;
3179                        if let Some(token) = token.filter(|token| !token.err.is_empty()) {
3180                            matched_action_error = Some(self.raised_token_error(
3181                                &token,
3182                                &current_rule,
3183                                ParseSite {
3184                                    source: src,
3185                                    stack: &stack,
3186                                    alts,
3187                                },
3188                            ));
3189                            matched_action_token = Some(token);
3190                            break;
3191                        }
3192                        continue;
3193                    }
3194                    match act_name.as_str() {
3195                        "@probeInit$" => {
3196                            current_rule
3197                                .k_mut()
3198                                .insert("pd_phase".into(), Value::Number(0.0));
3199                            let mark = Value::Number(context.mark() as f64);
3200                            current_rule.k_mut().insert("pd_mark".into(), mark);
3201                            // The passes until the decision are the probe's.
3202                            context.probe_open(&current_rule);
3203                        }
3204                        "@probeDecide$" => {
3205                            let mark = current_rule.k.get("pd_mark").and_then(|value| {
3206                                if let Value::Number(mark) = value {
3207                                    usize::try_from(*mark as u64).ok()
3208                                } else {
3209                                    None
3210                                }
3211                            });
3212                            let Some(mark) = mark.filter(|mark| *mark <= context.v_abs) else {
3213                                let mut error = TabnasError::new("internal", "", src, 0, 1, 1);
3214                                error.detail =
3215                                    "@probeDecide$: phase-0 @probeInit$ did not record a valid mark"
3216                                        .into();
3217                                return Err(error);
3218                            };
3219                            if let Err(error) = self.ensure_lookahead(
3220                                &mut lexer,
3221                                &mut context,
3222                                &mut current_rule,
3223                                1,
3224                                mode,
3225                                ParseSite {
3226                                    source: src,
3227                                    stack: &stack,
3228                                    alts,
3229                                },
3230                                Fetch::Rule,
3231                            ) {
3232                                return Err(self.attach_error(
3233                                    error,
3234                                    &current_rule,
3235                                    &stack,
3236                                    alts,
3237                                    None,
3238                                ));
3239                            }
3240                            let disambiguator =
3241                                current_rule.k.get("pd_d").and_then(|value| match value {
3242                                    Value::String(name) => Some(name.as_str()),
3243                                    _ => None,
3244                                });
3245                            let phase = if context
3246                                .t
3247                                .first()
3248                                .is_some_and(|token| Some(token.name.as_str()) == disambiguator)
3249                            {
3250                                1.0
3251                            } else {
3252                                2.0
3253                            };
3254                            context.rewind(mark)?;
3255                            current_rule
3256                                .k_mut()
3257                                .insert("pd_phase".into(), Value::Number(phase));
3258                            context.probe_close();
3259                        }
3260                        _ => self
3261                            .run_action_with_config(
3262                                act_name,
3263                                &mut current_rule,
3264                                &mut context,
3265                                matched.action_configs.get(act_name),
3266                            )
3267                            .map_err(|error| {
3268                                self.attach_action_error(error, src, &current_rule, &stack, alts)
3269                            })?,
3270                    }
3271                }
3272                if let Some(error) = matched_action_error {
3273                    let recovered_alt = Some(RuleDoneAlt {
3274                        b: matched.b,
3275                        g: matched.g.clone(),
3276                        p: matched.p.clone().unwrap_or_default(),
3277                        r: matched.r.clone().unwrap_or_default(),
3278                        err: None,
3279                    });
3280                    self.recover_error_pass(
3281                        error,
3282                        if is_open {
3283                            RuleState::Open
3284                        } else {
3285                            RuleState::Close
3286                        },
3287                        recovered_alt,
3288                        matched_action_token.is_some(),
3289                        src,
3290                        &mut current_rule,
3291                        &mut stack,
3292                        &mut context,
3293                        &mut lexer,
3294                        mode,
3295                    )?;
3296                    update_partial(mode, &root_node, &current_rule, &stack);
3297                    continue 'parse;
3298                }
3299                update_partial(mode, &root_node, &current_rule, &stack);
3300
3301                // The canonical action receives the live match record. Its
3302                // post-action p/r writes are a supported routing channel, so
3303                // resolve the transition only after the action sequence.
3304                // Nothing below reads `matched.p` or `matched.r` again: the
3305                // record's remaining readers take `b` and `g`. So the names
3306                // move out of it rather than being copied, which is the
3307                // second `String` each of them cost per rule step.
3308                let push_name = matched.p.take();
3309                let replace_name = matched.r.take();
3310                // Only a ruleDone subscriber ever reads this, and it is
3311                // cloned again at each of the transition arms below. A
3312                // grammar with no subscriber was building and copying it
3313                // several times per matched alternate for nobody.
3314                let done_alt = (!self.rule_done_subscribers.is_empty()).then(|| RuleDoneAlt {
3315                    b: matched.b,
3316                    g: matched.g.clone(),
3317                    p: push_name.clone().unwrap_or_default(),
3318                    r: replace_name.clone().unwrap_or_default(),
3319                    err: None,
3320                });
3321
3322                // Callback routes and action mutations cannot be validated at
3323                // grammar-install time. Reject an unknown destination at the
3324                // canonical point: after the matched action, but before any
3325                // lifecycle after-action or transition.
3326                //
3327                // Resolving it here also settles the transition below: the
3328                // arms take the shared name and the spec out of this one
3329                // lookup rather than hashing the same name twice more.
3330                // `push` wins over `replace` in the arms below, so this
3331                // resolves whichever of the two the parse will take.
3332                //
3333                // A route the grammar declared on this alternate was already
3334                // resolved when the rule was installed; all that is left of
3335                // it here is checking that the name the step is actually
3336                // routing to is still that name, which is a byte compare
3337                // against a handle rather than a hash of the same three
3338                // bytes for the tens of thousands of steps that route where
3339                // the grammar said they would.
3340                let mut route = match push_name.as_deref().or(replace_name.as_deref()) {
3341                    Some(name) => match prepared
3342                        .and_then(|prepared| prepared.alt(is_open, idx))
3343                        .map(|alt| if push_name.is_some() { &alt.p } else { &alt.r })
3344                        .and_then(|route| route.resolved(name))
3345                        .or_else(|| self.installed(name))
3346                    {
3347                        Some(resolved) => Some(resolved),
3348                        None => {
3349                            let mut token = Self::phase_token(&current_rule)
3350                                .cloned()
3351                                .or_else(|| context.t.first().cloned())
3352                                .unwrap_or_else(Token::no_token);
3353                            token.bad("unknown_rule");
3354                            token
3355                                .use_data_mut()
3356                                .insert("rulename".into(), Value::String(name.to_string()));
3357                            let error = self.raised_token_error(
3358                                &token,
3359                                &current_rule,
3360                                ParseSite {
3361                                    source: src,
3362                                    stack: &stack,
3363                                    alts,
3364                                },
3365                            );
3366                            self.recover_error_pass(
3367                                error,
3368                                if is_open {
3369                                    RuleState::Open
3370                                } else {
3371                                    RuleState::Close
3372                                },
3373                                done_alt,
3374                                false,
3375                                src,
3376                                &mut current_rule,
3377                                &mut stack,
3378                                &mut context,
3379                                &mut lexer,
3380                                mode,
3381                            )?;
3382                            update_partial(mode, &root_node, &current_rule, &stack);
3383                            continue 'parse;
3384                        }
3385                    },
3386                    None => None,
3387                };
3388
3389                // Resolve the transition before running lifecycle after-actions,
3390                // so they can inspect rule.next just like the canonical engine.
3391                // The action still belongs to the rule whose alternate matched.
3392                let completed_rule: Option<Rule>;
3393                let mut completed_value = None;
3394                if push_name.is_some() {
3395                    let (push_slot, push_shared, push_spec) =
3396                        route.take().expect("a push route was resolved above");
3397                    let mut child = Rule::bound(
3398                        push_shared.clone(),
3399                        current_rule.node.clone(),
3400                        Some(push_spec),
3401                        push_slot,
3402                    );
3403                    child.i = next_rule_id;
3404                    next_rule_id += 1;
3405                    child.d = stack.len() + 1;
3406                    child.parent_node = Some(current_rule.node.clone());
3407                    child.n = Rc::clone(&current_rule.n);
3408                    child.k = Rc::clone(&current_rule.k);
3409                    child.parent_rule = Some(bounded_history(
3410                        current_rule.snapshot(),
3411                        self.options.rule.history,
3412                        Link::PusherBefore,
3413                    ));
3414                    current_rule.next_rule_name = Some(push_shared);
3415                    current_rule.child_rule = Some(child.snapshot());
3416                    current_rule.next_rule = current_rule.child_rule.clone();
3417                    current_rule.note_child_push(&child);
3418                    // The link as this arm made it, so the relink below can
3419                    // tell whether an after action has changed it.
3420                    let linked = current_rule.child_rule.clone();
3421                    let after = self.run_after_actions(
3422                        spec,
3423                        prepared,
3424                        is_open,
3425                        &mut current_rule,
3426                        &mut context,
3427                        ParseSite {
3428                            source: src,
3429                            stack: &stack,
3430                            alts,
3431                        },
3432                    );
3433                    update_partial(mode, &root_node, &current_rule, &stack);
3434                    if self.recover_after_actions(
3435                        after,
3436                        if is_open {
3437                            RuleState::Open
3438                        } else {
3439                            RuleState::Close
3440                        },
3441                        done_alt.clone(),
3442                        src,
3443                        &mut current_rule,
3444                        &mut stack,
3445                        &mut context,
3446                        &mut lexer,
3447                        mode,
3448                    )? {
3449                        continue 'parse;
3450                    }
3451                    if is_open {
3452                        current_rule.state = RuleState::Close;
3453                    }
3454                    child.parent_rule = Some(bounded_history(
3455                        current_rule.snapshot(),
3456                        self.options.rule.history,
3457                        Link::Parent,
3458                    ));
3459                    // TypeScript and Go link the live rules, so from the
3460                    // child, `parent.child.parent.child` is the child
3461                    // itself. The snapshot linked above as `child` carries
3462                    // this rule as it stood before the push, whose `child`
3463                    // is the one pushed before (parser #259). With no
3464                    // bound, link the child again from a snapshot that
3465                    // carries this rule with the child linked, and give
3466                    // the child this rule as it then stands, so that a
3467                    // snapshot of the child reads the same chain: the
3468                    // pre-link record is two hops further down, past the
3469                    // four-hop read. The cost, measured on
3470                    // `rs/tests/rule_history_test.rs`'s flat array, is two
3471                    // more records kept per push, 8 for 6 per element.
3472                    // Under a bound the links stay as the canonical engine
3473                    // copies them, where that path reads nothing
3474                    // (`rule-history-bounded-pusher`). An after action that
3475                    // cleared or repointed `child` or `next` keeps its edit:
3476                    // the canonical engine links before the after actions
3477                    // and never overwrites them afterwards.
3478                    if crate::options::effective_rule_history(self.options.rule.history).is_none()
3479                        && current_rule.links_unchanged(&linked)
3480                    {
3481                        current_rule.relink_child(&child);
3482                        child.parent_rule = Some(current_rule.snapshot());
3483                    }
3484                    completed_rule = self.rule_done_copy(&current_rule);
3485                    // The child about to run shares this rule's node cell,
3486                    // and `child_node` may be a second handle on the very
3487                    // container it will write into. Let go of it for the
3488                    // duration -- see `Rule::park_child_node`. Taken after
3489                    // `rule_done_copy`, so a ruleDone subscriber still sees
3490                    // the rule exactly as it stood, and only when every pop
3491                    // that can resume this rule overwrites the field first
3492                    // (see `park_child_node` and `attempt_recover`).
3493                    if park_child_nodes {
3494                        current_rule.park_child_node();
3495                    }
3496                    stack.push(current_rule);
3497                    current_rule = child;
3498                } else if replace_name.is_some() {
3499                    let (replace_slot, replace_shared, replace_spec) =
3500                        route.take().expect("a replace route was resolved above");
3501                    let mut next = Rule::bound(
3502                        replace_shared.clone(),
3503                        current_rule.node.clone(),
3504                        Some(replace_spec),
3505                        replace_slot,
3506                    );
3507                    next.i = next_rule_id;
3508                    next_rule_id += 1;
3509                    next.d = current_rule.d;
3510                    next.parent_node = current_rule.parent_node.clone();
3511                    next.parent_rule = current_rule.parent_rule.clone();
3512                    next.n = Rc::clone(&current_rule.n);
3513                    next.k = Rc::clone(&current_rule.k);
3514                    current_rule.next_rule_name = Some(replace_shared);
3515                    current_rule.next_rule = Some(next.snapshot());
3516                    let after = self.run_after_actions(
3517                        spec,
3518                        prepared,
3519                        is_open,
3520                        &mut current_rule,
3521                        &mut context,
3522                        ParseSite {
3523                            source: src,
3524                            stack: &stack,
3525                            alts,
3526                        },
3527                    );
3528                    update_partial(mode, &root_node, &current_rule, &stack);
3529                    if self.recover_after_actions(
3530                        after,
3531                        if is_open {
3532                            RuleState::Open
3533                        } else {
3534                            RuleState::Close
3535                        },
3536                        done_alt.clone(),
3537                        src,
3538                        &mut current_rule,
3539                        &mut stack,
3540                        &mut context,
3541                        &mut lexer,
3542                        mode,
3543                    )? {
3544                        continue 'parse;
3545                    }
3546                    if is_open {
3547                        current_rule.state = RuleState::Close;
3548                    }
3549                    next.prev_rule = Some(bounded_history(
3550                        current_rule.snapshot(),
3551                        self.options.rule.history,
3552                        Link::Prev,
3553                    ));
3554                    // The rule being replaced stops existing here. If it is
3555                    // the one its parent PUSHED, the parent's `child` link
3556                    // stays on it -- TypeScript never relinks `rule.child`
3557                    // (rules.ts:665) and neither does Go (rule.go:1280) --
3558                    // so freeze the node cell and the record it ended on
3559                    // before it goes.
3560                    if let Some(parent) = stack.last_mut() {
3561                        parent.freeze_child(&current_rule);
3562                    }
3563                    // Moved rather than cloned: this arm hands the
3564                    // finished rule over instead of copying it, so the
3565                    // gate above has nothing to save here.
3566                    completed_rule = Some(current_rule);
3567                    current_rule = next;
3568                } else if is_open {
3569                    current_rule.next_rule_name = Some(current_rule.name.clone());
3570                    current_rule.next_rule = Some(current_rule.snapshot());
3571                    let after = self.run_after_actions(
3572                        spec,
3573                        prepared,
3574                        true,
3575                        &mut current_rule,
3576                        &mut context,
3577                        ParseSite {
3578                            source: src,
3579                            stack: &stack,
3580                            alts,
3581                        },
3582                    );
3583                    update_partial(mode, &root_node, &current_rule, &stack);
3584                    if self.recover_after_actions(
3585                        after,
3586                        RuleState::Open,
3587                        done_alt.clone(),
3588                        src,
3589                        &mut current_rule,
3590                        &mut stack,
3591                        &mut context,
3592                        &mut lexer,
3593                        mode,
3594                    )? {
3595                        continue 'parse;
3596                    }
3597                    current_rule.state = RuleState::Close;
3598                    completed_rule = self.rule_done_copy(&current_rule);
3599                } else {
3600                    // Close phase pop
3601                    current_rule.next_rule_name = stack.last().map(|rule| rule.name.clone());
3602                    current_rule.next_rule = stack.last().map(Rule::snapshot);
3603                    let after = self.run_after_actions(
3604                        spec,
3605                        prepared,
3606                        false,
3607                        &mut current_rule,
3608                        &mut context,
3609                        ParseSite {
3610                            source: src,
3611                            stack: &stack,
3612                            alts,
3613                        },
3614                    );
3615                    update_partial(mode, &root_node, &current_rule, &stack);
3616                    if self.recover_after_actions(
3617                        after,
3618                        RuleState::Close,
3619                        done_alt.clone(),
3620                        src,
3621                        &mut current_rule,
3622                        &mut stack,
3623                        &mut context,
3624                        &mut lexer,
3625                        mode,
3626                    )? {
3627                        continue 'parse;
3628                    }
3629                    let parent = stack.pop();
3630                    completed_rule = self.rule_done_copy(&current_rule);
3631                    if let Some(mut parent) = parent {
3632                        parent.accept_child(&current_rule);
3633                        current_rule = parent;
3634                    } else {
3635                        // Root rule popped! Done.
3636                        completed_value = Some(current_rule.node.borrow().clone());
3637                    }
3638                }
3639                // Read after every pass, subscribed or not, so that the
3640                // pass that opened or closed a probe is the only one its
3641                // flag covers.
3642                let probe = context.probe_take() || probe_at_start;
3643                if let Some(completed_rule) = &completed_rule {
3644                    self.notify_rule_done(
3645                        completed_rule,
3646                        &context,
3647                        if is_open {
3648                            RuleState::Open
3649                        } else {
3650                            RuleState::Close
3651                        },
3652                        done_alt,
3653                        probe,
3654                        src,
3655                        &stack,
3656                    )?;
3657                }
3658                if let Some(value) = completed_value {
3659                    final_value = Some(value);
3660                    break;
3661                }
3662                update_partial(mode, &root_node, &current_rule, &stack);
3663            } else if alts.is_empty() {
3664                // A state with no alternatives performs an implicit empty
3665                // pass. It still resolves next and runs lifecycle after-actions.
3666                let completed_rule: Option<Rule>;
3667                let mut completed_value = None;
3668                if is_open {
3669                    current_rule.next_rule_name = Some(current_rule.name.clone());
3670                    current_rule.next_rule = Some(current_rule.snapshot());
3671                    let after = self.run_after_actions(
3672                        spec,
3673                        prepared,
3674                        true,
3675                        &mut current_rule,
3676                        &mut context,
3677                        ParseSite {
3678                            source: src,
3679                            stack: &stack,
3680                            alts,
3681                        },
3682                    );
3683                    update_partial(mode, &root_node, &current_rule, &stack);
3684                    if self.recover_after_actions(
3685                        after,
3686                        RuleState::Open,
3687                        None,
3688                        src,
3689                        &mut current_rule,
3690                        &mut stack,
3691                        &mut context,
3692                        &mut lexer,
3693                        mode,
3694                    )? {
3695                        continue 'parse;
3696                    }
3697                    current_rule.state = RuleState::Close;
3698                    completed_rule = self.rule_done_copy(&current_rule);
3699                } else {
3700                    current_rule.next_rule_name = stack.last().map(|rule| rule.name.clone());
3701                    current_rule.next_rule = stack.last().map(Rule::snapshot);
3702                    let after = self.run_after_actions(
3703                        spec,
3704                        prepared,
3705                        false,
3706                        &mut current_rule,
3707                        &mut context,
3708                        ParseSite {
3709                            source: src,
3710                            stack: &stack,
3711                            alts,
3712                        },
3713                    );
3714                    update_partial(mode, &root_node, &current_rule, &stack);
3715                    if self.recover_after_actions(
3716                        after,
3717                        RuleState::Close,
3718                        None,
3719                        src,
3720                        &mut current_rule,
3721                        &mut stack,
3722                        &mut context,
3723                        &mut lexer,
3724                        mode,
3725                    )? {
3726                        continue 'parse;
3727                    }
3728                    let parent = stack.pop();
3729                    completed_rule = self.rule_done_copy(&current_rule);
3730                    if let Some(mut parent) = parent {
3731                        parent.accept_child(&current_rule);
3732                        current_rule = parent;
3733                    } else {
3734                        completed_value = Some(current_rule.node.borrow().clone());
3735                    }
3736                }
3737                let probe = context.probe_take() || probe_at_start;
3738                if let Some(completed_rule) = &completed_rule {
3739                    self.notify_rule_done(
3740                        completed_rule,
3741                        &context,
3742                        if is_open {
3743                            RuleState::Open
3744                        } else {
3745                            RuleState::Close
3746                        },
3747                        None,
3748                        probe,
3749                        src,
3750                        &stack,
3751                    )?;
3752                }
3753                if let Some(value) = completed_value {
3754                    final_value = Some(value);
3755                    break;
3756                }
3757                update_partial(mode, &root_node, &current_rule, &stack);
3758            } else {
3759                // Declared alternatives exist, but none matched.
3760                if is_open {
3761                    if let Err(error) = self.ensure_lookahead(
3762                        &mut lexer,
3763                        &mut context,
3764                        &mut current_rule,
3765                        1,
3766                        mode,
3767                        ParseSite {
3768                            source: src,
3769                            stack: &stack,
3770                            alts,
3771                        },
3772                        Fetch::Rule,
3773                    ) {
3774                        return Err(self.attach_error(error, &current_rule, &stack, alts, None));
3775                    }
3776                    if let Some(capture) = mode.continuation.as_deref_mut() {
3777                        let base = failed_alt_tins(&context, alts, &self.options);
3778                        capture.failure = continuation_tins(
3779                            &context,
3780                            &current_rule,
3781                            &stack,
3782                            &self.rules,
3783                            &self.options,
3784                            0,
3785                            Some(&base),
3786                        );
3787                    }
3788                    let t0 = context.t.first().cloned();
3789                    let (src_token, si, ri, ci) = if let Some(t) = t0.as_ref() {
3790                        (t.src.to_string(), t.site.pos, t.site.ri, t.site.ci)
3791                    } else {
3792                        (String::new(), src.len(), 1, 1)
3793                    };
3794                    let code = t0
3795                        .as_ref()
3796                        .map_or("unexpected", |t| deferred_error_code(t, mode.recovering));
3797                    let error = TabnasError::new(code, src_token, src, si, ri, ci);
3798                    let done_alt = (!alts.is_empty() && !self.rule_done_subscribers.is_empty())
3799                        .then(|| RuleDoneAlt {
3800                            b: 0,
3801                            g: Vec::new(),
3802                            p: String::new(),
3803                            r: String::new(),
3804                            err: t0.clone(),
3805                        });
3806                    let error = self.attach_error(error, &current_rule, &stack, alts, t0.as_ref());
3807                    self.recover_error_pass(
3808                        error,
3809                        RuleState::Open,
3810                        done_alt,
3811                        false,
3812                        src,
3813                        &mut current_rule,
3814                        &mut stack,
3815                        &mut context,
3816                        &mut lexer,
3817                        mode,
3818                    )?;
3819                    continue;
3820                } else {
3821                    if let Err(error) = self.ensure_lookahead(
3822                        &mut lexer,
3823                        &mut context,
3824                        &mut current_rule,
3825                        1,
3826                        mode,
3827                        ParseSite {
3828                            source: src,
3829                            stack: &stack,
3830                            alts,
3831                        },
3832                        Fetch::Rule,
3833                    ) {
3834                        return Err(self.attach_error(error, &current_rule, &stack, alts, None));
3835                    }
3836                    if let Some(capture) = mode.continuation.as_deref_mut() {
3837                        let base = failed_alt_tins(&context, alts, &self.options);
3838                        capture.failure = continuation_tins(
3839                            &context,
3840                            &current_rule,
3841                            &stack,
3842                            &self.rules,
3843                            &self.options,
3844                            0,
3845                            Some(&base),
3846                        );
3847                    }
3848                    let token = context.t.first().cloned();
3849                    let (source, pos, row, col) = token.as_ref().map_or_else(
3850                        || (String::new(), src.chars().count(), 1, 1),
3851                        |value| {
3852                            (
3853                                value.src.to_string(),
3854                                value.site.pos,
3855                                value.site.ri,
3856                                value.site.ci,
3857                            )
3858                        },
3859                    );
3860                    let code = token
3861                        .as_ref()
3862                        .map_or("unexpected", |t| deferred_error_code(t, mode.recovering));
3863                    let error = TabnasError::new(code, source, src, pos, row, col);
3864                    let done_alt = Some(RuleDoneAlt {
3865                        b: 0,
3866                        g: Vec::new(),
3867                        p: String::new(),
3868                        r: String::new(),
3869                        err: token.clone(),
3870                    });
3871                    let error =
3872                        self.attach_error(error, &current_rule, &stack, alts, token.as_ref());
3873                    self.recover_error_pass(
3874                        error,
3875                        RuleState::Close,
3876                        done_alt,
3877                        false,
3878                        src,
3879                        &mut current_rule,
3880                        &mut stack,
3881                        &mut context,
3882                        &mut lexer,
3883                        mode,
3884                    )?;
3885                    continue;
3886                }
3887            }
3888        }
3889
3890        let res = final_value.unwrap_or(Value::Null).unwrap_undefined();
3891        if mode.recovering {
3892            mode.partial = Some(PartialValue::Complete(res.clone()));
3893        }
3894
3895        // Post-loop check: ensure no unexpected trailing tokens. Recovery
3896        // keeps the completed value and reports the trailing fault. No
3897        // option turns the check off: `rule.finish` is the grammar's
3898        // end-of-source switch, kept in the options for its `@finish` to
3899        // read, not this check's (#250).
3900        if let Err(error) = self.ensure_lookahead(
3901            &mut lexer,
3902            &mut context,
3903            &mut current_rule,
3904            1,
3905            mode,
3906            ParseSite {
3907                source: src,
3908                stack: &stack,
3909                alts: &[],
3910            },
3911            Fetch::Trailing,
3912        ) {
3913            let error = self.attach_error(error, &current_rule, &stack, &[], None);
3914            if mode.recovering {
3915                mode.errors.push(error.clone());
3916                context.errs.push(error);
3917                return Ok(res);
3918            }
3919            return Err(error);
3920        }
3921        if let Some(t0) = context.t.first() {
3922            if t0.tin != TIN_ZZ {
3923                let code = if t0.tin == TIN_BD && !t0.why.is_empty() {
3924                    t0.why.as_str()
3925                } else {
3926                    "unexpected"
3927                };
3928                let error =
3929                    TabnasError::new(code, &*t0.src, src, t0.site.pos, t0.site.ri, t0.site.ci);
3930                let error = self.attach_error(
3931                    error,
3932                    &current_rule,
3933                    &stack,
3934                    &[AltSpec {
3935                        s: vec![vec![TIN_ZZ]],
3936                        ..Default::default()
3937                    }],
3938                    Some(t0),
3939                );
3940                if mode.recovering {
3941                    mode.errors.push(error.clone());
3942                    context.errs.push(error);
3943                    return Ok(res);
3944                }
3945                return Err(error);
3946            }
3947        }
3948        if self
3949            .options
3950            .result
3951            .fail
3952            .iter()
3953            .any(|failed| failed.deep_equal(&res))
3954        {
3955            let token = context.t.first();
3956            let error = token.map_or_else(
3957                || TabnasError::new("unexpected", "", src, 0, 1, 1),
3958                |token| {
3959                    TabnasError::new(
3960                        "unexpected",
3961                        &*token.src,
3962                        src,
3963                        token.site.pos,
3964                        token.site.ri,
3965                        token.site.ci,
3966                    )
3967                },
3968            );
3969            if mode.recovering {
3970                mode.errors.push(error.clone());
3971                context.errs.push(error);
3972                return Ok(res);
3973            }
3974            return Err(error);
3975        }
3976        Ok(res)
3977    }
3978}
3979
3980/// Keep a handle to the best partial node the recovery path would return.
3981///
3982/// Fifteen sites in the parse loop call this, twelve times per input
3983/// construct on the benchmark grammars, and outside recovery every one of them is a
3984/// load and a branch wrapped in a call. The guard is inline so the call
3985/// goes away. Inside recovery this deliberately clones only an `Rc` node
3986/// handle, never the `Value` being built: a `Value` snapshot keeps its
3987/// container shared and turns the next mutation into a copy of the entire
3988/// accumulated prefix.
3989///
3990/// The value read at the end is the one the last site would have taken:
3991/// the node is chosen by the same test, in the same order, and it keeps
3992/// the node even when recovery then pops the rules that held it. Only a
3993/// write to that node between the last site and the failure can tell the
3994/// two apart -- an action or callback that changes the node and then
3995/// fails, or is followed by a matched action whose error recovery gives up
3996/// on -- and the value is then the node as the failure left it, which is
3997/// what TypeScript returns: it reads the node in its `catch`
3998/// (`ts/src/parser.ts`), not before the step that failed.
3999#[inline]
4000fn update_partial(
4001    mode: &mut ParseMode<'_>,
4002    root_node: &Rc<RefCell<Value>>,
4003    current_rule: &Rule,
4004    stack: &[Rule],
4005) {
4006    if mode.recovering {
4007        mode.partial = best_partial_node(root_node, current_rule, stack).map(PartialValue::Node);
4008    }
4009}
4010
4011#[inline(never)]
4012fn best_partial_node(
4013    root_node: &Rc<RefCell<Value>>,
4014    current_rule: &Rule,
4015    stack: &[Rule],
4016) -> Option<Rc<RefCell<Value>>> {
4017    let usable = |node: &Rc<RefCell<Value>>| {
4018        (!matches!(*node.borrow(), Value::Undefined | Value::Null)).then(|| Rc::clone(node))
4019    };
4020
4021    usable(root_node)
4022        .or_else(|| stack.iter().find_map(|rule| usable(&rule.node)))
4023        .or_else(|| usable(&current_rule.node))
4024}
4025
4026fn error_token(error: &TabnasError) -> Token {
4027    let byte_position = error
4028        .full_source
4029        .char_indices()
4030        .nth(error.pos)
4031        .map_or(error.full_source.len(), |(index, _)| index);
4032    let mut token = Token::new(
4033        "#BD",
4034        TIN_BD,
4035        Value::Undefined,
4036        error.src.clone(),
4037        crate::Point {
4038            len: error.len,
4039            site: crate::Site {
4040                si: byte_position,
4041                pos: error.pos,
4042                ri: error.row,
4043                ci: error.col,
4044            },
4045        },
4046    );
4047    token.err = crate::TokenCode::from(error.code.as_str());
4048    token.why = token.err.clone();
4049    token
4050}
4051
4052/// The code an error with no matching alternative takes from the first
4053/// token of the lookahead, read as the canonical engine reads it at the
4054/// same point. Fail-fast, its deferred throw takes a bad token's why, else
4055/// `unexpected` (`bad.why || UNEXPECTED` in ts/src/rules.ts); when the
4056/// parse is recovering, `attemptRecover` takes the token's err ahead of
4057/// its why (`tkn.err || tkn.why`). This engine's own lexer faults set why
4058/// and err alike, so only a token a matcher built with err alone tells
4059/// the two apart: `unexpected` fail-fast, its err under recovery, in every
4060/// runtime (#285).
4061fn deferred_error_code(token: &Token, recovering: bool) -> &str {
4062    if token.tin != TIN_BD {
4063        "unexpected"
4064    } else if recovering && !token.err.is_empty() {
4065        &token.err
4066    } else if !token.why.is_empty() {
4067        &token.why
4068    } else {
4069        "unexpected"
4070    }
4071}
4072
4073fn raised_error_code(token: &Token) -> &str {
4074    if !token.err.is_empty() {
4075        &token.err
4076    } else if !token.why.is_empty() {
4077        &token.why
4078    } else {
4079        "unexpected"
4080    }
4081}
4082
4083fn mid_construct(code: &str) -> bool {
4084    matches!(code, "unprintable" | "invalid_unicode" | "invalid_ascii")
4085}
4086
4087/// Record a bad token met at a rule's fetch under recovery, in the order
4088/// TypeScript's `parse_alts` does it: a token inside the run the last one
4089/// began grows that run's error rather than being listed again; a new run
4090/// inside the suppress window of the recovery before it is a cascade of
4091/// that fault and is dropped; anything else is recorded. Returns whether
4092/// the fetch goes on past the token. It does not when the run outgrows
4093/// `maxSkip`, or when the list has outgrown `maxRecoveries`, a cap read
4094/// after recording, so the error that stops the parse is listed.
4095fn absorb_lex_error(
4096    error: &TabnasError,
4097    context: &mut Context,
4098    options: &Options,
4099    errors: &mut Vec<TabnasError>,
4100) -> bool {
4101    let recover = &options.parse.recover;
4102    let run = context
4103        .bad_error
4104        .filter(|index| *index < errors.len())
4105        .filter(|_| context.bad_to.is_some_and(|bad_to| error.pos <= bad_to));
4106    if let Some(index) = run {
4107        let previous = &mut errors[index];
4108        let recovered = previous.recovered.get_or_insert(crate::RecoveredAt {
4109            skipped: 0,
4110            sync: None,
4111            bad: true,
4112        });
4113        recovered.skipped = recovered.skipped.saturating_add(1);
4114        let skipped = recovered.skipped;
4115        if let Some(context_previous) = context.errs.get_mut(index) {
4116            *context_previous = previous.clone();
4117        }
4118        if recover.max_skip < skipped {
4119            return false;
4120        }
4121    } else if context
4122        .recover_at
4123        .is_some_and(|at| context.v_abs.saturating_sub(at) < recover.suppress)
4124    {
4125        context.bad_error = None;
4126    } else {
4127        let mut recorded = error.clone();
4128        recorded.recovered = Some(crate::RecoveredAt {
4129            skipped: 1,
4130            sync: None,
4131            bad: true,
4132        });
4133        errors.push(recorded.clone());
4134        context.errs.push(recorded);
4135        context.bad_error = Some(errors.len() - 1);
4136        context.recover_at = Some(context.v_abs);
4137    }
4138    context.bad_to = Some(error.pos.saturating_add(error.len.max(1)));
4139    errors.len() <= recover.max_recoveries
4140}
4141
4142fn slot_matches(slot: &[Tin], tin: Tin) -> bool {
4143    tin != TIN_BD && (slot.is_empty() || slot.contains(&tin) || slot.contains(&TIN_AA))
4144}
4145
4146fn alt_match_depth(alt: &AltSpec, context: &Context) -> usize {
4147    let mut depth = 0;
4148    while depth < alt.s.len() {
4149        let Some(token) = context.t.get(depth) else {
4150            break;
4151        };
4152        if !slot_matches(&alt.s[depth], token.tin) {
4153            break;
4154        }
4155        depth += 1;
4156    }
4157    depth
4158}
4159
4160fn completion_tins(slot: &[Tin]) -> impl Iterator<Item = Tin> + '_ {
4161    slot.iter()
4162        .copied()
4163        .chain(slot.is_empty().then_some(TIN_AA))
4164}
4165
4166fn failed_alt_tins(context: &Context, alts: &[AltSpec], options: &Options) -> Vec<Tin> {
4167    let mut out = BTreeSet::new();
4168    for alt in alts {
4169        if !groups_enabled(alt, options) {
4170            continue;
4171        }
4172        let depth = alt_match_depth(alt, context);
4173        if let Some(slot) = alt.s.get(depth) {
4174            out.extend(completion_tins(slot));
4175        }
4176    }
4177    out.into_iter().collect()
4178}
4179
4180fn lead_tins(alts: &[AltSpec], options: &Options, out: &mut BTreeSet<Tin>) {
4181    for alt in alts {
4182        if !groups_enabled(alt, options) {
4183            continue;
4184        }
4185        if let Some(slot) = alt.s.first() {
4186            out.extend(completion_tins(slot));
4187        }
4188    }
4189}
4190
4191fn has_empty_close(spec: &RuleSpec, options: &Options) -> bool {
4192    spec.close
4193        .iter()
4194        .any(|alt| groups_enabled(alt, options) && alt.s.is_empty())
4195}
4196
4197fn alt_has_sync_group(alt: &AltSpec, sync_groups: &[String]) -> bool {
4198    alt.g
4199        .split(',')
4200        .map(str::trim)
4201        .any(|tag| sync_groups.iter().any(|wanted| wanted == tag))
4202}
4203
4204fn add_close_tins(
4205    rule: &Rule,
4206    rules: &IndexMap<String, Arc<RuleSpec>>,
4207    options: &Options,
4208    tagged_only: bool,
4209    out: &mut BTreeSet<Tin>,
4210) {
4211    let Some(spec) = rules.get(&*rule.name) else {
4212        return;
4213    };
4214    for alt in &spec.close {
4215        if !groups_enabled(alt, options)
4216            || (tagged_only && !alt_has_sync_group(alt, &options.parse.recover.sync_groups))
4217        {
4218            continue;
4219        }
4220        if let Some(slot) = alt.s.first() {
4221            out.extend(completion_tins(slot));
4222        }
4223    }
4224}
4225
4226fn compute_sync_tins(
4227    rule: &Rule,
4228    stack: &[Rule],
4229    rules: &IndexMap<String, Arc<RuleSpec>>,
4230    options: &Options,
4231) -> BTreeSet<Tin> {
4232    let mut out = BTreeSet::new();
4233    add_close_tins(rule, rules, options, true, &mut out);
4234    for parent in stack.iter().rev() {
4235        add_close_tins(parent, rules, options, true, &mut out);
4236    }
4237    if out.is_empty() {
4238        add_close_tins(rule, rules, options, false, &mut out);
4239        for parent in stack.iter().rev() {
4240            add_close_tins(parent, rules, options, false, &mut out);
4241        }
4242    }
4243    for name in &options.parse.recover.sync_tokens {
4244        if let Some(tin) = options.token(name) {
4245            out.insert(tin);
4246        }
4247        if let Some(tins) = options.token_set.get(name.trim_start_matches('#')) {
4248            out.extend(tins.iter().copied());
4249        }
4250    }
4251    out
4252}
4253
4254fn accepts_close(
4255    rule: &Rule,
4256    tin: Tin,
4257    rules: &IndexMap<String, Arc<RuleSpec>>,
4258    options: &Options,
4259) -> bool {
4260    rules.get(&*rule.name).is_some_and(|spec| {
4261        spec.close.iter().any(|alt| {
4262            groups_enabled(alt, options)
4263                && (alt.s.is_empty() || alt.s.first().is_some_and(|slot| slot_matches(slot, tin)))
4264        })
4265    })
4266}
4267
4268fn add_openers(
4269    name: &str,
4270    rules: &IndexMap<String, Arc<RuleSpec>>,
4271    options: &Options,
4272    opened: &mut BTreeSet<String>,
4273    out: &mut BTreeSet<Tin>,
4274) {
4275    if name.is_empty() || !opened.insert(name.to_owned()) {
4276        return;
4277    }
4278    let Some(spec) = rules.get(name) else {
4279        return;
4280    };
4281    lead_tins(&spec.open, options, out);
4282    for alt in &spec.open {
4283        if !groups_enabled(alt, options) || !alt.s.is_empty() {
4284            continue;
4285        }
4286        if let Some(push) = alt.p.as_deref() {
4287            add_openers(push, rules, options, opened, out);
4288        }
4289        if let Some(replace) = alt.r.as_deref() {
4290            add_openers(replace, rules, options, opened, out);
4291        }
4292    }
4293}
4294
4295fn continuation_tins(
4296    context: &Context,
4297    rule: &Rule,
4298    stack: &[Rule],
4299    rules: &IndexMap<String, Arc<RuleSpec>>,
4300    options: &Options,
4301    query_pos: usize,
4302    failed: Option<&[Tin]>,
4303) -> Vec<Tin> {
4304    let Some(spec) = rules.get(&*rule.name) else {
4305        return Vec::new();
4306    };
4307    let state_alts = if rule.state == RuleState::Open {
4308        &spec.open
4309    } else {
4310        &spec.close
4311    };
4312    let mut out = BTreeSet::new();
4313
4314    if let Some(failed) = failed.filter(|tins| !tins.is_empty()) {
4315        out.extend(failed.iter().copied());
4316    } else {
4317        for alt in state_alts {
4318            if !groups_enabled(alt, options) {
4319                continue;
4320            }
4321            let depth = alt_match_depth(alt, context);
4322            if depth == query_pos {
4323                if let Some(slot) = alt.s.get(depth) {
4324                    out.extend(completion_tins(slot));
4325                }
4326            }
4327        }
4328    }
4329
4330    // If the current rule can close without consuming a token, closing
4331    // tokens accepted by each parent are legal at the same point too.
4332    let mut close_rule = rule;
4333    let mut parent_index = stack.len();
4334    while let Some(close_spec) = rules.get(&*close_rule.name) {
4335        if !has_empty_close(close_spec, options) || parent_index == 0 {
4336            break;
4337        }
4338        parent_index -= 1;
4339        let parent = &stack[parent_index];
4340        if let Some(parent_spec) = rules.get(&*parent.name) {
4341            lead_tins(&parent_spec.close, options, &mut out);
4342        }
4343        close_rule = parent;
4344    }
4345
4346    // A fully matched alternate can immediately hand control to a pushed or
4347    // replacement rule. Follow empty opening hand-offs transitively.
4348    let mut opened = BTreeSet::new();
4349    for alt in state_alts {
4350        if !groups_enabled(alt, options) || alt_match_depth(alt, context) != alt.s.len() {
4351            continue;
4352        }
4353        // A callback backtrack is only knowable while executing the match.
4354        // Do not speculate that its static default is the handover point.
4355        if alt.b_fn.is_some() {
4356            continue;
4357        }
4358        if alt.s.len().checked_sub(alt.b) != Some(query_pos) {
4359            continue;
4360        }
4361        if let Some(push) = alt.p.as_deref() {
4362            add_openers(push, rules, options, &mut opened, &mut out);
4363        }
4364        if let Some(replace) = alt.r.as_deref() {
4365            add_openers(replace, rules, options, &mut opened, &mut out);
4366        }
4367    }
4368
4369    out.into_iter().collect()
4370}
4371
4372/// The group tags a comma-separated group list declares.
4373///
4374/// One definition, because two places ask: the include/exclude filter in
4375/// `groups_enabled`, and the list the engine publishes into `matched.g`.
4376/// They have to agree on what a tag is -- trimmed, and never empty.
4377fn listed(list: &str) -> impl Iterator<Item = &str> {
4378    list.split(',')
4379        .map(str::trim)
4380        .filter(|entry| !entry.is_empty())
4381}
4382
4383pub(crate) fn groups_enabled(alt: &AltSpec, options: &Options) -> bool {
4384    // With neither an include nor an exclude list there is nothing to
4385    // test against, so every alternate is enabled whatever groups it
4386    // declares. That is the usual case, and it is asked once per
4387    // alternate per iteration.
4388    let include = options.rule.include.as_str();
4389    let exclude = options.rule.exclude.as_str();
4390    if include.is_empty() && exclude.is_empty() {
4391        return true;
4392    }
4393    // Iterators rather than three collected `Vec<&str>`. The question is
4394    // the same one and the answer is the same answer; the three heap
4395    // allocations per call were not part of either. The shipped JSON
4396    // preset sets `rule.include` to "json", so the early return above
4397    // never fires for it and every alternate of every rule step paid
4398    // them.
4399    let declares = |wanted: &str| listed(&alt.g).any(|group| group == wanted);
4400    let included = listed(include).next().is_none() || listed(include).any(&declares);
4401    included && !listed(exclude).any(&declares)
4402}
4403
4404fn builtin_condition_matches(reference: Option<&str>, rule: &Rule) -> bool {
4405    let phase = match rule.k.get("pd_phase") {
4406        Some(Value::Number(value)) => *value as i32,
4407        _ => 0,
4408    };
4409    match reference {
4410        None => true,
4411        Some("@probePhase0$") => phase == 0,
4412        Some("@probePhase1$") => phase == 1,
4413        Some("@probePhase2$") => phase == 2,
4414        Some(_) => false,
4415    }
4416}
4417
4418fn conditions_match(conditions: &[Condition], rule: &Rule, ancestors: &[Rule]) -> bool {
4419    conditions.iter().all(|condition| {
4420        let resolved = resolve_condition_path(rule, ancestors, &condition.path);
4421        if condition.op == CompareOp::Exist {
4422            let exists = condition_exists(rule, ancestors, &condition.path);
4423            let wanted = matches!(condition.value, Value::Bool(true));
4424            return exists == wanted;
4425        }
4426        let Some(actual) = resolved else {
4427            return !matches!(condition.op, CompareOp::Eq);
4428        };
4429        match condition.op {
4430            CompareOp::Eq => actual.deep_equal(&condition.value),
4431            CompareOp::Ne => !actual.deep_equal(&condition.value),
4432            CompareOp::Lt => ordered(&actual, &condition.value).is_none_or(|value| value < 0),
4433            CompareOp::Lte => ordered(&actual, &condition.value).is_none_or(|value| value <= 0),
4434            CompareOp::Gt => ordered(&actual, &condition.value).is_none_or(|value| value > 0),
4435            CompareOp::Gte => ordered(&actual, &condition.value).is_none_or(|value| value >= 0),
4436            CompareOp::Exist => unreachable!("handled above"),
4437        }
4438    })
4439}
4440
4441fn ordered(left: &Value, right: &Value) -> Option<i8> {
4442    match (left, right) {
4443        (Value::Number(left), Value::Number(right)) => Some(if left < right {
4444            -1
4445        } else if left > right {
4446            1
4447        } else {
4448            0
4449        }),
4450        (Value::String(left), Value::String(right)) => Some(match left.cmp(right) {
4451            std::cmp::Ordering::Less => -1,
4452            std::cmp::Ordering::Equal => 0,
4453            std::cmp::Ordering::Greater => 1,
4454        }),
4455        _ => None,
4456    }
4457}
4458
4459fn condition_exists(rule: &Rule, ancestors: &[Rule], path: &[String]) -> bool {
4460    if path.first().map(String::as_str) == Some("n") && path.len() == 2 {
4461        rule.n.contains_key(&path[1])
4462    } else if path.first().map(String::as_str) == Some("parent") {
4463        ancestors
4464            .split_last()
4465            .is_some_and(|(parent, parent_ancestors)| {
4466                condition_exists(parent, parent_ancestors, &path[1..])
4467            })
4468    } else if path.first().map(String::as_str) == Some("child") {
4469        rule.child_rule
4470            .as_deref()
4471            .is_some_and(|child| snapshot_condition_exists(child, &path[1..]))
4472    } else if path.first().map(String::as_str) == Some("prev") {
4473        rule.prev_rule
4474            .as_deref()
4475            .is_some_and(|prev| snapshot_condition_exists(prev, &path[1..]))
4476    } else if path.first().map(String::as_str) == Some("next") {
4477        if let Some(next) = rule.next_rule.as_deref() {
4478            snapshot_condition_exists(next, &path[1..])
4479        } else if rule.next_rule_name.as_deref() == Some(&*rule.name) {
4480            condition_exists(rule, ancestors, &path[1..])
4481        } else {
4482            false
4483        }
4484    } else {
4485        resolve_condition_path(rule, ancestors, path).is_some()
4486    }
4487}
4488
4489fn resolve_condition_path(rule: &Rule, ancestors: &[Rule], path: &[String]) -> Option<Value> {
4490    let root = path.first()?.as_str();
4491    let rest = &path[1..];
4492    match root {
4493        "n" if rest.len() == 1 => Some(Value::Number(*rule.n.get(&rest[0]).unwrap_or(&0) as f64)),
4494        "u" => map_path(&rule.u, rest),
4495        "k" => map_path(&rule.k, rest),
4496        "d" if rest.is_empty() => Some(Value::Number(rule.d as f64)),
4497        "i" if rest.is_empty() => Some(Value::Number(rule.i as f64)),
4498        "name" if rest.is_empty() => Some(Value::String(rule.name.to_string())),
4499        "state" if rest.is_empty() => Some(Value::String(
4500            match rule.state {
4501                RuleState::Open => "o",
4502                RuleState::Close => "c",
4503            }
4504            .into(),
4505        )),
4506        "node" => value_path(rule.node.borrow().clone(), rest),
4507        "need" if rest.is_empty() => Some(Value::Number(rule.need as f64)),
4508        "oN" if rest.is_empty() => Some(Value::Number(rule.o.len() as f64)),
4509        "cN" if rest.is_empty() => Some(Value::Number(rule.c.len() as f64)),
4510        "o" => token_list_path(&rule.o, rest),
4511        "c" => token_list_path(&rule.c, rest),
4512        "o0" => token_path(rule.o.first(), rest),
4513        "o1" => token_path(rule.o.get(1), rest),
4514        "c0" => token_path(rule.c.first(), rest),
4515        "c1" => token_path(rule.c.get(1), rest),
4516        "parent" => {
4517            let (parent, parent_ancestors) = ancestors.split_last()?;
4518            resolve_condition_path(parent, parent_ancestors, rest)
4519        }
4520        "child" => resolve_snapshot_path(rule.child_rule.as_deref()?, rest),
4521        "prev" => resolve_snapshot_path(rule.prev_rule.as_deref()?, rest),
4522        "next" => {
4523            if let Some(next) = rule.next_rule.as_deref() {
4524                resolve_snapshot_path(next, rest)
4525            } else if rule.next_rule_name.as_deref() == Some(&*rule.name) {
4526                resolve_condition_path(rule, ancestors, rest)
4527            } else {
4528                None
4529            }
4530        }
4531        "spec" if rest == ["name"] => Some(Value::String(rule.name.to_string())),
4532        _ => None,
4533    }
4534}
4535
4536/// Which link a bounded snapshot becomes (see [`bounded_history`]).
4537#[derive(Clone, Copy, PartialEq, Eq)]
4538enum Link {
4539    /// The `parent_rule` a pushed child keeps: the pusher once it has
4540    /// linked the child, made at the end of the push arm.
4541    Parent,
4542    /// The pusher before it links the child, made at the start of the
4543    /// push arm. It survives as the `parent_rule` of the child's snapshot
4544    /// taken at the push: under a bound the one the pusher links as
4545    /// `child`, and with none the one the child reads as
4546    /// `parent.child.parent.child`, since the push arm then links the
4547    /// child again once the pusher has linked it, and gives the child the
4548    /// pusher as it then stands (see [`Rule::relink_child`]). That second
4549    /// link is made after the pushing alternate's after-actions have run,
4550    /// where TypeScript and Go link the live rules before them: a state
4551    /// action on the pusher's close still reads the child pushed before,
4552    /// and six hops from the child still reach this record.
4553    PusherBefore,
4554    /// A replacement's `prev_rule`: the rule it replaces.
4555    Prev,
4556}
4557
4558/// A snapshot to link, bounded by `options.rule.history`
4559/// (`doc/rule-history-bound.md`): a copy that keeps `history - 1`
4560/// predecessors, each a copy the same way, with no `child` or `next`
4561/// links. Those links are what defeat a cut of the predecessors alone:
4562/// a rule's `child` is its finished child, whose `next` leads back to
4563/// the rule's own record, whose `prev` is a copy of its predecessor,
4564/// whose `child` does the same, a ladder through the whole sequence. So
4565/// `prev.child` and `prev.next` resolve to nothing, and so does a
4566/// predecessor's past them. A cut `next` takes its name with it: a
4567/// snapshot whose next has its own name reads itself as `next`, and a
4568/// copy that kept the name would read `prev.next` as `prev`.
4569///
4570/// The `parent` a pushed child keeps ([`Link::Parent`]) keeps the
4571/// pusher's own `child` and `next`, the child itself as it stood when
4572/// pushed, before it had a `next`: no ladder starts there, and
4573/// `parent.child` and `parent.next` read as they do unbounded. The copy
4574/// made before the pusher links the child ([`Link::PusherBefore`]) cuts
4575/// them: its `child` is the pusher's previous child, and a rule that
4576/// pushes again from its close phase would link every child it pushed,
4577/// each through the one before. So `parent.child.parent.child` and the
4578/// like, the pusher as it stood before the push, resolve to nothing
4579/// under a bound, as they do in TypeScript and Go. With no bound the
4580/// push arm links the child again (see [`Rule::relink_child`]), and
4581/// that path reads the child, as the live links of the other two
4582/// runtimes do.
4583///
4584/// What a rule reads through `prev` (counters, values, tokens, node and
4585/// name) and through `parent` (the pusher and its own parents) is kept.
4586/// A copy is a twenty-field struct with eight `Rc` clones, `history` of
4587/// them per link, and `history` is read as 1 to
4588/// [`crate::options::MAX_RULE_HISTORY`], so a link costs a constant.
4589/// `None` links the snapshot untouched.
4590fn bounded_history(
4591    snapshot: Rc<RuleSnapshot>,
4592    history: Option<usize>,
4593    link: Link,
4594) -> Rc<RuleSnapshot> {
4595    let Some(history) = crate::options::effective_rule_history(history) else {
4596        return snapshot;
4597    };
4598    // The links to copy, nearest first: the snapshot and up to
4599    // `history - 1` of its predecessors. Collected and then rebuilt from
4600    // the far end, with no recursion, so that a bound as long as the
4601    // chain costs stack nothing, as `RuleSnapshot`'s `Drop` walks the
4602    // same chain without it.
4603    let mut links: Vec<&Rc<RuleSnapshot>> = Vec::with_capacity(history);
4604    let mut current = Some(&snapshot);
4605    while let Some(snapshot) = current {
4606        if links.len() == history {
4607            break;
4608        }
4609        links.push(snapshot);
4610        current = snapshot.prev_rule.as_ref();
4611    }
4612    let mut prev: Option<Rc<RuleSnapshot>> = None;
4613    // `depth` counts back from the snapshot itself, which is 0.
4614    for (depth, original) in links.into_iter().enumerate().rev() {
4615        let mut copy = (**original).clone();
4616        if depth != 0 || link != Link::Parent {
4617            copy.child_rule = None;
4618            copy.next_rule = None;
4619            copy.next_rule_name = None;
4620        }
4621        copy.prev_rule = prev.take();
4622        prev = Some(Rc::new(copy));
4623    }
4624    prev.expect("at least the snapshot itself is copied")
4625}
4626
4627fn snapshot_condition_exists(rule: &RuleSnapshot, path: &[String]) -> bool {
4628    if path.first().map(String::as_str) == Some("n") && path.len() == 2 {
4629        rule.n.contains_key(&path[1])
4630    } else if path.first().map(String::as_str) == Some("parent") {
4631        rule.parent_rule
4632            .as_deref()
4633            .is_some_and(|parent| snapshot_condition_exists(parent, &path[1..]))
4634    } else if path.first().map(String::as_str) == Some("child") {
4635        rule.child_rule
4636            .as_deref()
4637            .is_some_and(|child| snapshot_condition_exists(child, &path[1..]))
4638    } else if path.first().map(String::as_str) == Some("prev") {
4639        rule.prev_rule
4640            .as_deref()
4641            .is_some_and(|prev| snapshot_condition_exists(prev, &path[1..]))
4642    } else if path.first().map(String::as_str) == Some("next") {
4643        if let Some(next) = rule.next_rule.as_deref() {
4644            snapshot_condition_exists(next, &path[1..])
4645        } else if rule.next_rule_name.as_deref() == Some(&*rule.name) {
4646            snapshot_condition_exists(rule, &path[1..])
4647        } else {
4648            false
4649        }
4650    } else {
4651        resolve_snapshot_path(rule, path).is_some()
4652    }
4653}
4654
4655fn resolve_snapshot_path(rule: &RuleSnapshot, path: &[String]) -> Option<Value> {
4656    let root = path.first()?.as_str();
4657    let rest = &path[1..];
4658    match root {
4659        "n" if rest.len() == 1 => Some(Value::Number(*rule.n.get(&rest[0]).unwrap_or(&0) as f64)),
4660        "u" => map_path(&rule.u, rest),
4661        "k" => map_path(&rule.k, rest),
4662        "d" if rest.is_empty() => Some(Value::Number(rule.d as f64)),
4663        "i" if rest.is_empty() => Some(Value::Number(rule.i as f64)),
4664        "name" if rest.is_empty() => Some(Value::String(rule.name.to_string())),
4665        "state" if rest.is_empty() => Some(Value::String(
4666            match rule.state {
4667                RuleState::Open => "o",
4668                RuleState::Close => "c",
4669            }
4670            .into(),
4671        )),
4672        "node" => value_path(rule.node.borrow().clone(), rest),
4673        "need" if rest.is_empty() => Some(Value::Number(rule.need as f64)),
4674        "oN" if rest.is_empty() => Some(Value::Number(rule.o.len() as f64)),
4675        "cN" if rest.is_empty() => Some(Value::Number(rule.c.len() as f64)),
4676        "o" => token_list_path(&rule.o, rest),
4677        "c" => token_list_path(&rule.c, rest),
4678        "o0" => token_path(rule.o.first(), rest),
4679        "o1" => token_path(rule.o.get(1), rest),
4680        "c0" => token_path(rule.c.first(), rest),
4681        "c1" => token_path(rule.c.get(1), rest),
4682        "parent" => resolve_snapshot_path(rule.parent_rule.as_deref()?, rest),
4683        "child" => resolve_snapshot_path(rule.child_rule.as_deref()?, rest),
4684        "prev" => resolve_snapshot_path(rule.prev_rule.as_deref()?, rest),
4685        "next" => {
4686            if let Some(next) = rule.next_rule.as_deref() {
4687                resolve_snapshot_path(next, rest)
4688            } else if rule.next_rule_name.as_deref() == Some(&*rule.name) {
4689                resolve_snapshot_path(rule, rest)
4690            } else {
4691                None
4692            }
4693        }
4694        "spec" if rest == ["name"] => Some(Value::String(rule.name.to_string())),
4695        _ => None,
4696    }
4697}
4698
4699fn map_path(map: &HashMap<String, Value>, path: &[String]) -> Option<Value> {
4700    let (name, rest) = path.split_first()?;
4701    value_path(map.get(name)?.clone(), rest)
4702}
4703
4704fn value_path(mut value: Value, path: &[String]) -> Option<Value> {
4705    for part in path {
4706        value = match value {
4707            Value::Object(map) => map.get(part)?.clone(),
4708            Value::Array(items) => items.get(part.parse::<usize>().ok()?)?.clone(),
4709            _ => return None,
4710        };
4711    }
4712    Some(value)
4713}
4714
4715fn token_list_path(tokens: &[Token], path: &[String]) -> Option<Value> {
4716    let (index, rest) = path.split_first()?;
4717    token_path(tokens.get(index.parse::<usize>().ok()?), rest)
4718}
4719
4720fn token_path(token: Option<&Token>, path: &[String]) -> Option<Value> {
4721    let token = token?;
4722    if path.is_empty() {
4723        let mut value = IndexMap::new();
4724        value.insert("tin".into(), Value::Number(token.tin as f64));
4725        value.insert("name".into(), Value::String(token.name.to_string()));
4726        value.insert("src".into(), Value::String(token.src.to_string()));
4727        value.insert("val".into(), token.val.clone());
4728        value.insert("why".into(), Value::String(token.why.to_string()));
4729        return Some(Value::object(value));
4730    }
4731    let (field, rest) = path.split_first()?;
4732    let value = match field.as_str() {
4733        "tin" => Value::Number(token.tin as f64),
4734        "name" => Value::String(token.name.to_string()),
4735        "src" => Value::String(token.src.to_string()),
4736        "val" => token.val.clone(),
4737        "why" => Value::String(token.why.to_string()),
4738        _ => return None,
4739    };
4740    value_path(value, rest)
4741}
4742
4743#[cfg(test)]
4744mod tests {
4745    use super::*;
4746
4747    /// `expected_tins`, `names` and `prepared` are derived from `rules` and
4748    /// positional in it, and `add_rule` is the only thing that writes any
4749    /// of the four. That is the whole reason `rules` is private: while it was
4750    /// public, an embedder inserting or replacing a rule straight into it
4751    /// left the derived tables describing the rule that used to be there,
4752    /// and lookahead went on gating the custom matchers on that rule's token
4753    /// identities. This asserts the invariant a second write path would
4754    /// break; making `add_rule` keep an existing entry instead of replacing
4755    /// it fails the second assertion.
4756    #[test]
4757    fn replacing_a_rule_replaces_the_tables_derived_from_it() {
4758        let mut parser = Parser::new(crate::Options::default());
4759
4760        let mut first = RuleSpec::new("val");
4761        first.bo.push("@enter".into());
4762        first.open.push(AltSpec {
4763            s: vec![vec![crate::TIN_NR]],
4764            a: vec!["@act".into()],
4765            ..Default::default()
4766        });
4767        parser.add_rule(first);
4768        let slot = parser
4769            .rules()
4770            .get_index_of("val")
4771            .expect("the rule was just installed");
4772        assert_eq!(parser.expected_tins[slot].at(true, 0), [crate::TIN_NR]);
4773        assert_eq!(&*parser.names[slot], "val");
4774        assert_eq!(parser.prepared[slot].before(true).len(), 1);
4775        assert_eq!(parser.prepared[slot].open[0].actions.len(), 1);
4776
4777        let mut second = RuleSpec::new("val");
4778        second.open.push(AltSpec {
4779            s: vec![vec![crate::TIN_ST]],
4780            ..Default::default()
4781        });
4782        parser.add_rule(second);
4783
4784        assert_eq!(parser.rules().len(), 1, "a replacement, not an addition");
4785        assert_eq!(
4786            parser.expected_tins[slot].at(true, 0),
4787            [crate::TIN_ST],
4788            "lookahead would still expect the replaced rule's tokens"
4789        );
4790        // The name table is positional now, so a replacement has to land on
4791        // the index the map kept for the key rather than append beside it:
4792        // an appended handle would leave `names` describing the wrong rule
4793        // at every index past this one.
4794        assert_eq!(parser.names.len(), 1, "one rule, one shared name");
4795        assert_eq!(parser.rules().get_index_of("val"), Some(slot));
4796        assert_eq!(&*parser.names[slot], "val");
4797        // The prepared table is positional for the same reason, and its
4798        // record has to describe the rule that is installed now: the parse
4799        // loop trusts a record only while its spec is the one the rule in
4800        // hand holds, so a record left pointing at the replaced spec is a
4801        // record the loop would stop using at all.
4802        assert_eq!(parser.prepared.len(), 1);
4803        assert_eq!(&*parser.prepared[slot].name, "val");
4804        assert!(Arc::ptr_eq(
4805            &parser.prepared[slot].spec,
4806            &parser.rules()["val"]
4807        ));
4808        // The action orders are derived from the same spec and go stale the
4809        // same way. The replacement declares neither the lifecycle action
4810        // nor the alternate action the first rule did, and an order left
4811        // over from that rule is one the loop would run for it.
4812        assert!(parser.prepared[slot].before(true).is_empty());
4813        assert!(parser.prepared[slot].open[0].actions.is_empty());
4814        assert!(!parser.prepared[slot].open[0].named);
4815    }
4816
4817    /// The accepted-token table is positional now, and the slot a rule
4818    /// carries is a hint rather than an authority: `name` is public and a
4819    /// callback may have written it between one token fetch and the next.
4820    /// What the rule is called is what decides which row answers, exactly
4821    /// as the name-keyed map this replaced decided it, and a name that is
4822    /// installed nowhere expects nothing rather than whatever happens to
4823    /// sit at its slot.
4824    #[test]
4825    fn expected_match_tins_follows_the_rule_name_when_the_slot_goes_stale() {
4826        fn rule_named(name: &str, tin: Tin) -> RuleSpec {
4827            let mut spec = RuleSpec::new(name);
4828            spec.open.push(AltSpec {
4829                s: vec![vec![tin]],
4830                ..Default::default()
4831            });
4832            spec
4833        }
4834
4835        let mut options = crate::Options::default();
4836        let tin = options.register_token("#QQ");
4837        options.match_tokens.insert(
4838            "#QQ".into(),
4839            crate::options::MatchToken {
4840                name: "#QQ".into(),
4841                tin,
4842                matcher: crate::options::MatchTokenMatcher::Regex(regex::Regex::new("^q").unwrap()),
4843                eager: false,
4844            },
4845        );
4846        let mut parser = Parser::new(options);
4847        parser.add_rule(rule_named("val", crate::TIN_NR));
4848        parser.add_rule(rule_named("other", crate::TIN_ST));
4849
4850        let val_slot = parser.rules().get_index_of("val").expect("installed");
4851        let other_slot = parser.rules().get_index_of("other").expect("installed");
4852        assert_ne!(val_slot, other_slot);
4853
4854        // Bound the way the parse loop binds it: slot, name and spec all
4855        // describe the same installed rule.
4856        let mut rule = Rule::new("val", Value::Undefined);
4857        rule.bind_spec(
4858            &parser.rules()["val"],
4859            parser.names[val_slot].clone(),
4860            val_slot,
4861        );
4862        assert_eq!(&*parser.expected_match_tins(&rule, 0), [crate::TIN_NR]);
4863
4864        // A callback renames the rule to another installed rule. The slot
4865        // still points at `val`, so the slot alone would answer with
4866        // `val`'s row; the name is what makes it `other`'s, which is what
4867        // the lookup by name always gave.
4868        rule.name = parser.names[other_slot].clone();
4869        assert_eq!(
4870            &*parser.expected_match_tins(&rule, 0),
4871            [crate::TIN_ST],
4872            "the rule is called `other` now, so `other`'s row answers"
4873        );
4874
4875        // A callback swaps the spec and leaves the name. Nothing about
4876        // which row answers depends on the spec, because the row is
4877        // derived from the name the rule was installed under.
4878        rule.name = parser.names[val_slot].clone();
4879        rule.spec = Arc::clone(&parser.rules()["other"]);
4880        assert_eq!(
4881            &*parser.expected_match_tins(&rule, 0),
4882            [crate::TIN_NR],
4883            "still called `val`, so still gated by `val`'s row"
4884        );
4885
4886        // A name installed nowhere expects nothing. Its slot is
4887        // `usize::MAX`, so nothing is in range to answer by accident.
4888        let ghost = Rule::new("ghost", Value::Undefined);
4889        assert_eq!(
4890            &*parser.expected_match_tins(&ghost, 0),
4891            &[] as &[Tin],
4892            "an uninstalled name has no row, not another rule's"
4893        );
4894    }
4895
4896    /// `expected_match_tins` exists to gate the custom matchers, so with no
4897    /// custom matcher registered it answers "nothing" without consulting
4898    /// the table -- the table is still built and still says what it said,
4899    /// and the moment a match token appears the same rule at the same slot
4900    /// gets the table's row again. The first assertion is what pins the
4901    /// short-circuit: were it dropped, the empty-matcher parser would
4902    /// return `[TIN_NR]` and the assertion would fail.
4903    #[test]
4904    fn expected_match_tins_is_empty_until_a_match_token_exists() {
4905        fn val_rule() -> RuleSpec {
4906            let mut spec = RuleSpec::new("val");
4907            spec.open.push(AltSpec {
4908                s: vec![vec![crate::TIN_NR]],
4909                ..Default::default()
4910            });
4911            spec
4912        }
4913        let rule = Rule::new("val", Value::Undefined);
4914
4915        let mut without = Parser::new(crate::Options::default());
4916        without.add_rule(val_rule());
4917        assert!(without.options.match_tokens.is_empty());
4918        assert_eq!(without.expected_tins[0].at(true, 0), [crate::TIN_NR]);
4919        assert_eq!(
4920            &*without.expected_match_tins(&rule, 0),
4921            &[] as &[Tin],
4922            "no custom matcher: nothing to gate, so nothing to look up"
4923        );
4924
4925        let mut options = crate::Options::default();
4926        let tin = options.register_token("#QQ");
4927        options.match_tokens.insert(
4928            "#QQ".into(),
4929            crate::options::MatchToken {
4930                name: "#QQ".into(),
4931                tin,
4932                matcher: crate::options::MatchTokenMatcher::Regex(regex::Regex::new("^q").unwrap()),
4933                eager: false,
4934            },
4935        );
4936        let mut with = Parser::new(options);
4937        with.add_rule(val_rule());
4938        assert_eq!(
4939            &*with.expected_match_tins(&rule, 0),
4940            [crate::TIN_NR],
4941            "a custom matcher is present, so the slot's tins gate it"
4942        );
4943        assert_eq!(
4944            &*with.expected_match_tins(&rule, 1),
4945            &[] as &[Tin],
4946            "a slot the rule never fills expects nothing"
4947        );
4948    }
4949}