functionalscript 0.44.0 → 0.45.0

package/fjs/bnf/descent/proof.f.mjs

@@ -7,7 +7,7 @@
 
 import { stringToCodePointList } from '../../text/utf16/module.f.mjs'
 import { map, toArray } from '../../types/list/module.f.mjs'
-import { commaJoin0Plus, option, range, repeat0Plus, set } from '../module.f.mjs'
+import { commaJoin0Plus, eof, option, range, repeat0Plus, set } from '../module.f.mjs'
 import { emptyTagMap, toData } from '../data/module.f.mjs'
 import { descentParser } from './module.f.mjs'
 import { assertEq, assertNotNullish } from '../../asserts/module.f.mjs'
@@ -323,6 +323,82 @@ export const proof = {
             if (result !== `{"ast":{"sequence":[{"tag":"minus","sequence":[[${cp1('-')},"minus"]]},{"sequence":[[${cp1('2')},"two"]]}]},"success":true,"idx":2}`) { throw result }
         },
     ],
+    logicalEof: [
+        () => {
+            // The matcher synthesizes one EOF after the physical input, so the
+            // `eof` terminal matches empty input. It contributes no AST leaf,
+            // and the public index stays physical.
+            const m = descentParser(eof)
+            const mr = m('', [])
+            assertEq(JSON.stringify(mr), '{"ast":{"sequence":[]},"success":true,"idx":0}')
+        },
+        () => {
+            // Callers pass physical symbols only, so EOF is not available
+            // before the end of the input.
+            const m = descentParser(eof)
+            const mr = descentParserCpOnly(m, '', toArray(stringToCodePointList('A')))
+            assertEq(mr.success, false)
+            const f = assertNotNullish(mr.failure)
+            assertEq(f.idx, 0)
+            assertEq(f.expected.length, 1)
+            assertEq(f.expected[0], eof)
+        },
+        () => {
+            // Non-empty input: the terminal consumes the synthesized EOF after
+            // the last code point, and `idx` still reports `input.length`.
+            const m = descentParser([range('AA'), eof])
+            const cp = toArray(stringToCodePointList('A'))
+            const mr = descentParserCpOnly(m, '', cp)
+            assertEq(mr.success, true)
+            assertEq(mr.idx, cp.length)
+            assertEq(JSON.stringify(mr.ast), `{"sequence":[{"sequence":[[${cp1('A')},null]]},{"sequence":[]}]}`)
+        },
+        () => {
+            // Exactly one EOF is synthesized: a second `eof` terminal has
+            // nothing left to consume, and its failure points at `input.length`.
+            const m = descentParser([eof, eof])
+            const mr = m('', [])
+            assertEq(mr.success, false)
+            const f = assertNotNullish(mr.failure)
+            assertEq(f.idx, 0)
+            assertEq(f.expected.length, 1)
+            assertEq(f.expected[0], eof)
+        },
+        () => {
+            // EOF as one alternative among ordinary terminals.
+            const m = descentParser({ a: range('AA'), e: eof })
+            assertEq(JSON.stringify(m('', [])), '{"ast":{"tag":"e","sequence":[]},"success":true,"idx":0}')
+            const mr = descentParserCpOnly(m, '', toArray(stringToCodePointList('A')))
+            assertEq(mr.success, true)
+            assertEq(mr.idx, 1)
+        },
+        () => {
+            // Repetition terminates on EOF: consuming it moves the complete
+            // cursor, so the repeat makes exactly one round and then takes its
+            // empty branch — with `idx` alone this would never stop.
+            const m = descentParser(repeat0Plus(eof))
+            const mr = m('', [])
+            assertEq(JSON.stringify(mr), '{"ast":{"sequence":[{"sequence":[]},{"tag":"none","sequence":[]}]},"success":true,"idx":0}')
+        },
+        () => {
+            // Backtracking restores the complete cursor: `x` consumes EOF and
+            // then fails, so `y` must still find EOF available.
+            const m = descentParser({ x: [eof, range('AA')], y: eof })
+            assertEq(JSON.stringify(m('', [])), '{"ast":{"tag":"y","sequence":[]},"success":true,"idx":0}')
+        },
+        () => {
+            // Diagnostic ordering by the complete cursor: `y` got further than
+            // `x` — the same physical index, but past the EOF it consumed — so
+            // only its expectation is reported, and at the physical end.
+            const m = descentParser({ x: range('AA'), y: [eof, range('BB')] })
+            const mr = m('', [])
+            assertEq(mr.success, false)
+            const f = assertNotNullish(mr.failure)
+            assertEq(f.idx, 0)
+            assertEq(f.expected.length, 1)
+            assertEq(f.expected[0], range('BB'))
+        },
+    ],
     furthestFailure: [
         () => {
             // A branch rejected *before* the high-water mark must not pull it back:

package/fjs/bnf/descent/types.d.ts

@@ -7,9 +7,11 @@ import type { CodePoint } from '../../text/utf16/types.ts';
 import type { TerminalRange } from '../types.ts';
 export type AstTag = string | true | undefined;
 /**
- * Recursive descent matcher for a single named rule.
+ * Recursive descent matcher for a single named rule, starting from `startPos` —
+ * a position that counts the synthesized end-of-input symbol, unlike the public
+ * `idx` of the result.
  */
-export type DescentMatchRule<T> = (name: string, tag: AstTag, s: readonly CodePointMeta<T>[], idx: number) => DescentMatchResult<T>;
+export type DescentMatchRule<T> = (name: string, tag: AstTag, s: readonly CodePointMeta<T>[], startPos: number) => DescentMatchResult<T>;
 /**
  * Where a match ran out of road, for diagnostics.
  *
@@ -24,6 +26,11 @@ export type DescentMatchRule<T> = (name: string, tag: AstTag, s: readonly CodePo
  *
  * `idx` is `0` with an empty `expected` when the match failed without ever
  * rejecting a terminal, as an empty variant does.
+ *
+ * `idx` is physical, so a terminal rejected at — or past — the synthesized
+ * end-of-input symbol reports `input.length`. The high-water mark itself is
+ * kept on the complete cursor, so those two are still ordered against each
+ * other and their expected terminals do not merge.
  */
 export type DescentFailure = {
     readonly idx: number;
@@ -41,8 +48,9 @@ export type DescentFailure = {
  * On failure `idx` has rewound to the start of the enclosing sequence and
  * locates nothing; read `failure.idx` instead.
  *
- * The same type describes a match in progress, where `failure` is likewise
- * absent until the match ends.
+ * `idx` is physical — `0 <= idx <= input.length` — so a match that consumed the
+ * synthesized end-of-input symbol reports `input.length`, the same as one that
+ * stopped just before it.
  */
 export type DescentMatchResult<T> = {
     readonly ast: AstRuleMeta<T>;

package/fjs/bnf/ll1/module.f.d.mts

@@ -8,19 +8,24 @@
  * 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.
  *
+ * The caller passes physical symbols only; the matcher synthesizes the one
+ * logical EOF ({@link eofSymbol}) after them, so a grammar can dispatch on the
+ * end of input with the `eof` terminal.
+ *
  * See `./types.ts` for the type-level API.
  *
  * @module
  *
+ * @import { CodePoint } from '../../text/utf16/types.ts'
  * @import { Properties } from '../../types/range_map/types.ts'
  * @import { StringSet } from '../../types/string_set/types.ts'
  * @import { EmptyTag, RuleSet } from '../data/types.ts'
  * @import { Rule as FRule } from '../types.ts'
- * @import { AstSequence, AstTag, Match, MatchResult, MatchRule, Remainder, _Dispatch, _DispatchMap, _DispatchResult, _DispatchRule } from './types.ts'
+ * @import { AstSequence, AstTag, Match, MatchResult, Remainder, _AstRule, _Dispatch, _DispatchMap, _DispatchResult, _DispatchRule } from './types.ts'
  */
 import type { RuleSet } from '../data/types.ts';
 import type { Rule as FRule } from '../types.ts';
-import type { Match, _DispatchMap } from './types.ts';
+import type { AstSequence, AstTag, Match, _AstRule, _DispatchMap, _DispatchRule } from './types.ts';
 /**
  * Builds a dispatch map for a {@link RuleSet} to enable predictive parsing.
  *
@@ -33,6 +38,27 @@ export declare const dispatchMap: (ruleSet: RuleSet) => _DispatchMap;
  * @type {(fr: FRule) => Match}
  */
 export declare const parser: (fr: FRule) => Match;
+export type _Cursor = number;
+export type _Position = _Cursor | null;
+export type _Result = {
+    readonly ast: _AstRule;
+    readonly success: boolean;
+    readonly pos: _Position;
+};
+export type _Frame = {
+    readonly tag: AstTag;
+    readonly rules: readonly string[];
+    readonly ruleIndex: number;
+    readonly seq: AstSequence;
+};
+export type _Stack = null | {
+    readonly top: _Frame;
+    readonly rest: _Stack;
+};
+export type _Task = {
+    readonly rule: _DispatchRule;
+    readonly pos: _Cursor;
+};
 /**
  * Creates an LL(1) parser from an already materialized {@link RuleSet}.
  *

package/fjs/bnf/ll1/module.f.mjs

@@ -8,22 +8,27 @@
  * 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.
  *
+ * The caller passes physical symbols only; the matcher synthesizes the one
+ * logical EOF ({@link eofSymbol}) after them, so a grammar can dispatch on the
+ * end of input with the `eof` terminal.
+ *
  * See `./types.ts` for the type-level API.
  *
  * @module
  *
+ * @import { CodePoint } from '../../text/utf16/types.ts'
  * @import { Properties } from '../../types/range_map/types.ts'
  * @import { StringSet } from '../../types/string_set/types.ts'
  * @import { EmptyTag, RuleSet } from '../data/types.ts'
  * @import { Rule as FRule } from '../types.ts'
- * @import { AstSequence, AstTag, Match, MatchResult, MatchRule, Remainder, _Dispatch, _DispatchMap, _DispatchResult, _DispatchRule } from './types.ts'
+ * @import { AstSequence, AstTag, Match, MatchResult, Remainder, _AstRule, _Dispatch, _DispatchMap, _DispatchResult, _DispatchRule } from './types.ts'
  */
 
 import { strictEqual } from '../../types/function/operator/module.f.mjs'
 import { toArray } from '../../types/list/module.f.mjs'
 import { rangeMap } from '../../types/range_map/module.f.mjs'
 import { contains, set } from '../../types/string_set/module.f.mjs'
-import { rangeDecode } from '../module.f.mjs'
+import { eofSymbol, rangeDecode } from '../module.f.mjs'
 import { definedEntries } from '../../types/object/module.f.mjs'
 import { emptyTagMap, toData } from '../data/module.f.mjs'
 
@@ -145,13 +150,101 @@ export const parser = fr => {
     return parserRuleSet(data[0])
 }
 
-/** @type {(tag: AstTag, sequence: AstSequence, r: Remainder) => MatchResult} */
-const mrSuccess = (tag, sequence, r) =>
-    [{tag, sequence}, true, r]
+/**
+ * A match position over the physical input: `0 .. cp.length` are the physical
+ * positions, and `cp.length + 1` is where the one synthesized EOF has been
+ * consumed.
+ *
+ * This is the `(idx, eofConsumed)` cursor written as one number: `eofConsumed`
+ * can only be true at the physical end, so the pair and the extended position
+ * hold the same information.
+ *
+ * @typedef {number} _Cursor
+ */
+
+/**
+ * Where a match stopped: a {@link _Cursor}, or `null` when it ran out of input
+ * — the `null` {@link Remainder} this backend reports for that.
+ *
+ * @typedef {_Cursor|null} _Position
+ */
+
+/**
+ * The machine's own result: a {@link MatchResult} positioned by a cursor
+ * instead of by a materialized remainder.
+ *
+ * @typedef {{
+ *     readonly ast: _AstRule
+ *     readonly success: boolean
+ *     readonly pos: _Position
+ * }} _Result
+ */
+
+/**
+ * A suspended rules-chain match: `rules[ruleIndex]` is being matched by the
+ * current task, and `seq` holds the ASTs matched so far — starting with the
+ * dispatched symbol's leaf, empty when that symbol was the synthesized EOF.
+ *
+ * @typedef {{
+ *     readonly tag: AstTag
+ *     readonly rules: readonly string[]
+ *     readonly ruleIndex: number
+ *     readonly seq: AstSequence
+ * }} _Frame
+ */
+
+/**
+ * Immutable cons-cell stack: O(1) push/pop, no array copying per step.
+ *
+ * @typedef {null | {
+ *     readonly top: _Frame
+ *     readonly rest: _Stack
+ * }} _Stack
+ */
+
+/**
+ * The rule invocation about to be evaluated, or `null` when a result is ready
+ * to resume the innermost frame instead.
+ *
+ * @typedef {{
+ *     readonly rule: _DispatchRule
+ *     readonly pos: _Cursor
+ * }} _Task
+ */
+
+/** @type {(tag: AstTag, sequence: AstSequence, pos: _Position) => _Result} */
+const mrSuccess = (tag, sequence, pos) =>
+    ({ast: {tag, sequence}, success: true, pos})
 
-/** @type {(tag: AstTag, sequence: AstSequence, r: Remainder) => MatchResult} */
-const mrFail = (tag, sequence, r) =>
-    [{tag, sequence}, false, r]
+/** @type {(tag: AstTag, sequence: AstSequence, pos: _Position) => _Result} */
+const mrFail = (tag, sequence, pos) =>
+    ({ast: {tag, sequence}, success: false, pos})
+
+/**
+ * The semantic symbol a cursor points at: a code point inside the physical
+ * input, and the synthesized {@link eofSymbol} at its end. Only meaningful
+ * where the cursor still has a symbol, `pos <= cp.length`.
+ *
+ * @type {(cp: readonly CodePoint[], pos: _Cursor) => number}
+ */
+const symbolAt = (cp, pos) => pos < cp.length ? cp[pos] : eofSymbol
+
+/**
+ * What consuming the symbol at a cursor contributes to the AST: the code point
+ * itself, and nothing for the synthesized EOF — it has no physical source
+ * element.
+ *
+ * @type {(cp: readonly CodePoint[], pos: _Cursor) => AstSequence}
+ */
+const leafAt = (cp, pos) => pos < cp.length ? [cp[pos]] : []
+
+/**
+ * The public remainder of a position. It stays physical, so consuming EOF
+ * leaves it empty; the slice is materialized once, at the end of a match.
+ *
+ * @type {(cp: readonly CodePoint[], pos: _Position) => Remainder}
+ */
+const remainderAt = (cp, pos) => pos === null ? null : cp.slice(Math.min(pos, cp.length))
 
 /**
  * Creates an LL(1) parser from an already materialized {@link RuleSet}.
@@ -161,39 +254,88 @@ const mrFail = (tag, sequence, r) =>
 export const parserRuleSet = ruleSet => {
     const map = dispatchMap(ruleSet)
 
-    /** @type {MatchRule} */
-    const f = ({emptyTag, rangeMap}, cp) => {
-        if (cp.length === 0) {
-            return mrSuccess(emptyTag, [], emptyTag === undefined ? null : cp)
-        }
-        const [cp0] = cp
-        const dr = dispatchOp.get(rangeMap)(cp0)
-        if (dr === null) {
-            return emptyTag === undefined
-                ? mrFail(emptyTag, [], cp)
-                : mrSuccess(emptyTag, [], cp)
-        }
-        /** @type {AstSequence} */
-        let seq = [cp0]
-        const [, ...restCp] = cp
-        /** @type {readonly number[]} */
-        let r = restCp
-        const {tag, rules} = dr
-        for (const i of rules) {
-            const rule = typeof i === 'string' ? /** @type {_DispatchRule} */ (map[i]) : i
-            const res = f(rule, r)
-            const [astRule, success, newR] = res
-            if (success === false) {
-                return res
+    /** @type {(name: string) => _DispatchRule} */
+    const dispatched = name => /** @type {_DispatchRule} */ (map[name])
+
+    // The matcher as an explicit-stack machine: each iteration either starts the
+    // current task (dispatching one rule and pushing a frame for the rules chain
+    // that symbol selected) or feeds the pending result into the innermost frame.
+    // Semantics are identical to the former recursive matcher, but the JS call
+    // stack stays O(1) however deep the grammar recurses: a right-recursive rule
+    // (e.g. a `repeat0Plus` chain) descends once per consumed code point, so the
+    // depth used to grow with input length and overflow (see the longInput proof
+    // group). Positions are cursors into the shared input array for the same
+    // reason: re-slicing the remainder per step made a match quadratic.
+    /** @type {(dr0: _DispatchRule, cp: readonly CodePoint[]) => MatchResult} */
+    const f = (dr0, cp) => {
+        /** @type {_Stack} */
+        let stack = null
+        /** @type {_Task|null} */
+        let task = {rule: dr0, pos: 0}
+        /** @type {_Result} */
+        let result = mrFail(undefined, [], 0)
+
+        while (true) {
+            if (task !== null) {
+                // The explicit annotation cuts a control-flow inference cycle
+                // (TS7022): `task`'s narrowed type feeds `pos`, which feeds the
+                // `task` assignment below that the narrowing depends on.
+                /** @type {_Task} */
+                const current = task
+                const {rule: {emptyTag, rangeMap}, pos} = current
+                task = null
+                // The one logical EOF is available at the physical end, and only
+                // there: a rule that dispatches on it consumes it, once. Past it
+                // no symbol is left to dispatch on.
+                const dr = pos > cp.length ? null : dispatchOp.get(rangeMap)(symbolAt(cp, pos))
+                if (dr === null) {
+                    if (emptyTag !== undefined) {
+                        result = mrSuccess(emptyTag, [], pos)
+                    } else if (pos >= cp.length) {
+                        // Nothing left to reject: the match ran out of input.
+                        result = mrSuccess(emptyTag, [], null)
+                    } else {
+                        result = mrFail(emptyTag, [], pos)
+                    }
+                    continue
+                }
+                const {tag, rules} = dr
+                const seq = leafAt(cp, pos)
+                const next = pos + 1
+                if (rules.length === 0) {
+                    result = mrSuccess(tag, seq, next)
+                } else {
+                    stack = {top: {tag, rules, ruleIndex: 0, seq}, rest: stack}
+                    task = {rule: dispatched(rules[0]), pos: next}
+                }
+                continue
+            }
+
+            if (stack === null) {
+                const {ast, success, pos} = result
+                return [ast, success, remainderAt(cp, pos)]
+            }
+            const frame = stack.top
+            stack = stack.rest
+
+            const {ast, success, pos} = result
+            // A failing item's own result propagates unchanged, exactly as the
+            // recursive version returned it through the chain.
+            if (success === false) { continue }
+            const seq = [...frame.seq, ast]
+            if (pos === null) {
+                result = mrSuccess(frame.tag, seq, null)
+                continue
             }
-            seq = [...seq, astRule]
-            if (newR === null) {
-                return mrSuccess(tag, seq, null)
+            const ruleIndex = frame.ruleIndex + 1
+            if (ruleIndex < frame.rules.length) {
+                stack = {top: {...frame, ruleIndex, seq}, rest: stack}
+                task = {rule: dispatched(frame.rules[ruleIndex]), pos}
+            } else {
+                result = mrSuccess(frame.tag, seq, pos)
             }
-            r = newR
         }
-        return mrSuccess(tag, seq, r)
     }
 
-    return (name, cp) => f(/** @type {_DispatchRule} */ (map[name]), cp)
+    return (name, cp) => f(dispatched(name), cp)
 }

package/fjs/bnf/ll1/proof.f.d.mts

@@ -7,6 +7,8 @@
 export declare const proof: {
     dispatch: (() => void)[];
     parser: (() => void)[];
+    longInput: (() => void)[];
+    logicalEof: (() => void)[];
     repeat: (() => void)[];
     repeatParser: (() => void)[];
     throw: {

package/fjs/bnf/ll1/proof.f.mjs

@@ -7,7 +7,7 @@
 
 import { stringToCodePointList } from '../../text/utf16/module.f.mjs'
 import { toArray } from '../../types/list/module.f.mjs'
-import { commaJoin0Plus, option, range, repeat0Plus, set } from '../module.f.mjs'
+import { commaJoin0Plus, eof, option, range, repeat0Plus, set } from '../module.f.mjs'
 import { toData } from '../data/module.f.mjs'
 import { dispatchMap, parser, parserRuleSet } from './module.f.mjs'
 import { assertEq } from '../../asserts/module.f.mjs'
@@ -274,6 +274,67 @@ export const proof = {
             expect('   [{ "q": [ 12, false, [}], "a"] }]  ', false)
         }
     ],
+    longInput: [
+        () => {
+            // Long right-recursive repetition: one `repeat0Plus` chain across the
+            // whole input. This is the shape that overflowed the JS call stack
+            // when the matcher recursed once per consumed code point.
+            const m = parser(repeat0Plus(set(' \n\r\t')))
+            const [, success, remainder] = m('', toArray(stringToCodePointList(' '.repeat(10000))))
+            assertEq(success, true)
+            assertEq(remainder?.length, 0)
+        },
+        () => {
+            // Deep non-repetition nesting: 5000 bracket levels in the JSON-like
+            // test grammar — a shape a repetition-specific fix would not cover.
+            const m = parser(deterministic())
+            const n = 5000
+            const cp = toArray(stringToCodePointList('['.repeat(n) + ']'.repeat(n)))
+            const [, success, remainder] = m('', cp)
+            assertEq(success, true)
+            assertEq(remainder?.length, 0)
+        },
+    ],
+    logicalEof: [
+        () => {
+            // EOF dispatches below every ordinary symbol, so its cut point is
+            // `-2` — the stored endpoint codes never reach the dispatch map.
+            const dm = dispatchMap(toData(eof)[0])
+            assertEq(JSON.stringify(dm), '{"":{"rangeMap":[[null,-2],[{"rules":[]},-1]]}}')
+        },
+        () => {
+            // The matcher synthesizes one EOF after the physical input, so an
+            // `eof` terminal matches empty input. It adds no AST leaf, and the
+            // remainder stays physical: empty, not `null`.
+            const m = parser(eof)
+            assertEq(JSON.stringify(m('', [])), '[{"sequence":[]},true,[]]')
+        },
+        () => {
+            // Callers pass physical symbols only, so EOF is not available
+            // before the end of the input.
+            const m = parser(eof)
+            assertEq(JSON.stringify(m('', [65])), '[{"sequence":[]},false,[65]]')
+        },
+        () => {
+            // Non-empty input: the terminal consumes the synthesized EOF after
+            // the last code point.
+            const m = parser([range('AA'), eof])
+            assertEq(JSON.stringify(m('', [65])), '[{"sequence":[65,{"sequence":[]}]},true,[]]')
+        },
+        () => {
+            // Exactly one EOF is synthesized: the second `eof` terminal has
+            // nothing to consume, so the match runs out of input — the `null`
+            // remainder this backend reports for that.
+            const m = parser([eof, eof])
+            assertEq(JSON.stringify(m('', [])), '[{"sequence":[{"sequence":[]}]},true,null]')
+        },
+        () => {
+            // EOF as one alternative among ordinary terminals.
+            const m = parser({ a: range('AA'), e: eof })
+            assertEq(JSON.stringify(m('', [])), '[{"tag":"e","sequence":[]},true,[]]')
+            assertEq(JSON.stringify(m('', [65])), '[{"tag":"a","sequence":[65]},true,[]]')
+        },
+    ],
     repeat: [
         () => {
             /** @type {readonly [RuleSet, string]} */

package/fjs/bnf/ll1/types.d.ts

@@ -16,12 +16,16 @@ export type _DispatchRule = {
 export type _Dispatch = RangeMapArray<_DispatchResult>;
 /** @internal */
 export type _DispatchResult = _DispatchRuleCollection | null;
-/** @internal */
-export type _DispatchRuleOrName = _DispatchRule | string;
-/** @internal */
+/**
+ * The rules a dispatched symbol selects, to be matched one after another. They
+ * are names into the {@link _DispatchMap}: the builder only ever appends rule
+ * names, so the matcher resolves each one there.
+ *
+ * @internal
+ */
 export type _DispatchRuleCollection = {
     readonly tag: string | undefined;
-    readonly rules: _DispatchRuleOrName[];
+    readonly rules: readonly string[];
 };
 /** @internal */
 export type _DispatchMap = StringMap<_DispatchRule>;
@@ -41,6 +45,9 @@ export type AstSequence = readonly (_AstRule | CodePoint)[];
 export type AstTag = string | true | undefined;
 /**
  * Represents the remaining input after a match attempt, or `null` if no match is possible.
+ *
+ * The remainder is physical: consuming the synthesized end-of-input symbol
+ * leaves it empty rather than making it `null`.
  */
 export type Remainder = readonly CodePoint[] | null;
 /**
@@ -51,9 +58,8 @@ export type Remainder = readonly CodePoint[] | null;
 export type MatchResult = readonly [_AstRule, boolean, Remainder];
 /**
  * LL(1) parser function for matching by rule name.
+ *
+ * `s` holds physical symbols only; the matcher synthesizes the one logical
+ * end-of-input symbol after them.
  */
 export type Match = (name: string, s: readonly CodePoint[]) => MatchResult;
-/**
- * Internal match function signature used by compiled dispatch rules.
- */
-export type MatchRule = (dr: _DispatchRule, s: readonly CodePoint[]) => MatchResult;

package/fjs/bnf/module.f.d.mts

@@ -12,6 +12,14 @@
  */
 import type { Tuple } from '../types/array/types.ts';
 import type { TerminalRange, Sequence, Rule, RangeVariant, None, Option, Repeat0Plus, Repeat1Plus, Join1Plus, Repeat } from './types.ts';
+/**
+ * The logical end-of-input symbol.
+ *
+ * `-1` is outside the non-negative physical-symbol domain, so no alphabet
+ * adapter can produce it and no ordinary symbol has to be reserved for it.
+ * Parser backends synthesize it exactly once, after the physical input.
+ */
+export declare const eofSymbol = -1;
 /** @type {(a: number, b: number) => TerminalRange} */
 export declare const rangeEncode: (a: number, b: number) => TerminalRange;
 /**
@@ -21,16 +29,17 @@ export declare const rangeEncode: (a: number, b: number) => TerminalRange;
  */
 export declare const oneEncode: (a: number) => TerminalRange;
 /**
- * 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.
+ * End-of-file marker: the singleton range of {@link eofSymbol}. Deliberately
+ * outside the ordinary symbol domain — and so outside Unicode — so it can
+ * never collide with a real code point.
  *
  * @type {TerminalRange}
  */
 export declare const eof: TerminalRange;
 /**
- * Full 24-bit symbol range packed into a single {@link TerminalRange}.
+ * Every ordinary symbol packed into a single {@link TerminalRange}. EOF is not
+ * one of them, so complements over this range never include it.
+ *
  * @type {TerminalRange}
  */
 export declare const fullRange: TerminalRange;
@@ -44,7 +53,7 @@ export declare const unicodeRange: TerminalRange;
  */
 export declare const unicodeMax: string;
 /**
- * Decodes a packed range into `[start, end]` symbols.
+ * Decodes a packed range into `[start, end]` semantic symbols.
  *
  * @type {(r: number) => Tuple<2, number>}
  */