@tabnas/abnf 0.2.0

package/dist/converter.js

@@ -0,0 +1,2106 @@
+"use strict";
+/* Copyright (c) 2025 Richard Rodger and other contributors, MIT License */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbnfParseError = exports.abnfRules = void 0;
+exports.abnf = abnf;
+exports.parseAbnf = parseAbnf;
+exports.emitGrammarSpec = emitGrammarSpec;
+exports.eliminateLeftRecursion = eliminateLeftRecursion;
+// Declarative definition of the ABNF grammar itself, expressed as
+// tabnas rules. Each rule names its `open`/`close` alt list and, where
+// necessary, a `bo`/`bc` state hook for AST assembly.
+//
+// Stage 8: incremental alternatives via `name =/ alt` now fold
+// into the earlier production with the same name. Quoted strings
+// default to case-insensitive (ABNF semantics), `%s` / `%i` force
+// sensitivity explicitly, numeric values and repetition prefixes
+// work as in previous stages.
+//
+// Token vocabulary:
+//   #DEF   `=`  (rule-definition operator)
+//   #DEFA  `=/` (incremental-alternatives operator)
+//   #ALT   `/`  (alternation)
+//   #STAR  `*`  (repetition separator)
+//   #NUM   decimal repetition count (matched via match.token)
+//   #NV    `%[xdb]NN[(-NN|(.NN)*)]` numeric value (match.token)
+//   #SS    `%s` (case-sensitive string prefix)
+//   #SI    `%i` (case-insensitive string prefix — same as default)
+//   #LP    `(`
+//   #RP    `)`
+//   #OB    `[` (optional-group open)
+//   #CB    `]` (optional-group close)
+//   #TX    bare identifier (tabnas default text token)
+//   #ST    quoted string literal (tabnas default string token)
+//   #ZZ    end-of-source
+//
+// Grammar:
+//   abnf        = production*
+//   production = IDENT ('=' / '=/') alts
+//   alts       = seq ('/' seq)*
+//   seq        = element*
+//   element    = repetition? atom
+//   repetition = NUM '*' NUM / NUM '*' / '*' NUM / '*' / NUM
+//   atom       = IDENT | STRING | ['%s' | '%i'] STRING | NUMVAL
+//              | '(' alts ')' | '[' alts ']'
+//   numval     = '%' ('x' / 'd' / 'b') DIGITS [ '-' DIGITS | ('.' DIGITS)* ]
+const abnfRules = {
+    // Top-level: accumulates productions into r.node.
+    abnf: {
+        bo: (r) => { r.node = []; },
+        open: [
+            { s: '#ZZ', g: 'empty' },
+            { p: 'prod' },
+        ],
+        close: [{ s: '#ZZ' }],
+    },
+    // One production per invocation; tail-recurses (r:'prod') for the
+    // next. Inherits its parent's node (the productions array) and
+    // appends to it in `bc` once its `alts` child has returned.
+    // Production header is `IDENT =` — a bareword rule name followed
+    // by the `=` definition operator.
+    prod: {
+        open: [
+            // Standalone definition:   name = alts
+            {
+                s: '#TX #DEF',
+                a: (r) => {
+                    r.u.name = r.o[0].val;
+                    r.u.incremental = false;
+                },
+                p: 'alts',
+            },
+            // Incremental alternatives:   name =/ alts
+            {
+                s: '#TX #DEFA',
+                a: (r) => {
+                    r.u.name = r.o[0].val;
+                    r.u.incremental = true;
+                },
+                p: 'alts',
+            },
+        ],
+        close: [
+            // A TX followed by `=` or `=/` means the next production has
+            // begun — back up 2 tokens so a fresh `prod` invocation sees
+            // them.
+            { s: '#TX #DEF', b: 2, r: 'prod' },
+            { s: '#TX #DEFA', b: 2, r: 'prod' },
+            { b: 1 },
+        ],
+        bc: (r) => {
+            if (r.child && r.child.node !== undefined) {
+                const prod = { name: r.u.name, alts: r.child.node };
+                if (r.u.incremental)
+                    prod.incremental = true;
+                r.node.push(prod);
+            }
+        },
+    },
+    // A list of alternative sequences separated by `/` (ABNF
+    // alternation). Owns its own array (`bo` resets it) and pushes
+    // each seq result in `bc`.
+    alts: {
+        bo: (r) => { r.node = []; },
+        open: [{ p: 'seq' }],
+        close: [
+            { s: '#ALT', p: 'seq' },
+            { b: 1 },
+        ],
+        bc: (r) => {
+            if (r.child && r.child.node !== undefined) {
+                r.node.push(r.child.node);
+            }
+        },
+    },
+    // A (possibly empty) sequence of elements. The 2-token lookahead
+    // `#TX #DEF` detects a following production boundary and bails
+    // out without consuming the tokens; a plain `#TX` at the leading
+    // position (tried later so the longer alt wins) is a rule
+    // reference inside the current sequence.
+    seq: {
+        bo: (r) => { r.node = []; },
+        open: [
+            { s: '#TX #DEF', b: 2, g: 'end' },
+            { s: '#TX #DEFA', b: 2, g: 'end' },
+            { s: '#ALT', b: 1, g: 'end' },
+            { s: '#ZZ', b: 1, g: 'end' },
+            { s: '#RP', b: 1, g: 'end' },
+            { s: '#CB', b: 1, g: 'end' },
+            // Listing element-starter tokens in `s:` here ensures the
+            // tcol-driven matcher considers each one when lexing.
+            { s: '#ST', b: 1, p: 'elem' },
+            { s: '#NV', b: 1, p: 'elem' },
+            { s: '#SS', b: 1, p: 'elem' },
+            { s: '#SI', b: 1, p: 'elem' },
+            { s: '#TX', b: 1, p: 'elem' },
+            { s: '#LP', b: 1, p: 'elem' },
+            { s: '#OB', b: 1, p: 'elem' },
+            { s: '#STAR', b: 1, p: 'elem' },
+            { s: '#NUM', b: 1, p: 'elem' },
+            { p: 'elem' },
+        ],
+        close: [
+            { s: '#TX #DEF', b: 2, g: 'end' },
+            { s: '#TX #DEFA', b: 2, g: 'end' },
+            { s: '#ALT', b: 1, g: 'end' },
+            { s: '#ZZ', b: 1, g: 'end' },
+            { s: '#RP', b: 1, g: 'end' },
+            { s: '#CB', b: 1, g: 'end' },
+            { s: '#ST', b: 1, p: 'elem' },
+            { s: '#NV', b: 1, p: 'elem' },
+            { s: '#SS', b: 1, p: 'elem' },
+            { s: '#SI', b: 1, p: 'elem' },
+            { s: '#TX', b: 1, p: 'elem' },
+            { s: '#LP', b: 1, p: 'elem' },
+            { s: '#OB', b: 1, p: 'elem' },
+            { s: '#STAR', b: 1, p: 'elem' },
+            { s: '#NUM', b: 1, p: 'elem' },
+            { b: 1 },
+        ],
+    },
+    // One element: an optional ABNF repetition prefix (`*A`, `1*A`,
+    // `m*nA`, `*nA`, `m*A`, `nA`) followed by an atom. The prefix is
+    // matched up front, stored on `r.u.min`/`r.u.max`; then `atom` is
+    // pushed to parse the actual element body, whose result is wrapped
+    // into an AST node and appended to the parent seq's array in close.
+    elem: {
+        bo: (r) => { r.u.min = 1; r.u.max = 1; },
+        open: [
+            // NUM '*' NUM — bounded repetition, followed by the atom
+            // itself (listed via the ATOM tokenset so every atom-starter
+            // tin — including `#NV` — is in tcol for this position).
+            {
+                s: '#NUM #STAR #NUM #ATOM',
+                b: 1,
+                a: (r) => {
+                    r.u.min = parseInt(r.o[0].src, 10);
+                    r.u.max = parseInt(r.o[2].src, 10);
+                },
+                p: 'atom',
+            },
+            // NUM '*' — at-least-NUM repetition followed by an atom.
+            {
+                s: '#NUM #STAR #ATOM',
+                b: 1,
+                a: (r) => {
+                    r.u.min = parseInt(r.o[0].src, 10);
+                    r.u.max = Infinity;
+                },
+                p: 'atom',
+            },
+            // '*' NUM — at-most-NUM repetition.
+            {
+                s: '#STAR #NUM #ATOM',
+                b: 1,
+                a: (r) => {
+                    r.u.min = 0;
+                    r.u.max = parseInt(r.o[1].src, 10);
+                },
+                p: 'atom',
+            },
+            // '*' — zero-or-more.
+            {
+                s: '#STAR #ATOM',
+                b: 1,
+                a: (r) => { r.u.min = 0; r.u.max = Infinity; },
+                p: 'atom',
+            },
+            // NUM — exact repetition count.
+            {
+                s: '#NUM #ATOM',
+                b: 1,
+                a: (r) => {
+                    const n = parseInt(r.o[0].src, 10);
+                    r.u.min = n;
+                    r.u.max = n;
+                },
+                p: 'atom',
+            },
+            // No prefix — push atom directly (min = max = 1).
+            { p: 'atom' },
+        ],
+        close: [{
+                // Wrap the returned atom (r.child.node) based on r.u.min/max
+                // and append to the parent seq's array.
+                a: (r) => {
+                    const item = r.child.node;
+                    const { min, max } = r.u;
+                    if (min === 1 && max === 1) {
+                        r.node.push(item);
+                    }
+                    else if (min === 0 && max === Infinity) {
+                        r.node.push({ kind: 'star', inner: item });
+                    }
+                    else if (min === 1 && max === Infinity) {
+                        r.node.push({ kind: 'plus', inner: item });
+                    }
+                    else if (min === 0 && max === 1) {
+                        r.node.push({ kind: 'opt', inner: item });
+                    }
+                    else {
+                        r.node.push({ kind: 'rep', min, max, inner: item });
+                    }
+                },
+            }],
+    },
+    // The atom body — a bareword ref, quoted-string terminal,
+    // parenthesised group, or bracketed optional. Sets its OWN r.node
+    // to the AST element so the enclosing `elem` rule can read it
+    // from `r.child.node` in its close state.
+    atom: {
+        bo: (r) => { r.node = undefined; },
+        open: [
+            // Case-sensitive string:   %s"foo"
+            {
+                s: '#SS #ST',
+                a: (r) => {
+                    r.node = {
+                        kind: 'term',
+                        literal: r.o[1].val,
+                        caseSensitive: true,
+                    };
+                },
+            },
+            // Case-insensitive string: %i"foo" (same as bare "foo" below,
+            // but spelled explicitly).
+            {
+                s: '#SI #ST',
+                a: (r) => {
+                    r.node = { kind: 'term', literal: r.o[1].val };
+                },
+            },
+            // Bare quoted string — case-insensitive per ABNF default.
+            {
+                s: '#ST',
+                a: (r) => {
+                    r.node = { kind: 'term', literal: r.o[0].val };
+                },
+            },
+            {
+                s: '#NV',
+                a: (r) => {
+                    r.node = parseNumericValue(r.o[0].src);
+                },
+            },
+            {
+                s: '#TX',
+                a: (r) => {
+                    r.node = { kind: 'ref', name: r.o[0].val };
+                },
+            },
+            {
+                s: '#LP',
+                a: (r) => { r.u.groupKind = 'group'; },
+                p: 'alts',
+            },
+            {
+                s: '#OB',
+                a: (r) => { r.u.groupKind = 'opt'; },
+                p: 'alts',
+            },
+        ],
+        close: [
+            {
+                s: '#RP',
+                c: (r) => r.u.groupKind === 'group',
+                a: (r) => {
+                    r.node = { kind: 'group', alts: r.child.node };
+                },
+            },
+            {
+                s: '#CB',
+                c: (r) => r.u.groupKind === 'opt',
+                a: (r) => {
+                    r.node = {
+                        kind: 'opt',
+                        inner: { kind: 'group', alts: r.child.node },
+                    };
+                },
+            },
+            // For simple atoms (string/ref), r.node is already set by
+            // open; we want to pop without consuming the next token.
+            // List every token that can legitimately follow an atom so
+            // the lexer's tcol-driven match-matcher emits #NUM, #STAR,
+            // and friends as their proper types here — otherwise the
+            // default number-matcher would lex `1` as #NR and the
+            // enclosing seq.close wouldn't recognise the digit as the
+            // start of a repetition prefix.
+            { s: '#TX', b: 1 },
+            { s: '#ST', b: 1 },
+            { s: '#NV', b: 1 },
+            { s: '#SS', b: 1 },
+            { s: '#SI', b: 1 },
+            { s: '#NUM', b: 1 },
+            { s: '#STAR', b: 1 },
+            { s: '#LP', b: 1 },
+            { s: '#OB', b: 1 },
+            { s: '#RP', b: 1 },
+            { s: '#CB', b: 1 },
+            { s: '#ALT', b: 1 },
+            { s: '#DEF', b: 1 },
+            { s: '#ZZ', b: 1 },
+            { b: 1 },
+        ],
+    },
+};
+exports.abnfRules = abnfRules;
+// Lazily built tabnas instance that parses ABNF source. Deferred
+// construction avoids a circular-import failure at module load time.
+let _abnfParser = null;
+function getAbnfParser() {
+    if (_abnfParser)
+        return _abnfParser;
+    const { Tabnas } = require('@tabnas/parser');
+    // ABNF defines its own grammar from scratch, so we don't load any
+    // grammar plugin — just use the bare engine with default tokens.
+    const j = new Tabnas({
+        rule: { start: 'abnf' },
+        fixed: {
+            token: {
+                // Clear JSON-oriented defaults we're not using so `:`, `,`
+                // and `{` have no special meaning inside ABNF source.
+                '#OS': null,
+                '#CS': null,
+                '#CL': null,
+                '#CA': null,
+                // Re-map `#OB` / `#CB` from JSON's `{` / `}` to ABNF's
+                // `[` / `]` optional-group brackets.
+                '#OB': '[',
+                '#CB': ']',
+                '#DEF': '=',
+                // `=/` — ABNF's incremental-alternatives operator. Longer
+                // than `=`, so tabnas's longest-match-wins fixed matcher
+                // tries it first.
+                '#DEFA': '=/',
+                '#ALT': '/',
+                '#STAR': '*',
+                '#LP': '(',
+                '#RP': ')',
+            },
+        },
+        match: {
+            token: {
+                // ABNF repetition counts: decimal integers.
+                '#NUM': /^[0-9]+/,
+                // ABNF numeric value notation:
+                //   %xNN        single hex code point
+                //   %dNN        single decimal code point
+                //   %bNN        single binary code point
+                //   %xNN-NN     hex range
+                //   %xNN.NN.NN  concatenated hex code points (= string)
+                // Digits are permissive (hex covers the decimal / binary
+                // subsets); `parseNumericValue` re-validates against the
+                // actual base.
+                '#NV': /^%[xdbXDB][0-9a-fA-F]+(?:[-.][0-9a-fA-F]+)*/,
+                // `%s` / `%i` prefixes on a quoted string. The lookahead
+                // requires `"` so they don't steal the `%` of `%xNN`.
+                '#SS': /^%[sS](?=")/,
+                '#SI': /^%[iI](?=")/,
+            },
+        },
+        tokenSet: {
+            // Tokens that can legitimately open an atom. Declaring this
+            // as a set lets elem.open use `#ATOM` inside its `s:` patterns
+            // — that way the tcol at the atom-starter position includes
+            // every matcher tin (notably #NV), so the lexer doesn't fall
+            // through to #TX when the actual atom is `%xNN`.
+            ATOM: ['#ST', '#NV', '#TX', '#LP', '#OB', '#SS', '#SI'],
+        },
+        comment: {
+            // ABNF uses `;` to start a line comment. Override tabnas's
+            // default `hash` definition (which used `#`) and disable the
+            // other comment styles so `//` and `/* */` aren't confused
+            // with the alternation operator.
+            def: {
+                hash: { line: true, start: ';', lex: true, eatline: false },
+                slash: null,
+                multi: null,
+            },
+        },
+    });
+    // Drop the default JSON rules — they would otherwise compete with
+    // ours for the starting token set.
+    const existing = j.rule();
+    for (const name of Object.keys(existing)) {
+        j.rule(name, null);
+    }
+    for (const name of Object.keys(abnfRules)) {
+        const spec = abnfRules[name];
+        j.rule(name, (rs) => {
+            if (spec.bo)
+                rs.bo(spec.bo);
+            if (spec.bc)
+                rs.bc(spec.bc);
+            if (spec.open)
+                rs.open(spec.open);
+            if (spec.close)
+                rs.close(spec.close);
+        });
+    }
+    _abnfParser = (src) => j.parse(src);
+    return _abnfParser;
+}
+// Rewrite a grammar so that the only element kinds remaining are
+// `term` and `ref`. Each `X?`, `X*`, `X+` occurrence is replaced by a
+// reference to a newly-generated helper production that expresses the
+// same language in plain ABNF.
+// Eliminate left recursion — both direct (P → P α) and indirect
+// (P → Q α, Q → P β) — via Paull's algorithm.
+//
+// Order the productions, and for each A_i walk back over A_1..A_{i-1}
+// inlining any leading reference into A_i's alternatives. Once the
+// only remaining leading self-reference on A_i is direct, rewrite to
+// the iterative form
+//   P → (β_1 | … | β_m) (α_1 | … | α_n)*
+// which tabnas's push-down parser can execute without re-entering P
+// at the same source position.
+//
+// The substitution step can duplicate alternatives, so pathological
+// grammars will enlarge — caller is expected to keep the grammar
+// reasonably small (this is a first-step converter, not a full
+// toolchain).
+function eliminateLeftRecursion(grammar) {
+    const originalOrder = grammar.productions.map((p) => p.name);
+    // Order productions so that rules referenced at a leading position
+    // are processed before the rules that reference them. Paull's
+    // substitution inlines A_j's alts into A_i for j < i, so putting
+    // dependencies first is what makes nullable-prefixed hidden left
+    // recursion reachable by the substitution step.
+    //
+    // Note: substitution here always runs, even for cycle-free
+    // grammars. The reason is pragmatic rather than theoretical —
+    // populating tcol from multi-token altPrefixes (needed so the
+    // lexer's regex matchers fire with the right tin in nested
+    // contexts) requires the full inlined shape. A future refactor
+    // could compute tcol from the un-substituted grammar and only
+    // apply Paull's to the cyclic SCCs, which would preserve more
+    // named-rule structure in the emitted AST.
+    let prods = topoOrderForPaull(grammar.productions.map((p) => ({
+        name: p.name,
+        alts: p.alts.map((a) => a.slice()),
+        nodeKind: p.nodeKind,
+    })));
+    for (let i = 0; i < prods.length; i++) {
+        // For each earlier production A_j, inline any alternative of
+        // A_i whose leading element is a reference to A_j.
+        for (let j = 0; j < i; j++) {
+            prods[i] = substituteLeadingRef(prods[i], prods[j]);
+        }
+        prods[i] = eliminateDirectLeftRec(prods[i]);
+    }
+    // Restore the caller's declared order, so the start rule still
+    // ends up first (and the user sees their rule names in a
+    // recognisable order when inspecting the spec).
+    const byName = new Map(prods.map((p) => [p.name, p]));
+    const ordered = [];
+    for (const name of originalOrder) {
+        const p = byName.get(name);
+        if (p) {
+            ordered.push(p);
+            byName.delete(name);
+        }
+    }
+    // Any generated productions created during substitution (none in
+    // the current implementation) would fall through here.
+    for (const p of byName.values())
+        ordered.push(p);
+    return { productions: ordered };
+}
+// Tarjan-flavoured SCC scan over the leading-reference graph:
+// returns the names of productions that participate in at least one
+// cycle (self-loop or longer). Used to scope Paull's substitution to
+// only the rules that actually need it.
+function findLeadingRefCycleMembers(prods) {
+    const byName = new Map(prods.map((p) => [p.name, p]));
+    const leadingRefs = (p) => {
+        const out = [];
+        for (const alt of p.alts) {
+            if (alt.length === 0)
+                continue;
+            const first = alt[0];
+            if (first.kind === 'ref' && byName.has(first.name))
+                out.push(first.name);
+        }
+        return out;
+    };
+    // Tarjan's SCC algorithm.
+    let index = 0;
+    const stack = [];
+    const onStack = new Set();
+    const indices = new Map();
+    const lowlinks = new Map();
+    const cyclic = new Set();
+    function strongConnect(name) {
+        indices.set(name, index);
+        lowlinks.set(name, index);
+        index++;
+        stack.push(name);
+        onStack.add(name);
+        const prod = byName.get(name);
+        if (prod) {
+            for (const target of leadingRefs(prod)) {
+                if (!indices.has(target)) {
+                    strongConnect(target);
+                    lowlinks.set(name, Math.min(lowlinks.get(name), lowlinks.get(target)));
+                }
+                else if (onStack.has(target)) {
+                    lowlinks.set(name, Math.min(lowlinks.get(name), indices.get(target)));
+                }
+            }
+        }
+        if (lowlinks.get(name) === indices.get(name)) {
+            // Pop the SCC. If it has more than one member, or it's a
+            // single member with a self-loop, mark as cyclic.
+            const scc = [];
+            let w;
+            do {
+                w = stack.pop();
+                onStack.delete(w);
+                scc.push(w);
+            } while (w !== name);
+            const isCycle = scc.length > 1 ||
+                (scc.length === 1 && leadingRefs(byName.get(scc[0])).includes(scc[0]));
+            if (isCycle)
+                for (const n of scc)
+                    cyclic.add(n);
+        }
+    }
+    for (const p of prods) {
+        if (!indices.has(p.name))
+            strongConnect(p.name);
+    }
+    return cyclic;
+}
+// Topological order over the "leading-position reference" graph:
+// an edge A → B exists when A has at least one alternative whose
+// first element is a reference to B. Cycles are preserved as-is
+// (Paull's handles them via the substitution + direct-LR rewrite).
+function topoOrderForPaull(prods) {
+    const byName = new Map(prods.map((p) => [p.name, p]));
+    const colour = new Map(); // 0 unseen, 1 in-progress, 2 done
+    const order = [];
+    function visit(name) {
+        const c = colour.get(name) ?? 0;
+        if (c !== 0)
+            return; // already seen or on the current path
+        colour.set(name, 1);
+        const p = byName.get(name);
+        if (p) {
+            for (const alt of p.alts) {
+                if (alt.length > 0 && alt[0].kind === 'ref' && byName.has(alt[0].name)) {
+                    visit(alt[0].name);
+                }
+            }
+            colour.set(name, 2);
+            order.push(p);
+        }
+        else {
+            colour.set(name, 2);
+        }
+    }
+    for (const p of prods)
+        visit(p.name);
+    return order;
+}
+// For every alternative of `target` that begins with a ref to
+// `source`, replace that alt with |source.alts| copies — each one
+// with the leading source-ref expanded to one of source's alts.
+function substituteLeadingRef(target, source) {
+    const newAlts = [];
+    for (const alt of target.alts) {
+        if (alt.length > 0 &&
+            alt[0].kind === 'ref' &&
+            alt[0].name === source.name) {
+            const tail = alt.slice(1);
+            for (const srcAlt of source.alts) {
+                newAlts.push([...srcAlt, ...tail]);
+            }
+        }
+        else {
+            newAlts.push(alt);
+        }
+    }
+    return { name: target.name, alts: newAlts, nodeKind: target.nodeKind };
+}
+// Rewrite a single production's direct left recursion to its
+// iterative equivalent. Equivalent to the previous version of
+// `eliminateLeftRecursion` but scoped to one production.
+function eliminateDirectLeftRec(prod) {
+    const recursive = [];
+    const seeds = [];
+    for (const alt of prod.alts) {
+        if (alt.length > 0 &&
+            alt[0].kind === 'ref' &&
+            alt[0].name === prod.name) {
+            recursive.push(alt.slice(1));
+        }
+        else {
+            seeds.push(alt);
+        }
+    }
+    // A trivial recursive alt `[P]` (P ::= P, nothing else) would
+    // derive P from P with no progress — semantically a no-op. Drop
+    // them silently, since nullable-prefix expansion in Paull's can
+    // legitimately produce them and erroring would hide a legal
+    // grammar.
+    const nonTrivialRecursive = recursive.filter((t) => t.length > 0);
+    if (nonTrivialRecursive.length === 0) {
+        // Either no recursion at all, or only trivial self-refs — keep
+        // just the seeds.
+        return { name: prod.name, alts: seeds, nodeKind: prod.nodeKind };
+    }
+    if (seeds.length === 0) {
+        throw new Error(`abnf: rule '${prod.name}' is purely left-recursive ` +
+            `(no seed alternative); cannot eliminate`);
+    }
+    const seedElement = seeds.length === 1 && seeds[0].length === 1
+        ? seeds[0][0]
+        : { kind: 'group', alts: seeds };
+    const tailInner = nonTrivialRecursive.length === 1 && nonTrivialRecursive[0].length === 1
+        ? nonTrivialRecursive[0][0]
+        : { kind: 'group', alts: nonTrivialRecursive };
+    return {
+        name: prod.name,
+        alts: [[seedElement, { kind: 'star', inner: tailInner }]],
+        nodeKind: prod.nodeKind,
+    };
+}
+function desugar(grammar) {
+    const extra = [];
+    const used = new Set(grammar.productions.map((p) => p.name));
+    function freshName(hint) {
+        // Collision-avoiding name like `_gen1`, `_gen2`, …
+        let i = extra.length;
+        let name;
+        do {
+            i++;
+            name = `_gen${i}_${hint}`;
+        } while (used.has(name));
+        used.add(name);
+        return name;
+    }
+    function desugarAlt(alt) {
+        return alt.map(desugarElement);
+    }
+    function desugarElement(el) {
+        if (el.kind === 'term' || el.kind === 'ref' || el.kind === 'regex') {
+            return el;
+        }
+        if (el.kind === 'group') {
+            // Recurse into the group's alts so nested sugar is flattened,
+            // then emit a helper production whose body is those alts.
+            const innerAlts = el.alts.map((a) => desugarAlt(a));
+            const name = freshName('group');
+            extra.push({ name, alts: innerAlts, nodeKind: 'helper' });
+            return { kind: 'ref', name };
+        }
+        // `opt`, `star`, `plus` all wrap a single inner element.
+        const inner = desugarElement(el.inner);
+        const hint = inner.kind === 'ref' ? inner.name :
+            inner.kind === 'term' ? 'term' : 'x';
+        if (el.kind === 'opt') {
+            // H ::= inner | (empty)
+            const name = freshName('opt_' + hint);
+            extra.push({ name, alts: [[inner], []], nodeKind: 'helper' });
+            return { kind: 'ref', name };
+        }
+        if (el.kind === 'star') {
+            // H = inner H / (empty)
+            const name = freshName('star_' + hint);
+            const selfRef = { kind: 'ref', name };
+            extra.push({ name, alts: [[inner, selfRef], []], nodeKind: 'helper' });
+            return { kind: 'ref', name };
+        }
+        if (el.kind === 'plus') {
+            // H = inner Tail   where   Tail = inner Tail / (empty)
+            const tailName = freshName('star_' + hint);
+            const plusName = freshName('plus_' + hint);
+            const tailRef = { kind: 'ref', name: tailName };
+            extra.push({
+                name: tailName,
+                alts: [[inner, tailRef], []],
+                nodeKind: 'helper',
+            });
+            extra.push({
+                name: plusName,
+                alts: [[inner, tailRef]],
+                nodeKind: 'helper',
+            });
+            return { kind: 'ref', name: plusName };
+        }
+        // ABNF m*n bounded repetition. Desugars to a concatenation of
+        // `min` mandatory copies of the inner element followed by a
+        // tail that accepts up to `(max - min)` more.
+        //   m*n A   =>   A{m}  [A[A[A...[A]]]]   (nested optionals)
+        //   m*  A   =>   A{m}  *A                 (mandatory prefix + star)
+        //   *n  A   =>   [A [A ... [A]]]          (n nested optionals)
+        // The helper's single alt has `min` repetitions of inner, then
+        // either a star-helper for (min, ∞) or `max - min` nested
+        // optionals for a finite range.
+        const { min, max } = el;
+        const repName = freshName('rep_' + hint);
+        const repAlt = [];
+        for (let i = 0; i < min; i++)
+            repAlt.push(inner);
+        if (max === Infinity) {
+            // Tail: unbounded star of inner.
+            const tailStarName = freshName('star_' + hint);
+            const tailStarRef = { kind: 'ref', name: tailStarName };
+            extra.push({
+                name: tailStarName,
+                alts: [[inner, tailStarRef], []],
+                nodeKind: 'helper',
+            });
+            repAlt.push(tailStarRef);
+        }
+        else {
+            // Nest (max - min) optionals: [A [A [A ...]]].
+            let nested = [];
+            for (let i = 0; i < max - min; i++) {
+                // Wrap current `nested` into an optional and prepend `inner`.
+                if (nested.length === 0) {
+                    nested = [{ kind: 'opt', inner: { kind: 'group', alts: [[inner]] } }];
+                }
+                else {
+                    nested = [{
+                            kind: 'opt',
+                            inner: { kind: 'group', alts: [[inner, ...nested]] },
+                        }];
+                }
+            }
+            repAlt.push(...nested);
+        }
+        extra.push({ name: repName, alts: [desugarAlt(repAlt)], nodeKind: 'helper' });
+        return { kind: 'ref', name: repName };
+    }
+    const rewritten = grammar.productions.map((p) => {
+        const out = {
+            name: p.name,
+            alts: p.alts.map(desugarAlt),
+            nodeKind: p.nodeKind,
+        };
+        // Probe-dispatch flags survive desugar unchanged — the emitter
+        // routes around the standard alt-compilation path for these.
+        if (p.probeDispatch)
+            out.probeDispatch = p.probeDispatch;
+        if (p.probeHelper)
+            out.probeHelper = p.probeHelper;
+        return out;
+    });
+    return { productions: [...rewritten, ...extra] };
+}
+// Error raised when the ABNF source itself can't be parsed.  Surfaces
+// line and column from the underlying tabnas error so the caller can
+// report them directly. The original error is kept on `.cause`.
+class AbnfParseError extends Error {
+    constructor(message, location, cause) {
+        super(message);
+        this.name = 'AbnfParseError';
+        this.line = location?.line;
+        this.column = location?.column;
+        this.cause = cause;
+    }
+}
+exports.AbnfParseError = AbnfParseError;
+// Parse ABNF source into a grammar AST via the tabnas-based parser.
+function parseAbnf(src) {
+    const parser = getAbnfParser();
+    let productions;
+    try {
+        productions = parser(src) ?? [];
+    }
+    catch (e) {
+        // TabnasError carries `lineNumber` / `columnNumber`; fall back to
+        // ad-hoc extraction from the error message otherwise.
+        const line = e?.lineNumber ?? e?.row;
+        const column = e?.columnNumber ?? e?.col;
+        const loc = (line != null && column != null)
+            ? ` at line ${line}, column ${column}`
+            : '';
+        const raw = e?.message ? String(e.message).split('\n')[0] : String(e);
+        throw new AbnfParseError(`abnf: parse error${loc}: ${raw}`, { line, column }, e);
+    }
+    if (!Array.isArray(productions) || productions.length === 0) {
+        throw new AbnfParseError('abnf: no productions found');
+    }
+    const merged = mergeIncrementals(productions);
+    return { productions: withCoreRules(merged) };
+}
+// RFC 5234 Appendix B.1 core rules. Parsed lazily on first use
+// and spliced into any user grammar that references them but
+// doesn't define them locally.
+const CORE_RULES_ABNF = `
+ALPHA  = %x41-5A / %x61-7A
+BIT    = "0" / "1"
+CHAR   = %x01-7F
+CR     = %x0D
+LF     = %x0A
+CRLF   = CR LF
+CTL    = %x00-1F / %x7F
+DIGIT  = %x30-39
+DQUOTE = %x22
+HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
+HTAB   = %x09
+OCTET  = %x00-FF
+SP     = %x20
+VCHAR  = %x21-7E
+WSP    = SP / HTAB
+`;
+let _coreRules = null;
+function getCoreRules() {
+    if (_coreRules)
+        return _coreRules;
+    const parser = getAbnfParser();
+    const raw = parser(CORE_RULES_ABNF);
+    // Core rules flatten to `src` in the output AST — they're
+    // character-class bricks, not structural nodes users want to see
+    // one-per-matched-character.
+    for (const p of raw)
+        p.nodeKind = 'core';
+    _coreRules = new Map(raw.map((p) => [p.name, p]));
+    return _coreRules;
+}
+function refsIn(alt, out) {
+    for (const el of alt) {
+        if (el.kind === 'ref')
+            out.add(el.name);
+        else if (el.kind === 'opt' || el.kind === 'star' ||
+            el.kind === 'plus' || el.kind === 'rep') {
+            refsIn([el.inner], out);
+        }
+        else if (el.kind === 'group') {
+            for (const a of el.alts)
+                refsIn(a, out);
+        }
+    }
+}
+// Add each RFC 5234 core rule that the user's grammar references
+// but doesn't define locally. Resolution is transitive: if the
+// user mentions HEXDIG, DIGIT is pulled in too. User definitions
+// always win — a local `DIGIT = …` is left untouched.
+function withCoreRules(user) {
+    const core = getCoreRules();
+    const defined = new Set(user.map((p) => p.name));
+    const needed = new Set();
+    const scan = (prods) => {
+        for (const p of prods) {
+            for (const alt of p.alts)
+                refsIn(alt, needed);
+        }
+    };
+    scan(user);
+    const out = [];
+    // Transitively add core rules, in declaration order.
+    let added = true;
+    while (added) {
+        added = false;
+        for (const [name, prod] of core) {
+            if (defined.has(name))
+                continue;
+            if (!needed.has(name))
+                continue;
+            defined.add(name);
+            out.push(prod);
+            scan([prod]);
+            added = true;
+        }
+    }
+    return [...user, ...out];
+}
+// Fold every `name =/ alt` production into the earlier production
+// with the same name by appending its alternatives. Throws if an
+// incremental references a name that hasn't been defined yet — ABNF
+// requires the base production to appear first.
+function mergeIncrementals(prods) {
+    const out = [];
+    const byName = new Map();
+    for (const p of prods) {
+        if (p.incremental) {
+            const base = byName.get(p.name);
+            if (!base) {
+                throw new AbnfParseError(`abnf: '${p.name} =/ …' has no earlier '${p.name} = …' to extend`);
+            }
+            base.alts.push(...p.alts);
+            continue;
+        }
+        // Strip the (absent) flag on a cleanly-written production so
+        // downstream code never sees it.
+        const clean = { name: p.name, alts: p.alts };
+        if (p.nodeKind)
+            clean.nodeKind = p.nodeKind;
+        out.push(clean);
+        byName.set(p.name, clean);
+    }
+    return out;
+}
+// -- Probe-dispatch analyser + rewriter -----------------------------
+//
+// ABNF has a large family of grammars that aren't LL(k) for any
+// bounded k. The canonical example is RFC 3986's `authority`:
+//
+//   authority = [ userinfo "@" ] host [ ":" port ]
+//   userinfo  = *( unreserved / pct-encoded / sub-delims / ":" )
+//   host      = IP-literal / IPv4address / reg-name
+//   reg-name  = *( unreserved / pct-encoded / sub-delims )
+//
+// `userinfo` and `reg-name` share a character vocabulary, so a
+// FIRST-set dispatcher can't decide which branch the optional
+// `[ userinfo "@" ]` belongs to — the disambiguating `@` can be
+// arbitrarily far from the start.
+//
+// For the common pattern `[X D] Y` — an optional group whose body
+// ends with a terminal D, followed by a sequence Y whose leading
+// terminals overlap with X's — we handle the ambiguity by rewriting
+// the rule to a probe+phase-retry dispatcher:
+//
+//   1. On first entry (phase 0), mark the token position and push a
+//      failure-proof probe rule that greedily consumes every token
+//      in the joint vocabulary of X and Y.
+//   2. When the probe returns, peek ctx.t[0]:
+//        D seen   → phase = 1 (take the `X D Y` branch)
+//        D absent → phase = 2 (take the `Y` branch)
+//      Rewind to the mark and `r:` back into the dispatcher.
+//   3. The dispatcher's open has a `c:`-guarded alt for each phase
+//      that pushes the corresponding committed branch.
+//
+// The primitives used (`r:`, `k:`, `c:`, `ctx.mark`, `ctx.rewind`,
+// `ctx.t`) are the same building blocks rules/parser already exposes
+// — no new tabnas machinery is needed.
+// Predicate: element is `[ X D ]` where X is one or more elements
+// and D is a terminal literal or a regex terminal.
+function isProbeableOpt(el) {
+    if (el.kind !== 'opt')
+        return null;
+    const inner = el.inner;
+    if (inner.kind !== 'group')
+        return null;
+    if (inner.alts.length !== 1)
+        return null;
+    const seq = inner.alts[0];
+    if (seq.length < 2)
+        return null;
+    const last = seq[seq.length - 1];
+    if (last.kind !== 'term' && last.kind !== 'regex')
+        return null;
+    return { xSeq: seq.slice(0, -1), disambiguator: last };
+}
+// Union of every terminal reachable by walking an element's subtree,
+// following refs transitively. Cycles are broken by the visited set.
+// Returns terminals as AbnfElements so the caller isn't tied to the
+// emitter's token-allocation step.
+function collectTerminalVocabElements(el, grammar, out, visited) {
+    if (el.kind === 'term') {
+        const k = termKey(el);
+        if (!out.has(k))
+            out.set(k, el);
+        return;
+    }
+    if (el.kind === 'regex') {
+        const k = regexKey(el);
+        if (!out.has(k))
+            out.set(k, el);
+        return;
+    }
+    if (el.kind === 'ref') {
+        if (visited.has(el.name))
+            return;
+        visited.add(el.name);
+        const prod = grammar.productions.find((p) => p.name === el.name);
+        if (!prod)
+            return;
+        for (const alt of prod.alts)
+            for (const sub of alt)
+                collectTerminalVocabElements(sub, grammar, out, visited);
+        return;
+    }
+    if (el.kind === 'opt' || el.kind === 'star' || el.kind === 'plus' ||
+        el.kind === 'rep') {
+        collectTerminalVocabElements(el.inner, grammar, out, visited);
+        return;
+    }
+    if (el.kind === 'group') {
+        for (const alt of el.alts)
+            for (const sub of alt)
+                collectTerminalVocabElements(sub, grammar, out, visited);
+        return;
+    }
+}
+function collectSeqVocabElements(seq, grammar) {
+    const out = new Map();
+    const visited = new Set();
+    for (const el of seq)
+        collectTerminalVocabElements(el, grammar, out, visited);
+    return out;
+}
+function mapsOverlap(a, b) {
+    for (const x of a.keys())
+        if (b.has(x))
+            return true;
+    return false;
+}
+// Rewrite every ambiguous `[X D] Y` subsequence in `grammar` into a
+// probe-dispatch pattern. The grammar at this point still has `opt`,
+// `group`, `star`, `plus`, `rep` sugar — intentionally, since that's
+// where the pattern is easy to recognise. Runs BEFORE token
+// allocation; probe metadata stores AbnfElements, and the emitter
+// resolves them to token names at emit time.
+function rewriteProbeDispatches(grammar) {
+    const reports = grammar.ambiguities ?? [];
+    const extra = [];
+    const used = new Set(grammar.productions.map((p) => p.name));
+    function freshName(hint) {
+        let name = hint;
+        let i = 1;
+        while (used.has(name)) {
+            name = hint + i;
+            i++;
+        }
+        used.add(name);
+        return name;
+    }
+    const rewritten = [];
+    for (const prod of grammar.productions) {
+        let newAlts = [];
+        let touched = false;
+        for (let altIdx = 0; altIdx < prod.alts.length; altIdx++) {
+            const alt = prod.alts[altIdx];
+            let resultAlt = [];
+            for (let i = 0; i < alt.length; i++) {
+                const el = alt[i];
+                const info = isProbeableOpt(el);
+                if (!info) {
+                    resultAlt.push(el);
+                    continue;
+                }
+                const ySeq = alt.slice(i + 1);
+                if (ySeq.length === 0) {
+                    // `[X D]` is the last thing in the alt — nothing follows, so
+                    // there's nothing to disambiguate against. Standard emit.
+                    resultAlt.push(el);
+                    continue;
+                }
+                const xVocab = collectSeqVocabElements(info.xSeq, grammar);
+                const yVocab = collectSeqVocabElements(ySeq, grammar);
+                if (!mapsOverlap(xVocab, yVocab)) {
+                    // The optional's leading tokens don't overlap with the tail's
+                    // leading tokens, so the normal FIRST-based dispatcher can
+                    // decide. No rewrite needed.
+                    resultAlt.push(el);
+                    continue;
+                }
+                // Joint vocab: union of everything the probe might need to
+                // consume. Includes the disambiguator, which we then remove so
+                // the probe stops on it and the peek works.
+                const vocab = new Map([...xVocab, ...yVocab]);
+                const d = info.disambiguator;
+                const dKey = d.kind === 'term' ? termKey(d)
+                    : d.kind === 'regex' ? regexKey(d)
+                        : null;
+                if (dKey)
+                    vocab.delete(dKey);
+                const dispatchName = freshName(`${prod.name}$pd${i}`);
+                const probeName = freshName(`${dispatchName}$probe`);
+                const withName = freshName(`${dispatchName}$with`);
+                const noName = freshName(`${dispatchName}$no`);
+                // Synthesise the probe helper.
+                extra.push({
+                    name: probeName,
+                    alts: [],
+                    probeHelper: { vocabElements: [...vocab.values()] },
+                    nodeKind: 'helper',
+                });
+                // Synthesise the committed branches. `with` = X D Y, `no` = Y.
+                extra.push({
+                    name: withName,
+                    alts: [[...info.xSeq, info.disambiguator, ...ySeq]],
+                    nodeKind: 'helper',
+                });
+                extra.push({
+                    name: noName,
+                    alts: [ySeq],
+                    nodeKind: 'helper',
+                });
+                // Synthesise the dispatcher. The `alts` list is a "virtual"
+                // spec — two ref-only alts — that exists solely to feed
+                // computeFirstSets the right FIRST/nullable answers (FIRST
+                // = FIRST(with) ∪ FIRST(no)). The emitter checks
+                // `probeDispatch` first and emits the phase-retry body
+                // instead of compiling `alts`.
+                extra.push({
+                    name: dispatchName,
+                    alts: [
+                        [{ kind: 'ref', name: withName }],
+                        [{ kind: 'ref', name: noName }],
+                    ],
+                    probeDispatch: {
+                        probeRule: probeName,
+                        disambiguator: info.disambiguator,
+                        withBranch: withName,
+                        noBranch: noName,
+                    },
+                    nodeKind: 'helper',
+                });
+                reports.push({
+                    rule: prod.name, altIdx, optIdx: i,
+                    reason: `optional prefix shares vocabulary with tail`,
+                    resolved: true,
+                });
+                resultAlt.push({ kind: 'ref', name: dispatchName });
+                // Everything that followed the opt is now inside the dispatcher
+                // (withBranch / noBranch), so skip the rest of the alt.
+                i = alt.length;
+                touched = true;
+            }
+            newAlts.push(resultAlt);
+        }
+        if (touched) {
+            rewritten.push({
+                name: prod.name,
+                alts: newAlts,
+                nodeKind: prod.nodeKind,
+            });
+        }
+        else {
+            rewritten.push(prod);
+        }
+    }
+    return {
+        productions: [...rewritten, ...extra],
+        ambiguities: reports,
+    };
+}
+// Emit a probe helper production. A self-looping rule that matches any
+// one of the vocab tokens and restarts; a final empty-alt fallback
+// ensures the rule NEVER fails — if the current lookahead isn't in the
+// vocab (or we're at #ZZ), the rule pops cleanly. This is the
+// failure-proof property the probe pattern relies on.
+function emitProbeHelper(prod, tag, ruleSpec, literals, regexTokens) {
+    const elems = prod.probeHelper.vocabElements;
+    const opens = [];
+    for (const el of elems) {
+        const tok = el.kind === 'term'
+            ? literals.get(termKey(el))
+            : el.kind === 'regex' ? regexTokens.get(regexKey(el))
+                : undefined;
+        if (tok)
+            opens.push({ s: tok, r: prod.name, g: tag });
+    }
+    // Empty fallback — pops without consuming anything. Must be last.
+    opens.push({ g: tag });
+    ruleSpec[prod.name] = { open: opens };
+}
+// Emit a probe-dispatch production. Encodes the three-phase retry
+// pattern; uses only standard tabnas primitives (r:, p:, c:, k:,
+// ctx.mark/rewind/t).
+function emitProbeDispatch(prod, tag, ruleSpec, refs, literals, regexTokens, useBuiltins) {
+    const { probeRule, disambiguator, withBranch, noBranch } = prod.probeDispatch;
+    const disambiguatorToken = disambiguator.kind === 'term'
+        ? literals.get(termKey(disambiguator))
+        : disambiguator.kind === 'regex'
+            ? regexTokens.get(regexKey(disambiguator))
+            : undefined;
+    if (!disambiguatorToken) {
+        throw new Error(`abnf: probe-dispatch rule '${prod.name}' has unresolvable ` +
+            `disambiguator (kind=${disambiguator.kind})`);
+    }
+    // `bubble` lifts the committed child's node up — pure tree-building
+    // (a `@bubble$` builtin or a closure, per refs mode; dropped in
+    // recognition mode either way).
+    const bubbleFields = refs.bubble((r) => {
+        if (r.child && r.child.node !== undefined)
+            r.node = r.child.node;
+    });
+    if (useBuiltins) {
+        // Function-free dispatcher: control logic is engine `$`-builtins,
+        // the disambiguator token rides in `k` config. See
+        // docs/design/alt-action-refs.md §6.3.
+        ruleSpec[prod.name] = {
+            open: [
+                { c: '@probePhase0$', a: '@probeInit$', p: probeRule,
+                    k: { pd_d: disambiguatorToken }, g: tag },
+                { c: '@probePhase1$', p: withBranch, g: tag },
+                { c: '@probePhase2$', p: noBranch, g: tag },
+            ],
+            close: [
+                { c: '@probePhase0$', a: '@probeDecide$', r: prod.name, g: tag },
+                { ...bubbleFields, g: tag },
+            ],
+        };
+        return;
+    }
+    const initMark = refs.register((r, ctx) => {
+        r.k.pd_phase = 0;
+        r.k.pd_mark = ctx.mark();
+    });
+    const decide = refs.register((r, ctx) => {
+        // ctx.t[0] is the first token the probe didn't consume. The probe
+        // never fails, so this always reflects a real position.
+        const peek = ctx.t[0];
+        ctx.rewind(r.k.pd_mark);
+        const matched = peek && peek.name === disambiguatorToken;
+        r.k.pd_phase = matched ? 1 : 2;
+    });
+    ruleSpec[prod.name] = {
+        open: [
+            // Phase 0 — first pass: mark and probe.
+            {
+                c: refs.register((r) => !r.k.pd_phase),
+                a: initMark,
+                p: probeRule,
+                g: tag,
+            },
+            // Phase 1 — disambiguator was seen: commit to X D Y.
+            {
+                c: refs.register((r) => r.k.pd_phase === 1),
+                p: withBranch,
+                g: tag,
+            },
+            // Phase 2 — disambiguator was not seen: commit to Y alone.
+            {
+                c: refs.register((r) => r.k.pd_phase === 2),
+                p: noBranch,
+                g: tag,
+            },
+        ],
+        close: [
+            // Phase 0 close: decide phase based on peek, rewind, retry self.
+            {
+                c: refs.register((r) => r.k.pd_phase === 0),
+                a: decide,
+                r: prod.name,
+                g: tag,
+            },
+            // Phase 1 / 2 close: lift the committed child's node up.
+            { ...bubbleFields, g: tag },
+        ],
+    };
+}
+// Convert an ABNF grammar AST into a tabnas GrammarSpec.
+function emitGrammarSpec(grammar, opts) {
+    const start = opts?.start ?? grammar.productions[0].name;
+    const tag = opts?.tag ?? 'abnf';
+    // Eliminate direct left recursion (P → P α | β) by rewriting to
+    // the equivalent right-recursive form P → β (α)*, then detect
+    // ambiguous `[X D] Y` optional-prefix patterns and rewrite them
+    // into probe-dispatch helpers; finally flatten any EBNF sugar
+    // (`?`, `*`, `+`, grouping) into plain ABNF.
+    grammar = eliminateLeftRecursion(grammar);
+    grammar = rewriteProbeDispatches(grammar);
+    grammar = desugar(grammar);
+    // Allocate a fixed token for each unique literal, and a match
+    // token for each unique regex terminal. Literals are keyed by
+    // (literal, effective-case-sensitivity) so a `%s"foo"` (sensitive)
+    // and a bare `"foo"` (insensitive) produce distinct tokens.
+    const literals = new Map(); // literal-key -> token name
+    const regexTokens = new Map(); // regex key -> token name
+    const usedNames = new Set();
+    const fixedTokens = {};
+    const matchTokens = {};
+    for (const prod of grammar.productions) {
+        for (const alt of prod.alts) {
+            for (const el of alt) {
+                if (el.kind === 'term') {
+                    const key = termKey(el);
+                    if (!literals.has(key)) {
+                        const name = allocTokenName(el.literal, usedNames);
+                        literals.set(key, name);
+                        if (isEffectivelyCaseSensitive(el)) {
+                            fixedTokens[name] = el.literal;
+                        }
+                        else {
+                            // Insensitive literal with at least one letter — emit
+                            // as an anchored regex with the `i` flag. Mark the
+                            // matcher `eager$` so tabnas's lexer fires it even
+                            // when the current rule's tcol doesn't list its tin.
+                            const re = new RegExp('^' + escapeRegExp(el.literal), 'i');
+                            re.eager$ = true;
+                            matchTokens[name] = re;
+                        }
+                    }
+                }
+                else if (el.kind === 'regex') {
+                    const key = regexKey(el);
+                    if (!regexTokens.has(key)) {
+                        const name = allocTokenName('rx_' + el.pattern, usedNames);
+                        regexTokens.set(key, name);
+                        matchTokens[name] = new RegExp('^' + el.pattern, el.flags);
+                    }
+                }
+            }
+        }
+        // Probe-helper productions store their vocab as AbnfElements —
+        // walk those too so the required tokens get allocated.
+        if (prod.probeHelper) {
+            for (const el of prod.probeHelper.vocabElements) {
+                if (el.kind === 'term') {
+                    const key = termKey(el);
+                    if (!literals.has(key)) {
+                        const name = allocTokenName(el.literal, usedNames);
+                        literals.set(key, name);
+                        if (isEffectivelyCaseSensitive(el)) {
+                            fixedTokens[name] = el.literal;
+                        }
+                        else {
+                            const re = new RegExp('^' + escapeRegExp(el.literal), 'i');
+                            re.eager$ = true;
+                            matchTokens[name] = re;
+                        }
+                    }
+                }
+                else if (el.kind === 'regex') {
+                    const key = regexKey(el);
+                    if (!regexTokens.has(key)) {
+                        const name = allocTokenName('rx_' + el.pattern, usedNames);
+                        regexTokens.set(key, name);
+                        matchTokens[name] = new RegExp('^' + el.pattern, el.flags);
+                    }
+                }
+            }
+        }
+    }
+    const knownRules = new Set(grammar.productions.map((p) => p.name));
+    const { firstSets, nullable } = computeFirstSets(grammar, literals, regexTokens);
+    const refs = new RefRegistry();
+    refs.useBuiltins = !!opts?.builtins;
+    refs.emitMarks = !!opts?.marks;
+    const ruleSpec = {};
+    for (const prod of grammar.productions) {
+        if (prod.probeHelper) {
+            emitProbeHelper(prod, tag, ruleSpec, literals, regexTokens);
+            continue;
+        }
+        if (prod.probeDispatch) {
+            emitProbeDispatch(prod, tag, ruleSpec, refs, literals, regexTokens, !!opts?.builtins);
+            continue;
+        }
+        // Standard path: a (possibly single-segment) set of alternatives
+        // compiled to tabnas alts. Simple alts collapse into `open` alts
+        // directly; multi-segment alts emit a chain of aux rules.
+        emitProduction(prod, grammar, literals, regexTokens, knownRules, tag, ruleSpec, firstSets, nullable, refs);
+    }
+    // Wrap the user-visible start rule in a synthetic rule that
+    // explicitly consumes #ZZ. Without this, a user rule that pops
+    // without matching the end-of-source token lets trailing content
+    // slip past tabnas's post-loop endtkn check (the lookahead buffer
+    // outlives the parse loop).
+    const startWrapper = '__start__';
+    ruleSpec[startWrapper] = {
+        open: [{
+                p: start,
+                g: tag,
+            }],
+        close: [{
+                s: '#ZZ',
+                // Return the start rule's AST node directly — the `__start__`
+                // wrapper exists only to ensure end-of-source gets consumed.
+                // The caller of `tabnas(src)` receives the tagged user-rule
+                // node (e.g. `{rule: 'URI', src, kids: [...]}`) unadorned.
+                ...refs.bubble((r) => {
+                    if (r.child && r.child.node !== undefined) {
+                        r.node = r.child.node;
+                    }
+                }),
+                g: tag,
+            }],
+    };
+    const options = {
+        fixed: { token: fixedTokens },
+        rule: { start: startWrapper },
+    };
+    if (Object.keys(matchTokens).length > 0) {
+        options.match = { token: matchTokens };
+    }
+    const spec = {
+        ref: refs.map,
+        options,
+        rule: ruleSpec,
+    };
+    return spec;
+}
+// Break an alternative into segments. Each segment is a (possibly
+// empty) run of terminal tokens followed by at most one rule
+// reference. A single-segment alt has at most one ref, located at the
+// very end; everything else has two or more segments.
+function segmentize(alt, literals, regexTokens) {
+    const segs = [];
+    let current = { terms: [], ref: null };
+    for (const el of alt) {
+        if (el.kind === 'term') {
+            current.terms.push(literals.get(termKey(el)));
+        }
+        else if (el.kind === 'regex') {
+            const key = regexKey(el);
+            current.terms.push(regexTokens.get(key));
+        }
+        else if (el.kind === 'ref') {
+            current.ref = el.name;
+            segs.push(current);
+            current = { terms: [], ref: null };
+        }
+        else {
+            // `opt`, `star`, `plus`, `group` must have been desugared
+            // before reaching the emitter.
+            throw new Error(`abnf: internal — unexpected element kind '${el.kind}' in emitter`);
+        }
+    }
+    if (current.terms.length > 0 || segs.length === 0) {
+        segs.push(current);
+    }
+    return segs;
+}
+function regexKey(el) {
+    return `/${el.pattern}/${el.flags}`;
+}
+function isSingleSegment(alt) {
+    let sawRef = false;
+    for (const el of alt) {
+        if (el.kind === 'ref') {
+            if (sawRef)
+                return false;
+            sawRef = true;
+        }
+        else if (el.kind === 'term' || el.kind === 'regex') {
+            if (sawRef)
+                return false; // terminal after a ref — multi-segment
+        }
+        else {
+            // Desugar should have eliminated sugar kinds.
+            return false;
+        }
+    }
+    return true;
+}
+function validateRefs(alt, knownRules, ruleName) {
+    for (const el of alt) {
+        if (el.kind === 'ref' && !knownRules.has(el.name)) {
+            throw new Error(`abnf: rule '${ruleName}' references unknown rule '${el.name}'`);
+        }
+    }
+}
+// Registry used by the emitter to allocate unique `@`-prefixed
+// FuncRef names for inline action functions. The resulting spec is
+// still declarative: every function appears once, keyed by name,
+// under the spec's `ref` map.
+class RefRegistry {
+    constructor() {
+        this.refs = {};
+        this.counter = 0;
+        // When set, tree-building actions are emitted as engine `$`-builtin
+        // refs + `k` config (pure data) instead of registered closures. See
+        // docs/design/alt-action-refs.md §6.4 and implementation-diary.md.
+        this.useBuiltins = false;
+        // When set, the emitter stamps user-rule alts with a `m` mark.
+        this.emitMarks = false;
+    }
+    register(fn) {
+        const name = `@abnf_a${this.counter++}`;
+        this.refs[name] = fn;
+        return name;
+    }
+    get map() {
+        return this.refs;
+    }
+    // Tree-action emitters. Each returns the alt-spec fields to merge
+    // (`{a}` in closure mode, `{a, k}` in builtins mode).
+    node(cfg, closure) {
+        return this.useBuiltins
+            ? { a: '@node$', k: { node$: cfg } }
+            : { a: this.register(closure) };
+    }
+    capture(cfg, closure) {
+        return this.useBuiltins
+            ? { a: '@capture$', k: { capture$: cfg } }
+            : { a: this.register(closure) };
+    }
+    bubble(closure) {
+        return this.useBuiltins ? { a: '@bubble$' } : { a: this.register(closure) };
+    }
+}
+function mkAstNode(ruleName, nodeKind) {
+    return nodeKind === 'user'
+        ? { rule: ruleName, src: '', kids: [] }
+        : { src: '', kids: [] };
+}
+// A stable, human-predictable "mark" for an alternative — its leading
+// discriminator: the first matched token name (sans `#`), the pushed
+// rule name, or `_` for the empty alt. Used for `@<rule>:o|c:<mark>`
+// user-action references. See docs/design/alt-action-refs.md §3.
+function altDiscriminator(alt, literals, regexTokens) {
+    if (alt.length === 0)
+        return '_';
+    const el = alt[0];
+    if (el.kind === 'term') {
+        return (literals.get(termKey(el)) || '').replace(/^#/, '') || '_';
+    }
+    if (el.kind === 'regex') {
+        return (regexTokens.get(regexKey(el)) || '').replace(/^#/, '') || '_';
+    }
+    if (el.kind === 'ref')
+        return el.name;
+    return '_';
+}
+// Assign a unique mark per source alternative (same alt object → same
+// mark, so fan-out copies share it). Collisions get a `~N` suffix.
+function assignMarks(alts, literals, regexTokens) {
+    const marks = new Map();
+    const seen = new Map();
+    for (const alt of alts) {
+        const base = altDiscriminator(alt, literals, regexTokens);
+        const n = (seen.get(base) || 0) + 1;
+        seen.set(base, n);
+        marks.set(alt, n === 1 ? base : `${base}~${n}`);
+    }
+    return marks;
+}
+function segmentToAlt(seg, tag, refs, initNode, ruleName, nodeKind) {
+    const spec = { g: tag };
+    if (seg.terms.length > 0)
+        spec.s = seg.terms.join(' ');
+    if (seg.ref)
+        spec.p = seg.ref;
+    // Default tree-building: accumulate each matched terminal's source
+    // text into `r.node.src`. Head alts also allocate a fresh AST node
+    // so the child doesn't inherit (and then mutate) its parent's.
+    const nterms = seg.terms.length;
+    if (nterms > 0 || initNode) {
+        Object.assign(spec, refs.node({ init: initNode, rule: ruleName, kind: nodeKind, nterms }, (r) => {
+            if (initNode)
+                r.node = mkAstNode(ruleName, nodeKind);
+            const n = r.node;
+            for (let i = 0; i < nterms; i++)
+                n.src += r.o[i].src;
+        }));
+    }
+    return spec;
+}
+// Close-state action: merge the just-returned child rule's AST node
+// into the current rule's. Tagged children (user rules) get pushed
+// verbatim into `kids`; untagged (helper / core) flatten — their
+// `src` appends and their `kids` extend. Either way `src`
+// concatenates so every ancestor's `.src` reflects everything it
+// matched.
+function captureChildFields(refs, ruleName, nodeKind) {
+    return refs.capture({ rule: ruleName, kind: nodeKind }, (r) => {
+        if (r.node == null)
+            r.node = mkAstNode(ruleName, nodeKind);
+        const n = r.node;
+        const c = r.child && r.child.node;
+        if (c == null)
+            return;
+        if (typeof c !== 'object' || !('src' in c)) {
+            // Legacy shape — wrap as a leaf kid.
+            n.kids.push(c);
+            return;
+        }
+        // Defensive: if the child somehow shares this rule's node
+        // object, skip the merge rather than push a self-reference. (A
+        // properly-emitted grammar always allocates fresh child nodes.)
+        if (c === n)
+            return;
+        n.src += c.src;
+        if (c.rule)
+            n.kids.push(c);
+        else if (Array.isArray(c.kids))
+            n.kids.push(...c.kids);
+    });
+}
+function emitProduction(prod, grammar, literals, regexTokens, knownRules, tag, ruleSpec, firstSets, nullable, refs) {
+    for (const alt of prod.alts) {
+        validateRefs(alt, knownRules, prod.name);
+    }
+    const allSimple = prod.alts.every(isSingleSegment);
+    if (allSimple) {
+        // Every alternative collapses to one tabnas alt — emit them
+        // directly into the production's open state. This is a head
+        // rule, so each alt initialises its own node array. Empty alts
+        // are sorted to the end so tabnas's first-match-wins doesn't let
+        // them short-circuit non-empty alternatives.
+        const ordered = [
+            ...prod.alts.filter((alt) => alt.length > 0),
+            ...prod.alts.filter((alt) => alt.length === 0),
+        ];
+        // Ref-only alternatives have no terminal to discriminate on, so
+        // tabnas's first-match-wins would silently let them shadow any
+        // later alternative. Guard them with FIRST-set peeks when the
+        // production has more than one alt.
+        const prodKind = prod.nodeKind ?? 'user';
+        const marks = (prodKind === 'user' && refs.emitMarks)
+            ? assignMarks(ordered, literals, regexTokens)
+            : null;
+        const needsPeek = ordered.length > 1;
+        const opens = [];
+        for (const alt of ordered) {
+            const segs = segmentize(alt, literals, regexTokens);
+            const seg = segs[0];
+            const isRefOnly = alt.length >= 1 &&
+                alt.every((el) => el.kind === 'ref') &&
+                seg.terms.length === 0 &&
+                seg.ref != null;
+            const mark = marks ? marks.get(alt) : undefined;
+            if (needsPeek && isRefOnly) {
+                const firstTokens = firstOfAlt(alt, literals, regexTokens, firstSets, nullable);
+                if (firstTokens) {
+                    for (const tok of firstTokens) {
+                        const o = {
+                            s: tok,
+                            b: 1,
+                            p: seg.ref,
+                            ...refs.node({ init: true, rule: prod.name, kind: prodKind, nterms: 0 }, (r) => { r.node = mkAstNode(prod.name, prodKind); }),
+                            g: tag,
+                        };
+                        if (mark)
+                            o.m = mark;
+                        opens.push(o);
+                    }
+                    continue;
+                }
+            }
+            const o = segmentToAlt(seg, tag, refs, true, prod.name, prodKind);
+            if (mark)
+                o.m = mark;
+            opens.push(o);
+        }
+        const rs = { open: opens };
+        // If any alt has a push, the close state must capture the
+        // returned child. Add a universal fallback close alt whose
+        // action is a no-op when there was no push.
+        if (prod.alts.some((alt) => alt.some((el) => el.kind === 'ref'))) {
+            const close = {
+                ...captureChildFields(refs, prod.name, prod.nodeKind ?? 'user'),
+                g: tag,
+            };
+            if (marks)
+                close.m = '_';
+            rs.close = [close];
+        }
+        ruleSpec[prod.name] = rs;
+        return;
+    }
+    if (prod.alts.length === 1) {
+        // Single-alt, multi-segment: chain rules directly on the
+        // production.
+        emitChain(prod.name, prod.alts[0], literals, regexTokens, tag, ruleSpec, refs, prod.nodeKind ?? 'user');
+        return;
+    }
+    // Multi-alt with at least one multi-segment alternative: emit a
+    // dispatcher. Each alt becomes its own chained impl rule
+    // (`<prodname>$alt<i>`); the main rule's open peeks the first token
+    // and pushes the matching impl rule. Using `p:` (not `r:`) keeps
+    // the parent's `child` pointer valid so the parent can read the
+    // impl's node in its close-state action.
+    const dispatchOpen = [];
+    let emptyAltSeen = false;
+    const dispatchMarks = ((prod.nodeKind ?? 'user') === 'user' && refs.emitMarks)
+        ? assignMarks(prod.alts, literals, regexTokens)
+        : null;
+    for (let i = 0; i < prod.alts.length; i++) {
+        const alt = prod.alts[i];
+        const implName = `${prod.name}$alt${i}`;
+        const mark = dispatchMarks ? dispatchMarks.get(alt) : undefined;
+        if (alt.length === 0) {
+            // Empty alt acts as fallback — handled after the loop.
+            emptyAltSeen = true;
+            continue;
+        }
+        emitChain(implName, alt, literals, regexTokens, tag, ruleSpec, refs, 'helper');
+        // Fan out this alt into one dispatch entry per concrete token
+        // sequence it can start with. Up to LOOKAHEAD_K tokens per
+        // prefix is enough for the grammars this converter targets; a
+        // ref with multiple alts produces one prefix per sub-alt so
+        // overlapping FIRST sets between competing alts can still be
+        // separated by their second (or later) token.
+        // The dispatcher itself is a user (or helper) rule — it must
+        // allocate its own AST node on every dispatch alt, otherwise the
+        // node inherited from the parent via makeRule(ctx, rule.node)
+        // would be shared and the dispatcher's captureChildRef would
+        // mutate the parent's tree.
+        const dispatchKind = prod.nodeKind ?? 'user';
+        const initDispatchFields = refs.node({ init: true, rule: prod.name, kind: dispatchKind, nterms: 0 }, (r) => { r.node = mkAstNode(prod.name, dispatchKind); });
+        const LOOKAHEAD_K = 4;
+        const prefixes = altPrefixes(alt, grammar, literals, regexTokens, LOOKAHEAD_K);
+        const usable = prefixes.filter((p) => p.length > 0);
+        if (usable.length > 0) {
+            for (const p of usable) {
+                const o = {
+                    s: p.join(' '),
+                    b: p.length,
+                    p: implName,
+                    ...initDispatchFields,
+                    g: tag,
+                };
+                if (mark)
+                    o.m = mark;
+                dispatchOpen.push(o);
+            }
+        }
+        else {
+            const firstTokens = firstOfAlt(alt, literals, regexTokens, firstSets, nullable);
+            if (firstTokens === null) {
+                throw new Error(`abnf: rule '${prod.name}' alternative ${i} is nullable ` +
+                    `but is not the only empty alt; FIRST set is ambiguous`);
+            }
+            for (const tok of firstTokens) {
+                const o = {
+                    s: tok, b: 1, p: implName, ...initDispatchFields, g: tag,
+                };
+                if (mark)
+                    o.m = mark;
+                dispatchOpen.push(o);
+            }
+        }
+    }
+    if (emptyAltSeen) {
+        // Fallback: matches any token (or none), pops immediately with
+        // an empty tree. Tagged with the user rule name so a consumer
+        // walking the tree still gets a placeholder node for the empty
+        // alternative.
+        const fallbackKind = prod.nodeKind ?? 'user';
+        const o = {
+            ...refs.node({ init: true, rule: prod.name, kind: fallbackKind, nterms: 0 }, (r) => { r.node = mkAstNode(prod.name, fallbackKind); }),
+            g: tag,
+        };
+        if (dispatchMarks)
+            o.m = '_';
+        dispatchOpen.push(o);
+    }
+    const dispClose = {
+        // Merge the chosen impl's result up into the dispatcher's node,
+        // tagged with the user rule name (so the enclosing rule sees a
+        // `{rule, src, kids}` child, not the impl chain's transparent
+        // `{src, kids}`).
+        ...captureChildFields(refs, prod.name, prod.nodeKind ?? 'user'),
+        g: tag,
+    };
+    if (dispatchMarks)
+        dispClose.m = '_';
+    ruleSpec[prod.name] = { open: dispatchOpen, close: [dispClose] };
+}
+// Emit a (possibly single-step) chain of rules for one alt under the
+// given head rule name. Segment 0 goes into `headName`; later
+// segments get synthetic `<headName>$stepN` continuations.
+//
+// `headKind` controls the head rule's AST node shape: 'user' tags
+// the head's node with the rule name; 'helper' leaves it untagged
+// (transparent to the enclosing user rule). Step rules are always
+// helpers — they inherit and accumulate into the head's node via
+// `r:` replacement.
+function emitChain(headName, alt, literals, regexTokens, tag, ruleSpec, refs, headKind = 'helper') {
+    const segs = segmentize(alt, literals, regexTokens);
+    const chainName = (i) => i === 0 ? headName : `${headName}$step${i}`;
+    for (let i = 0; i < segs.length; i++) {
+        const name = chainName(i);
+        const seg = segs[i];
+        const kind = i === 0 ? headKind : 'helper';
+        // Only the head of the chain initialises the node object; later
+        // steps inherit and continue to accumulate into it via `r:`.
+        const headAlt = segmentToAlt(seg, tag, refs, i === 0, name, kind);
+        // Single-alt user rule: the head alt is user-addressable.
+        if (i === 0 && headKind === 'user' && refs.emitMarks) {
+            headAlt.m = altDiscriminator(alt, literals, regexTokens);
+        }
+        const open = [headAlt];
+        const rs = { open };
+        const isLast = i === segs.length - 1;
+        if (!isLast) {
+            // Non-last step: after the push returns, capture the child's
+            // node and replace with the next step rule.
+            rs.close = [{
+                    r: chainName(i + 1),
+                    ...captureChildFields(refs, name, kind),
+                    g: tag,
+                }];
+        }
+        else if (seg.ref) {
+            // Last step, but it had a push — we still need to capture the
+            // final child before popping.
+            rs.close = [{ ...captureChildFields(refs, name, kind), g: tag }];
+        }
+        ruleSpec[name] = rs;
+    }
+}
+// Compute FIRST(ref) for every production, plus which productions
+// are nullable (can derive the empty string). Iterates to a fixed
+// point. Terminals in FIRST sets are represented by their allocated
+// token names (e.g. `#X`).
+function computeFirstSets(grammar, literals, regexTokens) {
+    const firstSets = new Map();
+    const nullable = new Set();
+    for (const p of grammar.productions)
+        firstSets.set(p.name, new Set());
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const prod of grammar.productions) {
+            const first = firstSets.get(prod.name);
+            for (const alt of prod.alts) {
+                // Walk the alt, accumulating FIRST until a non-nullable
+                // position is hit.
+                let altNullable = true;
+                for (const el of alt) {
+                    if (el.kind === 'term' || el.kind === 'regex') {
+                        const tok = el.kind === 'term'
+                            ? literals.get(termKey(el))
+                            : regexTokens.get(regexKey(el));
+                        if (!first.has(tok)) {
+                            first.add(tok);
+                            changed = true;
+                        }
+                        altNullable = false;
+                        break;
+                    }
+                    if (el.kind === 'ref') {
+                        const refFirst = firstSets.get(el.name) ?? new Set();
+                        for (const tok of refFirst) {
+                            if (!first.has(tok)) {
+                                first.add(tok);
+                                changed = true;
+                            }
+                        }
+                        if (!nullable.has(el.name)) {
+                            altNullable = false;
+                            break;
+                        }
+                        continue;
+                    }
+                    // Desugar should have eliminated other kinds.
+                    throw new Error(`abnf: internal — unexpected kind in FIRST: ${el.kind}`);
+                }
+                if (altNullable && !nullable.has(prod.name)) {
+                    nullable.add(prod.name);
+                    changed = true;
+                }
+            }
+        }
+    }
+    return { firstSets, nullable };
+}
+// FIRST set for a specific alternative (not the whole production).
+// Returns null if the alt is nullable — the caller must treat that
+// case separately (typically as a fallback empty alt).
+function firstOfAlt(alt, literals, regexTokens, firstSets, nullable) {
+    const out = new Set();
+    for (const el of alt) {
+        if (el.kind === 'term' || el.kind === 'regex') {
+            const tok = el.kind === 'term'
+                ? literals.get(termKey(el))
+                : regexTokens.get(regexKey(el));
+            out.add(tok);
+            return out;
+        }
+        if (el.kind === 'ref') {
+            const rf = firstSets.get(el.name) ?? new Set();
+            for (const tok of rf)
+                out.add(tok);
+            if (!nullable.has(el.name))
+                return out;
+            // else keep walking into the next element
+            continue;
+        }
+        throw new Error(`abnf: internal — unexpected kind in firstOfAlt: ${el.kind}`);
+    }
+    // Alt is nullable — no non-empty prefix.
+    return null;
+}
+// Longest deterministic terminal prefix of a rule — the longest
+// sequence of tokens that every alternative of the rule starts
+// with. Refs are followed into their target rule, with a `visited`
+// set guarding cycles. An empty array means there's no confident
+// prefix (the rule either has divergent alts, starts with a multi-
+// alt ref, or hits a cycle), so the caller should fall back to a
+// single-token FIRST-set lookahead instead.
+function ruleLiteralPrefix(name, grammar, literals, regexTokens, visited) {
+    if (visited.has(name))
+        return [];
+    const next = new Set(visited);
+    next.add(name);
+    const prod = grammar.productions.find((p) => p.name === name);
+    if (!prod || prod.alts.length === 0)
+        return [];
+    const prefixes = prod.alts.map((alt) => altLiteralPrefix(alt, grammar, literals, regexTokens, next));
+    if (prefixes.some((p) => p.length === 0))
+        return [];
+    const minLen = Math.min(...prefixes.map((p) => p.length));
+    const common = [];
+    for (let i = 0; i < minLen; i++) {
+        const tok = prefixes[0][i];
+        if (prefixes.every((p) => p[i] === tok))
+            common.push(tok);
+        else
+            break;
+    }
+    return common;
+}
+function altLiteralPrefix(alt, grammar, literals, regexTokens, visited) {
+    const out = [];
+    for (const el of alt) {
+        if (el.kind === 'term') {
+            out.push(literals.get(termKey(el)));
+        }
+        else if (el.kind === 'regex') {
+            out.push(regexTokens.get(regexKey(el)));
+        }
+        else if (el.kind === 'ref') {
+            const sub = ruleLiteralPrefix(el.name, grammar, literals, regexTokens, visited);
+            // Take the ref's literal prefix and stop — we can't see past
+            // the ref without more expensive analysis.
+            out.push(...sub);
+            return out;
+        }
+        else {
+            return out;
+        }
+    }
+    return out;
+}
+// Enumerate concrete token-sequence prefixes an alternative can
+// start with, each at most `maxK` tokens long. Refs with multiple
+// alternatives fan out into one prefix per sub-alternative so the
+// caller can emit a dedicated dispatch alt for each path. When a
+// ref cycles back or exhausts depth, the path is *terminated* at
+// the tokens accumulated so far — the `done` flag is propagated
+// out of nested calls so a truncated sub-prefix is never extended
+// with tokens from elements the outer alt happens to list after the
+// cycled ref.
+function altPrefixesRaw(alt, grammar, literals, regexTokens, maxK, visited = new Set()) {
+    let paths = [{ tokens: [], done: false }];
+    for (const el of alt) {
+        const next = [];
+        for (const p of paths) {
+            if (p.done || p.tokens.length >= maxK) {
+                next.push(p);
+                continue;
+            }
+            if (el.kind === 'term') {
+                next.push({
+                    tokens: [...p.tokens, literals.get(termKey(el))],
+                    done: false,
+                });
+            }
+            else if (el.kind === 'regex') {
+                next.push({
+                    tokens: [...p.tokens, regexTokens.get(regexKey(el))],
+                    done: false,
+                });
+            }
+            else if (el.kind === 'ref') {
+                if (visited.has(el.name)) {
+                    next.push({ tokens: p.tokens, done: true });
+                    continue;
+                }
+                const childVisited = new Set(visited);
+                childVisited.add(el.name);
+                const target = grammar.productions.find((pr) => pr.name === el.name);
+                if (!target || target.alts.length === 0) {
+                    next.push({ tokens: p.tokens, done: true });
+                    continue;
+                }
+                for (const sub of target.alts) {
+                    const subPaths = altPrefixesRaw(sub, grammar, literals, regexTokens, maxK - p.tokens.length, childVisited);
+                    for (const sp of subPaths) {
+                        next.push({
+                            tokens: [...p.tokens, ...sp.tokens],
+                            // Propagate `done` so the outer loop won't extend a
+                            // cycle-truncated sub-prefix.
+                            done: sp.done,
+                        });
+                    }
+                }
+            }
+            else {
+                // Desugar should have eliminated group/star/etc. at this point.
+                next.push({ tokens: p.tokens, done: true });
+            }
+        }
+        paths = next;
+        if (paths.every((p) => p.done || p.tokens.length >= maxK))
+            break;
+    }
+    return paths;
+}
+function altPrefixes(alt, grammar, literals, regexTokens, maxK) {
+    const raw = altPrefixesRaw(alt, grammar, literals, regexTokens, maxK);
+    const seen = new Set();
+    const out = [];
+    for (const p of raw) {
+        const key = p.tokens.join(' ');
+        if (!seen.has(key)) {
+            seen.add(key);
+            out.push(p.tokens);
+        }
+    }
+    return out;
+}
+// A quoted-string literal is effectively case-sensitive either
+// when the user explicitly wrote `%s"…"` or when it contains no
+// ASCII letters (there's nothing to fold — `"+"` matches `+` in
+// any "case").
+function isEffectivelyCaseSensitive(el) {
+    if (el.caseSensitive === true)
+        return true;
+    return !/[A-Za-z]/.test(el.literal);
+}
+// Map a term element to the key used to look up (or allocate) its
+// emitted token. The key folds together the literal and its
+// effective case-sensitivity so a sensitive and an insensitive
+// occurrence of the same string are distinct tokens.
+function termKey(el) {
+    return (isEffectivelyCaseSensitive(el) ? 'cs:' : 'ci:') + el.literal;
+}
+function escapeRegExp(s) {
+    return s.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&');
+}
+// Decode an ABNF numeric value (`%xNN`, `%dNN`, `%bNN`, or one of
+// the range/concatenation forms) into a `AbnfElement`.
+//
+//   %x61            => single-char term "a"
+//   %x66.6f.6f      => concatenated term "foo"
+//   %x30-39         => regex character class [\u0030-\u0039]
+//
+// Hex is case-insensitive; decimal and binary accept only digits
+// in their respective ranges. Range endpoints must be the same
+// base as the prefix (RFC 5234 doesn't allow mixing).
+function parseNumericValue(src) {
+    const base = src[1].toLowerCase();
+    const radix = base === 'x' ? 16 : base === 'd' ? 10 : 2;
+    const body = src.slice(2);
+    if (body.includes('-')) {
+        const [loStr, hiStr] = body.split('-');
+        const lo = parseInt(loStr, radix);
+        const hi = parseInt(hiStr, radix);
+        if (lo === hi) {
+            return { kind: 'term', literal: String.fromCharCode(lo) };
+        }
+        const toEsc = (n) => '\\u' + n.toString(16).padStart(4, '0');
+        return {
+            kind: 'regex',
+            pattern: '[' + toEsc(lo) + '-' + toEsc(hi) + ']',
+            flags: '',
+        };
+    }
+    const parts = body.split('.');
+    const chars = parts.map((n) => String.fromCharCode(parseInt(n, radix)));
+    return { kind: 'term', literal: chars.join('') };
+}
+function allocTokenName(literal, used) {
+    const base = literal
+        .replace(/[^A-Za-z0-9]/g, '_')
+        .toUpperCase()
+        .replace(/^_+|_+$/g, '');
+    const candidate = base.length > 0 ? '#' + base : '#T';
+    if (!used.has(candidate)) {
+        used.add(candidate);
+        return candidate;
+    }
+    let i = 1;
+    while (used.has(candidate + i))
+        i++;
+    const chosen = candidate + i;
+    used.add(chosen);
+    return chosen;
+}
+// Public entry point: take ABNF source and return a tabnas GrammarSpec.
+function abnf(src, opts) {
+    const grammar = parseAbnf(src);
+    return emitGrammarSpec(grammar, opts);
+}
+//# sourceMappingURL=converter.js.map