functionalscript 0.44.0 → 0.46.0

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

@@ -6,41 +6,40 @@
 import type { CodePoint } from '../../text/utf16/types.ts';
 import type { RangeMapArray } from '../../types/range_map/types.ts';
 import type { StringMap } from '../../types/object/types.ts';
-import type { EmptyTag } from '../data/types.ts';
-/** @internal */
+import type { Ast } from '../matcher/types.ts';
+/**
+ * A rule's dispatch entry: its first set as a range map, and — for a variant
+ * that can match empty — the branch a dispatch miss selects.
+ *
+ * @internal
+ */
 export type _DispatchRule = {
-    readonly emptyTag: EmptyTag;
+    readonly empty: _DispatchBranch | undefined;
     readonly rangeMap: _Dispatch;
 };
 /** @internal */
 export type _Dispatch = RangeMapArray<_DispatchResult>;
 /** @internal */
-export type _DispatchResult = _DispatchRuleCollection | null;
-/** @internal */
-export type _DispatchRuleOrName = _DispatchRule | string;
-/** @internal */
-export type _DispatchRuleCollection = {
-    readonly tag: string | undefined;
-    readonly rules: _DispatchRuleOrName[];
-};
-/** @internal */
-export type _DispatchMap = StringMap<_DispatchRule>;
+export type _DispatchResult = _DispatchBranch | null;
 /**
- * Represents a parsed AST rule, consisting of a rule name and its parsed sequence.
+ * A branch as dispatch selects it: the name of the rule to invoke — a name
+ * into the {@link _DispatchMap} — and the tag its node gets. Only a variant's
+ * entries are ever read as branches; every other rule kind consults its range
+ * map solely for first-set membership.
  *
  * @internal
  */
-export type _AstRule = {
-    readonly tag: AstTag;
-    readonly sequence: AstSequence;
+export type _DispatchBranch = {
+    readonly tag: string | undefined;
+    readonly name: string;
 };
-/**
- * Represents a parsed AST sequence.
- */
-export type AstSequence = readonly (_AstRule | CodePoint)[];
-export type AstTag = string | true | undefined;
+/** @internal */
+export type _DispatchMap = StringMap<_DispatchRule>;
 /**
  * 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;
 /**
@@ -48,12 +47,11 @@ export type Remainder = readonly CodePoint[] | null;
  *
  * Represents the result of a match operation, including the parsed AST rule and the remainder of the input.
  */
-export type MatchResult = readonly [_AstRule, boolean, Remainder];
+export type MatchResult = readonly [Ast<CodePoint>, 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/matcher/module.f.d.mts

@@ -0,0 +1,66 @@
+/**
+ * The layer every BNF matcher backend shares: the {@link Cursor} it matches at,
+ * the {@link Ast} it builds, and the constructors that pair them.
+ *
+ * `fjs/bnf/ll1` and `fjs/bnf/descent` are two machines over one contract, and
+ * the contract is what lives here — not the machines. Backtracking, frame
+ * shapes, failure reporting and the public result type are each backend's own,
+ * and deliberately different; where the input sits, what a consumed symbol
+ * contributes to the AST, and how a node is built are not.
+ *
+ * The three are one module rather than three because they are interdependent:
+ * {@link leafAt} produces AST leaves, and {@link mrSuccess} builds AST nodes
+ * positioned by a cursor. Splitting them would put one concept behind three
+ * imports.
+ *
+ * See `./types.ts` for the type-level API and `./README.md` for the contract
+ * this implements.
+ *
+ * @module
+ *
+ * @import { Ast, AstResult, AstSequence, AstTag, Cursor } from './types.ts'
+ */
+import type { AstResult, AstSequence, AstTag, Cursor } from './types.ts';
+/**
+ * What consuming the symbol at a cursor contributes to the AST: the leaf
+ * itself, and nothing for the synthesized end-of-input symbol — it has no
+ * physical source element, so it never reaches an AST.
+ *
+ * @type {<L>(input: readonly L[], pos: Cursor) => AstSequence<L>}
+ */
+export declare const leafAt: <L>(input: readonly L[], pos: Cursor) => AstSequence<L>;
+/**
+ * The semantic symbol a cursor points at: one read out of the physical input,
+ * and the synthesized {@link eofSymbol} at its end. Only meaningful where the
+ * cursor still has a symbol, `pos <= input.length`.
+ *
+ * `symbolOf` is the one place backends differ — it is how a leaf yields its
+ * symbol, `identity` where the leaf *is* the code point and a destructuring
+ * where it carries metadata alongside. Each backend binds its own partial
+ * application once at module scope.
+ *
+ * @type {<L>(symbolOf: (leaf: L) => number) => (input: readonly L[], pos: Cursor) => number}
+ */
+export declare const symbolAt: <L>(symbolOf: (leaf: L) => number) => (input: readonly L[], pos: Cursor) => number;
+/**
+ * The public, physical index of a cursor. Consuming the synthesized
+ * end-of-input symbol moves the cursor past the physical end, and both cursors
+ * report `length`.
+ *
+ * @type {(length: number) => (pos: Cursor) => number}
+ */
+export declare const physicalIdx: (length: number) => (pos: Cursor) => number;
+export type _Mr<L, P> = (tag: AstTag, sequence: AstSequence<L>, pos: P) => AstResult<L, P>;
+/**
+ * A matched node at a position.
+ *
+ * @type {<L, P>(tag: AstTag, sequence: AstSequence<L>, pos: P) => AstResult<L, P>}
+ */
+export declare const mrSuccess: <L, P>(tag: AstTag, sequence: AstSequence<L>, pos: P) => AstResult<L, P>;
+/**
+ * A node that did not match, at the position the caller should resume from —
+ * which a backtracking backend rewinds and a predictive one does not.
+ *
+ * @type {<L, P>(tag: AstTag, sequence: AstSequence<L>, pos: P) => AstResult<L, P>}
+ */
+export declare const mrFail: <L, P>(tag: AstTag, sequence: AstSequence<L>, pos: P) => AstResult<L, P>;

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

@@ -0,0 +1,81 @@
+/**
+ * The layer every BNF matcher backend shares: the {@link Cursor} it matches at,
+ * the {@link Ast} it builds, and the constructors that pair them.
+ *
+ * `fjs/bnf/ll1` and `fjs/bnf/descent` are two machines over one contract, and
+ * the contract is what lives here — not the machines. Backtracking, frame
+ * shapes, failure reporting and the public result type are each backend's own,
+ * and deliberately different; where the input sits, what a consumed symbol
+ * contributes to the AST, and how a node is built are not.
+ *
+ * The three are one module rather than three because they are interdependent:
+ * {@link leafAt} produces AST leaves, and {@link mrSuccess} builds AST nodes
+ * positioned by a cursor. Splitting them would put one concept behind three
+ * imports.
+ *
+ * See `./types.ts` for the type-level API and `./README.md` for the contract
+ * this implements.
+ *
+ * @module
+ *
+ * @import { Ast, AstResult, AstSequence, AstTag, Cursor } from './types.ts'
+ */
+
+import { eofSymbol } from '../module.f.mjs'
+
+/**
+ * What consuming the symbol at a cursor contributes to the AST: the leaf
+ * itself, and nothing for the synthesized end-of-input symbol — it has no
+ * physical source element, so it never reaches an AST.
+ *
+ * @type {<L>(input: readonly L[], pos: Cursor) => AstSequence<L>}
+ */
+export const leafAt = (input, pos) => pos < input.length ? [input[pos]] : []
+
+/**
+ * The semantic symbol a cursor points at: one read out of the physical input,
+ * and the synthesized {@link eofSymbol} at its end. Only meaningful where the
+ * cursor still has a symbol, `pos <= input.length`.
+ *
+ * `symbolOf` is the one place backends differ — it is how a leaf yields its
+ * symbol, `identity` where the leaf *is* the code point and a destructuring
+ * where it carries metadata alongside. Each backend binds its own partial
+ * application once at module scope.
+ *
+ * @type {<L>(symbolOf: (leaf: L) => number) => (input: readonly L[], pos: Cursor) => number}
+ */
+export const symbolAt = symbolOf => (input, pos) =>
+    pos < input.length ? symbolOf(input[pos]) : eofSymbol
+
+/**
+ * The public, physical index of a cursor. Consuming the synthesized
+ * end-of-input symbol moves the cursor past the physical end, and both cursors
+ * report `length`.
+ *
+ * @type {(length: number) => (pos: Cursor) => number}
+ */
+export const physicalIdx = length => pos => Math.min(pos, length)
+
+/**
+ * @template L
+ * @template P
+ * @typedef {(tag: AstTag, sequence: AstSequence<L>, pos: P) => AstResult<L, P>} _Mr
+ */
+
+/** @type {<L, P>(success: boolean) => _Mr<L, P>} */
+const mr = success => (tag, sequence, pos) => ({ ast: { tag, sequence }, success, pos })
+
+/**
+ * A matched node at a position.
+ *
+ * @type {<L, P>(tag: AstTag, sequence: AstSequence<L>, pos: P) => AstResult<L, P>}
+ */
+export const mrSuccess = mr(true)
+
+/**
+ * A node that did not match, at the position the caller should resume from —
+ * which a backtracking backend rewinds and a predictive one does not.
+ *
+ * @type {<L, P>(tag: AstTag, sequence: AstSequence<L>, pos: P) => AstResult<L, P>}
+ */
+export const mrFail = mr(false)

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

@@ -0,0 +1,10 @@
+/**
+ * @import { CodePointMeta } from '../descent/types.ts'
+ */
+export declare const proof: {
+    leafAt: (() => void)[];
+    symbolAt: (() => void)[];
+    physicalIdx: () => void;
+    mrSuccess: () => void;
+    mrFail: () => void;
+};

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

@@ -0,0 +1,79 @@
+/**
+ * @import { CodePointMeta } from '../descent/types.ts'
+ */
+
+import { assertEq } from '../../asserts/module.f.mjs'
+import { identity } from '../../types/function/module.f.mjs'
+import { eofSymbol } from '../module.f.mjs'
+import { leafAt, mrFail, mrSuccess, physicalIdx, symbolAt } from './module.f.mjs'
+
+/** @type {readonly CodePointMeta<string>[]} */
+const withMeta = [[0x41, 'a'], [0x42, 'b']]
+
+/** @type {(leaf: CodePointMeta<string>) => number} */
+const metaSymbolOf = ([symbol]) => symbol
+
+export const proof = {
+    leafAt: [
+        () => {
+            // Inside the physical input a leaf is contributed whole, whatever a
+            // backend chose a leaf to be.
+            assertEq(JSON.stringify(leafAt([65, 66], 0)), '[65]')
+            assertEq(JSON.stringify(leafAt([65, 66], 1)), '[66]')
+            assertEq(JSON.stringify(leafAt(withMeta, 0)), '[[65,"a"]]')
+        },
+        () => {
+            // At and past the physical end there is nothing to contribute: the
+            // synthesized end-of-input symbol has no source element, so it never
+            // reaches an AST.
+            assertEq(JSON.stringify(leafAt([65, 66], 2)), '[]')
+            assertEq(JSON.stringify(leafAt([65, 66], 3)), '[]')
+            assertEq(JSON.stringify(leafAt([], 0)), '[]')
+        },
+    ],
+    symbolAt: [
+        () => {
+            // `identity` is the leaf reader of a backend whose leaf *is* the
+            // symbol; a pair's reader takes its first half. Same positions, same
+            // symbols.
+            /** @type {(leaf: number) => number} */
+            const symbolOf = identity
+            assertEq(symbolAt(symbolOf)([65, 66], 0), 65)
+            assertEq(symbolAt(metaSymbolOf)(withMeta, 0), 65)
+            assertEq(symbolAt(metaSymbolOf)(withMeta, 1), 66)
+        },
+        () => {
+            // The one synthesized end-of-input symbol sits at the physical end,
+            // for either leaf shape.
+            /** @type {(leaf: number) => number} */
+            const symbolOf = identity
+            assertEq(symbolAt(symbolOf)([65, 66], 2), eofSymbol)
+            assertEq(symbolAt(metaSymbolOf)(withMeta, 2), eofSymbol)
+            assertEq(symbolAt(symbolOf)([], 0), eofSymbol)
+        },
+    ],
+    physicalIdx: () => {
+        const physical = physicalIdx(2)
+        assertEq(physical(0), 0)
+        assertEq(physical(2), 2)
+        // Consuming the end-of-input symbol moves the cursor past the physical
+        // end, and both cursors report the same public index — which is what
+        // keeps a public position physical.
+        assertEq(physical(3), 2)
+    },
+    mrSuccess: () => {
+        assertEq(
+            JSON.stringify(mrSuccess('some', [65], 1)),
+            '{"ast":{"tag":"some","sequence":[65]},"success":true,"pos":1}')
+        // The position type is the backend's own: `null` is how a predictive
+        // backend says it ran out of input.
+        assertEq(
+            JSON.stringify(mrSuccess(undefined, [], null)),
+            '{"ast":{"sequence":[]},"success":true,"pos":null}')
+    },
+    mrFail: () => {
+        assertEq(
+            JSON.stringify(mrFail(true, [], 0)),
+            '{"ast":{"tag":true,"sequence":[]},"success":false,"pos":0}')
+    },
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Type-level API for the layer every BNF matcher backend shares: the position
+ * it matches at, the AST it builds, and the result that pairs them.
+ *
+ * @module
+ */
+/**
+ * Tag of an AST node: the variant branch that matched, `true` where a rule
+ * matched empty input without naming a branch, and `undefined` where the rule
+ * is not a choice at all.
+ */
+export type AstTag = string | true | undefined;
+/**
+ * An AST over leaves of type `L`. A backend picks `L` for what it keeps of a
+ * consumed symbol — the code point alone, or the code point with metadata.
+ */
+export type Ast<L> = {
+    readonly tag: AstTag;
+    readonly sequence: AstSequence<L>;
+};
+/** The children of an {@link Ast} node: nested nodes and consumed leaves. */
+export type AstSequence<L> = readonly (Ast<L> | L)[];
+/**
+ * A match position over input of `length` leaves: `0 .. length` are the
+ * physical positions, and `length + 1` is where the one synthesized
+ * end-of-input symbol has been consumed.
+ *
+ * This is the complete cursor `(idx, eofConsumed)` of
+ * [the BNF contract](../README.md#logical-eof-in-parser-input) written as one
+ * number. `eofConsumed` can only be true at the physical end, so the pair and
+ * the extended position hold the same information — and being one number is
+ * what makes every ordering a backend needs a plain `<`, because consuming EOF
+ * *is* progress even though the public index does not move. A backend that
+ * treated it as no progress would loop forever on a repetition over a rule that
+ * can match EOF.
+ *
+ * Public positions are physical, so a cursor is converted back with
+ * `physicalIdx` before it leaves a backend.
+ */
+export type Cursor = number;
+/**
+ * A matcher's own result: the AST built so far, whether it matched, and where
+ * it stopped.
+ *
+ * `P` is the position type. A backend whose match always has one uses
+ * {@link Cursor}; one that also reports running out of input uses
+ * `Cursor | null`. Public results are each backend's own type — this is the
+ * shape they are built from, not the shape they return.
+ */
+export type AstResult<L, P> = {
+    readonly ast: Ast<L>;
+    readonly success: boolean;
+    readonly pos: P;
+};

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>}
  */

package/fjs/bnf/module.f.mjs

@@ -31,12 +31,52 @@ const offset = 24
 
 const mask = (1 << offset) - 1
 
-const isValid = contains(0, mask)
+/**
+ * How many stored endpoint codes one 24-bit half holds: `2 ** 24`.
+ */
+const terminalSize = mask + 1
+
+/**
+ * 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 const eofSymbol = -1
+
+/**
+ * The largest ordinary symbol, `2 ** 24 - 2`: the semantic domain is
+ * `[-1] | [0, 2 ** 24 - 2]`, exactly `2 ** 24` terminals, one per stored code.
+ */
+const maxSymbol = mask - 1
+
+const isValid = contains(eofSymbol, maxSymbol)
+
+/**
+ * Semantic terminal to its stored 24-bit endpoint code. Branchless: EOF wraps
+ * to `2 ** 24 - 1` (the top of the stored space) and every ordinary symbol
+ * keeps its own value as its code.
+ *
+ * @type {(value: number) => number}
+ */
+const encodeTerminal = value => (value + terminalSize) & mask
+
+/**
+ * The inverse of `encodeTerminal`, also branchless.
+ *
+ * Stored codes are an implementation representation, not semantic terminal
+ * ordering — `2 ** 24 - 1` is the largest code but the smallest terminal — so
+ * range operations that care about ordering must compare decoded values.
+ *
+ * @type {(value: number) => number}
+ */
+const decodeTerminal = value => ((value + 1) & mask) - 1
 
 /** @type {(a: number, b: number) => TerminalRange} */
 export const rangeEncode = (a, b) => {
     assert(isValid(a) && isValid(b) && a <= b)
-    return Number((BigInt(a) << BigInt(offset)) | BigInt(b))
+    return Number((BigInt(encodeTerminal(a)) << BigInt(offset)) | BigInt(encodeTerminal(b)))
 }
 
 /**
@@ -47,20 +87,21 @@ export const rangeEncode = (a, b) => {
 export const oneEncode = a => rangeEncode(a, a)
 
 /**
- * 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 const eof = oneEncode(mask)
+export const eof = oneEncode(eofSymbol)
 
 /**
- * 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 const fullRange = 0x000000_FFFFFF
+export const fullRange = rangeEncode(0, maxSymbol)
 
 /**
  * Unicode scalar value range packed into a single {@link TerminalRange}.
@@ -74,12 +115,12 @@ export const unicodeRange = 0x000000_10FFFF
 export const unicodeMax = codePointListToString([0x10FFFF])
 
 /**
- * Decodes a packed range into `[start, end]` symbols.
+ * Decodes a packed range into `[start, end]` semantic symbols.
  *
  * @type {(r: number) => Tuple<2, number>}
  */
 export const rangeDecode = r =>
-    [Number(BigInt(r) >> BigInt(offset)), r & mask]
+    [decodeTerminal(Number(BigInt(r) >> BigInt(offset))), decodeTerminal(r & mask)]
 
 const mapOneEncode = map(oneEncode)
 

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

@@ -9,6 +9,8 @@ export declare const proof: {
         rangeEncodeInvalid: (() => void)[];
         rangeInvalid: (() => void)[];
     };
+    terminal: (() => void)[];
+    complement: (() => void)[];
     str: (() => void)[];
     set: () => void;
     commaJoin0Plus: () => void;

package/fjs/bnf/proof.f.mjs

@@ -4,8 +4,18 @@
  * @import { Rule } from './types.ts'
  */
 
-import { assert, assertEq } from '../asserts/module.f.mjs'
 import {
+    assert,
+    assertEq,
+    assertStructurallySame,
+} from '../asserts/module.f.mjs'
+import {
+    eof,
+    eofSymbol,
+    fullRange,
+    not,
+    notSet,
+    rangeDecode,
     rangeEncode,
     str,
     set,
@@ -15,8 +25,14 @@ import {
     oneEncode,
     repeat1Plus,
 } from './module.f.mjs'
+import { definedValues } from '../types/object/module.f.mjs'
 import { classic, deterministic } from './testlib.f.mjs'
 
+// The last ordinary symbol, `2 ** 24 - 2`. Written out because the range codec
+// is what these tests check: deriving it from the codec would move both sides
+// of every assertion together.
+const maxSymbol = 0xFFFFFE
+
 export const proof = {
     test: () => {
         classic()
@@ -24,8 +40,14 @@ export const proof = {
     },
     throw: {
         rangeEncodeInvalid: [
-            () => { rangeEncode(-1, 0) },
-            () => { rangeEncode(0, -1) },
+            // one below `eofSymbol`, the smallest semantic terminal
+            () => { rangeEncode(-2, 0) },
+            () => { rangeEncode(0, -2) },
+            // one above the largest ordinary symbol: `2 ** 24 - 1` is EOF's
+            // stored code, not a terminal of its own
+            () => { rangeEncode(0, maxSymbol + 1) },
+            // semantic ordering, so EOF is below every ordinary symbol
+            () => { rangeEncode(0, eofSymbol) },
             () => { rangeEncode(5, 3) },
         ],
         rangeInvalid: [
@@ -33,6 +55,60 @@ export const proof = {
             () => { range('abc') },
         ],
     },
+    terminal: [
+        () => {
+            // EOF is the singleton `[-1, -1]` and keeps the stored code
+            // `2 ** 24 - 1` at both endpoints.
+            assertEq(eof, 0xFFFFFF_FFFFFF)
+            const [a, b] = rangeDecode(eof)
+            assertEq(a, eofSymbol)
+            assertEq(b, eofSymbol)
+        },
+        () => {
+            // `fullRange` holds the ordinary symbols only.
+            const [a, b] = rangeDecode(fullRange)
+            assertEq(a, 0)
+            assertEq(b, maxSymbol)
+        },
+        () => {
+            // Round trips over the whole semantic domain: EOF, the ordinary
+            // minimum, an ordinary symbol, and the ordinary maximum.
+            for (const v of [eofSymbol, 0, 0x10FFFF, maxSymbol]) {
+                const [a, b] = rangeDecode(oneEncode(v))
+                assertEq(a, v)
+                assertEq(b, v)
+            }
+        },
+        () => {
+            // Ordinary symbols keep their own value as their stored code, so a
+            // packed literal still reads as its endpoints.
+            assertEq(oneEncode(0x20), 0x000020_000020)
+            const [a, b] = rangeDecode(0x000030_000039)
+            assertEq(a, 0x30)
+            assertEq(b, 0x39)
+        },
+        () => {
+            // A range may span EOF and ordinary symbols; the endpoints are
+            // ordered semantically, not by stored code.
+            const [a, b] = rangeDecode(rangeEncode(eofSymbol, maxSymbol))
+            assertEq(a, eofSymbol)
+            assertEq(b, maxSymbol)
+        },
+    ],
+    complement: [
+        () => {
+            // The complement of nothing over `fullRange` is `fullRange`: EOF is
+            // not an ordinary symbol, so no complement can produce it.
+            const r = definedValues(not({}))
+            assertEq(r.length, 1)
+            assertEq(r[0], fullRange)
+        },
+        () => {
+            const r = definedValues(notSet('a'))
+            const decoded = r.map(rangeDecode)
+            assertStructurallySame(decoded, [[0, 0x60], [0x62, maxSymbol]])
+        },
+    ],
     str: [
         () => {
             const result = str('a')