functionalscript 0.37.0 → 0.38.0

package/{fs → fjs}/bnf/data/proof.f.js

@@ -3,21 +3,16 @@ import { identity } from '../../types/function/module.f.js';
 import { sort } from '../../types/object/module.f.js';
 import { oneEncode, option, range, rangeDecode, repeat0Plus, set } from '../module.f.js';
 import { classic, deterministic } from '../testlib.f.js';
-import { toData } from './module.f.js';
+import { emptyTagMap, toData } from './module.f.js';
+import { assertEq } from '../../asserts/module.f.js';
 export const proof = {
     rangeDecode: () => {
         const decoded1 = stringify(sort)(rangeDecode(0x000079_000087));
-        if (decoded1 !== '[121,135]') {
-            throw decoded1;
-        }
+        assertEq(decoded1, '[121,135]');
         const decoded2 = stringify(sort)(rangeDecode(0x000080_000087));
-        if (decoded2 !== '[128,135]') {
-            throw decoded2;
-        }
+        assertEq(decoded2, '[128,135]');
         const decoded3 = stringify(sort)(rangeDecode(0x10FFFF_10FFFF));
-        if (decoded3 !== '[1114111,1114111]') {
-            throw decoded3;
-        }
+        assertEq(decoded3, '[1114111,1114111]');
     },
     rangeEncode: () => {
         const encoded1 = oneEncode(0x79);
@@ -70,26 +65,20 @@ export const proof = {
             const varintRule = { true: 'true', false: 'false' };
             const result = stringify(sort)(toData(varintRule));
             const expected = '[{"":{"false":"5","true":"0"},"0":["1","2","3","4"],"1":1946157172,"2":1912602738,"3":1962934389,"4":1694498917,"5":["6","7","8","9","4"],"6":1711276134,"7":1627390049,"8":1811939436,"9":1929379955},""]';
-            if (result !== expected) {
-                throw [result, expected];
-            }
+            assertEq(result, expected, [result, expected]);
         },
         () => {
             const lazyRule = () => 'true';
             const lazyRule0 = () => 'false';
             const result = stringify(sort)(toData([lazyRule, lazyRule0]));
             const expected = '[{"":["lazyRule","lazyRule0"],"0":1946157172,"1":1912602738,"2":1962934389,"3":1694498917,"4":1711276134,"5":1627390049,"6":1811939436,"7":1929379955,"lazyRule":["0","1","2","3"],"lazyRule0":["4","5","6","7","3"]},""]';
-            if (result !== expected) {
-                throw [result, expected];
-            }
+            assertEq(result, expected, [result, expected]);
         },
         () => {
             const emptyRule = '';
             const result = stringify(sort)(toData(emptyRule));
             const expected = '[{"":[]},""]';
-            if (result !== expected) {
-                throw [result, expected];
-            }
+            assertEq(result, expected, [result, expected]);
         },
         () => {
             const optionRule = option('a');
@@ -120,6 +109,52 @@ export const proof = {
             throw result;
         }
     },
+    emptyTagMap: [
+        () => {
+            const stringRule = 'true';
+            const result = JSON.stringify(emptyTagMap(toData(stringRule)[0]));
+            assertEq(result, '{}');
+        },
+        () => {
+            const emptyRule = '';
+            const result = JSON.stringify(emptyTagMap(toData(emptyRule)[0]));
+            assertEq(result, '{"":true}');
+        },
+        () => {
+            const emptyRule = '';
+            const varintRule = { true: 'true', e: emptyRule };
+            const result = JSON.stringify(emptyTagMap(toData(varintRule)[0]));
+            assertEq(result, '{"5":true,"":"e"}');
+        },
+        () => {
+            const repeatRule = repeat0Plus(option('a'));
+            const result = JSON.stringify(emptyTagMap(toData(repeatRule)[0]));
+            assertEq(result, '{"0":"none","3":true,"":true,"r":"none"}');
+        },
+        () => {
+            // Regression for the sequence case: a sequence is nullable iff
+            // *all* of its items are, not just the first one. The old
+            // descent-only implementation pinned the result to nullable as
+            // soon as it saw the leading empty item, and reported this
+            // 2-item sequence as nullable even though its second item is a
+            // mandatory terminal.
+            const data = toData(['', range('AA')]);
+            const emptyTags = emptyTagMap(data[0]);
+            assertEq(emptyTags[data[1]], undefined, emptyTags);
+        },
+        () => {
+            // Regression: a fixed round count (one round per rule) settles
+            // the nullable/non-nullable *set* — a standard result — but a
+            // variant's chosen *tag* can still change for rounds after that,
+            // while a cyclic dependency's own tag catches up. Here A is
+            // nullable via 'x' (A -> E, both settle in 2 rounds), but B (a
+            // 1-item sequence over A) only becomes nullable once A does, and
+            // once B is nullable, A's true winning branch is 'y' (A -> B) —
+            // reachable only by iterating to an actual fixpoint.
+            const rs = { A: { x: 'E', y: 'B' }, B: ['A'], E: [] };
+            assertEq(emptyTagMap(rs).A, 'y');
+        },
+    ],
     example: () => {
         const grammar = {
             space: 0x000020_000020,

package/{fs → fjs}/bnf/descent/module.f.d.ts

@@ -1,20 +1,16 @@
 /**
  * Recursive descent matcher backend over the BNF data {@link RuleSet}.
  *
- * Built from the serializable IR in `fs/bnf/data`, this is a sibling of the
- * LL(1) dispatch builder (`fs/bnf/ll1`). It walks the grammar by recursive
+ * Built from the serializable IR in `fjs/bnf/data`, this is a sibling of the
+ * LL(1) dispatch builder (`fjs/bnf/ll1`). It walks the grammar by recursive
  * descent and preserves per-code-point metadata, producing a metadata-aware
- * AST ({@link AstRuleMeta}). It also exposes {@link createEmptyTagMap}, which
- * records whether each rule can match the empty input.
+ * AST ({@link AstRuleMeta}). Nullability (which rule can match empty input) is
+ * computed once by {@link emptyTagMap} in `fjs/bnf/data`.
  *
  * @module
  */
 import { type CodePoint } from '../../text/utf16/module.f.ts';
-import { type StringMap } from '../../types/object/module.f.ts';
-import { type RuleSet } from '../data/module.f.ts';
 import { type Rule as FRule } from '../module.f.ts';
-type EmptyTagEntry = string | boolean;
-type EmptyTagMap = StringMap<string, EmptyTagEntry>;
 export type AstTag = string | true | undefined;
 /**
  * Recursive descent matcher for a single named rule.
@@ -43,14 +39,8 @@ export type AstRuleMeta<T> = {
     readonly tag: AstTag;
     readonly sequence: AstSequenceMeta<T>;
 };
-/**
- * Creates a map that describes whether each rule can consume empty input and,
- * for tagged variants, which tag represents the empty match.
- */
-export declare const createEmptyTagMap: (data: readonly [RuleSet, string]) => EmptyTagMap;
 /**
  * Creates a recursive descent parser that preserves metadata for each consumed
  * code point.
  */
 export declare const descentParser: <T>(fr: FRule) => DescentMatch<T>;
-export {};

package/fjs/bnf/descent/module.f.js

@@ -0,0 +1,124 @@
+/**
+ * Recursive descent matcher backend over the BNF data {@link RuleSet}.
+ *
+ * Built from the serializable IR in `fjs/bnf/data`, this is a sibling of the
+ * LL(1) dispatch builder (`fjs/bnf/ll1`). It walks the grammar by recursive
+ * descent and preserves per-code-point metadata, producing a metadata-aware
+ * AST ({@link AstRuleMeta}). Nullability (which rule can match empty input) is
+ * computed once by {@link emptyTagMap} in `fjs/bnf/data`.
+ *
+ * @module
+ */
+import {} from '../../text/utf16/module.f.js';
+import { rangeDecode } from '../module.f.js';
+import { contains as rangeContains } from '../../types/range/module.f.js';
+import { definedEntries } from '../../types/object/module.f.js';
+import { emptyTagMap, toData } from '../data/module.f.js';
+import {} from '../module.f.js';
+/**
+ * Creates a recursive descent parser that preserves metadata for each consumed
+ * code point.
+ */
+export const descentParser = (fr) => {
+    const data = toData(fr);
+    const emptyTags = emptyTagMap(data[0]);
+    // The recursive-descent matcher as an explicit-stack machine: each iteration either
+    // starts the current task (pushing a frame for a sequence/variant and descending into
+    // its first child) or feeds the pending result into the innermost frame. Semantics are
+    // identical to the former recursive `f`, but the JS call stack stays O(1) regardless of
+    // grammar recursion depth — right-recursive rules (e.g. repeat0Plus chains) no longer
+    // overflow on long input (see the longInput proof group).
+    const f = (name, tag, cp, idx) => {
+        const mrSuccess = (tag, sequence, idx) => [{ tag, sequence }, true, idx];
+        const mrFail = (tag, sequence, idx) => [{ tag, sequence }, false, idx];
+        let stack = null;
+        let task = { name, tag, idx };
+        let result = mrFail(undefined, [], idx);
+        while (true) {
+            if (task !== null) {
+                const { name, tag, idx } = task;
+                task = null;
+                // The explicit annotation cuts a control-flow inference cycle (TS7022):
+                // `name`'s narrowed type feeds `rule`, whose type would otherwise feed the
+                // later `task` assignments that `name`'s narrowing depends on.
+                const rule = data[0][name];
+                if (typeof rule === 'number') {
+                    const emptyTag = emptyTags[name];
+                    if (idx >= cp.length) {
+                        result = emptyTag === undefined ? mrFail(emptyTag, [], idx) : mrSuccess(emptyTag, [], idx);
+                    }
+                    else {
+                        const cpi = cp[idx];
+                        const range = rangeDecode(rule);
+                        result = rangeContains(...range)(cpi[0]) ? mrSuccess(tag, [cpi], idx + 1) : mrFail(emptyTag, [], idx);
+                    }
+                }
+                else if (rule instanceof Array) {
+                    if (rule.length === 0) {
+                        result = mrSuccess(tag, [], idx);
+                    }
+                    else {
+                        stack = { top: { kind: 'seq', tag, items: rule, itemIndex: 0, startIdx: idx, seq: [] }, rest: stack };
+                        task = { name: rule[0], tag: undefined, idx };
+                    }
+                }
+                else {
+                    const entries = definedEntries(rule);
+                    const emptyTag = emptyTags[name];
+                    const emptyResult = mrFail(emptyTag, [], idx);
+                    if (entries.length === 0) {
+                        result = emptyResult;
+                    }
+                    else {
+                        stack = { top: { kind: 'variant', entries, entryIndex: 0, idx, emptyResult }, rest: stack };
+                        const [entryTag, entryName] = entries[0];
+                        task = { name: entryName, tag: entryTag, idx };
+                    }
+                }
+                continue;
+            }
+            if (stack === null) {
+                return result;
+            }
+            const frame = stack.top;
+            stack = stack.rest;
+            if (frame.kind === 'seq') {
+                const [astRule, success, nidx] = result;
+                if (success === false) {
+                    result = mrFail(frame.tag, [], frame.startIdx);
+                }
+                else {
+                    const seq = [...frame.seq, astRule];
+                    const itemIndex = frame.itemIndex + 1;
+                    if (itemIndex < frame.items.length) {
+                        stack = { top: { ...frame, itemIndex, seq }, rest: stack };
+                        task = { name: frame.items[itemIndex], tag: undefined, idx: nidx };
+                    }
+                    else {
+                        result = mrSuccess(frame.tag, seq, nidx);
+                    }
+                }
+            }
+            else {
+                // success that consumed input wins immediately: the frame stays popped and
+                // `result` propagates to the frame below, matching the recursive `return m`.
+                if (!(result[1] && frame.idx !== result[2])) {
+                    const emptyResult = result[1] ? result : frame.emptyResult;
+                    const entryIndex = frame.entryIndex + 1;
+                    if (entryIndex < frame.entries.length) {
+                        stack = { top: { ...frame, entryIndex, emptyResult }, rest: stack };
+                        const [entryTag, entryName] = frame.entries[entryIndex];
+                        task = { name: entryName, tag: entryTag, idx: frame.idx };
+                    }
+                    else {
+                        result = emptyResult;
+                    }
+                }
+            }
+        }
+    };
+    const match = (name, cp) => {
+        return f(name, undefined, cp, 0);
+    };
+    return match;
+};

package/{fs → fjs}/bnf/descent/proof.f.d.ts

@@ -1,5 +1,6 @@
 export declare const proof: {
     emptyTags: (() => void)[];
     descentParser: (() => void)[];
+    longInput: (() => void)[];
     descentParserWithMeta: (() => void)[];
 };

package/{fs → fjs}/bnf/descent/proof.f.js

@@ -2,8 +2,9 @@ import { stringToCodePointList } from '../../text/utf16/module.f.js';
 import { map, toArray } from '../../types/list/module.f.js';
 import { commaJoin0Plus, option, range, repeat0Plus, set } from '../module.f.js';
 import { deterministic } from '../testlib.f.js';
-import { toData } from '../data/module.f.js';
-import { createEmptyTagMap, descentParser } from './module.f.js';
+import { emptyTagMap, toData } from '../data/module.f.js';
+import { descentParser } from './module.f.js';
+import { assertEq } from '../../asserts/module.f.js';
 const mapCodePoint = (cp) => [cp, undefined];
 const descentParserCpOnly = (m, name, cp) => {
     const cpm = toArray(map(mapCodePoint)(cp));
@@ -14,34 +15,34 @@ export const proof = {
         () => {
             const stringRule = 'true';
             const data = toData(stringRule);
-            const emptyTags = createEmptyTagMap(data);
+            const emptyTags = emptyTagMap(data[0]);
             const result = JSON.stringify(emptyTags);
-            if (result !== '{"0":false,"1":false,"2":false,"3":false,"":false}') {
+            if (result !== '{}') {
                 throw result;
             }
         },
         () => {
             const terminalRangeRule = range('AF');
             const data = toData(terminalRangeRule);
-            const emptyTags = createEmptyTagMap(data);
+            const emptyTags = emptyTagMap(data[0]);
             const result = JSON.stringify(emptyTags);
-            if (result !== '{"":false}') {
+            if (result !== '{}') {
                 throw result;
             }
         },
         () => {
             const varintRule = { true: 'true', false: 'false' };
             const data = toData(varintRule);
-            const emptyTags = createEmptyTagMap(data);
+            const emptyTags = emptyTagMap(data[0]);
             const result = JSON.stringify(emptyTags);
-            if (result !== '{"0":false,"1":false,"2":false,"3":false,"4":false,"5":false,"6":false,"7":false,"8":false,"9":false,"":false}') {
+            if (result !== '{}') {
                 throw result;
             }
         },
         () => {
             const emptyRule = '';
             const data = toData(emptyRule);
-            const emptyTags = createEmptyTagMap(data);
+            const emptyTags = emptyTagMap(data[0]);
             const result = JSON.stringify(emptyTags);
             if (result !== '{"":true}') {
                 throw result;
@@ -51,27 +52,27 @@ export const proof = {
             const emptyRule = '';
             const varintRule = { true: 'true', e: emptyRule };
             const data = toData(varintRule);
-            const emptyTags = createEmptyTagMap(data);
+            const emptyTags = emptyTagMap(data[0]);
             const result = JSON.stringify(emptyTags);
-            if (result !== '{"0":false,"1":false,"2":false,"3":false,"4":false,"5":true,"":"e"}') {
+            if (result !== '{"5":true,"":"e"}') {
                 throw result;
             }
         },
         () => {
             const repeatRule = repeat0Plus(option('a'));
             const data = toData(repeatRule);
-            const emptyTags = createEmptyTagMap(data);
+            const emptyTags = emptyTagMap(data[0]);
             const result = JSON.stringify(emptyTags);
-            if (result !== '{"0":"none","1":false,"2":false,"3":true,"r":"none","":true}') {
+            if (result !== '{"0":"none","3":true,"":true,"r":"none"}') {
                 throw result;
             }
         },
         () => {
             const repeatRule = repeat0Plus(set(' \n\r\t'));
             const data = toData(repeatRule);
-            const emptyTags = createEmptyTagMap(data);
+            const emptyTags = emptyTagMap(data[0]);
             const result = JSON.stringify(emptyTags);
-            if (result !== '{"0":false,"1":false,"2":false,"3":false,"4":false,"5":true,"r":"none","":true}') {
+            if (result !== '{"5":true,"r":"none"}') {
                 throw result;
             }
         }
@@ -151,6 +152,15 @@ export const proof = {
                 throw result;
             }
         },
+        () => {
+            const emptyVariantRule = {};
+            const m = descentParser(emptyVariantRule);
+            const mr = m("", []);
+            const result = JSON.stringify(mr);
+            if (result !== '[{"sequence":[]},false,0]') {
+                throw result;
+            }
+        },
         () => {
             const stringRule = 'AB';
             const m = descentParser(stringRule);
@@ -214,9 +224,7 @@ export const proof = {
                 const cp = toArray(stringToCodePointList(s));
                 const mr = descentParserCpOnly(m, '', cp);
                 const success = mr[1] && mr[2] === cp.length;
-                if (success !== expected) {
-                    throw mr;
-                }
+                assertEq(success, expected, mr);
             };
             expect('a', true);
             expect('', true);
@@ -236,9 +244,7 @@ export const proof = {
                 const cp = toArray(stringToCodePointList(s));
                 const mr = descentParserCpOnly(m, 'value', cp);
                 const success = mr[1] && mr[2] === cp.length;
-                if (success !== expected) {
-                    throw mr;
-                }
+                assertEq(success, expected, mr);
             };
             expect('', false);
             expect('[]', true);
@@ -252,9 +258,7 @@ export const proof = {
                 const cp = toArray(stringToCodePointList(s));
                 const mr = descentParserCpOnly(m, '', cp);
                 const success = mr[1] && mr[2] === cp.length;
-                if (success !== expected) {
-                    throw mr;
-                }
+                assertEq(success, expected, mr);
             };
             expect('   true   ', true);
             expect('   tr2ue   ', false);
@@ -278,6 +282,33 @@ export const proof = {
             expect('   [{ "q": [ 12, false, [}], "a"] }]  ', false);
         }
     ],
+    // Regression for the stack-recursive matcher bug: the matcher used to recurse
+    // natively once per grammar step, so match depth grew with input length and these
+    // inputs threw "RangeError: Maximum call stack size exceeded" at a few thousand
+    // code points. The explicit-frame-stack matcher handles them in O(1) JS call stack.
+    longInput: [
+        () => {
+            // long right-recursive repetition: one repeat0Plus chain across the whole input
+            const rule = repeat0Plus(set(' \n\r\t'));
+            const name = toData(rule)[1];
+            const m = descentParser(rule);
+            const cp = toArray(stringToCodePointList(' '.repeat(10000)));
+            const [, ok, idx] = descentParserCpOnly(m, name, cp);
+            assertEq(ok, true);
+            assertEq(idx, 10000);
+        },
+        () => {
+            // deep non-repetition nesting: 5000 bracket levels in the JSON-like test
+            // grammar — a shape that repetition-specific fixes (a `repeat` primitive)
+            // would not cover
+            const m = descentParser(deterministic());
+            const n = 5000;
+            const cp = toArray(stringToCodePointList('['.repeat(n) + ']'.repeat(n)));
+            const [, ok, idx] = descentParserCpOnly(m, '', cp);
+            assertEq(ok, true);
+            assertEq(idx, n * 2);
+        },
+    ],
     descentParserWithMeta: [
         () => {
             const emptyRule = '';

package/{fs → fjs}/bnf/ll1/module.f.d.ts

@@ -1,20 +1,20 @@
 /**
  * LL(1) dispatch/matcher backend over the BNF data {@link RuleSet}.
  *
- * Built from the serializable IR in `fs/bnf/data`, this is one member of the
+ * Built from the serializable IR in `fjs/bnf/data`, this is one member of the
  * family of automaton builders that consume a {@link RuleSet}: it compiles the
  * grammar into a predictive {@link dispatchMap} and matches input into an AST
  * ({@link MatchResult}). It throws at build time (`can not merge …`) when the
- * grammar is not LL(1) — a first/first conflict.
+ * grammar is not LL(1) — a first/first conflict. Nullability is looked up from
+ * {@link emptyTagMap} in `fjs/bnf/data` rather than re-derived here.
  *
  * @module
  */
 import { type CodePoint } from '../../text/utf16/module.f.ts';
 import { type RangeMapArray } from '../../types/range_map/module.f.ts';
 import { type StringMap } from '../../types/object/module.f.ts';
-import { type RuleSet } from '../data/module.f.ts';
+import { type EmptyTag, type RuleSet } from '../data/module.f.ts';
 import { type Rule as FRule } from '../module.f.ts';
-type EmptyTag = string | true | undefined;
 type DispatchRule = {
     readonly emptyTag: EmptyTag;
     readonly rangeMap: Dispatch;

package/{fs → fjs}/bnf/ll1/module.f.js

@@ -1,11 +1,12 @@
 /**
  * LL(1) dispatch/matcher backend over the BNF data {@link RuleSet}.
  *
- * Built from the serializable IR in `fs/bnf/data`, this is one member of the
+ * Built from the serializable IR in `fjs/bnf/data`, this is one member of the
  * family of automaton builders that consume a {@link RuleSet}: it compiles the
  * grammar into a predictive {@link dispatchMap} and matches input into an AST
  * ({@link MatchResult}). It throws at build time (`can not merge …`) when the
- * grammar is not LL(1) — a first/first conflict.
+ * grammar is not LL(1) — a first/first conflict. Nullability is looked up from
+ * {@link emptyTagMap} in `fjs/bnf/data` rather than re-derived here.
  *
  * @module
  */
@@ -16,7 +17,7 @@ import { rangeMap } from '../../types/range_map/module.f.js';
 import { contains, set } from '../../types/string_set/module.f.js';
 import { rangeDecode } from '../module.f.js';
 import { definedEntries } from '../../types/object/module.f.js';
-import { toData } from '../data/module.f.js';
+import { emptyTagMap, toData } from '../data/module.f.js';
 import {} from '../module.f.js';
 const dispatchOp = rangeMap({
     union: a => b => {
@@ -35,6 +36,7 @@ const dispatchOp = rangeMap({
  * Builds a dispatch map for a {@link RuleSet} to enable predictive parsing.
  */
 export const dispatchMap = (ruleSet) => {
+    const nullMap = emptyTagMap(ruleSet);
     const addRuleToDispatch = (dr, name) => {
         if (dr === null)
             return null;
@@ -70,7 +72,7 @@ export const dispatchMap = (ruleSet) => {
                     if (emptyTag === true) {
                         result = result.map(x => [addRuleToDispatch(x[0], item), x[1]]);
                         result = toArray(dispatchOp.merge(result)(dr.rangeMap));
-                        emptyTag = dr.emptyTag !== undefined ? true : undefined;
+                        emptyTag = nullMap[item] !== undefined ? true : undefined;
                     }
                     else {
                         result = result.map(x => [addRuleToDispatch(x[0], item), x[1]]);
@@ -87,7 +89,7 @@ export const dispatchMap = (ruleSet) => {
             for (const [tag, item] of entries) {
                 dm = dispatchRule(dm, item, newCurrent);
                 const dr = dm[item];
-                if (dr.emptyTag !== undefined) {
+                if (nullMap[item] !== undefined) {
                     emptyTag = tag;
                 }
                 else {

package/{fs → fjs}/bnf/ll1/proof.f.d.ts

@@ -6,4 +6,5 @@ export declare const proof: {
     throw: {
         ambiguousVariantDispatch: () => void;
     };
+    cyclicNullability: () => void;
 };

package/{fs → fjs}/bnf/ll1/proof.f.js

@@ -4,6 +4,7 @@ import { commaJoin0Plus, option, range, repeat0Plus, set } from '../module.f.js'
 import { deterministic } from '../testlib.f.js';
 import { toData } from '../data/module.f.js';
 import { dispatchMap, parser, parserRuleSet } from './module.f.js';
+import { assertEq } from '../../asserts/module.f.js';
 export const proof = {
     dispatch: [
         () => {
@@ -238,9 +239,7 @@ export const proof = {
             const isSuccess = (mr) => mr[1] && mr[2]?.length === 0;
             const expect = (s, success) => {
                 const mr = m('', toArray(stringToCodePointList(s)));
-                if (isSuccess(mr) !== success) {
-                    throw mr;
-                }
+                assertEq(isSuccess(mr), success, mr);
             };
             expect('a', true);
             expect('', true);
@@ -259,9 +258,7 @@ export const proof = {
             const isSuccess = (mr) => mr[1] && mr[2]?.length === 0;
             const expect = (s, success) => {
                 const mr = m('value', toArray(stringToCodePointList(s)));
-                if (isSuccess(mr) !== success) {
-                    throw mr;
-                }
+                assertEq(isSuccess(mr), success, mr);
             };
             expect('', false);
             expect('[]', true);
@@ -274,9 +271,7 @@ export const proof = {
             const isSuccess = (mr) => mr[1] && mr[2]?.length === 0;
             const expect = (s, success) => {
                 const mr = m('', toArray(stringToCodePointList(s)));
-                if (isSuccess(mr) !== success) {
-                    throw mr;
-                }
+                assertEq(isSuccess(mr), success, mr);
             };
             expect('   true   ', true);
             expect('   tr2ue   ', false);
@@ -354,5 +349,27 @@ export const proof = {
             const conflictRule = { 'a': range('AA'), 'b': range('AA') };
             dispatchMap(toData(conflictRule)[0]);
         }
-    }
+    },
+    // Regression: `emptyTagMap` must stay correct for cyclic rule references.
+    // A naive single-pass, memoized derivation that marks a rule nullable as
+    // a placeholder *before* recursing into its own children (to break the
+    // cycle) over-approximates nullability here, and made `dispatchMap`
+    // falsely report a first/first conflict for this grammar even though it
+    // has none — `value` only ever nests inside brackets or is the literal
+    // `a`, and `ws` is genuinely optional on both sides of it.
+    cyclicNullability: () => {
+        const ws = option(' ');
+        const value = () => ({ array: ['[', value, ']'], leaf: 'a' });
+        const m = parser([ws, value, ws]); // must not throw 'can not merge'
+        const expect = (s, success) => {
+            const mr = m('', toArray(stringToCodePointList(s)));
+            assertEq(mr[1] && mr[2]?.length === 0, success, mr);
+        };
+        expect('a', true);
+        expect(' a ', true);
+        expect('[a]', true);
+        expect('[[a]]', true);
+        expect(' [[a]] ', true);
+        expect('b', false);
+    },
 };

package/{fs → fjs}/bnf/module.f.d.ts

@@ -6,6 +6,21 @@ import { type Array2 } from '../types/array/module.f.ts';
  * For example: 0xBBBBBB_EEEEEE
  * - 0xBBBBBB is the first symbol (24 bits)
  * - 0xEEEEEE is the last symbol (24 bits)
+ *
+ * 24 bits per half, not 26 (the most `float64`'s 52-bit safe-integer mantissa
+ * could fit two of): 24 is divisible by 4, so each half is exactly 6 hex
+ * digits, and the packed pair reads as a plain `0xYYYYYY_ZZZZZZ` literal with
+ * no partial hex digit at either boundary. 26 bits would still be safe to
+ * store but wouldn't align to hex nibbles, making the packed literal harder
+ * to read and split by eye.
+ *
+ * Not 16 bits (32 bits total) either, even though a 32-bit pair would fit in
+ * a JS bitwise operator's native 32-bit range (JS `|`/`&`/`<<`/etc. operate on
+ * 32-bit ints, whereas the 48-bit pair used here, and even a 52-bit one,
+ * would need converting to `BigInt` for bitwise operations). 16 bits per
+ * symbol can't hold a full Unicode code point: the max scalar value `0x10FFFF`
+ * needs 21 bits, well past `0xFFFF`. So the bitwise-op convenience of 16 loses
+ * to the requirement of representing every Unicode code point in one half.
  */
 export type TerminalRange = number;
 /**
@@ -16,10 +31,6 @@ export declare const fullRange: TerminalRange;
  * Unicode scalar value range packed into a single {@link TerminalRange}.
  */
 export declare const unicodeRange: TerminalRange;
-/**
- * Maximal non-Unicode symbol encoded as a string value.
- */
-export declare const max: string;
 /**
  * Maximal Unicode code point encoded as a string value.
  */
@@ -48,7 +59,10 @@ export declare const rangeEncode: (a: number, b: number) => TerminalRange;
  */
 export declare const oneEncode: (a: number) => TerminalRange;
 /**
- * End-of-file marker represented as one code point beyond Unicode range.
+ * End-of-file marker: `mask`, the single largest value the 24-bit symbol
+ * space can hold (the top of `fullRange`). Deliberately outside Unicode
+ * (`unicodeRange` tops out at `0x10FFFF`) so it can never collide with a
+ * real code point.
  */
 export declare const eof: TerminalRange;
 /**