functionalscript 0.41.0 → 0.42.0

package/fjs/mcp/proof.f.js

@@ -1,6 +1,9 @@
 import { assert, assertEq } from '../asserts/module.f.js';
 import { pure, step } from '../effects/module.f.js';
 import { create } from '../effects/memory/module.f.js';
+import { parse as parseJson } from '../media/json/module.f.js';
+import { number as rttiNumber, option, string as rttiString } from '../types/rtti/module.f.js';
+import { parse as rttiParse } from '../types/rtti/parse/module.f.js';
 import { msb, u8ListToVec, vec8, repeat, length, maxLengthBytes } from '../types/bit_vec/module.f.js';
 import { vecToCBase32 } from '../basen/cbase32/module.f.js';
 import { encode as base64Encode } from '../basen/base64/module.f.js';
@@ -12,10 +15,24 @@ import { nonEmpty, empty as elEmpty } from '../effects/list/module.f.js';
 import { mcpStep, uninitializedState, } from '../protocol/mcp/module.f.js';
 import { emptyState, virtual } from '../effects/node/virtual/module.f.js';
 import { casConfig, casMcpHandlers } from './module.f.js';
-import { ok as resultOk } from '../types/result/module.f.js';
+import { ok as resultOk, unwrap } from '../types/result/module.f.js';
 import { stdioTransport } from '../protocol/mcp/stdio/module.f.js';
 import { fromVec } from '../types/uint8array/module.f.js';
 import { initEvo } from '../cas/evo/module.f.js';
+// `cas_get`'s result JSON. As an rtti schema it both describes the shape and
+// checks it, so reading a field needs neither a hand-written type nor an `as`
+// cast — a response that drifts from this fails the test at the parse, not
+// silently at the assertion. `uri` is always emitted; only the payload
+// (`text` for `type: 'text'`, `blob` for `type: 'base64'`) is conditional.
+const casGetResult = {
+    length: rttiNumber,
+    mimeType: rttiString,
+    type: rttiString,
+    uri: rttiString,
+    text: option(rttiString),
+    blob: option(rttiString),
+};
+const parseCasGetResult = rttiParse(casGetResult);
 // ── Session driver ──────────────────────────────────────────────────────────────
 // Feeds each message to `handler` in order, collecting every response.
 const feed = (handler) => (msgs) => {
@@ -70,11 +87,13 @@ const runStdio = (root, home = '/home/user') => (msgs) => {
     const stdout = virtual({ ...emptyState, root, stdin: toBytes(input) })(effect)[0].stdout;
     // Only requests get a written line (notifications, like `initialized`,
     // write nothing) — drop the `init` response, keep one line per `msgs` entry.
-    return stdout.split('\n').filter(line => line.length > 0).slice(1).map(line => JSON.parse(line));
+    return stdout.split('\n').filter(line => line.length > 0).slice(1).map(line => unwrap(parseJson(line)));
 };
 const resultOf = (resp) => resp.result;
 const item0 = (resp) => resultOf(resp).content[0];
 const textOf = (resp) => item0(resp).text;
+/** The `text` payload of a `cas_get` response, parsed and checked against {@link casGetResult}. */
+const casGetResultOf = (resp) => unwrap(parseCasGetResult(unwrap(parseJson(textOf(resp)))));
 // A plain text sample for text add→get round-trips.
 const textSample = 'hello, world!';
 // A valid `vnd.fjs.revision` blob: every required field present, including the
@@ -115,7 +134,7 @@ const largeMultiChunkBlobMeta = (chunk0, chunk1, expectedType, expectedMime) =>
         call(2, 'cas_get', { hash }),
     ]).slice(2);
     assert(!resultOf(metaResp).isError);
-    const meta = JSON.parse(textOf(metaResp));
+    const meta = casGetResultOf(metaResp);
     assertEq(meta.type, expectedType);
     assertEq(meta.mimeType, expectedMime);
     assertEq(meta.length, Number((length(chunk0) + length(chunk1)) / 8n));
@@ -204,7 +223,7 @@ export const proof = {
             call(2, 'cas_get', { hash, content: true }),
         ]);
         assert(!resultOf(getResp).isError);
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.type, 'base64');
         assertEq(result.length, 90_000);
     },
@@ -274,7 +293,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, getResp] = session(call(2, 'cas_add', { content: textSample }), call(3, 'cas_get', { hash }));
         assert(!resultOf(getResp).isError);
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.mimeType, 'text/plain');
         assertEq(result.type, 'text');
         assertEq(result.length, textSample.length);
@@ -286,7 +305,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, getResp] = session(call(2, 'cas_add', { content: textSample }), call(3, 'cas_get', { hash, content: true }));
         assert(!resultOf(getResp).isError);
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.type, 'text');
         assertEq(result.mimeType, 'text/plain');
         assertEq(result.text, textSample);
@@ -297,7 +316,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, getResp] = session(call(2, 'cas_add', { content: binarySample, type: 'base64' }), call(3, 'cas_get', { hash }));
         assert(!resultOf(getResp).isError);
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.text, undefined);
         assertEq(result.type, 'text');
         assertEq(result.mimeType, 'text/plain');
@@ -308,7 +327,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, getResp] = session(call(2, 'cas_add', { content: binarySample, type: 'base64' }), call(3, 'cas_get', { hash, content: true }));
         assert(!resultOf(getResp).isError);
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.type, 'text');
         assertEq(result.text, '*');
     },
@@ -317,7 +336,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, getResp] = session(call(2, 'cas_add', { content: textSample }), call(3, 'cas_get', { hash, content: true }));
         assert(!resultOf(getResp).isError);
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.text, textSample);
     },
     // Text content (no magic-byte match, valid UTF-8) comes back with type:'text' when content requested.
@@ -326,7 +345,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, getResp] = session(call(2, 'cas_add', { content: textSample }), call(3, 'cas_get', { hash, content: true }));
         assertEq(item0(getResp) === null ? null : item0(getResp).type, 'text');
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.type, 'text');
         assertEq(result.mimeType, 'text/plain');
     },
@@ -337,7 +356,7 @@ export const proof = {
         const [, getResp] = session(call(2, 'cas_add', { content: pngSample, type: 'base64' }), call(3, 'cas_get', { hash, content: true }));
         assert(!resultOf(getResp).isError);
         assertEq(item0(getResp).type, 'text');
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.type, 'base64');
         assertEq(result.mimeType, 'image/png');
         assertEq(result.blob, pngSample);
@@ -351,7 +370,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, metaResp] = session(call(2, 'cas_add', { content: revisionSample }), call(3, 'cas_get', { hash }));
         assert(!resultOf(metaResp).isError);
-        const meta = JSON.parse(textOf(metaResp));
+        const meta = casGetResultOf(metaResp);
         assertEq(meta.mimeType, revisionMediaType);
         assertEq(meta.type, 'text');
     },
@@ -362,7 +381,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, getResp] = session(call(2, 'cas_add', { content: revisionSample }), call(3, 'cas_get', { hash, content: true }));
         assert(!resultOf(getResp).isError);
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.mimeType, revisionMediaType);
         assertEq(result.type, 'text');
         assertEq(result.text, revisionSample);
@@ -449,7 +468,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, metaResp] = session(call(2, 'cas_add', { content: 'text content' }), call(3, 'cas_get', { hash }));
         assert(!resultOf(metaResp).isError);
-        const meta = JSON.parse(textOf(metaResp));
+        const meta = casGetResultOf(metaResp);
         assertEq(meta.mimeType, 'text/plain');
         assertEq(meta.type, 'text');
         assertEq(meta.length, 12);
@@ -460,7 +479,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, metaResp] = session(call(2, 'cas_add', { content: pngSample, type: 'base64' }), call(3, 'cas_get', { hash }));
         assert(!resultOf(metaResp).isError);
-        const meta = JSON.parse(textOf(metaResp));
+        const meta = casGetResultOf(metaResp);
         assertEq(meta.mimeType, 'image/png');
         assertEq(meta.type, 'base64');
         assertEq(meta.length, 10);
@@ -473,7 +492,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, metaResp] = session(call(2, 'cas_add', { content: binaryB64, type: 'base64' }), call(3, 'cas_get', { hash }));
         assert(!resultOf(metaResp).isError);
-        const meta = JSON.parse(textOf(metaResp));
+        const meta = casGetResultOf(metaResp);
         assertEq(meta.mimeType, 'application/octet-stream');
         assertEq(meta.type, 'base64');
         assertEq(meta.blob, undefined);
@@ -487,7 +506,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, metaResp] = session(call(2, 'cas_add', { content: nulB64, type: 'base64' }), call(3, 'cas_get', { hash }));
         assert(!resultOf(metaResp).isError);
-        const meta = JSON.parse(textOf(metaResp));
+        const meta = casGetResultOf(metaResp);
         assertEq(meta.mimeType, 'application/octet-stream');
         assertEq(meta.type, 'base64');
     },
@@ -508,7 +527,7 @@ export const proof = {
         const hash = textOf(addResp);
         const [, getResp] = session(call(2, 'cas_add', { content: binaryB64, type: 'base64' }), call(3, 'cas_get', { hash, content: true }));
         assert(!resultOf(getResp).isError);
-        const result = JSON.parse(textOf(getResp));
+        const result = casGetResultOf(getResp);
         assertEq(result.mimeType, 'application/octet-stream');
         assertEq(result.type, 'base64');
         assertEq(result.blob, binaryB64);

package/fjs/media/json/module.f.d.ts

@@ -2,6 +2,9 @@
  * JSON value types, rtti schemas, and utilities: `serialize`, `stringify`,
  * `parse`, and `setProperty` for immutable nested updates.
  *
+ * `parse` is the total, `Result`-returning `text → Unknown` entry point built
+ * on this module's own tokenizer and parser.
+ *
  * The JSON value types (`Unknown`, `Primitive`) are derived from the rtti
  * schemas defined here, so the schema is the single source of truth — no
  * hand-written types to keep in sync.
@@ -9,6 +12,7 @@
  * @module
  */
 import { type List } from '../../types/list/module.f.ts';
+import type { Result } from '../../types/result/module.f.ts';
 import { type Entry as ObjectEntry } from '../../types/object/module.f.ts';
 import type { Ts } from '../../types/rtti/ts/module.f.ts';
 /** rtti schema matching any JSON primitive: `null`, `boolean`, `number`, or `string`. */
@@ -46,5 +50,15 @@ export declare const serialize: (mapEntries: MapEntries) => (value: Unknown) =>
  * https://tc39.es/ecma262/#sec-serializejsonproperty
  */
 export declare const stringify: (mapEntries: MapEntries) => (value: Unknown) => string;
-export declare const parse: (value: string) => Unknown;
+/**
+ * Parses `text` as JSON with this module's own pure tokenizer and parser,
+ * reporting failure as a `Result` rather than throwing: malformed input is
+ * *available* as an `error` to branch on. Whether to branch or to `unwrap` it
+ * back into a panic is the caller's decision — the parser no longer makes it
+ * for them.
+ *
+ * The result is an untyped {@link Unknown}; narrow it to a domain type with an
+ * rtti schema (`fjs/types/rtti/parse`) rather than with an `as` cast.
+ */
+export declare const parse: (text: string) => Result<Unknown, string>;
 export {};

package/fjs/media/json/module.f.js

@@ -2,6 +2,9 @@
  * JSON value types, rtti schemas, and utilities: `serialize`, `stringify`,
  * `parse`, and `setProperty` for immutable nested updates.
  *
+ * `parse` is the total, `Result`-returning `text → Unknown` entry point built
+ * on this module's own tokenizer and parser.
+ *
  * The JSON value types (`Unknown`, `Primitive`) are derived from the rtti
  * schemas defined here, so the schema is the single source of truth — no
  * hand-written types to keep in sync.
@@ -10,6 +13,9 @@
  */
 import { next, flat, map } from '../../types/list/module.f.js';
 import { concat } from '../../types/string/module.f.js';
+import { stringToList } from '../../text/utf16/module.f.js';
+import { parse as parseTokens } from './parser/module.f.js';
+import { tokenize } from './tokenizer/module.f.js';
 import { at, definedEntries } from '../../types/object/module.f.js';
 import { compose, fn } from '../../types/function/module.f.js';
 import { objectWrap, arrayWrap, stringSerialize, numberSerialize, nullSerialize, boolSerialize } from './serializer/module.f.js';
@@ -90,4 +96,14 @@ export const serialize = sort => {
  * https://tc39.es/ecma262/#sec-serializejsonproperty
  */
 export const stringify = sort => compose(serialize(sort))(concat);
-export const parse = JSON.parse;
+/**
+ * Parses `text` as JSON with this module's own pure tokenizer and parser,
+ * reporting failure as a `Result` rather than throwing: malformed input is
+ * *available* as an `error` to branch on. Whether to branch or to `unwrap` it
+ * back into a panic is the caller's decision — the parser no longer makes it
+ * for them.
+ *
+ * The result is an untyped {@link Unknown}; narrow it to a domain type with an
+ * rtti schema (`fjs/types/rtti/parse`) rather than with an `as` cast.
+ */
+export const parse = text => parseTokens(tokenize(stringToList(text)));

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

@@ -4,7 +4,7 @@
  * @module
  */
 import { error, ok } from '../../../types/result/module.f.js';
-import { fold, first, drop, toArray, concat } from '../../../types/list/module.f.js';
+import { fold, next, toArray, concat } from '../../../types/list/module.f.js';
 import {} from '../../../types/function/operator/module.f.js';
 import {} from '../tokenizer/module.f.js';
 import { setReplace } from '../../../types/ordered_map/module.f.js';
@@ -33,9 +33,19 @@ const startArray = state => {
     const newStack = state.top === null ? null : { first: state.top, tail: state.stack };
     return { status: '[', top: { kind: 'array', values: null }, stack: newStack };
 };
+// Pops the enclosing container off `stack`. `next` is forced here rather than
+// left as a `drop(1)` thunk: the stack is written only by startArray/startObject,
+// 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.
+const popStack = stack => {
+    const ne = next(stack);
+    return ne === null
+        ? { status: '', top: null, stack: null }
+        : { status: '', top: ne.first, stack: ne.tail };
+};
 const endArray = state => {
     const array = state.top !== null ? toArray(state.top.values) : null;
-    const newState = { status: '', top: first(null)(state.stack), stack: drop(1)(state.stack) };
+    const newState = popStack(state.stack);
     return pushValue(newState)(array);
 };
 const startObject = state => {
@@ -44,7 +54,7 @@ const startObject = state => {
 };
 const endObject = state => {
     const obj = state.top?.kind === 'object' ? fromMap(state.top.values) : null;
-    const newState = { status: '', top: first(null)(state.stack), stack: drop(1)(state.stack) };
+    const newState = popStack(state.stack);
     return pushValue(newState)(obj);
 };
 const tokenToValue = token => {

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

@@ -1,4 +1,5 @@
 export declare const proof: {
     valid: (() => void)[];
     invalid: (() => void)[];
+    siblingContainers: (() => void)[];
 };

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

@@ -274,5 +274,41 @@ export const proof = {
             const result = stringify(obj);
             assertEq(result, '["error","unexpected token"]');
         },
-    ]
+    ],
+    // Regression: closing a container used to pop the parser stack lazily
+    // (`drop(1)`, which is `apply(dropStep)` and returns a `Thunk`), leaving one
+    // unforced thunk per closed container. The chain was forced only at the end,
+    // costing a call-stack frame per container and overflowing at roughly 5000 of
+    // them — nested or flat siblings alike — while primitives were unbounded,
+    // since they never push or pop. `popStack` in `module.f.ts` forces the pop
+    // instead, which is why these sizes are safe now.
+    siblingContainers: [
+        () => {
+            const [tag, value] = parse(tokenizeString(`[${Array(6000).fill('{}').join(',')}]`));
+            assertEq(tag, 'ok');
+            assertEq(Array.isArray(value) ? value.length : -1, 6000);
+        },
+        () => {
+            const [tag, value] = parse(tokenizeString(`[${Array(6000).fill('[]').join(',')}]`));
+            assertEq(tag, 'ok');
+            assertEq(Array.isArray(value) ? value.length : -1, 6000);
+        },
+        () => {
+            const keys = Array.from({ length: 6000 }, (_, i) => `"k${i}":{}`);
+            const [tag, value] = parse(tokenizeString(`{${keys.join(',')}}`));
+            assertEq(tag, 'ok');
+            assertEq(typeof value === 'object' && value !== null ? Object.keys(value).length : -1, 6000);
+        },
+        () => {
+            // deep nesting shares the same stack path and overflowed at 5000
+            const [tag] = parse(tokenizeString('['.repeat(5000) + ']'.repeat(5000)));
+            assertEq(tag, 'ok');
+        },
+        () => {
+            // baseline that always worked: primitives never touch the stack
+            const [tag, value] = parse(tokenizeString(`[${Array.from({ length: 12000 }, (_, i) => i).join(',')}]`));
+            assertEq(tag, 'ok');
+            assertEq(Array.isArray(value) ? value.length : -1, 12000);
+        },
+    ],
 };

package/fjs/media/json/proof.f.d.ts

@@ -5,4 +5,8 @@ export declare const proof: {
         identity: () => void;
     }[];
     undefined: () => void;
+    parse: {
+        ok: () => void;
+        error: () => void;
+    };
 };

package/fjs/media/json/proof.f.js

@@ -1,4 +1,4 @@
-import { setProperty, stringify } from './module.f.js';
+import { parse, setProperty, stringify } from './module.f.js';
 import { sort } from '../../types/object/module.f.js';
 import { identity } from '../../types/function/module.f.js';
 import { assertEq } from '../../asserts/module.f.js';
@@ -82,5 +82,17 @@ export const proof = {
     ],
     undefined: () => {
         assertEq(stringify(sort)({ x: undefined }), '{}');
-    }
+    },
+    parse: {
+        ok: () => {
+            const [t, v] = parse('{"a":[1,true,null],"b":"x"}');
+            assertEq(t, 'ok');
+            assertEq(stringify(sort)(v), '{"a":[1,true,null],"b":"x"}');
+        },
+        // Malformed input is an error value, not a throw.
+        error: () => {
+            const [t] = parse('{');
+            assertEq(t, 'error');
+        },
+    },
 };

package/fjs/media/json/serializer/module.f.d.ts

@@ -1,6 +1,10 @@
 /**
  * JSON serializer for deterministic string output.
  *
+ * `stringSerialize` is FunctionalScript, not the host's `JSON.stringify`: it
+ * escapes over this repository's own UTF-16 decoder and reproduces the
+ * ECMAScript `QuoteJSONString` result exactly, lone surrogates included.
+ *
  * @module
  */
 import { type List } from '../../../types/list/module.f.ts';

package/fjs/media/json/serializer/module.f.js

@@ -1,15 +1,52 @@
 /**
  * JSON serializer for deterministic string output.
  *
+ * `stringSerialize` is FunctionalScript, not the host's `JSON.stringify`: it
+ * escapes over this repository's own UTF-16 decoder and reproduces the
+ * ECMAScript `QuoteJSONString` result exactly, lone surrogates included.
+ *
  * @module
  */
-import { flat, reduce, empty } from '../../../types/list/module.f.js';
+import { flat, map, reduce, empty } from '../../../types/list/module.f.js';
 import {} from '../../../types/function/operator/module.f.js';
+import { concat } from '../../../types/string/module.f.js';
+import { codePointToString, stringToCodePointList, } from '../../../text/utf16/module.f.js';
+import { errorMask } from '../../../text/code_point/module.f.js';
+import { backspace, cr, digit0, ff, ht, latinSmallLetterA, lf, quotationMark, reverseSolidus, space, } from '../../../text/ascii/module.f.js';
 const jsonStringify = JSON.stringify;
+const { fromCharCode } = String;
+/**
+ * The code points JSON gives a two-character escape. Every other code point
+ * below `space` has no short form and goes through `unicodeEscape` instead.
+ */
+const escapeTable = {
+    [backspace]: '\\b',
+    [ht]: '\\t',
+    [lf]: '\\n',
+    [ff]: '\\f',
+    [cr]: '\\r',
+    [quotationMark]: '\\"',
+    [reverseSolidus]: '\\\\',
+};
+const hexDigit = (value) => fromCharCode(value < 10 ? digit0 + value : latinSmallLetterA + value - 10);
+/**
+ * `\uXXXX` with lowercase hex digits, matching ECMAScript's `UnicodeEscape`.
+ */
+const unicodeEscape = (unit) => `\\u${hexDigit(unit >> 12 & 0xf)}${hexDigit(unit >> 8 & 0xf)}${hexDigit(unit >> 4 & 0xf)}${hexDigit(unit & 0xf)}`;
+/**
+ * Escapes one decoded code point. A code point tagged with `errorMask` is an
+ * unpaired surrogate, which well-formed JSON stringification (ES2019) emits as
+ * its `\uXXXX` escape rather than as a code unit; everything else is either a
+ * named escape, a `\u00XX` control escape, or the character itself.
+ */
+const escapeCodePoint = (codePoint) => (codePoint & errorMask) !== 0
+    ? unicodeEscape(codePoint & 0xffff)
+    : escapeTable[codePoint]
+        ?? (codePoint < space ? unicodeEscape(codePoint) : codePointToString(codePoint));
 /**
  * Serializes a string as a JSON string literal.
  */
-export const stringSerialize = input => [jsonStringify(input)];
+export const stringSerialize = input => [`"${concat(map(escapeCodePoint)(stringToCodePointList(input)))}"`];
 /**
  * Serializes a number as a JSON number literal.
  */

package/fjs/media/json/serializer/proof.f.js

@@ -1,7 +1,12 @@
 import { arrayWrap, boolSerialize, numberSerialize, objectWrap, stringSerialize } from './module.f.js';
 import * as list from '../../../types/list/module.f.js';
+import { concat } from '../../../types/string/module.f.js';
 import { assertEq } from '../../../asserts/module.f.js';
 const { toArray } = list;
+// The expected literals below are what the host's `JSON.stringify` produces for
+// the same input; `stringSerialize` has to reproduce them exactly, so any
+// divergence in the FunctionalScript escaping shows up here as a failure.
+const serialized = (input) => concat(stringSerialize(input));
 export const proof = {
     arrayWrap: [
         () => {
@@ -38,14 +43,33 @@ export const proof = {
         }
     ],
     stringSerialize: [
-        () => {
-            const result = JSON.stringify(toArray(stringSerialize('abc')));
-            assertEq(result, '["\\"abc\\""]');
-        },
-        () => {
-            const result = JSON.stringify(toArray(stringSerialize('123')));
-            assertEq(result, '["\\"123\\""]');
-        }
+        () => { assertEq(serialized('abc'), '"abc"'); },
+        () => { assertEq(serialized('123'), '"123"'); },
+        () => { assertEq(serialized(''), '""'); },
+        // one chunk, like every other leaf serializer in this module
+        () => { assertEq(toArray(stringSerialize('a"')).length, 1); },
+        // the two escapes JSON requires outside the control block
+        () => { assertEq(serialized('a"b'), '"a\\"b"'); },
+        () => { assertEq(serialized('a\\b'), '"a\\\\b"'); },
+        // every named control escape
+        () => { assertEq(serialized('\b\f\n\r\t'), '"\\b\\f\\n\\r\\t"'); },
+        // control code points without a named escape, covering both hex-digit
+        // halves: '0'-'9' and 'a'-'f'
+        () => { assertEq(serialized('\u0000'), '"\\u0000"'); },
+        () => { assertEq(serialized('\u000b'), '"\\u000b"'); },
+        () => { assertEq(serialized('\u001f'), '"\\u001f"'); },
+        // `space` is the first code point copied through unescaped, and DEL is
+        // not a JSON escape at all
+        () => { assertEq(serialized(' \u007f'), '" \u007f"'); },
+        // a surrogate pair decodes to one code point and survives unchanged
+        () => { assertEq(serialized('😀'), '"😀"'); },
+        // unpaired surrogates, well-formed-stringify escaped: leading, trailing,
+        // in the middle, doubled, and left over at end of input
+        () => { assertEq(serialized('\ud800'), '"\\ud800"'); },
+        () => { assertEq(serialized('\udfff'), '"\\udfff"'); },
+        () => { assertEq(serialized('a\udc00b'), '"a\\udc00b"'); },
+        () => { assertEq(serialized('\ud800\ud800'), '"\\ud800\\ud800"'); },
+        () => { assertEq(serialized('a\ud83d'), '"a\\ud83d"'); },
     ],
     numberSerialize: [
         () => {

package/fjs/media/module.f.d.ts

@@ -5,17 +5,31 @@
  * `fjs/media/type` classifies raw bytes (magic-byte signatures, UTF-8
  * text-vs-binary) with no notion of a JSON dialect. `detect` here adds one
  * more classification step in front of it: when the whole blob is
- * whole-blob-valid UTF-8 text (as `fjs/media/type` already determined), try
- * parsing it as JSON and validating it against a known dialect's rtti schema
- * (currently just `vnd.fjs.revision` — see `fjs/media/revision`). A match
- * reports the dialect's derived media type; anything that isn't valid JSON,
- * or doesn't validate against a known dialect, falls through to the
+ * whole-blob-valid UTF-8 text (as `fjs/media/type` already determined), parse
+ * it as JSON and match the parsed value against the dialects the caller
+ * registered. A match reports that dialect's derived media type; anything that
+ * isn't valid JSON, or matches no registered dialect, falls through to the
  * `fjs/media/type` verdict unchanged.
  *
+ * The dialect set is a **parameter**, not an import: `detect(dialects)(bytes)`.
+ * This module therefore knows no dialect of its own — `fjs/media/revision`
+ * exports its own {@link DialectEntry} (`revisionDialect`), and a caller passes
+ * the list it wants recognized. Any format following the `vnd.fjs.<name>`
+ * convention (see `fjs/media/revision/README.md`), in this repo or downstream,
+ * is registerable the same way.
+ *
  * Detection is semantic, not syntactic: any JSON that satisfies a dialect's
  * schema is recognized regardless of key order, whitespace, or any other
  * serialization detail — there is no byte-level shortcut such as a
- * `{"dialect":` prefix check.
+ * `{"dialect":` prefix check. The text is parsed **once**, and each entry's
+ * `match` runs on the same parsed value, so N dialects cost N schema walks
+ * rather than N parses.
+ *
+ * A reported `mime_type` is a claim about a blob's *shape*, not a promise that
+ * decoding it succeeds: how strict detection is, is the dialect's own call (see
+ * {@link dialectEntry}'s `extraValidate`). Never route a decode decision
+ * through this verdict — a caller that intends to decode calls its dialect's
+ * decoder, which stays the authority.
  *
  * This only classifies an already-buffered `Vec` (`detectVec`'s single-`Vec`
  * form), because dialect validation needs the whole parsed value. A single
@@ -29,9 +43,77 @@
  */
 import type { Vec } from '../types/bit_vec/module.f.ts';
 import { type DetectMeta } from './type/module.f.ts';
+import type { Struct } from '../types/rtti/module.f.ts';
+import type { Ts, Unknown } from '../types/rtti/ts/module.f.ts';
+/**
+ * One registered dialect: the name it tags itself with, and a predicate
+ * deciding whether an already-parsed value is one of its blobs.
+ *
+ * `match` takes rtti's `Unknown` — the encoding-neutral one, admitting
+ * `bigint` and `undefined` — not `fjs/media/json`'s JSON-only `Unknown`, so an
+ * entry stays usable by a future non-JSON detector over the same dialects.
+ *
+ * The type is deliberately not opaque: a caller may write the struct by hand.
+ * The list is that caller's own declaration of what it wants recognized,
+ * passed to its own `detect` call, so a fabricated entry mislabels only that
+ * caller's results — there is no trust boundary between a caller and entries it
+ * writes itself. The boundary that does exist, untrusted blob content, is on
+ * the other side of `match`.
+ */
+export type DialectEntry = {
+    readonly dialect: string;
+    readonly match: (_: Unknown) => boolean;
+};
+/**
+ * Registers a dialect for detection: its rtti schema, plus whatever rtti can't
+ * say about it.
+ *
+ * The dialect name is read out of the schema's own `dialect` member — that
+ * member is a string const in a dialect schema, which is what makes the schema
+ * self-discriminating, so a separate name alongside it would be a second copy
+ * that can disagree with the first. It follows that no registration can claim
+ * one dialect while validating another's blobs. The media type is likewise
+ * derived rather than supplied: `application/${dialect}+json`, the mechanical
+ * derivation `fjs/media/revision/README.md` documents.
+ *
+ * `extraValidate` runs *after* structural validation, on the dialect's own
+ * decoded type, and closes the gap rtti leaves — "this string is
+ * cbase32-decodable", "this number is a non-negative safe integer". It returns
+ * `boolean`, so it has no error channel and nothing to report but yes or no,
+ * and it never sees the raw bytes: parsing and the schema walk stay with the
+ * detector. Omitting it gets classification (what a blob claims to be and
+ * structurally looks like); supplying it gets detection as strict as the
+ * dialect's own decoder.
+ *
+ * **The name is neither grammar-checked nor allowlisted.** A schema saying
+ * `dialect: 'foo'` yields `application/foo+json`, and that is intended:
+ * `vnd.fjs.*` is this repo's convention for its *own* formats, not a constraint
+ * on what a caller may detect — another vendor's `vnd.*` blob, or a widely used
+ * name not under `vnd.` at all, is a legitimate thing to register. The name is
+ * not attacker-controlled either: it comes from a schema a programmer wrote and
+ * passed here, never from the blob being classified, so no untrusted string
+ * reaches `mime_type` along this path. (A detector that read the name *out of*
+ * a blob would need the RFC 6838 grammar check and an allowlist; this one does
+ * not.) Registering a name that is not a valid RFC 6838 restricted-name yields
+ * a malformed media type in the registrant's own results, and nowhere else.
+ *
+ * The constraint is `Struct` — every member must be a real rtti `Type`, which
+ * is what rejects a member like `() => 42` at compile time (rtti would read it
+ * as a thunk and `match` would *throw* on the first blob rather than return
+ * `false`). TypeScript cannot also require a direct string `dialect` member
+ * under that constraint, so that half is asserted here instead: loudly, once,
+ * when the entry is constructed. A thunk-form `dialect`
+ * (`() => ['const', 'x']`) is a perfectly valid rtti schema, it just is not
+ * registerable — write the string directly, as `revisionSchema` does.
+ */
+export declare const dialectEntry: <T extends Struct>(type: T, extraValidate?: (_: Ts<T>) => boolean) => DialectEntry;
 /**
- * Classifies a whole buffered `Vec`, the same three-way `{ length, mime_type,
- * type }` shape as `fjs/media/type` `detectVec`, but with dialect-tagged JSON
- * recognized ahead of the plain `text/plain` fallback.
+ * Classifies a whole buffered `Vec` against `dialects`, returning the same
+ * three-way `{ length, mime_type, type }` shape as `fjs/media/type`
+ * `detectVec`, but with dialect-tagged JSON recognized ahead of the plain
+ * `text/plain` fallback. The first entry whose `match` accepts the parsed value
+ * wins; entries that overlap are the registrant's own business, since matching
+ * `dialect` as an exact literal already makes structural validation reject
+ * every other dialect's blob.
  */
-export declare const detect: (bytes: Vec) => DetectMeta;
+export declare const detect: (dialects: readonly DialectEntry[]) => (bytes: Vec) => DetectMeta;