functionalscript 0.45.0 → 0.46.1

package/README.md

@@ -5,13 +5,15 @@
 FunctionalScript is a safe, purely functional programming language and a strict subset of
 [ECMAScript](https://en.wikipedia.org/wiki/ECMAScript)/[JavaScript](https://en.wikipedia.org/wiki/JavaScript). It's inspired by
 
-- [JSON](https://en.wikipedia.org/wiki/JSON) and [JSON5](https://json5.org/) as subsets of JavaScript.
-  JSON is also a subset of FunctionalScript.
+- [JSON](https://en.wikipedia.org/wiki/JSON) and [JSON5](https://json5.org/) as subsets of JavaScript values.
+  JSON is also a subset of FunctionalScript values.
 - [asm.JS](https://en.wikipedia.org/wiki/Asm.js) (a precursor of [WebAssembly](https://en.wikipedia.org/wiki/WebAssembly)),
   as a subset of JavaScript.
 - [TypeScript](https://en.wikipedia.org/wiki/TypeScript), as a superset of JavaScript.
 
-[A working draft of the FunctionalScript specification](./todo/lang/README.md).
+[The FunctionalScript specification](./spec/README.md) describes the language
+the compiler accepts today; features not implemented yet are in
+[`spec/todo/`](./spec/todo/README.md).
 
 Learn more about
 

package/fjs/asn.1/module.f.mjs

@@ -19,6 +19,7 @@ import {
     vec,
     vec8,
 } from '../types/bit_vec/module.f.mjs'
+import { assert } from '../asserts/module.f.mjs'
 import { identity } from '../types/function/module.f.mjs'
 import { max } from '../types/function/compare/module.f.mjs'
 import { encode as b128encode, decode as b128decode } from '../basen/base128/module.f.mjs'
@@ -65,7 +66,13 @@ const parsedTagEncode = ([classPc, number]) => {
 /** @type {(v: Vec) => readonly[_ParsedTag, Vec]} */
 const parsedTagDecode = v => {
     const [firstByte, rest] = pop8(v)
-    const classPc = /** @type {_ClassPc} */(firstByte & classPcMask)
+    const classPc = firstByte & classPcMask
+    // `classPcMask` is the top three bits, so the result is one of eight values;
+    // the assert is what narrows `bigint` to `_ClassPc`.
+    assert(classPc === 0b000_00000n || classPc === 0b001_00000n
+        || classPc === 0b010_00000n || classPc === 0b011_00000n
+        || classPc === 0b100_00000n || classPc === 0b101_00000n
+        || classPc === 0b110_00000n || classPc === 0b111_00000n, classPc)
     const firstByteNumber = firstByte & tagNumberMask
     const [number, rest1] = firstByteNumber < tagNumberMask
         ? [firstByteNumber, rest]

package/fjs/asn.1/proof.f.d.mts

@@ -49,5 +49,15 @@ export declare const proof: {
         withArc: () => void;
     };
     unknownTag: () => void;
+    tagClass: {
+        universalPrimitive: () => void;
+        universalConstructed: () => void;
+        applicationPrimitive: () => void;
+        applicationConstructed: () => void;
+        contextPrimitive: () => void;
+        contextConstructed: () => void;
+        privatePrimitive: () => void;
+        privateConstructed: () => void;
+    };
     raw: (() => void)[];
 };

package/fjs/asn.1/proof.f.mjs

@@ -296,6 +296,22 @@ export const proof = {
         // Re-encoding an UnsupportedRecord returns it unchanged (it is already the TLV bytes)
         assertEq(encode(decoded), raw, 'encode should round-trip UnsupportedRecord')
     },
+    // parsedTagDecode narrows the top three bits of the tag's first byte
+    // (class + primitive/constructed) to one of exactly eight values via an
+    // 8-way `||` assert. Every other test in this file only ever exercises
+    // the universal-primitive tag (top bits 000), so each of the other seven
+    // comparisons has never had a case where it's the one that turns the
+    // assert true — one round trip per class×P/C combination covers them all.
+    tagClass: {
+        universalPrimitive: () => check(0x02n, vec8(0x42n), empty),
+        universalConstructed: () => check(0x22n, vec8(0x42n), empty),
+        applicationPrimitive: () => check(0x42n, vec8(0x42n), empty),
+        applicationConstructed: () => check(0x62n, vec8(0x42n), empty),
+        contextPrimitive: () => check(0x82n, vec8(0x42n), empty),
+        contextConstructed: () => check(0xA2n, vec8(0x42n), empty),
+        privatePrimitive: () => check(0xC2n, vec8(0x42n), empty),
+        privateConstructed: () => check(0xE2n, vec8(0x42n), empty),
+    },
     raw: [
         () => {
             const e = encodeRaw([0x00n, vec8(0x23n)])

package/fjs/basen/base128/module.f.mjs

@@ -6,12 +6,27 @@
  * @import { Vec } from '../../types/bit_vec/types.ts'
  */
 
+import { mask } from '../../types/bigint/module.f.mjs'
 import { vec8, msb, empty } from '../../types/bit_vec/module.f.mjs'
 
 const { concat, popFront } = msb
 
 const pop8 = popFront(8n)
 
+/**
+ * The varint layout both halves below agree on, stated once: each byte carries
+ * seven payload bits in its low end, and its top bit is set on every byte
+ * except the last.
+ *
+ * `encode` and `decode` are exact inverses, so the two must agree bit for bit.
+ * The masks are derived from `payloadBits` rather than written as `0x7f` and
+ * `0x80` so that agreement is structural rather than a pair of literals a
+ * reader has to match up.
+ */
+const payloadBits = 7n
+const payloadMask = mask(payloadBits)
+const continuationFlag = 1n << payloadBits
+
 /**
  * Encodes a bigint into an MSB Base128 vector.
  *
@@ -22,10 +37,12 @@ export const encode = uint => {
     /** @type {Vec} */
     let result = empty
     while (true) {
-        const item = uint & 0x7Fn
-        const flag = result === empty ? 0n : 0x80n
+        const item = uint & payloadMask
+        // The first byte built is the last one emitted, so it is the only one
+        // without the continuation flag.
+        const flag = result === empty ? 0n : continuationFlag
         result = concat(vec8(flag | item))(result)
-        uint >>= 7n
+        uint >>= payloadBits
         if (uint === 0n) {
             return result
         }
@@ -42,8 +59,8 @@ export const decode = v => {
     let result = 0n
     while (true) {
         const [byte, rest] = pop8(v)
-        result = (result << 7n) | (byte & 0x7Fn)
-        if (byte < 0x80n) {
+        result = (result << payloadBits) | (byte & payloadMask)
+        if ((byte & continuationFlag) === 0n) {
             return [result, rest]
         }
         v = rest

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

@@ -3,10 +3,11 @@
  * {@link toData} conversion from the functional grammar.
  *
  * This module is the pure, parser-agnostic substrate: it defines the
- * {@link RuleSet} data form (`Rule = Variant | Sequence | TerminalRange`) and
- * converts a functional grammar into it. The automaton builders that consume a
- * {@link RuleSet} live in their own sibling modules (`fjs/bnf/ll1`,
- * `fjs/bnf/descent`, …), so the IR stays free of any one parser's machinery.
+ * {@link RuleSet} data form (`Rule = Variant | Sequence | TerminalRange |
+ * Repeat`) and converts a functional grammar into it. The automaton builders
+ * that consume a {@link RuleSet} live in their own sibling modules
+ * (`fjs/bnf/ll1`, `fjs/bnf/descent`, …), so the IR stays free of any one
+ * parser's machinery.
  *
  * See `./types.ts` for the type-level API.
  *
@@ -14,11 +15,23 @@
  *
  * @import { DataRule, Rule as FRule, Sequence as FSequence } from '../types.ts'
  * @import { StringMap } from '../../types/object/types.ts'
- * @import { EmptyTag, Rule, RuleSet, Sequence, Variant } from './types.ts'
+ * @import { StringSet } from '../../types/string_set/types.ts'
+ * @import { EmptyTag, Repeat, Rule, RuleSet, Sequence, Variant } from './types.ts'
  */
 import type { Rule as FRule } from '../types.ts';
 import type { StringMap } from '../../types/object/types.ts';
-import type { EmptyTag, Rule, RuleSet } from './types.ts';
+import type { EmptyTag, Repeat, Rule, RuleSet } from './types.ts';
+/**
+ * Whether a data rule is a {@link Repeat}.
+ *
+ * Every rule-dispatch site asks this instead of testing for a string inline, so
+ * the repetition rule kind has exactly one discriminator to move when the
+ * surrounding rule model changes.
+ *
+ * @param {Rule} rule
+ * @returns {rule is Repeat}
+ */
+export declare const isRepeat: (rule: Rule) => rule is Repeat;
 export type _EmptyTagMap = StringMap<EmptyTag>;
 /**
  * Computes, for every rule in the set, whether it can match empty input, by
@@ -38,6 +51,19 @@ export type _EmptyTagMap = StringMap<EmptyTag>;
 export declare const emptyTagMap: (ruleSet: RuleSet) => _EmptyTagMap;
 export type _FRuleMap = StringMap<FRule>;
 export type _NewRule = (m: _FRuleMap) => readonly [_FRuleMap, RuleSet, Rule];
+/**
+ * Rewrites every right-recursive 0-or-more rule of a {@link RuleSet} into a
+ * {@link Repeat}, and drops the rules that the rewrite orphans.
+ *
+ * The dropped rules are the recursive branch and, unless something else still
+ * refers to it, the empty one: both are reachable only through the variant that
+ * the {@link Repeat} replaces. Pruning them keeps the invariant that every rule
+ * of a generated set is reachable from its entry, so the serialized form holds
+ * no dead grammar.
+ *
+ * @type {(ruleSet: RuleSet, entry: string) => RuleSet}
+ */
+export declare const detectRepeat: (ruleSet: RuleSet, entry: string) => RuleSet;
 /**
  * Converts a functional grammar rule into serializable BNF data and returns
  * the generated rule set with the entry rule identifier.

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

@@ -3,10 +3,11 @@
  * {@link toData} conversion from the functional grammar.
  *
  * This module is the pure, parser-agnostic substrate: it defines the
- * {@link RuleSet} data form (`Rule = Variant | Sequence | TerminalRange`) and
- * converts a functional grammar into it. The automaton builders that consume a
- * {@link RuleSet} live in their own sibling modules (`fjs/bnf/ll1`,
- * `fjs/bnf/descent`, …), so the IR stays free of any one parser's machinery.
+ * {@link RuleSet} data form (`Rule = Variant | Sequence | TerminalRange |
+ * Repeat`) and converts a functional grammar into it. The automaton builders
+ * that consume a {@link RuleSet} live in their own sibling modules
+ * (`fjs/bnf/ll1`, `fjs/bnf/descent`, …), so the IR stays free of any one
+ * parser's machinery.
  *
  * See `./types.ts` for the type-level API.
  *
@@ -14,13 +15,27 @@
  *
  * @import { DataRule, Rule as FRule, Sequence as FSequence } from '../types.ts'
  * @import { StringMap } from '../../types/object/types.ts'
- * @import { EmptyTag, Rule, RuleSet, Sequence, Variant } from './types.ts'
+ * @import { StringSet } from '../../types/string_set/types.ts'
+ * @import { EmptyTag, Repeat, Rule, RuleSet, Sequence, Variant } from './types.ts'
  */
 
 import { stringToCodePointList } from '../../text/utf16/module.f.mjs'
 import { map, toArray } from '../../types/list/module.f.mjs'
 import { oneEncode } from '../module.f.mjs'
-import { definedEntries } from '../../types/object/module.f.mjs'
+import { definedEntries, definedValues } from '../../types/object/module.f.mjs'
+import { contains, set } from '../../types/string_set/module.f.mjs'
+
+/**
+ * Whether a data rule is a {@link Repeat}.
+ *
+ * Every rule-dispatch site asks this instead of testing for a string inline, so
+ * the repetition rule kind has exactly one discriminator to move when the
+ * surrounding rule model changes.
+ *
+ * @param {Rule} rule
+ * @returns {rule is Repeat}
+ */
+export const isRepeat = rule => typeof rule === 'string'
 
 /** @typedef {StringMap<EmptyTag>} _EmptyTagMap */
 
@@ -30,6 +45,10 @@ const emptyTagOf = map => rule => {
         return undefined
     } else if (rule instanceof Array) {
         return rule.every(item => map[item] !== undefined) ? true : undefined
+    } else if (isRepeat(rule)) {
+        // Zero repetitions is a match whatever the body does, and it carries no
+        // tag of its own — a repetition is a sequence of items, not a choice.
+        return true
     } else {
         /** @type {EmptyTag} */
         let tag = undefined
@@ -176,6 +195,92 @@ const toDataAdd = map => fr => {
     return [map2, { ...set, [id]: rule }, id]
 }
 
+//
+
+const { fromEntries } = Object
+
+/** @type {(rule: Rule) => Sequence} */
+const refs = rule => {
+    if (typeof rule === 'number') {
+        return []
+    } else if (rule instanceof Array) {
+        return rule
+    } else if (isRepeat(rule)) {
+        return [rule]
+    } else {
+        return definedValues(rule)
+    }
+}
+
+/** @type {(ruleSet: RuleSet) => (visited: StringSet, name: string) => StringSet} */
+const visit = ruleSet => (visited, name) =>
+    contains(name)(visited)
+        ? visited
+        : refs(ruleSet[name]).reduce(visit(ruleSet), set(name)(visited))
+
+/**
+ * Every rule the entry rule can reach, itself included.
+ *
+ * @type {(ruleSet: RuleSet) => (entry: string) => StringSet}
+ */
+const reachable = ruleSet => entry => visit(ruleSet)(null, entry)
+
+/** @type {(rule: Rule) => boolean} */
+const isNone = rule => rule instanceof Array && rule.length === 0
+
+/**
+ * The {@link Repeat} — the name of the item to repeat — that `name` encodes as
+ * right-recursion, or `undefined` when it encodes something else.
+ *
+ * The shape recognized is exactly the unambiguous 0-or-more list: a two-branch
+ * variant whose branches are an empty sequence and `[item, name]`, in either
+ * order. Everything looser stays as it is — an operator-style tree, a separated
+ * list, or a 1-or-more chain all reach `name` again, but their extra items make
+ * the grouping a real choice rather than a list, so folding them into a flat
+ * sequence would discard structure no rule name is left to recover.
+ *
+ * Two further conditions keep the fold sound rather than merely plausible:
+ * `item` must not lead back to `name`, so `name`'s only self-reference is the
+ * tail one, and `item` must not match empty, since a body that can consume
+ * nothing has infinitely many parses of the same input.
+ *
+ * @type {(ruleSet: RuleSet, emptyTags: _EmptyTagMap) => (name: string) => Repeat | undefined}
+ */
+const repeatOf = (ruleSet, emptyTags) => name => {
+    const rule = ruleSet[name]
+    if (typeof rule === 'number' || rule instanceof Array || isRepeat(rule)) { return undefined }
+    const branches = definedValues(rule)
+    if (branches.length !== 2) { return undefined }
+    const [a, b] = branches
+    const step = isNone(ruleSet[a]) ? b : isNone(ruleSet[b]) ? a : undefined
+    if (step === undefined) { return undefined }
+    const stepRule = ruleSet[step]
+    if (!(stepRule instanceof Array) || stepRule.length !== 2 || stepRule[1] !== name) { return undefined }
+    const [item] = stepRule
+    if (emptyTags[item] !== undefined || contains(name)(reachable(ruleSet)(item))) { return undefined }
+    return item
+}
+
+/**
+ * Rewrites every right-recursive 0-or-more rule of a {@link RuleSet} into a
+ * {@link Repeat}, and drops the rules that the rewrite orphans.
+ *
+ * The dropped rules are the recursive branch and, unless something else still
+ * refers to it, the empty one: both are reachable only through the variant that
+ * the {@link Repeat} replaces. Pruning them keeps the invariant that every rule
+ * of a generated set is reachable from its entry, so the serialized form holds
+ * no dead grammar.
+ *
+ * @type {(ruleSet: RuleSet, entry: string) => RuleSet}
+ */
+export const detectRepeat = (ruleSet, entry) => {
+    const repeat = repeatOf(ruleSet, emptyTagMap(ruleSet))
+    /** @type {RuleSet} */
+    const next = fromEntries(entries(ruleSet).map(([k, v]) => [k, repeat(k) ?? v]))
+    const live = reachable(next)(entry)
+    return fromEntries(entries(next).filter(([k]) => contains(k)(live)))
+}
+
 /**
  * Converts a functional grammar rule into serializable BNF data and returns
  * the generated rule set with the entry rule identifier.
@@ -184,5 +289,5 @@ const toDataAdd = map => fr => {
  */
 export const toData = fr => {
     const [, ruleSet, id] = toDataAdd({})(fr)
-    return [ruleSet, id]
+    return [detectRepeat(ruleSet, id), id]
 }

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

@@ -7,6 +7,8 @@ export declare const proof: {
     rangeDecode: () => void;
     rangeEncode: () => void;
     toData: (() => void)[];
+    isRepeat: () => void;
+    detectRepeat: (() => void)[];
     variantTest: () => void;
     emptyTagMap: (() => void)[];
     example: () => void;

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

@@ -6,8 +6,8 @@
 
 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'
@@ -88,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,39 +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 ({@link eofSymbol}) after them, so a grammar can require the end
- * of input with the `eof` terminal.
+ * 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 { AstRuleMeta, AstTag, AstSequenceMeta, CodePointMeta, 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 { AstRuleMeta, DescentMatch } from './types.ts';
-export type _Cursor = number;
+import type { AstResult, Cursor } from '../matcher/types.ts';
+import type { CodePointMeta, DescentMatch } from './types.ts';
 export type _Failure = {
-    readonly pos: _Cursor;
+    readonly pos: Cursor;
     readonly expected: readonly TerminalRange[];
 };
-export type _Result<T> = {
-    readonly ast: AstRuleMeta<T>;
-    readonly success: boolean;
-    readonly pos: _Cursor;
-};
+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.