functionalscript 0.44.0 → 0.46.0

package/fjs/mcp/proof.f.mjs

@@ -1,42 +1,37 @@
-/** @import { Unknown } from '../media/json/types.ts' */
+/**
+ * @import { Unknown } from '../media/json/types.ts'
+ * @import { Operation } from '../effects/types.ts'
+ * @import { Response } from '../protocol/json_rpc/types.ts'
+ * @import { Handle } from '../protocol/mcp/types.ts'
+ * @import { Vec } from '../types/bit_vec/types.ts'
+ * @import { FileCasOperation } from '../cas/types.ts'
+ * @import { List } from '../effects/list/types.ts'
+ * @import { Effect } from '../effects/types.ts'
+ * @import { ContentItem, ToolsCallResult } from '../protocol/mcp/types.ts'
+ * @import { IoChannel, Mkdir, Now, RandomInt, ReadBytes, Rename } from '../effects/node/types.ts'
+ * @import { Dir } from '../effects/node/virtual/types.ts'
+ */
 
 import { assert, assertEq } from '../asserts/module.f.mjs'
-import { pure, step } from '../effects/module.f.mjs'
-/** @import { Effect, Operation } from '../effects/types.ts' */
+import { pureOk, step } from '../effects/module.f.mjs'
 import { create } from '../effects/memory/module.f.mjs'
 import { parse as parseJson } from '../media/json/module.f.mjs'
 import { number as rttiNumber, option, string as rttiString } from '../types/rtti/module.f.mjs'
 import { parse as rttiParse } from '../types/rtti/parse/module.f.mjs'
-/** @import { Response } from '../protocol/json_rpc/types.ts' */
-/** @import { Vec } from '../types/bit_vec/types.ts' */
 import { msb, u8ListToVec, vec8, repeat, length, maxLengthBytes } from '../types/bit_vec/module.f.mjs'
 import { vecToCBase32 } from '../basen/cbase32/module.f.mjs'
 import { encode as base64Encode } from '../basen/base64/module.f.mjs'
 import { utf8 } from '../text/module.f.mjs'
 import { fileCas } from '../cas/module.f.mjs'
-/** @import { FileCasOperation } from '../cas/types.ts' */
 import { dialect as revisionDialect, mediaType as revisionMediaType } from '../media/revision/module.f.mjs'
 import { sha256 } from '../crypto/sha2/module.f.mjs'
 import { nonEmpty, empty as elEmpty } from '../effects/list/module.f.mjs'
-/** @import { List } from '../effects/list/types.ts' */
 import {
     mcpStep, uninitializedState,
 } from '../protocol/mcp/module.f.mjs'
-/** @import { McpSessionState, ToolsCallResult } from '../protocol/mcp/types.ts' */
-/**
- * @import {
- *   IoResult,
- *   Mkdir,
- *   Now,
- *   RandomInt,
- *   ReadBytes,
- *   Rename,
- * } from '../effects/node/types.ts'
- */
 import { emptyState, virtual } from '../effects/node/virtual/module.f.mjs'
-/** @import { Dir } from '../effects/node/virtual/types.ts' */
 import { casConfig, casMcpHandlers } from './module.f.mjs'
-import { ok as resultOk, unwrap } from '../types/result/module.f.mjs'
+import { ok as resultOk, unwrap, unwrap as unwrapResult } from '../types/result/module.f.mjs'
 import { stdioTransport } from '../protocol/mcp/stdio/module.f.mjs'
 import { fromVec } from '../types/uint8array/module.f.mjs'
 import { initEvo } from '../cas/evo/module.f.mjs'
@@ -62,14 +57,16 @@ const parseCasGetResult = rttiParse(casGetResult)
 // Feeds each message to `handler` in order, collecting every response.
 /**
  * @template {Operation} O
- * @param {(v: Unknown) => Effect<O, Response | null>} handler
- * @returns {(msgs: readonly unknown[]) => Effect<O, readonly unknown[]>}
+ * @param {Handle<O>} handler
+ * @returns {(msgs: readonly unknown[]) => Effect<O, readonly unknown[], never>}
  */
 const feed = handler => msgs => {
-    /** @type {(i: number, acc: readonly unknown[]) => Effect<O, readonly unknown[]>} */
+    /** @type {(i: number, acc: readonly unknown[]) => Effect<O, readonly unknown[], never>} */
     const go = (i, acc) => (
         i === msgs.length
-            ? pure(acc)
+            ? pureOk(acc)
+            // The channel stays `never`: a `Handle` has absorbed its own
+            // failures into the response, so every message contributes one.
             : step(
                 handler(/** @type {Unknown} */ (msgs[i])),
                 r => go(i + 1, [...acc, r]))
@@ -88,11 +85,10 @@ const runSessionVirtual =
             initEvo(fileCas(sha256)(home)),
             cacheKey => step(
                 create(uninitializedState),
-                sessionKey => {
-                    const step = mcpStep(casConfig)(casMcpHandlers(home)(cacheKey))(sessionKey)
-                    return feed(step)(msgs)
-                }))
-        return virtual({ ...emptyState, root })(effect)[1]
+                sessionKey => feed(mcpStep(casConfig)(casMcpHandlers(home)(cacheKey))(sessionKey))(msgs)))
+        // A proof has nobody to report a channel failure to, so it panics: the
+        // session either ran or the test is meaningless.
+        return unwrapResult(virtual({ ...emptyState, root })(effect)[1])
     }
 
 // Seeds a blob directly into the virtual store via `c.write`, bypassing the
@@ -105,8 +101,8 @@ const runSessionVirtual =
 const seedBlob = (root, home = '/home/user') => chunks => {
     const c = fileCas(sha256)(home)
     const stream = chunks.reduceRight(
-        (/** @type {List<never, IoResult<Vec>>} */ tail, chunk) => nonEmpty(resultOk(chunk), tail),
-        /** @type {List<never, IoResult<Vec>>} */ (elEmpty()))
+        (/** @type {List<never, Vec, IoChannel>} */ tail, chunk) => nonEmpty(chunk, tail),
+        /** @satisfies {List<never, Vec, IoChannel>} */ (elEmpty()))
     const [state, result] = virtual({ ...emptyState, root })(c.write(stream))
     assert(result[0] === 'ok', result)
     return [state.root, vecToCBase32(result[1])]
@@ -150,7 +146,7 @@ const runStdio =
         const effect = step(
             initEvo(fileCas(sha256)(home)),
             cacheKey => step(
-                create(/** @type {McpSessionState} */ (uninitializedState)),
+                create(uninitializedState),
                 sessionKey =>
                     stdioTransport(mcpStep(casConfig)(casMcpHandlers(home)(cacheKey))(sessionKey))
             )
@@ -161,15 +157,80 @@ const runStdio =
         return stdout.split('\n').filter(line => line.length > 0).slice(1).map(line => unwrap(parseJson(line)))
     }
 
+/**
+ * The `result` of a `tools/call` response.
+ *
+ * This is the one place a response crosses from `unknown` to a typed
+ * {@link ToolsCallResult}. The structural essentials are checked here so the
+ * accessors below — and every call site — do not have to assume them; only the
+ * final step from a checked `content` array to `ToolsCallResult` is taken on
+ * trust, because rtti's `parse` reads `Unknown`, and getting there from
+ * `unknown` is the same problem one level down.
+ */
 /** @type {(resp: unknown) => ToolsCallResult} */
-const resultOf = resp =>
-    /** @type {{ readonly result: ToolsCallResult }} */ (resp).result
+const resultOf = resp => {
+    assert(typeof resp === 'object' && resp !== null && 'result' in resp, resp)
+    const { result } = resp
+    assert(typeof result === 'object' && result !== null && 'content' in result, result)
+    const { content } = result
+    assert(content instanceof Array, content)
+    return /** @type {ToolsCallResult} */ (result)
+}
 
-/** @type {(resp: unknown) => unknown} */
-const item0 = resp => resultOf(resp).content[0]
+/** @type {(resp: unknown) => ContentItem} */
+const item0 = resp => {
+    const [item] = resultOf(resp).content
+    assert(item !== undefined, resp)
+    return item
+}
 
 /** @type {(resp: unknown) => string} */
-const textOf = resp => (/** @type {{ readonly text: string }} */ (item0(resp))).text
+const textOf = resp => {
+    const item = item0(resp)
+    assert(item.type === 'text', item)
+    return item.text
+}
+
+// The accessors below read a response that is `unknown` at this boundary. They
+// check their way in rather than casting, so a malformed response fails at the
+// read with the offending value attached.
+
+/** Whether `resp` is an object carrying `key`. */
+/** @type {(resp: unknown, key: 'error' | 'result') => boolean} */
+const has = (resp, key) => typeof resp === 'object' && resp !== null && key in resp
+
+/** @type {(resp: unknown) => number} */
+const errorCode = resp => {
+    assert(typeof resp === 'object' && resp !== null && 'error' in resp, resp)
+    const { error } = resp
+    assert(typeof error === 'object' && error !== null && 'code' in error, error)
+    const { code } = error
+    assert(typeof code === 'number', code)
+    return code
+}
+
+/** @type {(resp: unknown) => unknown} */
+const idOf = resp => {
+    assert(typeof resp === 'object' && resp !== null && 'id' in resp, resp)
+    return resp.id
+}
+
+/** The `name` and `inputSchema.type` of each tool in a `tools/list` result. */
+/** @type {(resp: unknown) => readonly { readonly name: string, readonly schemaType: unknown }[]} */
+const toolsOf = resp => {
+    assert(typeof resp === 'object' && resp !== null && 'result' in resp, resp)
+    const { result } = resp
+    assert(typeof result === 'object' && result !== null && 'tools' in result, result)
+    const { tools } = result
+    assert(tools instanceof Array, tools)
+    return tools.map(t => {
+        assert(typeof t === 'object' && t !== null && 'name' in t && 'inputSchema' in t, t)
+        const { name, inputSchema } = t
+        assert(typeof name === 'string', name)
+        assert(typeof inputSchema === 'object' && inputSchema !== null && 'type' in inputSchema, inputSchema)
+        return { name, schemaType: inputSchema.type }
+    })
+}
 
 /** The `text` payload of a `cas_get` response, parsed and checked against {@link casGetResult}. */
 const casGetResultOf = (/** @type {unknown} */ resp) =>
@@ -183,12 +244,12 @@ const textSample = 'hello, world!'
 const revisionSample = `{"dialect":"${revisionDialect}","subject":"8","parents":[],"snapshot":"8","generation":0}`
 
 // A base64-encoded binary payload for binary add→get round-trips.
-const binarySample = /** @type {string} */ (base64Encode(vec8(0x2An)))
+const binarySample = base64Encode(vec8(0x2An))
 
 // A base64 blob whose leading bytes are the PNG magic-byte signature, so
 // `cas_get` detects its type and returns base64 with mimeType image/png.
-const pngSample = /** @type {string} */ (base64Encode(
-    u8ListToVec(msb)([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x01])))
+const pngSample = base64Encode(
+    u8ListToVec(msb)([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x01]))
 
 // Returns the RFC 4648 base64 encoding of `n` zero bytes, computed directly
 // without bigint arithmetic — independent of `base64.encode` so these tests
@@ -216,10 +277,10 @@ const largeMultiChunkBlobMeta =
     (/** @type {Vec} */ chunk0, /** @type {Vec} */ chunk1, /** @type {string} */ expectedType,
         /** @type {string} */ expectedMime) => () => {
         const [root, hash] = seedBlob({})([chunk0, chunk1])
-        const [metaResp] = /** @type {readonly unknown[]} */ (runSessionVirtual(root)([
+        const [metaResp] = runSessionVirtual(root)([
             init, initialized,
             call(2, 'cas_get', { hash }),
-        ]).slice(2))
+        ]).slice(2)
         assert(!resultOf(metaResp).isError)
         const meta = casGetResultOf(metaResp)
         assertEq(meta.type, expectedType)
@@ -272,10 +333,10 @@ export const proof = {
     // buffered inline. The metadata-only path (above) still returns its size/type.
     getContentLargeBlobTooLargeError: () => {
         const [root, hash] = seedBlob({})([asciiChunk, asciiChunk])
-        const [getResp] = /** @type {readonly unknown[]} */ (runSessionVirtual(root)([
+        const [getResp] = runSessionVirtual(root)([
             init, initialized,
             call(2, 'cas_get', { hash, content: true }),
-        ]).slice(2))
+        ]).slice(2)
         assertEq(resultOf(getResp).isError, true)
         const text = textOf(getResp)
         assert(text.includes('too large'))
@@ -309,9 +370,8 @@ export const proof = {
         const [getResp] = runStdio(root)([
             call(2, 'cas_get', { hash, content: true }),
         ])
-        const err = /** @type {{ readonly error?: { readonly code: number }, readonly id: unknown }} */ (getResp)
-        assertEq(err.error?.code, -32603)
-        assertEq(err.id, 2)
+        assertEq(errorCode(getResp), -32603)
+        assertEq(idOf(getResp), 2)
     },
 
     // The paired boundary case: a blob whose base64 inflation leaves enough
@@ -344,19 +404,18 @@ export const proof = {
         const [getResp] = runStdio(root)([
             call(2, 'cas_get', { hash, content: true }),
         ])
-        const err = /** @type {{ readonly error?: { readonly code: number }, readonly id: unknown }} */ (getResp)
-        assertEq(err.error?.code, -32603)
-        assertEq(err.id, 2)
+        assertEq(errorCode(getResp), -32603)
+        assertEq(idOf(getResp), 2)
     },
 
     toolsListAdvertisesSevenTools: () => {
         const [resp] = runSessionVirtual({})([init, initialized, list(2)]).slice(2)
-        const tools = (/** @type {{ result: { tools: readonly { name: string }[] } }} */ (resp)).result.tools
+        const tools = toolsOf(resp)
         assertEq(tools.length, 7)
         assertEq(tools.map(t => t.name).join(','), 'cas_add,cas_get,cas_list,evo_list,evo_head,evo_revision,evo_add')
-        const add = (/** @type {{ result: { tools: readonly { inputSchema: { type?: string } }[] } }} */ (resp))
-            .result.tools[0]
-        assertEq(add.inputSchema.type, 'object')
+        const [add] = tools
+        assert(add !== undefined, tools)
+        assertEq(add.schemaType, 'object')
     },
 
     // The same server also exposes Evo (fjs/cas/evo): add a revision, then
@@ -483,7 +542,7 @@ export const proof = {
             call(2, 'cas_add', { content: textSample }),
             call(3, 'cas_get', { hash, content: true }),
         )
-        assertEq(item0(getResp) === null ? null : (/** @type {{ type: string }} */ (item0(getResp))).type, 'text')
+        assertEq(item0(getResp).type, 'text')
         const result = casGetResultOf(getResp)
         assertEq(result.type, 'text')
         assertEq(result.mimeType, 'text/plain')
@@ -498,7 +557,7 @@ export const proof = {
             call(3, 'cas_get', { hash, content: true }),
         )
         assert(!resultOf(getResp).isError)
-        assertEq((/** @type {{ type: string }} */ (item0(getResp))).type, 'text')
+        assertEq(item0(getResp).type, 'text')
         const result = casGetResultOf(getResp)
         assertEq(result.type, 'base64')
         assertEq(result.mimeType, 'image/png')
@@ -627,8 +686,8 @@ export const proof = {
 
     toolErrorIsNotJsonRpcError: () => {
         const [resp] = session(call(2, 'cas_add', { content: 'not valid!', type: 'base64' }))
-        assert(!('error' in /** @type {object} */ (resp)))
-        assert('result' in /** @type {object} */ (resp))
+        assert(!has(resp, 'error'), resp)
+        assert(has(resp, 'result'), resp)
     },
 
     // cas_get without content:true returns only metadata.
@@ -664,7 +723,7 @@ export const proof = {
 
     getMetaOctetStreamForUnknownBinary: () => {
         const binaryContent = u8ListToVec(msb)([0xFF, 0xFE, 0x00, 0x01])
-        const binaryB64 = /** @type {string} */ (base64Encode(binaryContent))
+        const binaryB64 = base64Encode(binaryContent)
         const [addResp] = session(call(2, 'cas_add', { content: binaryB64, type: 'base64' }))
         const hash = textOf(addResp)
         const [, metaResp] = session(
@@ -682,7 +741,7 @@ export const proof = {
     // base64/octet-stream, not text/plain.
     getMetaOctetStreamForNulBlob: () => {
         const nulContent = u8ListToVec(msb)([0x00, 0x00, 0x00])
-        const nulB64 = /** @type {string} */ (base64Encode(nulContent))
+        const nulB64 = base64Encode(nulContent)
         const [addResp] = session(call(2, 'cas_add', { content: nulB64, type: 'base64' }))
         const hash = textOf(addResp)
         const [, metaResp] = session(
@@ -709,7 +768,7 @@ export const proof = {
     // cas_get with content:true on octet-stream (no magic bytes, not UTF-8) returns inline base64.
     getOctetStreamWithContentIncludesBase64: () => {
         const binaryContent = u8ListToVec(msb)([0xFF, 0xFE, 0x00, 0x01])
-        const binaryB64 = /** @type {string} */ (base64Encode(binaryContent))
+        const binaryB64 = base64Encode(binaryContent)
         const [addResp] = session(call(2, 'cas_add', { content: binaryB64, type: 'base64' }))
         const hash = textOf(addResp)
         const [, getResp] = session(

package/fjs/media/html/module.f.d.mts

@@ -1,3 +1,15 @@
+/**
+ * HTML serialization helpers: `Element`/`Attributes` builders, void-tag
+ * handling, attribute/text escaping, and a UTF-8 emitter for full documents.
+ * See `./types.ts` for the `Element`/`Node` type-level API.
+ *
+ * @module
+ *
+ * @import { List } from '../../types/list/types.ts'
+ * @import { Entry, StringMap } from '../../types/object/types.ts'
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { Element, Node } from './types.ts'
+ */
 import type { List } from '../../types/list/types.ts';
 import type { StringMap } from '../../types/object/types.ts';
 import type { Vec } from '../../types/bit_vec/types.ts';

package/fjs/media/html/module.f.mjs

@@ -4,19 +4,21 @@
  * See `./types.ts` for the `Element`/`Node` type-level API.
  *
  * @module
+ *
+ * @import { List } from '../../types/list/types.ts'
+ * @import { Entry, StringMap } from '../../types/object/types.ts'
+ * @import { Vec } from '../../types/bit_vec/types.ts'
+ * @import { Element, Node } from './types.ts'
  */
-/** @import { List } from '../../types/list/types.ts' */
+
 import { map, flatMap, flat, concat as listConcat } from '../../types/list/module.f.mjs'
 import { concat, concat as stringConcat } from '../../types/string/module.f.mjs'
 import { definedEntries } from '../../types/object/module.f.mjs'
-/** @import { Entry, StringMap } from '../../types/object/types.ts' */
 import { compose } from '../../types/function/module.f.mjs'
 import { stringToList } from '../../text/utf16/module.f.mjs'
 import { includes } from '../../types/array/module.f.mjs'
-/** @import { Vec } from '../../types/bit_vec/types.ts' */
 import { utf8 } from '../../text/module.f.mjs'
 import { quotationMark, ampersand, lessThanSign, greaterThanSign } from '../../text/ascii/module.f.mjs'
-/** @import { Element, Node } from './types.ts' */
 
 const { fromCharCode } = String
 
@@ -65,7 +67,7 @@ const escapeTable = /** @type {const} */ ({
 
 /** @type {(code: number) => string} */
 const escapeCharCode = code =>
-    escapeTable[/** @type {keyof typeof escapeTable} */ (code)] ?? fromCharCode(code)
+    escapeTable[code] ?? fromCharCode(code)
 
 const escape = compose(stringToList)(map(escapeCharCode))
 

package/fjs/media/html/proof.f.d.mts

@@ -1,3 +1,6 @@
+/**
+ * @import { Element } from './types.ts'
+ */
 export declare const proof: {
     empty: () => void;
     empty2: () => void;

package/fjs/media/html/proof.f.mjs

@@ -1,5 +1,8 @@
+/**
+ * @import { Element } from './types.ts'
+ */
+
 import { htmlToString } from "./module.f.mjs"
-/** @import { Element } from './types.ts' */
 import { assertEq } from '../../asserts/module.f.mjs'
 
 export const proof = {

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

@@ -0,0 +1,82 @@
+/**
+ * Extended JSON: the ordinary JSON data model with `bigint` added to the
+ * primitive leaves, so bare integer syntax survives a parse exactly.
+ *
+ * It is a runtime representation, not a syntax. `stringify` emits ordinary,
+ * valid JSON text — there is no `123n` literal, tagged object, or
+ * quoted-integer convention — and ordinary JavaScript consumers of that text
+ * are free to read it back into whatever numeric representation they use,
+ * `JSON.parse`'s `number` included. What the extended codec adds is that
+ * *this* codec reads it back into the same runtime value it wrote.
+ *
+ * ### Parse
+ *
+ * The split is lexical, not mathematical: **a token containing `.` or `e` /
+ * `E` is a `number`, even when its value is an integer.**
+ *
+ * ```text
+ * 123    -> 123n        -123   -> -123n      0     -> 0n
+ * -0     -> -0          1.5    -> 1.5        1.0   -> 1
+ * 1e3    -> 1000        1E3    -> 1000
+ * ```
+ *
+ * `-0` is the exception to bare integer syntax: `bigint` has no negative zero,
+ * so keeping it as a `number` is what preserves the sign the JSON text spells.
+ *
+ * The extended domain is exact where it claims to be, so it rejects rather
+ * than rounds: a token whose value is outside the finite `number` range
+ * (`1e400`) is a parse `error`, not `Infinity`. Ordinary rounding within that
+ * range is inherent to `number` and is not an error — `1e-400` is `0`, and
+ * `0.1` is the nearest double, as everywhere else.
+ *
+ * ### Serialize
+ *
+ * Spelling follows the runtime type of the leaf, so parsing the output returns
+ * the value that was written:
+ *
+ * ```text
+ * 0n -> 0     -> 0n        3n -> 3    -> 3n
+ * 0  -> 0.0   -> 0         3  -> 3.0  -> 3
+ * -0 -> -0    -> -0
+ * ```
+ *
+ * A `bigint` is always its full base-10 digits, **never** exponent notation,
+ * however large: exponent syntax belongs to the `number` side and would parse
+ * back as one. A whole-valued `number` other than `-0` gets a non-integer
+ * spelling (`3.0`) for the same reason. This `.0` rule is the extended codec's
+ * own; the standard codec in [`../module.f.mjs`](../module.f.mjs) has its own
+ * numeric spelling and does not route through here.
+ *
+ * `NaN`, `Infinity` and `-Infinity` cannot arrive from JSON text but can be
+ * supplied programmatically, and JSON has no syntax for them. They serialize
+ * as `null`, matching what `JSON.stringify` does with them.
+ *
+ * @module
+ *
+ * @import { Result } from '../../../types/result/types.ts'
+ * @import { List } from '../../../types/list/types.ts'
+ * @import { NumberPolicy } from '../parser/types.ts'
+ * @import { Primitive, Unknown, _MapEntries } from './types.ts'
+ */
+import type { Result } from '../../../types/result/types.ts';
+import type { List } from '../../../types/list/types.ts';
+import type { Unknown, _MapEntries } from './types.ts';
+/**
+ * Parses `text` as extended JSON, reporting failure as a `Result` rather than
+ * throwing.
+ *
+ * @type {(text: string) => Result<Unknown, string>}
+ */
+export declare const parse: (text: string) => Result<Unknown, string>;
+/**
+ * Serializes an extended JSON value as a list of string chunks.
+ *
+ * @type {(mapEntries: _MapEntries) => (value: Unknown) => List<string>}
+ */
+export declare const serialize: (mapEntries: _MapEntries) => (value: Unknown) => List<string>;
+/**
+ * Serializes an extended JSON value as ordinary JSON text.
+ *
+ * @type {(mapEntries: _MapEntries) => (value: Unknown) => string}
+ */
+export declare const stringify: (mapEntries: _MapEntries) => (value: Unknown) => string;

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

@@ -0,0 +1,153 @@
+/**
+ * Extended JSON: the ordinary JSON data model with `bigint` added to the
+ * primitive leaves, so bare integer syntax survives a parse exactly.
+ *
+ * It is a runtime representation, not a syntax. `stringify` emits ordinary,
+ * valid JSON text — there is no `123n` literal, tagged object, or
+ * quoted-integer convention — and ordinary JavaScript consumers of that text
+ * are free to read it back into whatever numeric representation they use,
+ * `JSON.parse`'s `number` included. What the extended codec adds is that
+ * *this* codec reads it back into the same runtime value it wrote.
+ *
+ * ### Parse
+ *
+ * The split is lexical, not mathematical: **a token containing `.` or `e` /
+ * `E` is a `number`, even when its value is an integer.**
+ *
+ * ```text
+ * 123    -> 123n        -123   -> -123n      0     -> 0n
+ * -0     -> -0          1.5    -> 1.5        1.0   -> 1
+ * 1e3    -> 1000        1E3    -> 1000
+ * ```
+ *
+ * `-0` is the exception to bare integer syntax: `bigint` has no negative zero,
+ * so keeping it as a `number` is what preserves the sign the JSON text spells.
+ *
+ * The extended domain is exact where it claims to be, so it rejects rather
+ * than rounds: a token whose value is outside the finite `number` range
+ * (`1e400`) is a parse `error`, not `Infinity`. Ordinary rounding within that
+ * range is inherent to `number` and is not an error — `1e-400` is `0`, and
+ * `0.1` is the nearest double, as everywhere else.
+ *
+ * ### Serialize
+ *
+ * Spelling follows the runtime type of the leaf, so parsing the output returns
+ * the value that was written:
+ *
+ * ```text
+ * 0n -> 0     -> 0n        3n -> 3    -> 3n
+ * 0  -> 0.0   -> 0         3  -> 3.0  -> 3
+ * -0 -> -0    -> -0
+ * ```
+ *
+ * A `bigint` is always its full base-10 digits, **never** exponent notation,
+ * however large: exponent syntax belongs to the `number` side and would parse
+ * back as one. A whole-valued `number` other than `-0` gets a non-integer
+ * spelling (`3.0`) for the same reason. This `.0` rule is the extended codec's
+ * own; the standard codec in [`../module.f.mjs`](../module.f.mjs) has its own
+ * numeric spelling and does not route through here.
+ *
+ * `NaN`, `Infinity` and `-Infinity` cannot arrive from JSON text but can be
+ * supplied programmatically, and JSON has no syntax for them. They serialize
+ * as `null`, matching what `JSON.stringify` does with them.
+ *
+ * @module
+ *
+ * @import { Result } from '../../../types/result/types.ts'
+ * @import { List } from '../../../types/list/types.ts'
+ * @import { NumberPolicy } from '../parser/types.ts'
+ * @import { Primitive, Unknown, _MapEntries } from './types.ts'
+ */
+
+import { concat } from '../../../types/string/module.f.mjs'
+import { compose } from '../../../types/function/module.f.mjs'
+import { error, ok } from '../../../types/result/module.f.mjs'
+import { stringToList } from '../../../text/utf16/module.f.mjs'
+import { parse as parseTokens } from '../parser/module.f.mjs'
+import { tokenize } from '../tokenizer/module.f.mjs'
+import { isBareInteger, numberLexeme } from '../number/module.f.mjs'
+import { treeSerialize, stringSerialize, nullSerialize, boolSerialize } from '../serializer/module.f.mjs'
+
+const { isFinite } = Number
+
+const { is } = Object
+
+/**
+ * The extended numeric policy, applied to the token's exact lexeme.
+ *
+ * Bare integer syntax is materialized as `bigint` straight from that lexeme —
+ * never through `number`, which would round anything above
+ * `Number.MAX_SAFE_INTEGER`. Everything else is `number`, and is rejected if
+ * the finite `number` range cannot hold it.
+ *
+ * @type {NumberPolicy<number | bigint>}
+ */
+const numberPolicy = ({ value }) => {
+    if (isBareInteger(numberLexeme(value))) {
+        return ok(value === '-0' ? -0 : BigInt(value))
+    }
+    const n = Number(value)
+    return isFinite(n) ? ok(n) : error(`number is out of the finite range: ${value}`)
+}
+
+/**
+ * Parses `text` as extended JSON, reporting failure as a `Result` rather than
+ * throwing.
+ *
+ * @type {(text: string) => Result<Unknown, string>}
+ */
+export const parse = text => parseTokens(numberPolicy)(tokenize(stringToList(text)))
+
+const negativeZeroSerialize = ['-0']
+
+/**
+ * Spells a `number` so that reparsing it returns a `number` — never a
+ * `bigint`.
+ *
+ * A whole-valued `number` already spells itself with `.` or `e` often enough
+ * (`1e+21`, `1.5`); when it does not, `.0` is appended, which is the same
+ * value in JSON and the other lexical branch on the way back. `-0` is written
+ * out as the exact token `-0`, the one bare integer the parser keeps as a
+ * `number`.
+ *
+ * @type {(value: number) => List<string>}
+ */
+const numberSerialize = value => {
+    if (is(value, -0)) { return negativeZeroSerialize }
+    if (!isFinite(value)) { return nullSerialize }
+    const text = `${value}`
+    return [isBareInteger(numberLexeme(text)) ? `${text}.0` : text]
+}
+
+/**
+ * Spells a `bigint` as its full base-10 digits. `BigInt`'s own decimal form is
+ * exactly that: no `n` suffix, and no exponent notation at any magnitude.
+ *
+ * @type {(value: bigint) => List<string>}
+ */
+const bigintSerialize = value => [`${value}`]
+
+/** @type {(value: Primitive) => List<string>} */
+const primitiveSerialize = value => {
+    switch (typeof value) {
+        case 'boolean': { return boolSerialize(value) }
+        case 'bigint': { return bigintSerialize(value) }
+        case 'number': { return numberSerialize(value) }
+        case 'string': { return stringSerialize(value) }
+        default: { return nullSerialize }
+    }
+}
+
+/**
+ * Serializes an extended JSON value as a list of string chunks.
+ *
+ * @type {(mapEntries: _MapEntries) => (value: Unknown) => List<string>}
+ */
+export const serialize = treeSerialize(primitiveSerialize)
+
+/**
+ * Serializes an extended JSON value as ordinary JSON text.
+ *
+ * @type {(mapEntries: _MapEntries) => (value: Unknown) => string}
+ */
+export const stringify = sort => compose(serialize(sort))(concat)