functionalscript 0.44.0 → 0.46.0

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 } 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 } 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)
@@ -63,39 +101,72 @@ const popStack = stack => {
         : { status: '', top: ne.first, stack: ne.tail }
 }
 
-/** @type {(state: _StateParse) => _JsonState} */
+/**
+ * `endArray` only ever runs while parsing the array `startArray` opened
+ * (status `'['`/`'[v'`), so `state.top` is always that array here.
+ *
+ * @template P
+ * @param {_StateParse<P>} state
+ * @returns {_JsonState<P>}
+ */
 const endArray = state => {
-    const array = state.top !== null ? toArray(state.top.values) : null
+    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 }
 }
 
-/** @type {(state: _StateParse) => _JsonState} */
+/**
+ * `endObject` only ever runs while parsing the object `startObject` opened
+ * (status `'{'`/`'{v'`), so `state.top` is always that object here.
+ *
+ * @template P
+ * @param {_StateParse<P>} state
+ * @returns {_JsonState<P>}
+ */
 const endObject = state => {
-    const obj = state.top?.kind === 'object' ? fromMap(state.top.values) : null
+    const { top } = state
+    assert(top !== null && top.kind === 'object', top)
+    const obj = fromMap(top.values)
     const newState = popStack(state.stack)
     return pushValue(newState)(obj)
 }
 
-/** @type {(token: JsonToken) => Unknown} */
-const tokenToValue = token => {
+/**
+ * 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 {<P>(policy: NumberPolicy<P>) => (token: _ValueToken) => Result<ParseUnknown<P>, string>}
+ */
+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
-        default: return null
+        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 {(token: JsonToken) => boolean} */
+/** @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}
+ */
 const isValueToken = token => {
     switch (token.kind) {
         case 'null':
@@ -107,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)
@@ -203,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')
-        },
-    },
-}

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

@@ -1,8 +1,13 @@
 /**
  * @import { JsonToken } from '../tokenizer/types.ts'
+ * @import { NumberPolicy } from './types.ts'
  */
 export declare const proof: {
     valid: (() => void)[];
     invalid: (() => void)[];
     siblingContainers: (() => void)[];
+    policy: {
+        exactLexeme: () => void;
+        rejected: () => void;
+    };
 };

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

@@ -1,18 +1,26 @@
 /**
  * @import { JsonToken } from '../tokenizer/types.ts'
+ * @import { NumberPolicy } from './types.ts'
  */
 
-import { parse } from './module.f.mjs'
+import { parse as parseWithPolicy } from './module.f.mjs'
 import { tokenize } from '../tokenizer/module.f.mjs'
 import { toArray } from '../../../types/list/module.f.mjs'
 import { stringify as jsonStringify } from '../module.f.mjs'
 import { sort } from '../../../types/object/module.f.mjs'
 import { stringToList } from '../../../text/utf16/module.f.mjs'
+import { error, ok } from '../../../types/result/module.f.mjs'
 import { assertEq } from '../../../asserts/module.f.mjs'
 
 /** @type {(s: string) => readonly JsonToken[]} */
 const tokenizeString = s => toArray(tokenize(stringToList(s)))
 
+/** The structural machine is proved through the ordinary `number` policy. */
+/** @type {NumberPolicy<number>} */
+const numberPolicy = token => ok(parseFloat(token.value))
+
+const parse = parseWithPolicy(numberPolicy)
+
 const stringify = jsonStringify(sort)
 
 export const proof = {
@@ -311,4 +319,26 @@ export const proof = {
             assertEq(Array.isArray(value) ? value.length : -1, 12000)
         },
     ],
+    // The numeric policy is the parser's only opinion about numbers: it is
+    // handed the token, so it reads the exact lexeme, and it may reject one.
+    policy: {
+        // the lexeme reaches the policy unrounded — `1.0`, `1e0` and `1` are
+        // one `number` but three tokens
+        exactLexeme: () => {
+            /** @type {NumberPolicy<string>} */
+            const lexemePolicy = token => ok(token.value)
+            const [tag, value] = parseWithPolicy(lexemePolicy)(tokenizeString('[1.0,1e0,1,-0]'))
+            assertEq(tag, 'ok')
+            assertEq(stringify(value), '["1.0","1e0","1","-0"]')
+        },
+        // a policy that cannot represent the number fails the parse as an
+        // ordinary `Result`, with its own message
+        rejected: () => {
+            /** @type {NumberPolicy<never>} */
+            const rejectPolicy = () => error('no numbers here')
+            const [tag, message] = parseWithPolicy(rejectPolicy)(tokenizeString('{"a":[1]}'))
+            assertEq(tag, 'error')
+            assertEq(message, 'no numbers here')
+        },
+    },
 }

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

@@ -1,34 +1,58 @@
 /**
- * Internal state types for the JSON parser.
+ * Types for the shared structural JSON parser: its numeric policy, the tree
+ * that policy produces, and the parser's internal state.
  *
  * @module
  */
-import type { Unknown } from '../types.ts';
+import type { Tree } from '../types.ts';
 import type { OrderedMap } from '../../../types/ordered_map/types.ts';
 import type { List } from '../../../types/list/types.ts';
-export type _JsonObject = {
+import type { Result } from '../../../types/result/types.ts';
+import type { JsonToken } from '../tokenizer/types.ts';
+import type { NumberToken } from '../../../js/tokenizer/types.ts';
+/** JSON tokens that carry a directly-usable value. */
+export type _ValueToken = Extract<JsonToken, {
+    readonly kind: 'null' | 'false' | 'true' | 'string' | 'number';
+}>;
+/**
+ * A numeric policy: how one codec materializes a JSON number token into its
+ * own numeric domain `P`.
+ *
+ * The policy is handed the token itself, so it decides from the exact lexeme —
+ * before any narrowing the parser might otherwise have imposed. It may fail:
+ * a valid JSON number can be outside the domain the codec offers (the extended
+ * codec has no non-finite `number`), and that has to be an ordinary parse
+ * error rather than an escaping runtime exception.
+ */
+export type NumberPolicy<P> = (token: NumberToken) => Result<P, string>;
+/**
+ * The tree a numeric policy `P` parses into: JSON's containers over `P` plus
+ * the primitives every policy shares.
+ */
+export type ParseUnknown<P> = Tree<P | null | boolean | string>;
+export type _JsonObject<P> = {
     readonly kind: 'object';
-    readonly values: OrderedMap<Unknown>;
+    readonly values: OrderedMap<ParseUnknown<P>>;
     readonly key: string;
 };
-export type _JsonArray = {
+export type _JsonArray<P> = {
     readonly kind: 'array';
-    readonly values: List<Unknown>;
+    readonly values: List<ParseUnknown<P>>;
 };
-type _JsonStackElement = _JsonObject | _JsonArray;
-export type _JsonStack = List<_JsonStackElement>;
-export type _StateParse = {
+type _JsonStackElement<P> = _JsonObject<P> | _JsonArray<P>;
+export type _JsonStack<P> = List<_JsonStackElement<P>>;
+export type _StateParse<P> = {
     readonly status: '' | '[' | '[v' | '[,' | '{' | '{k' | '{:' | '{v' | '{,';
-    readonly top: _JsonStackElement | null;
-    readonly stack: _JsonStack;
+    readonly top: _JsonStackElement<P> | null;
+    readonly stack: _JsonStack<P>;
 };
-type _StateResult = {
+type _StateResult<P> = {
     readonly status: 'result';
-    readonly value: Unknown;
+    readonly value: ParseUnknown<P>;
 };
 type _StateError = {
     readonly status: 'error';
     readonly message: string;
 };
-export type _JsonState = _StateParse | _StateResult | _StateError;
+export type _JsonState<P> = _StateParse<P> | _StateResult<P> | _StateError;
 export {};

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

@@ -8,7 +8,7 @@
  * `typeof`. That spelling is deliberate: `@type {const}` also type-checks here,
  * but leaves declaration emit no name for the recursive positions, so it
  * inlines the structure, gives up at depth, and degrades the emitted `.d.mts`
- * to `any`. See AGENTS.md §6.2.
+ * to `any`. See `fjs/AGENTS.md` §3.2.
  *
  * The TypeScript counterparts live in the sibling
  * [`../types.ts`](../types.ts), which pins them against these schemas with

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

@@ -8,7 +8,7 @@
  * `typeof`. That spelling is deliberate: `@type {const}` also type-checks here,
  * but leaves declaration emit no name for the recursive positions, so it
  * inlines the structure, gives up at depth, and degrades the emitted `.d.mts`
- * to `any`. See AGENTS.md §6.2.
+ * to `any`. See `fjs/AGENTS.md` §3.2.
  *
  * The TypeScript counterparts live in the sibling
  * [`../types.ts`](../types.ts), which pins them against these schemas with

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

@@ -2,6 +2,9 @@
  * Proof for the JSON rtti schemas.
  *
  * @module
+ *
+ * @import { ValidateE } from '../../../types/rtti/common/types.ts'
+ * @import { Unknown } from '../../../types/rtti/ts/types.ts'
  */
 export declare const proof: {
     primitive: {

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

@@ -2,26 +2,26 @@
  * Proof for the JSON rtti schemas.
  *
  * @module
+ *
+ * @import { ValidateE } from '../../../types/rtti/common/types.ts'
+ * @import { Unknown } from '../../../types/rtti/ts/types.ts'
  */
 
 import { assertEq } from '../../../asserts/module.f.mjs'
-import { validate } from '../../../types/rtti/validate/module.f.mjs'
+import { parse } from '../../../types/rtti/parse/module.f.mjs'
 import { primitive, unknown, object, array } from './module.f.mjs'
 
-/** @import { ValidateE } from '../../../types/rtti/common/types.ts' */
-/** @import { Unknown } from '../../../types/rtti/ts/types.ts' */
-
-// Reduces a validation to its `ok`/`error` tag: these schemas are about what is
-// accepted, not about the payload, which validation returns unchanged. The
-// erased `ValidateE` keeps the shared helper from re-instantiating each
-// schema's deep recursive result type (TS2589).
+// Reduces a parse to its `ok`/`error` tag: these schemas are about what is
+// accepted, not about the payload `parse` rebuilds. The erased `ValidateE`
+// keeps the shared helper from re-instantiating each schema's deep recursive
+// result type (TS2589).
 /** @type {(v: ValidateE) => (value: Unknown) => string} */
 const tag = v => value => v(value)[0]
 
-const primitiveAccepts = tag(validate(primitive))
-const unknownAccepts = tag(validate(unknown))
-const objectAccepts = tag(validate(object))
-const arrayAccepts = tag(validate(array))
+const primitiveAccepts = tag(parse(primitive))
+const unknownAccepts = tag(parse(unknown))
+const objectAccepts = tag(parse(object))
+const arrayAccepts = tag(parse(array))
 
 export const proof = {
     primitive: {