functionalscript 0.45.0 → 0.46.0

package/fjs/media/json/number/module.f.mjs

@@ -0,0 +1,136 @@
+/**
+ * Bounded lexical analysis of a JSON number token.
+ *
+ * `NumberToken.value` is the canonical lossless numeric source, and these
+ * helpers read it **without narrowing it first**: every operation here costs
+ * at most the length of the token, so a valid JSON number is classified
+ * correctly whatever its magnitude. In particular no helper builds a
+ * coefficient bigint, converts an arbitrary exponent to `number`, or evaluates
+ * a power such as `10 ** exponent`.
+ *
+ * That matters for schema-directed consumers, which have to decide questions
+ * such as "is this token an integer?" *before* a materializer rounds the value
+ * into `number`: `1.00000000000000001` and `1` are the same `number` but
+ * different tokens.
+ *
+ * @module
+ *
+ * @import { Sign } from '../../../types/function/compare/types.ts'
+ * @import { NumberLexeme } from './types.ts'
+ */
+
+import { cmp } from '../../../types/function/compare/module.f.mjs'
+
+/**
+ * Splits a JSON number token into its lexical parts.
+ *
+ * The token is grammar-validated by the tokenizer —
+ * `-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?` — so this is a split, not a
+ * validation.
+ *
+ * @type {(value: string) => NumberLexeme}
+ */
+export const numberLexeme = value => {
+    const sign = value.startsWith('-') ? '-' : ''
+    const unsigned = value.slice(sign.length)
+    // at most one of 'e'/'E' can occur, so whichever `indexOf` finds is it
+    const lowerE = unsigned.indexOf('e')
+    const eIndex = lowerE < 0 ? unsigned.indexOf('E') : lowerE
+    const coefficient = eIndex < 0 ? unsigned : unsigned.slice(0, eIndex)
+    const expText = eIndex < 0 ? '' : unsigned.slice(eIndex + 1)
+    const dotIndex = coefficient.indexOf('.')
+    const int = dotIndex < 0 ? coefficient : coefficient.slice(0, dotIndex)
+    const frac = dotIndex < 0 ? '' : coefficient.slice(dotIndex + 1)
+    const expSign = expText.startsWith('-')
+        ? '-'
+        : expText.startsWith('+') ? '+' : ''
+    return { sign, int, frac, expSign, exp: expText.slice(expSign.length) }
+}
+
+/**
+ * Whether the lexeme is bare integer syntax: no `.` and no `e` / `E`.
+ *
+ * The distinction is lexical, not mathematical — `1e3` is not bare integer
+ * syntax even though its value is the integer `1000`.
+ *
+ * @type {(lexeme: NumberLexeme) => boolean}
+ */
+export const isBareInteger = ({ frac, exp }) => frac === '' && exp === ''
+
+/** @type {(digits: string) => string} */
+const stripLeadingZeros = digits => {
+    let i = 0
+    while (i < digits.length && digits[i] === '0') { i += 1 }
+    return digits.slice(i)
+}
+
+/** @type {(digits: string) => number} */
+const trailingZeroCount = digits => {
+    let n = 0
+    while (n < digits.length && digits[digits.length - 1 - n] === '0') { n += 1 }
+    return n
+}
+
+/**
+ * Compares arbitrarily long non-negative digit text against an ordinary
+ * non-negative integer, in the length of that text.
+ *
+ * Leading zeros are dropped, so equal-length digit strings compare
+ * numerically as strings and unequal lengths are decided by length alone.
+ * `bound` therefore never has to be turned into digit text long enough to
+ * match `digits`, and `digits` never has to become a number.
+ *
+ * @type {(digits: string) => (bound: number) => Sign}
+ */
+const compareDigits = digits => bound => {
+    const a = stripLeadingZeros(digits)
+    const b = stripLeadingZeros(`${bound}`)
+    const byLength = cmp(a.length)(b.length)
+    return byLength === 0 ? cmp(a)(b) : byLength
+}
+
+/**
+ * Whether the lexeme's exponent is at least `bound`, an ordinary integer
+ * small enough to have come from the token's own length.
+ *
+ * The exponent itself is never converted: its sign decides which side of the
+ * comparison can already be answered, and only its digit text is compared —
+ * so `1e-99999999999999999999` is settled by looking at the sign and a length,
+ * not by representing that exponent.
+ *
+ * @type {(lexeme: NumberLexeme) => (bound: number) => boolean}
+ */
+const exponentAtLeast = ({ expSign, exp }) => bound =>
+    expSign === '-'
+        // a negative exponent reaches `bound` only if `bound` is not positive
+        // and the exponent's magnitude stays within `-bound`
+        ? bound <= 0 && compareDigits(exp)(-bound) <= 0
+        // a non-negative exponent (`''` — an absent exponent — included, since
+        // its digit text is then empty and compares as zero) always reaches a
+        // non-positive `bound`
+        : bound <= 0 || compareDigits(exp)(bound) >= 0
+
+/**
+ * Whether the lexeme spells a mathematical integer.
+ *
+ * This is the exact question, not the lexical one: `1e3` and `1.00` are
+ * integral while `1.5` is not. It stays bounded by the token's length.
+ *
+ * The value is `coefficient × 10 ** (exponent - fractionDigits)`, so it is an
+ * integer exactly when the exponent shifts the decimal point no further right
+ * than the coefficient's own trailing zeros allow. Both sides of that
+ * comparison — the fraction-digit count and the trailing-zero count — are
+ * bounded by the token, so the exponent only ever has to be compared against a
+ * small number.
+ *
+ * A zero coefficient is the simple case: zero is integral for any exponent, so
+ * the exponent is not examined at all.
+ *
+ * @type {(lexeme: NumberLexeme) => boolean}
+ */
+export const isIntegral = lexeme => {
+    const { int, frac } = lexeme
+    const coefficient = `${int}${frac}`
+    const zeros = trailingZeroCount(coefficient)
+    return zeros === coefficient.length || exponentAtLeast(lexeme)(frac.length - zeros)
+}

package/fjs/media/json/number/proof.f.d.mts

@@ -0,0 +1,24 @@
+export declare const proof: {
+    numberLexeme: {
+        int: () => void;
+        negative: () => void;
+        fraction: () => void;
+        exponent: () => void;
+        capitalExponent: () => void;
+        plusExponent: () => void;
+        minusExponent: () => void;
+        unbounded: () => void;
+    };
+    isBareInteger: {
+        int: () => void;
+        zero: () => void;
+        fraction: () => void;
+        exponent: () => void;
+    };
+    isIntegral: {
+        zero: (() => void)[];
+        plain: (() => void)[];
+        exponent: (() => void)[];
+        unbounded: (() => void)[];
+    };
+};

package/fjs/media/json/number/proof.f.mjs

@@ -0,0 +1,86 @@
+import { isBareInteger, isIntegral, numberLexeme } from './module.f.mjs'
+import { assert, assertStructurallySame } from '../../../asserts/module.f.mjs'
+
+/** @type {(value: string) => boolean} */
+const integral = value => isIntegral(numberLexeme(value))
+
+/** @type {(value: string) => boolean} */
+const bareInteger = value => isBareInteger(numberLexeme(value))
+
+// An exponent long enough that representing it as a `number` loses digits and
+// `10 ** exponent` is not a computation anyone can afford. Every check below
+// that uses it must be decided by the token's shape alone.
+const hugeExp = '99999999999999999999'
+
+export const proof = {
+    numberLexeme: {
+        int: () => assertStructurallySame(
+            numberLexeme('123'),
+            { sign: '', int: '123', frac: '', expSign: '', exp: '' }),
+        negative: () => assertStructurallySame(
+            numberLexeme('-123'),
+            { sign: '-', int: '123', frac: '', expSign: '', exp: '' }),
+        fraction: () => assertStructurallySame(
+            numberLexeme('-0.125'),
+            { sign: '-', int: '0', frac: '125', expSign: '', exp: '' }),
+        exponent: () => assertStructurallySame(
+            numberLexeme('1e10'),
+            { sign: '', int: '1', frac: '', expSign: '', exp: '10' }),
+        capitalExponent: () => assertStructurallySame(
+            numberLexeme('1.5E10'),
+            { sign: '', int: '1', frac: '5', expSign: '', exp: '10' }),
+        plusExponent: () => assertStructurallySame(
+            numberLexeme('1e+10'),
+            { sign: '', int: '1', frac: '', expSign: '+', exp: '10' }),
+        minusExponent: () => assertStructurallySame(
+            numberLexeme('1e-10'),
+            { sign: '', int: '1', frac: '', expSign: '-', exp: '10' }),
+        // nothing is narrowed, so an unrepresentable exponent is just text
+        unbounded: () => assertStructurallySame(
+            numberLexeme(`-1.5e-${hugeExp}`),
+            { sign: '-', int: '1', frac: '5', expSign: '-', exp: hugeExp }),
+    },
+    // bare integer syntax: no `.` and no `e`/`E`, whatever the value is
+    isBareInteger: {
+        int: () => assert(bareInteger('-1230')),
+        zero: () => assert(bareInteger('-0')),
+        fraction: () => assert(!bareInteger('1.0')),
+        exponent: () => assert(!bareInteger('1e3')),
+    },
+    isIntegral: {
+        // a zero coefficient is integral at any exponent, and is decided
+        // without looking at the exponent at all
+        zero: [
+            () => assert(integral('0')),
+            () => assert(integral('-0.000')),
+            () => assert(integral(`0.0e-${hugeExp}`)),
+        ],
+        plain: [
+            () => assert(integral('123')),
+            () => assert(integral('1.00')),
+            () => assert(!integral('1.5')),
+            () => assert(!integral('1.50')),
+        ],
+        // the exponent moves the point; only the coefficient's own trailing
+        // zeros can absorb a move to the right
+        exponent: [
+            () => assert(integral('1e3')),
+            () => assert(integral('1.5e1')),
+            () => assert(integral('1.5e2')),
+            () => assert(integral('150e-1')),
+            () => assert(!integral('1.5e-1')),
+            () => assert(!integral('15e-2')),
+            () => assert(!integral('1.55e1')),
+            () => assert(!integral('1.0000000000001e5')),
+            // leading zeros in the exponent are not extra magnitude
+            () => assert(integral('1.5e001')),
+        ],
+        // decided from lengths and a sign, never by representing the exponent
+        unbounded: [
+            () => assert(integral(`1e${hugeExp}`)),
+            () => assert(integral(`1.5e${hugeExp}`)),
+            () => assert(!integral(`1e-${hugeExp}`)),
+            () => assert(!integral(`1.5e-${hugeExp}`)),
+        ],
+    },
+}

package/fjs/media/json/number/types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Types for the lexical view of a JSON number token.
+ *
+ * @module
+ */
+/**
+ * The parts of a JSON number lexeme, each kept as text.
+ *
+ * Nothing here is narrowed to a runtime numeric type, so a lexeme describes
+ * every syntactically valid JSON number — including coefficients larger than
+ * the runtime can build as a `bigint` and exponents beyond `number` precision.
+ *
+ * The empty string means "absent" for both optional parts, which is
+ * unambiguous: JSON requires at least one digit after `.` and at least one
+ * exponent digit, so a present part is never empty.
+ */
+export type NumberLexeme = {
+    /** `'-'` for a negative number, `''` otherwise. */
+    readonly sign: '' | '-';
+    /** The integer digits; always at least one digit. */
+    readonly int: string;
+    /** The fraction digits, or `''` when the lexeme has no `.`. */
+    readonly frac: string;
+    /** The exponent sign as written, or `''` when it is omitted. */
+    readonly expSign: '' | '+' | '-';
+    /** The exponent digits, or `''` when the lexeme has no `e` / `E`. */
+    readonly exp: string;
+};

package/fjs/media/json/parser/module.f.d.mts

@@ -1,30 +1,42 @@
 /**
- * JSON parser that consumes tokenizer output into JSON values.
+ * The shared structural JSON parser: one tokenizer, one container state
+ * machine, and a numeric policy per codec.
+ *
+ * The state machine builds objects and arrays; a number token is handed to the
+ * `NumberPolicy` the caller supplies, together with its exact lexeme. Numeric
+ * syntax therefore stays lossless all the way to the policy, and each codec
+ * chooses its own runtime numeric domain from the same parse:
+ *
+ * ```text
+ * JSON text -> tokenizer -> parse(policy) -+-> json.Unknown       (number)
+ *                                          +-> extended.Unknown   (number | bigint)
+ *                                          +-> another policy's domain
+ * ```
+ *
+ * No codec has to materialize another codec's domain first: standard JSON
+ * parsing never needs an intermediate `bigint`, and extended parsing never
+ * needs an intermediate rounded `number`.
  *
  * @module
  *
- * @import { Unknown } from '../types.ts'
  * @import { Result } from '../../../types/result/types.ts'
  * @import { List } from '../../../types/list/types.ts'
  * @import { Fold } from '../../../types/function/operator/types.ts'
  * @import { JsonToken } from '../tokenizer/types.ts'
- * @import { _JsonObject, _JsonArray, _StateParse, _JsonState, _JsonStack, _ValueToken } from './types.ts'
+ * @import { NumberPolicy, ParseUnknown, _JsonObject, _JsonArray, _StateParse, _JsonState, _JsonStack, _ValueToken } from './types.ts'
  */
-import type { Unknown } from '../types.ts';
 import type { Result } from '../../../types/result/types.ts';
 import type { List } from '../../../types/list/types.ts';
 import type { JsonToken } from '../tokenizer/types.ts';
+import type { NumberPolicy, ParseUnknown } from './types.ts';
 /**
- * Parses a list of JSON tokens into a JSON-compatible value.
+ * Parses a list of JSON tokens into the value domain `policy` materializes
+ * numbers into.
  *
  * Returns `ok` with the parsed value on success, or `error` with a message
- * when the token sequence is invalid or incomplete.
+ * when the token sequence is invalid or incomplete — or when `policy` rejects
+ * a number token that its domain cannot represent.
  *
- * @type {(tokenList: List<JsonToken>) => Result<Unknown, string>}
+ * @type {<P>(policy: NumberPolicy<P>) => (tokenList: List<JsonToken>) => Result<ParseUnknown<P>, string>}
  */
-export declare const parse: (tokenList: List<JsonToken>) => Result<Unknown, string>;
-export declare const proof: {
-    pushKey: {
-        nonObjectTop: () => void;
-    };
-};
+export declare const parse: <P>(policy: NumberPolicy<P>) => (tokenList: List<JsonToken>) => Result<ParseUnknown<P>, string>;

package/fjs/media/json/parser/module.f.mjs

@@ -1,48 +1,86 @@
 /**
- * JSON parser that consumes tokenizer output into JSON values.
+ * The shared structural JSON parser: one tokenizer, one container state
+ * machine, and a numeric policy per codec.
+ *
+ * The state machine builds objects and arrays; a number token is handed to the
+ * `NumberPolicy` the caller supplies, together with its exact lexeme. Numeric
+ * syntax therefore stays lossless all the way to the policy, and each codec
+ * chooses its own runtime numeric domain from the same parse:
+ *
+ * ```text
+ * JSON text -> tokenizer -> parse(policy) -+-> json.Unknown       (number)
+ *                                          +-> extended.Unknown   (number | bigint)
+ *                                          +-> another policy's domain
+ * ```
+ *
+ * No codec has to materialize another codec's domain first: standard JSON
+ * parsing never needs an intermediate `bigint`, and extended parsing never
+ * needs an intermediate rounded `number`.
  *
  * @module
  *
- * @import { Unknown } from '../types.ts'
  * @import { Result } from '../../../types/result/types.ts'
  * @import { List } from '../../../types/list/types.ts'
  * @import { Fold } from '../../../types/function/operator/types.ts'
  * @import { JsonToken } from '../tokenizer/types.ts'
- * @import { _JsonObject, _JsonArray, _StateParse, _JsonState, _JsonStack, _ValueToken } from './types.ts'
+ * @import { NumberPolicy, ParseUnknown, _JsonObject, _JsonArray, _StateParse, _JsonState, _JsonStack, _ValueToken } from './types.ts'
  */
 
+import { assert } from '../../../asserts/module.f.mjs'
 import { error, ok } from '../../../types/result/module.f.mjs'
 import { fold, next, toArray, concat } from '../../../types/list/module.f.mjs'
 import { setReplace } from '../../../types/ordered_map/module.f.mjs'
 import { fromMap } from '../../../types/object/module.f.mjs'
-import { assertEq } from '../../../asserts/module.f.mjs'
 
-/** @type {(obj: _JsonObject) => (key: string) => _JsonObject} */
+/**
+ * Every syntax error the parser can report is the same one: a token that
+ * cannot follow the state it arrived in. It carries no position or metadata,
+ * so one shared value serves all of them — and no numeric policy either, so
+ * the same value serves every instantiation of the parser.
+ *
+ * @type {_JsonState<never>}
+ */
+const unexpectedToken = { status: 'error', message: 'unexpected token' }
+
+/** @type {<P>(obj: _JsonObject<P>) => (key: string) => _JsonObject<P>} */
 const addKeyToObject =
     obj => key => ({ kind: 'object', values: obj.values, key: key })
 
-/** @type {(obj: _JsonObject) => (value: Unknown) => _JsonObject} */
+/** @type {<P>(obj: _JsonObject<P>) => (value: ParseUnknown<P>) => _JsonObject<P>} */
 const addValueToObject =
     obj => value => ({ kind: 'object', values: setReplace(obj.key)(value)(obj.values), key: '' })
 
-/** @type {(array: _JsonArray) => (value: Unknown) => _JsonArray} */
+/** @type {<P>(array: _JsonArray<P>) => (value: ParseUnknown<P>) => _JsonArray<P>} */
 const addToArray =
     array => value => ({ kind: 'array', values: concat(array.values)([value]) })
 
-/** @type {(state: _StateParse) => (key: string) => _JsonState} */
+/**
+ * `pushKey` only ever runs while parsing the object `startObject` opened
+ * (status `'{'`/`'{,'`), so `state.top` is always that object here — the same
+ * construction guarantee `endArray` relies on below.
+ *
+ * @template P
+ * @param {_StateParse<P>} state
+ * @returns {(key: string) => _JsonState<P>}
+ */
 const pushKey = state => value => {
-    if (state.top?.kind === 'object') { return { status: '{k', top: addKeyToObject(state.top)(value), stack: state.stack } }
-    return { status: 'error', message: 'error' }
+    const { top } = state
+    assert(top !== null && top.kind === 'object', top)
+    return {
+        status: '{k',
+        top: addKeyToObject(top)(value),
+        stack: state.stack,
+    }
 }
 
-/** @type {(state: _StateParse) => (value: Unknown) => _JsonState} */
+/** @type {<P>(state: _StateParse<P>) => (value: ParseUnknown<P>) => _JsonState<P>} */
 const pushValue = state => value => {
     if (state.top === null) { return { status: 'result', value: value } }
     if (state.top.kind === 'array') { return { status: '[v', top: addToArray(state.top)(value), stack: state.stack } }
     return { status: '{v', top: addValueToObject(state.top)(value), stack: state.stack }
 }
 
-/** @type {(state: _StateParse) => _JsonState} */
+/** @type {<P>(state: _StateParse<P>) => _JsonState<P>} */
 const startArray = state => {
     const newStack = state.top === null ? null : { first: state.top, tail: state.stack }
     return { status: '[', top: { kind: 'array', values: null }, stack: newStack }
@@ -54,7 +92,7 @@ const startArray = state => {
  * always as a literal cons, and a lazy pop would leave one unforced thunk per
  * closed container — a chain that overflows the stack when it is finally forced.
  *
- * @type {(stack: _JsonStack) => _StateParse}
+ * @type {<P>(stack: _JsonStack<P>) => _StateParse<P>}
  */
 const popStack = stack => {
     const ne = next(stack)
@@ -67,15 +105,19 @@ const popStack = stack => {
  * `endArray` only ever runs while parsing the array `startArray` opened
  * (status `'['`/`'[v'`), so `state.top` is always that array here.
  *
- * @type {(state: _StateParse) => _JsonState}
+ * @template P
+ * @param {_StateParse<P>} state
+ * @returns {_JsonState<P>}
  */
 const endArray = state => {
-    const array = toArray(/** @type {_JsonArray} */ (state.top).values)
+    const { top } = state
+    assert(top !== null && top.kind === 'array', top)
+    const array = toArray(top.values)
     const newState = popStack(state.stack)
     return pushValue(newState)(array)
 }
 
-/** @type {(state: _StateParse) => _JsonState} */
+/** @type {<P>(state: _StateParse<P>) => _JsonState<P>} */
 const startObject = state => {
     const newStack = state.top === null ? null : { first: state.top, tail: state.stack }
     return { status: '{', top: { kind: 'object', values: null, key: '' }, stack: newStack }
@@ -85,10 +127,14 @@ const startObject = state => {
  * `endObject` only ever runs while parsing the object `startObject` opened
  * (status `'{'`/`'{v'`), so `state.top` is always that object here.
  *
- * @type {(state: _StateParse) => _JsonState}
+ * @template P
+ * @param {_StateParse<P>} state
+ * @returns {_JsonState<P>}
  */
 const endObject = state => {
-    const obj = fromMap(/** @type {_JsonObject} */ (state.top).values)
+    const { top } = state
+    assert(top !== null && top.kind === 'object', top)
+    const obj = fromMap(top.values)
     const newState = popStack(state.stack)
     return pushValue(newState)(obj)
 }
@@ -96,19 +142,27 @@ const endObject = state => {
 /**
  * Only ever called on a token `isValueToken` has already confirmed carries a
  * value, so the switch covers every `_ValueToken` case with no fallback arm.
+ * A number is the one leaf the parser does not know how to build: `policy`
+ * owns that decision and may reject the token.
  *
- * @type {(token: _ValueToken) => Unknown}
+ * @type {<P>(policy: NumberPolicy<P>) => (token: _ValueToken) => Result<ParseUnknown<P>, string>}
  */
-const tokenToValue = token => {
+const tokenToValue = policy => token => {
     switch (token.kind) {
-        case 'null': return null
-        case 'false': return false
-        case 'true': return true
-        case 'number': return parseFloat(token.value)
-        case 'string': return token.value
+        case 'null': return ok(null)
+        case 'false': return ok(false)
+        case 'true': return ok(true)
+        case 'number': return policy(token)
+        case 'string': return ok(token.value)
     }
 }
 
+/** @type {<P>(policy: NumberPolicy<P>) => (state: _StateParse<P>) => (token: _ValueToken) => _JsonState<P>} */
+const pushLeaf = policy => state => token => {
+    const [kind, value] = tokenToValue(policy)(token)
+    return kind === 'error' ? { status: 'error', message: value } : pushValue(state)(value)
+}
+
 /**
  * @param {JsonToken} token
  * @returns {token is _ValueToken}
@@ -124,95 +178,99 @@ const isValueToken = token => {
     }
 }
 
-/** @type {(token: JsonToken) => (state: _StateParse) => _JsonState} */
-const parseValueOp = token => state => {
+/** @type {<P>(policy: NumberPolicy<P>) => (token: JsonToken) => (state: _StateParse<P>) => _JsonState<P>} */
+const parseValueOp = policy => token => state => {
     switch (token.kind) {
         // A value is required here (top level, after `[`+`,`, or after `:`),
         // so `]` is never valid — strict JSON has no trailing commas.
         case ']':
-            return { status: 'error', message: 'unexpected token' }
+            return unexpectedToken
         case '[': return startArray(state)
         case '{': return startObject(state)
         default:
-            if (isValueToken(token)) { return pushValue(state)(tokenToValue(token)) }
-            return { status: 'error', message: 'unexpected token' }
+            if (isValueToken(token)) { return pushLeaf(policy)(state)(token) }
+            return unexpectedToken
     }
 }
 
-/** @type {(token: JsonToken) => (state: _StateParse) => _JsonState} */
-const parseArrayStartOp = token => state => {
-    if (isValueToken(token)) { return pushValue(state)(tokenToValue(token)) }
+/** @type {<P>(policy: NumberPolicy<P>) => (token: JsonToken) => (state: _StateParse<P>) => _JsonState<P>} */
+const parseArrayStartOp = policy => token => state => {
+    if (isValueToken(token)) { return pushLeaf(policy)(state)(token) }
     if (token.kind === '[') { return startArray(state) }
     if (token.kind === ']') { return endArray(state) }
     if (token.kind === '{') { return startObject(state) }
-    return { status: 'error', message: 'unexpected token' }
+    return unexpectedToken
 }
 
-/** @type {(token: JsonToken) => (state: _StateParse) => _JsonState} */
+/** @type {<P>(token: JsonToken) => (state: _StateParse<P>) => _JsonState<P>} */
 const parseArrayValueOp = token => state => {
     if (token.kind === ']') { return endArray(state) }
     if (token.kind === ',') { return { status: '[,', top: state.top, stack: state.stack } }
-    return { status: 'error', message: 'unexpected token' }
+    return unexpectedToken
 }
 
-/** @type {(token: JsonToken) => (state: _StateParse) => _JsonState} */
+/** @type {<P>(token: JsonToken) => (state: _StateParse<P>) => _JsonState<P>} */
 const parseObjectStartOp = token => state => {
     if (token.kind === 'string') { return pushKey(state)(token.value) }
     if (token.kind === '}') { return endObject(state) }
-    return { status: 'error', message: 'unexpected token' }
+    return unexpectedToken
 }
 
-/** @type {(token: JsonToken) => (state: _StateParse) => _JsonState} */
+/** @type {<P>(token: JsonToken) => (state: _StateParse<P>) => _JsonState<P>} */
 const parseObjectKeyOp = token => state => {
     if (token.kind === ':') { return { status: '{:', top: state.top, stack: state.stack } }
-    return { status: 'error', message: 'unexpected token' }
+    return unexpectedToken
 }
 
-/** @type {(token: JsonToken) => (state: _StateParse) => _JsonState} */
+/** @type {<P>(token: JsonToken) => (state: _StateParse<P>) => _JsonState<P>} */
 const parseObjectNextOp = token => state => {
     if (token.kind === '}') { return endObject(state) }
     if (token.kind === ',') { return { status: '{,', top: state.top, stack: state.stack } }
-    return { status: 'error', message: 'unexpected token' }
+    return unexpectedToken
 }
 
-/** @type {(token: JsonToken) => (state: _StateParse) => _JsonState} */
+/** @type {<P>(token: JsonToken) => (state: _StateParse<P>) => _JsonState<P>} */
 const parseObjectCommaOp = token => state => {
     // After a `,` a member (string key) is required — `}` here would be a
     // trailing comma, which strict JSON rejects.
     if (token.kind === 'string') { return pushKey(state)(token.value) }
-    return { status: 'error', message: 'unexpected token' }
+    return unexpectedToken
 }
 
-/** @type {Fold<JsonToken, _JsonState>} */
-const foldOp = token => state => {
+/** @type {<P>(policy: NumberPolicy<P>) => Fold<JsonToken, _JsonState<P>>} */
+const foldOp = policy => token => state => {
     if (token.kind === 'eof')
         return state
 
     switch (state.status) {
-        case 'result': return { status: 'error', message: 'unexpected token' }
+        case 'result': return unexpectedToken
         case 'error': return { status: 'error', message: state.message }
-        case '': return parseValueOp(token)(state)
-        case '[': return parseArrayStartOp(token)(state)
+        case '': return parseValueOp(policy)(token)(state)
+        case '[': return parseArrayStartOp(policy)(token)(state)
         case '[v': return parseArrayValueOp(token)(state)
-        case '[,': return parseValueOp(token)(state)
+        case '[,': return parseValueOp(policy)(token)(state)
         case '{': return parseObjectStartOp(token)(state)
         case '{k': return parseObjectKeyOp(token)(state)
-        case '{:': return parseValueOp(token)(state)
+        case '{:': return parseValueOp(policy)(token)(state)
         case '{v': return parseObjectNextOp(token)(state)
         case '{,': return parseObjectCommaOp(token)(state)
     }
 }
 
 /**
- * Parses a list of JSON tokens into a JSON-compatible value.
+ * Parses a list of JSON tokens into the value domain `policy` materializes
+ * numbers into.
  *
  * Returns `ok` with the parsed value on success, or `error` with a message
- * when the token sequence is invalid or incomplete.
+ * when the token sequence is invalid or incomplete — or when `policy` rejects
+ * a number token that its domain cannot represent.
  *
- * @type {(tokenList: List<JsonToken>) => Result<Unknown, string>}
+ * @type {<P>(policy: NumberPolicy<P>) => (tokenList: List<JsonToken>) => Result<ParseUnknown<P>, string>}
  */
-export const parse = tokenList => {
-    const state = fold(foldOp)({ status: '', top: null, stack: null })(tokenList)
+export const parse = policy => tokenList => {
+    /** @type {_JsonState<never>} */
+    const init = { status: '', top: null, stack: null }
+    const state = fold(foldOp(policy))(init)(tokenList)
     switch (state.status) {
         case 'result': return ok(state.value)
         case 'error': return error(state.message)
@@ -220,17 +278,3 @@ export const parse = tokenList => {
     }
 }
 
-export const proof = {
-    pushKey: {
-        // `pushKey` is only ever invoked while `state.top` is an object (the
-        // state machine's `'{'`/`'{,'` statuses guarantee it), so its
-        // non-object guard is a defensive branch unreachable through `parse`.
-        // Call it directly to cover that branch.
-        nonObjectTop: () => {
-            /** @type {_StateParse} */
-            const state = { status: '[', top: { kind: 'array', values: null }, stack: null }
-            const result = pushKey(state)('key')
-            assertEq(result.status, 'error')
-        },
-    },
-}