functionalscript 0.44.0 → 0.46.0

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

@@ -6,10 +6,9 @@
 
 import { identity } from '../../types/function/module.f.mjs'
 import { sort } from '../../types/object/module.f.mjs'
-import { oneEncode, option, range, rangeDecode, repeat0Plus, set } from '../module.f.mjs'
-import { emptyTagMap, toData } from './module.f.mjs'
+import { none, oneEncode, option, range, rangeDecode, repeat0Plus, set } from '../module.f.mjs'
+import { detectRepeat, emptyTagMap, isRepeat, toData } from './module.f.mjs'
 import { assertEq } from '../../asserts/module.f.mjs'
-
 import { stringify } from '../../media/json/module.f.mjs'
 import { classic, deterministic } from '../testlib.f.mjs'
 
@@ -89,11 +88,82 @@ export const proof = {
             if (result !== '[{"0":{"some":"1","none":"3"},"1":["2"],"2":1627390049,"3":[],"":["0","r"],"r":{"some":"","none":"3"}},"r"]') { throw result }
         },
         () => {
+            // The item is not nullable, so this one folds into a `repeat`, and
+            // the recursive and empty branches it replaced are pruned.
             const repeatRule = repeat0Plus(set(' \n\r\t'))
             const result = stringify(identity)(toData(repeatRule))
-            if (result !== '[{"0":{" ":"1","\\n":"2","\\r":"3","\\t":"4"},"1":536870944,"2":167772170,"3":218103821,"4":150994953,"5":[],"":["0","r"],"r":{"some":"","none":"5"}},"r"]') { throw result }
+            const expected = '[{"0":{" ":"1","\\n":"2","\\r":"3","\\t":"4"},"1":536870944,"2":167772170,"3":218103821,"4":150994953,"r":"0"},"r"]'
+            assertEq(result, expected, [result, expected])
         }
     ],
+    isRepeat: () => {
+        assertEq(isRepeat('a'), true)
+        // Nothing else in a rule set is a string, so the four rule kinds are
+        // told apart by JavaScript type alone — no shape has to be probed.
+        assertEq(isRepeat(['a', 'b']), false)
+        assertEq(isRepeat({ some: 'a' }), false)
+        assertEq(isRepeat(oneEncode(0x41)), false)
+    },
+    detectRepeat: [
+        () => {
+            const result = stringify(identity)(toData(repeat0Plus(range('AF'))))
+            const expected = '[{"0":1090519110,"r":"0"},"r"]'
+            assertEq(result, expected, [result, expected])
+        },
+        () => {
+            // Nothing about the fold depends on `repeat0Plus`: a hand-written
+            // 0-or-more list is the same shape and folds the same way. `classic`
+            // spells one out as `characters`.
+            const [ruleSet] = toData(classic())
+            const repeats = Object.entries(ruleSet).filter(([, v]) => isRepeat(v))
+            assertEq(JSON.stringify(repeats), '[["characters","character"]]')
+        },
+        () => {
+            // Already folded: a `repeat` is not itself a variant to fold again.
+            const [ruleSet, entry] = toData(repeat0Plus(range('AF')))
+            assertEq(
+                stringify(identity)(detectRepeat(ruleSet, entry)),
+                stringify(identity)(ruleSet))
+        },
+        () => {
+            // 1-or-more: the base branch is the item, not the empty rule.
+            const digit = range('09')
+            const digits = () => ({ digit, digits: [digit, digits] })
+            const result = stringify(identity)(toData(digits))
+            const expected = '[{"0":["","digits"],"":805306425,"digits":{"digit":"","digits":"0"}},"digits"]'
+            assertEq(result, expected, [result, expected])
+        },
+        () => {
+            // A separated list repeats `[item, separator, self]`; which of the
+            // three items are the list's elements is not something the shape
+            // says, so it stays a variant.
+            const sep = () => ({ none, list: [range('09'), ',', sep] })
+            const result = stringify(identity)(toData(sep))
+            const expected = '[{"0":["1","2","sep"],"1":805306425,"2":["3"],"3":738197548,"":[],"sep":{"none":"","list":"0"}},"sep"]'
+            assertEq(result, expected, [result, expected])
+        },
+        () => {
+            // The tail is not the rule's only self-reference: the item leads back
+            // into it, so the recursion is a tree rather than a list.
+            const nested = () => ({ none, some: [inner, nested] })
+            const inner = () => ({ leaf: range('AA'), group: ['(', nested, ')'] })
+            const [ruleSet] = toData(nested)
+            assertEq(JSON.stringify(ruleSet.nested), '{"none":"","some":"0"}')
+        },
+        () => {
+            // A nullable item gives the same input infinitely many parses, so
+            // the repetition is not the unambiguous one this fold is limited to.
+            const [ruleSet, entry] = toData(repeat0Plus(option('a')))
+            assertEq(JSON.stringify(ruleSet[entry]), '{"some":"","none":"3"}')
+        },
+        () => {
+            // Two branches, an empty one and a terminal: the non-empty branch is
+            // not a sequence at all.
+            const result = stringify(identity)(toData({ e: '', a: range('AA') }))
+            const expected = '[{"0":[],"1":1090519105,"":{"e":"0","a":"1"}},""]'
+            assertEq(result, expected, [result, expected])
+        },
+    ],
     variantTest: () => {
         const varintRule = { a: 'a', b: 'b'}
         const result = stringify(sort)(toData(varintRule))

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

@@ -16,15 +16,33 @@ export type TerminalRange = number;
 export type Sequence = readonly string[];
 /** A variant of rule names. */
 export type Variant = StringMap<string>;
+/**
+ * Zero or more repetitions of the named rule.
+ *
+ * The functional grammar has no repetition primitive — `repeat0Plus(x)` expands
+ * to a right-recursive variant — so this is the one rule kind `toData` derives
+ * rather than transcribes: it recognizes the unambiguous 0-or-more shape and
+ * emits this instead, which is what lets a parser backend match the body
+ * iteratively and produce one flat node for the whole repetition.
+ *
+ * A bare rule name keeps the four rule kinds disjoint by JavaScript type alone:
+ * a number is a {@link TerminalRange}, an array a {@link Sequence}, an object a
+ * {@link Variant}, and a string this. Nothing else in a {@link RuleSet} is a
+ * string, so no shape has to be probed to tell one kind from another. (The
+ * *functional* `DataRule` does have a string case — a Unicode literal — but
+ * that one never reaches here: `toData` expands it to terminals.)
+ */
+export type Repeat = string;
 /**
  * Grammar rule definition.
  *
  * It can be one of:
  * - a tagged variant map,
  * - a sequence of referenced rule names,
- * - an encoded terminal range.
+ * - an encoded terminal range,
+ * - the name of a rule to repeat zero or more times.
  */
-export type Rule = Variant | Sequence | TerminalRange;
+export type Rule = Variant | Sequence | TerminalRange | Repeat;
 /** The full grammar */
 export type RuleSet = Readonly<Record<string, Rule>>;
 /**

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

@@ -4,24 +4,53 @@
  * 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`.
+ * AST over leaves that carry it — `Ast<CodePointMeta<T>>`, built with the
+ * shared layer in `fjs/bnf/matcher`. Nullability (which rule can match empty
+ * input) is computed once by {@link emptyTagMap} in `fjs/bnf/data`.
+ *
+ * The caller passes physical symbols only; the matcher synthesizes the one
+ * logical EOF after them, so a grammar can require the end of input with the
+ * `eof` terminal.
  *
  * A failed result also carries a {@link DescentFailure}: the furthest position a
  * terminal was rejected at, which — unlike the result's own index — never
  * rewinds and is what diagnostics should be built from.
  *
+ * A `Repeat` rule is matched iteratively rather than by descending into itself
+ * once per item, so a repetition produces one AST node holding a flat sequence
+ * of the items it matched instead of the right-recursive chain its functional
+ * spelling would otherwise build.
+ *
  * See `./types.ts` for the type-level API.
  *
  * @module
  *
  * @import { TerminalRange } from '../types.ts'
- * @import { Rule as DataRule, Sequence } from '../data/types.ts'
+ * @import { Rule as DataRule, RuleSet, Sequence } from '../data/types.ts'
  * @import { Rule as FRule } from '../types.ts'
- * @import { AstTag, AstSequenceMeta, DescentFailure, DescentMatch, DescentMatchResult, DescentMatchRule } from './types.ts'
+ * @import { List } from '../../types/list/types.ts'
+ * @import { Ast, AstResult, AstSequence, AstTag, Cursor } from '../matcher/types.ts'
+ * @import { CodePointMeta, DescentFailure, DescentMatch, DescentMatchResult, DescentMatchRule } from './types.ts'
  */
+import type { TerminalRange } from '../types.ts';
+import type { RuleSet } from '../data/types.ts';
 import type { Rule as FRule } from '../types.ts';
-import type { DescentMatch } from './types.ts';
+import type { AstResult, Cursor } from '../matcher/types.ts';
+import type { CodePointMeta, DescentMatch } from './types.ts';
+export type _Failure = {
+    readonly pos: Cursor;
+    readonly expected: readonly TerminalRange[];
+};
+export type _Result<T> = AstResult<CodePointMeta<T>, Cursor>;
+/**
+ * Creates a recursive descent parser from an already materialized
+ * {@link RuleSet}, preserving metadata for each consumed code point.
+ *
+ * @template T
+ * @param {RuleSet} ruleSet
+ * @returns {DescentMatch<T>}
+ */
+export declare const descentParserRuleSet: <T>(ruleSet: RuleSet) => DescentMatch<T>;
 /**
  * Creates a recursive descent parser that preserves metadata for each consumed
  * code point.

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

@@ -4,52 +4,97 @@
  * 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`.
+ * AST over leaves that carry it — `Ast<CodePointMeta<T>>`, built with the
+ * shared layer in `fjs/bnf/matcher`. Nullability (which rule can match empty
+ * input) is computed once by {@link emptyTagMap} in `fjs/bnf/data`.
+ *
+ * The caller passes physical symbols only; the matcher synthesizes the one
+ * logical EOF after them, so a grammar can require the end of input with the
+ * `eof` terminal.
  *
  * A failed result also carries a {@link DescentFailure}: the furthest position a
  * terminal was rejected at, which — unlike the result's own index — never
  * rewinds and is what diagnostics should be built from.
  *
+ * A `Repeat` rule is matched iteratively rather than by descending into itself
+ * once per item, so a repetition produces one AST node holding a flat sequence
+ * of the items it matched instead of the right-recursive chain its functional
+ * spelling would otherwise build.
+ *
  * See `./types.ts` for the type-level API.
  *
  * @module
  *
  * @import { TerminalRange } from '../types.ts'
- * @import { Rule as DataRule, Sequence } from '../data/types.ts'
+ * @import { Rule as DataRule, RuleSet, Sequence } from '../data/types.ts'
  * @import { Rule as FRule } from '../types.ts'
- * @import { AstTag, AstSequenceMeta, DescentFailure, DescentMatch, DescentMatchResult, DescentMatchRule } from './types.ts'
+ * @import { List } from '../../types/list/types.ts'
+ * @import { Ast, AstResult, AstSequence, AstTag, Cursor } from '../matcher/types.ts'
+ * @import { CodePointMeta, DescentFailure, DescentMatch, DescentMatchResult, DescentMatchRule } from './types.ts'
  */
 
 import { rangeDecode } from '../module.f.mjs'
 import { contains as rangeContains } from '../../types/range/module.f.mjs'
+import { concat, toArray } from '../../types/list/module.f.mjs'
 import { definedEntries } from '../../types/object/module.f.mjs'
-import { emptyTagMap, toData } from '../data/module.f.mjs'
+import { emptyTagMap, isRepeat, toData } from '../data/module.f.mjs'
+import { leafAt, mrFail, mrSuccess, physicalIdx, symbolAt } from '../matcher/module.f.mjs'
+
+/**
+ * The furthest-failure record while matching, positioned by the complete
+ * {@link Cursor}. {@link DescentFailure} is its public, physically-positioned
+ * form.
+ *
+ * @typedef {{
+ *     readonly pos: Cursor
+ *     readonly expected: readonly TerminalRange[]
+ * }} _Failure
+ */
+
+/**
+ * The machine's own result: a {@link DescentMatchResult} positioned by the
+ * complete cursor, and with no failure record — that one is tracked per match
+ * rather than per frame. This backend always has a position, so it needs no
+ * `null` case.
+ *
+ * @template T
+ * @typedef {AstResult<CodePointMeta<T>, Cursor>} _Result
+ */
+
+/**
+ * A leaf here is a code point with its metadata, so its symbol is the first
+ * half. This is the only thing {@link symbolAt} needs to know about a leaf.
+ *
+ * @type {<T>(leaf: CodePointMeta<T>) => number}
+ */
+const symbolOf = ([symbol]) => symbol
+
+const symbolAtCp = symbolAt(symbolOf)
 
 /**
  * Folds one rejected terminal into the furthest-failure record: further along
- * replaces, the same position accumulates (ignoring repeats), earlier is
- * discarded.
+ * replaces, the same cursor accumulates (ignoring repeats), earlier is
+ * discarded. The comparison is on the complete cursor, so a failure after EOF
+ * was consumed is further than one at the same physical index before it.
  *
- * @type {(failure: DescentFailure, idx: number, terminal: TerminalRange) => DescentFailure}
+ * @type {(failure: _Failure, pos: Cursor, terminal: TerminalRange) => _Failure}
  */
-const recordFailure = (failure, idx, terminal) => {
-    if (idx > failure.idx) { return { idx, expected: [terminal] } }
-    if (idx < failure.idx || failure.expected.includes(terminal)) { return failure }
-    return { idx, expected: [...failure.expected, terminal] }
+const recordFailure = (failure, pos, terminal) => {
+    if (pos > failure.pos) { return { pos, expected: [terminal] } }
+    if (pos < failure.pos || failure.expected.includes(terminal)) { return failure }
+    return { pos, expected: [...failure.expected, terminal] }
 }
 
 /**
- * Creates a recursive descent parser that preserves metadata for each consumed
- * code point.
+ * Creates a recursive descent parser from an already materialized
+ * {@link RuleSet}, preserving metadata for each consumed code point.
  *
  * @template T
- * @param {FRule} fr
+ * @param {RuleSet} ruleSet
  * @returns {DescentMatch<T>}
  */
-export const descentParser = fr => {
-    const data = toData(fr)
-    const emptyTags = emptyTagMap(data[0])
+export const descentParserRuleSet = ruleSet => {
+    const emptyTags = emptyTagMap(ruleSet)
 
     // A suspended sequence match: items[itemIndex] is being matched by the current
     // task; `seq` holds the ASTs of the items already matched.
@@ -59,8 +104,8 @@ export const descentParser = fr => {
      *     readonly tag: AstTag
      *     readonly items: Sequence
      *     readonly itemIndex: number
-     *     readonly startIdx: number
-     *     readonly seq: AstSequenceMeta<T>
+     *     readonly startPos: Cursor
+     *     readonly seq: AstSequence<CodePointMeta<T>>
      * }} _SeqFrame
      */
 
@@ -72,12 +117,30 @@ export const descentParser = fr => {
      *     readonly kind: 'variant'
      *     readonly entries: readonly (readonly [string, string])[]
      *     readonly entryIndex: number
-     *     readonly idx: number
-     *     readonly emptyResult: DescentMatchResult<T>
+     *     readonly pos: Cursor
+     *     readonly emptyResult: _Result<T>
      * }} _VariantFrame
      */
 
-    /** @typedef {_SeqFrame | _VariantFrame} _Frame */
+    // A suspended repetition: `item` is being matched by the current task for the
+    // round that began at `roundStart`, and `items` holds the ASTs of the rounds
+    // that already completed. They accumulate as a list rather than an array
+    // because a repetition is as long as its input: appending to an array per
+    // round would copy the whole prefix each time and make one repetition
+    // quadratic in the number of items it matched.
+    /**
+     * @typedef {{
+     *     readonly kind: 'repeat'
+     *     readonly tag: AstTag
+     *     readonly item: string
+     *     readonly items: _Items
+     *     readonly roundStart: Cursor
+     * }} _RepeatFrame
+     */
+
+    /** @typedef {List<Ast<CodePointMeta<T>>>} _Items */
+
+    /** @typedef {_SeqFrame | _VariantFrame | _RepeatFrame} _Frame */
 
     // Immutable cons-cell stack: O(1) push/pop, no array copying per step.
     /**
@@ -91,12 +154,28 @@ export const descentParser = fr => {
     // tuple), or null when a result is ready to resume the innermost frame.
     /**
      * @typedef {{
+     *     readonly kind: 'rule'
      *     readonly name: string
      *     readonly tag: AstTag
-     *     readonly idx: number
-     * }} _Task
+     *     readonly pos: Cursor
+     * }} _RuleTask
      */
 
+    // The next round of a repetition, about to be started. Both the rule that
+    // introduces a repetition and the frame that finishes one of its rounds go
+    // through this, so a round is set up in exactly one place.
+    /**
+     * @typedef {{
+     *     readonly kind: 'repeat'
+     *     readonly tag: AstTag
+     *     readonly item: string
+     *     readonly items: _Items
+     *     readonly pos: Cursor
+     * }} _RepeatTask
+     */
+
+    /** @typedef {_RuleTask | _RepeatTask} _Task */
+
     // 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
@@ -104,97 +183,130 @@ export const descentParser = fr => {
     // grammar recursion depth — right-recursive rules (e.g. repeat0Plus chains) no longer
     // overflow on long input (see the longInput proof group).
     /** @type {DescentMatchRule<T>} */
-    const f = (name, tag, cp, idx) => {
-        /** @type {(tag: AstTag, sequence: AstSequenceMeta<T>, idx: number) => DescentMatchResult<T>} */
-        const mrSuccess = (tag, sequence, idx) => ({ ast: {tag, sequence}, success: true, idx })
-        /** @type {(tag: AstTag, sequence: AstSequenceMeta<T>, idx: number) => DescentMatchResult<T>} */
-        const mrFail = (tag, sequence, idx) => ({ ast: {tag, sequence}, success: false, idx })
+    const f = (name, tag, cp, startPos) => {
+        const physical = physicalIdx(cp.length)
 
         /** @type {_Stack} */
         let stack = null
         /** @type {_Task | null} */
-        let task = { name, tag, idx }
-        /** @type {DescentMatchResult<T>} */
-        let result = mrFail(undefined, [], idx)
+        let task = { kind: 'rule', name, tag, pos: startPos }
+        /** @type {_Result<T>} */
+        let result = mrFail(undefined, [], startPos)
         // High-water mark across the whole match, so it survives the rewinds a
         // failing sequence item does to `result`.
-        /** @type {DescentFailure} */
-        let furthest = { idx: 0, expected: [] }
+        /** @type {_Failure} */
+        let furthest = { pos: 0, expected: [] }
 
         while (true) {
             if (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 { name, tag, idx } = /** @type {_Task} */ (task)
+                const current = /** @type {_Task} */ (task)
                 task = null
+                if (current.kind === 'repeat') {
+                    // One round of a repetition is one match of its item, so the
+                    // frame below carries the rounds already collected and the
+                    // position this round may have to rewind to.
+                    stack = { top: { kind: 'repeat', tag: current.tag, item: current.item, items: current.items, roundStart: current.pos }, rest: stack }
+                    task = { kind: 'rule', name: current.item, tag: undefined, pos: current.pos }
+                    continue
+                }
+                const { name, tag, pos } = current
                 /** @type {DataRule} */
-                const rule = data[0][name]
+                const rule = ruleSet[name]
                 if (typeof rule === 'number') {
                     // No nullable case: `emptyTagOf` in `bnf/data` returns `undefined`
                     // for every terminal, so `emptyTags[name]` here is always
                     // `undefined` and a terminal either consumes one symbol or fails.
-                    if (idx < cp.length && rangeContains(...rangeDecode(rule))(cp[idx][0])) {
-                        result = mrSuccess(tag, [cp[idx]], idx + 1)
+                    // Past the synthesized EOF there is no symbol left to consume.
+                    if (pos <= cp.length && rangeContains(...rangeDecode(rule))(symbolAtCp(cp, pos))) {
+                        result = mrSuccess(tag, leafAt(cp, pos), pos + 1)
                     } else {
                         // The only place a terminal is rejected, so the only place
                         // the furthest failure can advance.
-                        furthest = recordFailure(furthest, idx, rule)
-                        result = mrFail(undefined, [], idx)
+                        furthest = recordFailure(furthest, pos, rule)
+                        result = mrFail(undefined, [], pos)
                     }
                 } else if (rule instanceof Array) {
                     if (rule.length === 0) {
-                        result = mrSuccess(tag, [], idx)
+                        result = mrSuccess(tag, [], pos)
                     } else {
-                        stack = { top: { kind: 'seq', tag, items: rule, itemIndex: 0, startIdx: idx, seq: [] }, rest: stack }
-                        task = { name: rule[0], tag: undefined, idx }
+                        stack = { top: { kind: 'seq', tag, items: rule, itemIndex: 0, startPos: pos, seq: [] }, rest: stack }
+                        task = { kind: 'rule', name: rule[0], tag: undefined, pos }
                     }
+                } else if (isRepeat(rule)) {
+                    task = { kind: 'repeat', tag, item: rule, items: null, pos }
                 } else {
                     const entries = definedEntries(rule)
                     const emptyTag = emptyTags[name]
-                    const emptyResult = mrFail(emptyTag, [], idx)
+                    const emptyResult = mrFail(emptyTag, [], pos)
                     if (entries.length === 0) {
                         result = emptyResult
                     } else {
-                        stack = { top: { kind: 'variant', entries, entryIndex: 0, idx, emptyResult }, rest: stack }
+                        stack = { top: { kind: 'variant', entries, entryIndex: 0, pos, emptyResult }, rest: stack }
                         const [entryTag, entryName] = entries[0]
-                        task = { name: entryName, tag: entryTag, idx }
+                        task = { kind: 'rule', name: entryName, tag: entryTag, pos }
                     }
                 }
                 continue
             }
 
             if (stack === null) {
+                const { ast, success, pos } = result
+                /** @type {DescentMatchResult<T>} */
+                const mr = { ast, success, idx: physical(pos) }
                 // A success has nothing to diagnose; only a failure carries it.
-                return result.success ? result : { ...result, failure: furthest }
+                return success
+                    ? mr
+                    : { ...mr, failure: { idx: physical(furthest.pos), expected: furthest.expected } }
             }
             const frame = stack.top
             stack = stack.rest
 
             if (frame.kind === 'seq') {
-                const { ast: astRule, success, idx: nidx } = result
+                const { ast: astRule, success, pos } = result
                 if (success === false) {
-                    result = mrFail(frame.tag, [], frame.startIdx)
+                    result = mrFail(frame.tag, [], frame.startPos)
                 } 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 }
+                        task = { kind: 'rule', name: frame.items[itemIndex], tag: undefined, pos }
+                    } else {
+                        result = mrSuccess(frame.tag, seq, pos)
+                    }
+                }
+            } else if (frame.kind === 'repeat') {
+                if (result.success === false) {
+                    // A round that fails ends the repetition instead of failing
+                    // it: the rounds before it stand, and the whole match rewinds
+                    // to where the failed round began.
+                    result = mrSuccess(frame.tag, toArray(frame.items), frame.roundStart)
+                } else {
+                    const items = concat(frame.items)([result.ast])
+                    if (result.pos === frame.roundStart) {
+                        // A round that consumed nothing would repeat forever. Only
+                        // a hand-written `repeat` over a nullable rule reaches
+                        // this — `toData` never derives one — so keep the one
+                        // empty round and stop.
+                        result = mrSuccess(frame.tag, toArray(items), result.pos)
                     } else {
-                        result = mrSuccess(frame.tag, seq, nidx)
+                        task = { kind: 'repeat', tag: frame.tag, item: frame.item, items, pos: result.pos }
                     }
                 }
             } 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.success && frame.idx !== result.idx)) {
+                // Consuming EOF counts as consumption, because the cursor moved.
+                if (!(result.success && frame.pos !== result.pos)) {
                     const emptyResult = result.success ? 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 }
+                        task = { kind: 'rule', name: entryName, tag: entryTag, pos: frame.pos }
                     } else {
                         result = emptyResult
                     }
@@ -210,3 +322,13 @@ export const descentParser = fr => {
 
     return match
 }
+
+/**
+ * Creates a recursive descent parser that preserves metadata for each consumed
+ * code point.
+ *
+ * @template T
+ * @param {FRule} fr
+ * @returns {DescentMatch<T>}
+ */
+export const descentParser = fr => descentParserRuleSet(toData(fr)[0])

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

@@ -2,6 +2,7 @@
  * @module
  *
  * @import { CodePoint } from '../../text/utf16/types.ts'
+ * @import { RuleSet } from '../data/types.ts'
  * @import { DescentMatch, CodePointMeta, DescentMatchResult } from './types.ts'
  */
 export declare const proof: {
@@ -9,5 +10,7 @@ export declare const proof: {
     descentParser: (() => void)[];
     longInput: (() => void)[];
     descentParserWithMeta: (() => void)[];
+    logicalEof: (() => void)[];
+    repeat: (() => void)[];
     furthestFailure: (() => void)[];
 };