functionalscript 0.35.2 → 0.36.0

package/fs/djs/parser/proof.f.js

@@ -251,6 +251,18 @@ export const proof = {
                 throw obj[1].message;
             }
         },
+        // A literal control character inside a string is not valid JSON
+        // syntax (RFC 8259 §7), and DJS string literals are JSON strings.
+        () => {
+            const tokenList = tokenizeString('export default "\t"');
+            const obj = parseFromTokens(tokenList);
+            if (obj[0] !== 'error') {
+                throw obj;
+            }
+            if (obj[1].message !== 'unexpected token') {
+                throw obj[1].message;
+            }
+        },
         () => {
             const tokenList = tokenizeString('export default [,]');
             const obj = parseFromTokens(tokenList);

package/fs/effects/module.f.d.ts

@@ -1,9 +1,17 @@
 /**
  * Core effect type constructors and combinators.
  *
+ * Effect helpers are **step adapters**: functions that return a continuation
+ * `(t: T) => Effect<Q, R>` meant to be passed into `.step`, never wrappers
+ * that take the effect itself as an argument. `Effect` has no pipeline
+ * operator to lean on and must not be extended with new methods, so
+ * `.step(adapterA).step(adapterB)` is how helpers compose — flat,
+ * left-to-right, in evaluation order. See {@link okStep} for an example.
+ *
  * @module
  */
 import { type List } from '../types/list/module.f.ts';
+import type { Result } from '../types/result/module.f.ts';
 export type Operation = readonly [string, (..._: readonly never[]) => unknown];
 export type Effect<O extends Operation, T> = {
     value: Value<O, T>;
@@ -43,6 +51,13 @@ export declare const foldStep: <O extends Operation, T, S>(f: (item: T) => (stat
  * results. The `void` accumulator sibling of `foldStep`.
  */
 export declare const forEachStep: <O extends Operation, T>(f: (item: T) => Effect<O, void>) => (items: List<T>) => Effect<O, void>;
+/**
+ * A step adapter for the `error` short-circuit: `error` → pass it through
+ * unchanged as `pure`, `ok` → continue with `f`. Collapses the hand-written
+ * `r[0] === 'error' ? pure(r) : f(r[1])` check that recurs at every site
+ * chaining `Effect<O, Result<T, E>>` steps.
+ */
+export declare const okStep: <T, E, O extends Operation, R>(f: (value: T) => Effect<O, Result<R, E>>) => (r: Result<T, E>) => Effect<O, Result<R, E>>;
 /**
  * The decoded form of an effect's next step: either a final `result`, or a
  * `command` to perform with its `payload` and the `continuation` to resume

package/fs/effects/module.f.js

@@ -1,6 +1,13 @@
 /**
  * Core effect type constructors and combinators.
  *
+ * Effect helpers are **step adapters**: functions that return a continuation
+ * `(t: T) => Effect<Q, R>` meant to be passed into `.step`, never wrappers
+ * that take the effect itself as an argument. `Effect` has no pipeline
+ * operator to lean on and must not be extended with new methods, so
+ * `.step(adapterA).step(adapterB)` is how helpers compose — flat,
+ * left-to-right, in evaluation order. See {@link okStep} for an example.
+ *
  * @module
  */
 import { fold } from "../types/list/module.f.js";
@@ -39,6 +46,13 @@ export const foldStep = (f) => (init) => (items) => fold(item => acc => acc.step
  * results. The `void` accumulator sibling of `foldStep`.
  */
 export const forEachStep = (f) => (items) => foldStep((item) => () => f(item))(undefined)(items);
+/**
+ * A step adapter for the `error` short-circuit: `error` → pass it through
+ * unchanged as `pure`, `ok` → continue with `f`. Collapses the hand-written
+ * `r[0] === 'error' ? pure(r) : f(r[1])` check that recurs at every site
+ * chaining `Effect<O, Result<T, E>>` steps.
+ */
+export const okStep = (f) => (r) => r[0] === 'error' ? pure(r) : f(r[1]);
 /**
  * Decodes an effect's next step: a pure result, or a command to perform.
  *

package/fs/effects/node/module.f.js

@@ -13,8 +13,8 @@ import { toCodePointList } from "../../text/utf8/module.f.js";
 import { codePointListToString } from "../../text/utf16/module.f.js";
 import { reverse } from "../../types/list/module.f.js";
 import { length } from "../../types/bit_vec/module.f.js";
-import { ok, error as resultError } from "../../types/result/module.f.js";
-import { do_, pure } from "../module.f.js";
+import { ok, error as resultError, mapOk } from "../../types/result/module.f.js";
+import { do_, okStep, pure } from "../module.f.js";
 /**
  * True if `e` is a "file or directory does not exist" (`ENOENT`) error.
  *
@@ -43,7 +43,7 @@ export const readFile = do_('readFile');
  * on errors (e.g. convert them into domain-specific errors) or `unwrap` at the
  * call site.
  */
-export const readUtf8File = (path) => readFile(path).step(r => pure(r[0] === 'ok' ? ok(utf8ToString(r[1])) : r));
+export const readUtf8File = (path) => readFile(path).step(r => pure(mapOk(utf8ToString)(r)));
 export const readdir = do_('readdir');
 export const writeFile = do_('writeFile');
 /** Writes a string to `path` as UTF-8 bytes. */
@@ -70,22 +70,12 @@ const writeLoop = (path) => {
             return pure(resultError('invalid buffer size'));
         }
         return writeBytes(path, offset, v)
-            .step((r) => {
-            if (r[0] === 'error') {
-                return pure(r);
-            }
-            return f(offset + Number(lenV >> 3n), tail);
-        });
+            .step(okStep(() => f(offset + Number(lenV >> 3n), tail)));
     });
     return f;
 };
 export const writeFromStream = (path, e) => createExclusive(path)
-    .step(([r, v]) => {
-    if (r === 'error') {
-        return pure(resultError(v));
-    }
-    return writeLoop(path)(0, e);
-});
+    .step(okStep(() => writeLoop(path)(0, e)));
 export const stat = do_('stat');
 export const createServer = do_('createServer');
 export const listen = do_('listen');

package/fs/effects/node/module.js

@@ -146,6 +146,8 @@ const readStdinByte = async () => {
         }
     }
 };
+const randomMax = Number(1n << 32n);
+const { randomInt } = crypto;
 const runNodeEffect = asyncRun({
     ...memoryOperationMap(),
     all: async (...effects) => await Promise.all(effects.map(runNodeEffect)),
@@ -191,7 +193,7 @@ const runNodeEffect = asyncRun({
             await fh.close();
         }
     }),
-    randomInt: async () => crypto.randomInt(2 ** 32),
+    randomInt: async () => randomInt(randomMax),
     access: path => asyncTryCatch(() => access(path)),
     createExclusive: path => asyncTryCatch(async () => {
         const fh = await open(path, 'wx');

package/fs/effects/node/proof.f.d.ts

@@ -61,4 +61,7 @@ export declare const proof: {
     randomInt: {
         increments: () => void;
     };
+    writeFromStream: {
+        createExclusiveFails: () => void;
+    };
 };

package/fs/effects/node/proof.f.js

@@ -1,8 +1,9 @@
 import { empty, isVec, uint, vec8 } from "../../types/bit_vec/module.f.js";
 import { utf8, utf8ToString } from "../../text/module.f.js";
 import { decode, pure } from "../module.f.js";
-import { both, fetch, mkdir, now, readdir, readFile, readUtf8File, rm, sandbox, writeFile, writeUtf8File, rename, readBytes, randomInt } from "./module.f.js";
+import { both, fetch, mkdir, now, readdir, readFile, readUtf8File, rm, sandbox, writeFile, writeUtf8File, rename, readBytes, randomInt, writeFromStream } from "./module.f.js";
 import { create as memCreate, read as memRead, write as memWrite } from "../memory/module.f.js";
+import { empty as listEmpty } from "../list/module.f.js";
 import { emptyState, virtual } from "./virtual/module.f.js";
 export const proof = {
     map: () => {
@@ -553,4 +554,21 @@ export const proof = {
             }
         },
     },
+    writeFromStream: {
+        createExclusiveFails: () => {
+            // The destination already exists, so `createExclusive` fails (EEXIST) and
+            // the error propagates without ever touching `writeBytes`.
+            const [state, [t, result]] = virtual({
+                ...emptyState,
+                root: { hello: [vec8(0x2an)] },
+            })(writeFromStream('hello', listEmpty()));
+            if (t !== 'error') {
+                throw result;
+            }
+            const file = state.root.hello;
+            if (!Array.isArray(file) || uint(file[0]) !== 0x2an) {
+                throw file;
+            }
+        },
+    },
 };

package/fs/effects/node/virtual/module.f.js

@@ -4,7 +4,7 @@
  * @module
  */
 import { todo } from "../../../asserts/module.f.js";
-import { join, parse } from "../../../path/module.f.js";
+import { isProperPrefix, join, parse } from "../../../path/module.f.js";
 import { utf8ToString } from "../../../text/module.f.js";
 import { empty, length, maxLengthBytes, msb, vec } from "../../../types/bit_vec/module.f.js";
 import { error, ok } from "../../../types/result/module.f.js";
@@ -218,7 +218,6 @@ const insertEntityAt = (dir, path, entity) => {
     }
     return [{ ...dir, [first]: newSub }, result];
 };
-const isProperPrefix = (prefix, path) => prefix.length < path.length && prefix.every((seg, i) => seg === path[i]);
 const rename = (src, dst) => (state) => {
     const srcParsed = parse(src);
     const dstParsed = parse(dst);

package/fs/effects/proof.f.d.ts

@@ -2,6 +2,7 @@ export declare const proof: {
     lazy: {
         value: () => void;
         deferred: () => void;
+        step: () => void;
     };
     foldStep: {
         empty: () => void;
@@ -12,6 +13,10 @@ export declare const proof: {
         empty: () => void;
         runs: () => void;
     };
+    okStep: {
+        ok: () => void;
+        error: () => void;
+    };
     decode: () => void;
     match: {
         done: () => void;

package/fs/effects/proof.f.js

@@ -1,4 +1,5 @@
-import { decode, do_, foldStep, forEachStep, lazy, match, pure } from "./module.f.js";
+import { decode, do_, foldStep, forEachStep, lazy, match, okStep, pure } from "./module.f.js";
+import { error, ok } from "../types/result/module.f.js";
 const assertPure = (e, expected) => {
     const d = decode(e);
     if (!d.done) {
@@ -26,6 +27,10 @@ export const proof = {
                 throw 'decode must force the thunk';
             }
         },
+        step: () => {
+            const e = lazy(() => 5).step(v => pure(v * 2));
+            assertPure(e, 10);
+        },
     },
     foldStep: {
         empty: () => {
@@ -51,6 +56,22 @@ export const proof = {
             assertPure(e, undefined);
         },
     },
+    okStep: {
+        ok: () => {
+            const e = pure(ok(5)).step(okStep((v) => pure(ok(v * 2))));
+            const d = decode(e);
+            if (!d.done || d.result[0] !== 'ok' || d.result[1] !== 10) {
+                throw e.value;
+            }
+        },
+        error: () => {
+            const e = pure(error('oops')).step(okStep(v => pure(ok(v * 2))));
+            const d = decode(e);
+            if (!d.done || d.result[0] !== 'error' || d.result[1] !== 'oops') {
+                throw e.value;
+            }
+        },
+    },
     decode: () => {
         const d = decode(do_('add')(2, 3));
         if (d.done) {

package/fs/fjs/proof.f.d.ts

@@ -2,6 +2,7 @@ export declare const proof: {
     help: () => void;
     compileRequiresArgs: () => void;
     runModule: () => void;
+    mcp: () => void;
     throw: {
         runImportError: () => void;
     };

package/fs/fjs/proof.f.js

@@ -22,6 +22,12 @@ export const proof = {
         // `run` strips the command and file name, so `main` sees two arguments
         assertEq(code, 2);
     },
+    mcp: () => {
+        // stdin is empty in the virtual environment, so the server sees EOF
+        // immediately and shuts down cleanly, exercising the `mcp` handler.
+        const [, code] = run({})(['mcp']);
+        assertEq(code, 0);
+    },
     throw: {
         runImportError: () => {
             run({})(['run', 'missing.f.ts']);

package/fs/fsc/module.f.d.ts

@@ -6,5 +6,6 @@ export declare const proof: {
     throw: {
         unionConflict: () => void;
     };
+    defHandler: () => void;
 };
 export {};

package/fs/fsc/module.f.js

@@ -9,6 +9,7 @@ import { reduce as listReduce, toArray, map } from "../types/list/module.f.js";
 import { range as asciiRange } from "../text/ascii/module.f.js";
 import { fn } from "../types/function/module.f.js";
 import { one } from "../types/range/module.f.js";
+import { assertEq } from "../asserts/module.f.js";
 const fromCharCode = String.fromCharCode;
 const unexpectedSymbol = codePoint => [[`unexpected symbol ${codePoint}`], unexpectedSymbol];
 const def = () => unexpectedSymbol;
@@ -65,5 +66,8 @@ export const proof = {
             b(undefined);
             union(a)(b);
         }
-    }
+    },
+    // `def` is the range-map's default handler; the public API never calls it directly
+    // (`init` covers every code point), so exercise it here where it's in scope.
+    defHandler: () => assertEq(def(undefined), unexpectedSymbol)
 };

package/fs/js/tokenizer/module.f.d.ts

@@ -92,7 +92,7 @@ export type JsTokenWithMetadata = {
     readonly token: JsToken;
     readonly metadata: TokenMetadata;
 };
-type ErrorMessage = '" are missing' | 'unescaped character' | 'invalid hex value' | 'unexpected character' | 'invalid number' | 'invalid token' | '*\/ expected' | 'unterminated string literal' | 'eof';
+type ErrorMessage = '" are missing' | 'unescaped character' | 'invalid hex value' | 'unexpected character' | 'invalid number' | 'invalid token' | '*\/ expected' | 'unterminated string literal' | 'unescaped control character in string' | 'eof';
 export declare const isKeywordToken: (token: JsToken) => boolean;
 export declare const tokenize: (input: List<number>) => (path: string) => List<JsTokenWithMetadata>;
 export declare const proof: {

package/fs/js/tokenizer/module.f.js

@@ -372,10 +372,16 @@ const invalidNumberStateOp = create(() => () => [empty, { kind: 'invalidNumber'
         return [{ first: { kind: 'error', message: 'invalid number' }, tail: next[0] }, next[1]];
     })
 ]);
+const rangeSetStringControl = [
+    [0x00, 0x09],
+    [0x0b, 0x0c],
+    [0x0e, 0x1f],
+];
 const parseStringStateOp = create((state) => input => [empty, { kind: 'string', value: appendChar(state.value)(input) }])([
     rangeFunc(one(quotationMark))(state => () => [[{ kind: 'string', value: state.value }], { kind: 'initial' }]),
     rangeFunc(one(reverseSolidus))(state => () => [empty, { kind: 'escapeChar', value: state.value }]),
-    rangeSetFunc(rangeSetNewLine)(() => () => [[{ kind: 'error', message: 'unterminated string literal' }], { kind: 'nl' }])
+    rangeSetFunc(rangeSetNewLine)(() => () => [[{ kind: 'error', message: 'unterminated string literal' }], { kind: 'nl' }]),
+    rangeSetFunc(rangeSetStringControl)(state => () => [[{ kind: 'error', message: 'unescaped control character in string' }], { kind: 'string', value: state.value }])
 ]);
 const parseEscapeDefault = state => input => {
     const next = tokenizeOp(input, { kind: 'string', value: state.value });

package/fs/js/tokenizer/proof.f.js

@@ -141,6 +141,65 @@ export const proof = {
                 throw result;
             }
         },
+        () => {
+            // literal TAB inside a string is rejected; the escaped form is not
+            const result = stringify(tokenizeString('"\t"'));
+            if (result !== '[{"kind":"error","message":"unescaped control character in string"},{"kind":"string","value":""},{"kind":"eof"}]') {
+                throw result;
+            }
+        },
+        () => {
+            const result = stringify(tokenizeString('"\\t"'));
+            if (result !== '[{"kind":"string","value":"\\t"},{"kind":"eof"}]') {
+                throw result;
+            }
+        },
+        () => {
+            // literal VT (no JSON short escape; only \u000b is valid)
+            const result = stringify(tokenizeString('"\v"'));
+            if (result !== '[{"kind":"error","message":"unescaped control character in string"},{"kind":"string","value":""},{"kind":"eof"}]') {
+                throw result;
+            }
+        },
+        () => {
+            const result = stringify(tokenizeString('"\\u000b"'));
+            if (result !== '[{"kind":"string","value":"\\u000b"},{"kind":"eof"}]') {
+                throw result;
+            }
+        },
+        () => {
+            // literal FF is rejected; the escaped form is not
+            const result = stringify(tokenizeString('"\f"'));
+            if (result !== '[{"kind":"error","message":"unescaped control character in string"},{"kind":"string","value":""},{"kind":"eof"}]') {
+                throw result;
+            }
+        },
+        () => {
+            const result = stringify(tokenizeString('"\\f"'));
+            if (result !== '[{"kind":"string","value":"\\f"},{"kind":"eof"}]') {
+                throw result;
+            }
+        },
+        () => {
+            // literal NUL (no JSON short escape; only \u0000 is valid)
+            const result = stringify(tokenizeString('"\0"'));
+            if (result !== '[{"kind":"error","message":"unescaped control character in string"},{"kind":"string","value":""},{"kind":"eof"}]') {
+                throw result;
+            }
+        },
+        () => {
+            const result = stringify(tokenizeString('"\\u0000"'));
+            if (result !== '[{"kind":"string","value":"\\u0000"},{"kind":"eof"}]') {
+                throw result;
+            }
+        },
+        () => {
+            // control character surrounded by ordinary text still recovers the rest of the string
+            const result = stringify(tokenizeString('"a\tb"'));
+            if (result !== '[{"kind":"error","message":"unescaped control character in string"},{"kind":"string","value":"ab"},{"kind":"eof"}]') {
+                throw result;
+            }
+        },
         () => {
             const result = stringify(tokenizeString('"\\u1234"'));
             if (result !== '[{"kind":"string","value":"ሴ"},{"kind":"eof"}]') {

package/fs/json/parser/proof.f.js

@@ -155,6 +155,24 @@ export const proof = {
                 throw result;
             }
         },
+        // A literal control character inside a string is not valid JSON (RFC
+        // 8259 §7) even though the shared tokenizer would otherwise accept it.
+        () => {
+            const tokenList = tokenizeString('"\t"');
+            const obj = parse(tokenList);
+            const result = stringify(obj);
+            if (result !== '["error","unexpected token"]') {
+                throw result;
+            }
+        },
+        () => {
+            const tokenList = tokenizeString('{"a":"\t"}');
+            const obj = parse(tokenList);
+            const result = stringify(obj);
+            if (result !== '["error","unexpected token"]') {
+                throw result;
+            }
+        },
         () => {
             const tokenList = tokenizeString('[,]');
             const obj = parse(tokenList);

package/fs/path/module.f.d.ts

@@ -38,3 +38,9 @@ export declare const join: (...list: readonly string[]) => string;
  * E.g. `relativize('/repo', '/repo/fs/a.ts')` → `'./fs/a.ts'`.
  */
 export declare const relativize: (base: string, path: string) => string;
+/**
+ * Returns `true` when `prefix` is a strict ancestor of `path` in segment space:
+ * every segment of `prefix` matches the corresponding segment of `path`, and
+ * `path` has at least one additional segment.
+ */
+export declare const isProperPrefix: (prefix: readonly string[], path: readonly string[]) => boolean;

package/fs/path/module.f.js

@@ -63,3 +63,9 @@ export const join = (...list) => list.join('/');
  * E.g. `relativize('/repo', '/repo/fs/a.ts')` → `'./fs/a.ts'`.
  */
 export const relativize = (base, path) => base !== '' && path.startsWith(base) ? `.${path.slice(base.length)}` : path;
+/**
+ * Returns `true` when `prefix` is a strict ancestor of `path` in segment space:
+ * every segment of `prefix` matches the corresponding segment of `path`, and
+ * `path` has at least one additional segment.
+ */
+export const isProperPrefix = (prefix, path) => prefix.length < path.length && prefix.every((seg, i) => seg === path[i]);

package/fs/path/proof.f.d.ts

@@ -4,4 +4,5 @@ export declare const proof: {
     joinTest: (() => void)[];
     relativizeTest: (() => void)[];
     toPosixTest: (() => void)[];
+    isProperPrefixTest: (() => void)[];
 };

package/fs/path/proof.f.js

@@ -1,4 +1,4 @@
-import { concat, join, normalize, relativize, toPosix } from "./module.f.js";
+import { concat, isProperPrefix, join, normalize, relativize, toPosix } from "./module.f.js";
 const normalizeTest = [
     () => {
         const norm = normalize("dir/file.json");
@@ -129,4 +129,42 @@ const toPosixTest = [
         }
     },
 ];
-export const proof = { normalizeTest, concatTest, joinTest, relativizeTest, toPosixTest };
+const isProperPrefixTest = [
+    () => {
+        const r = isProperPrefix(['a', 'b'], ['a', 'b', 'c']);
+        if (r !== true) {
+            throw r;
+        }
+    },
+    () => {
+        const r = isProperPrefix(['a', 'b'], ['a', 'b']);
+        if (r !== false) {
+            throw r;
+        }
+    },
+    () => {
+        const r = isProperPrefix(['a', 'x'], ['a', 'b', 'c']);
+        if (r !== false) {
+            throw r;
+        }
+    },
+    () => {
+        const r = isProperPrefix(['a', 'b', 'c'], ['a', 'b']);
+        if (r !== false) {
+            throw r;
+        }
+    },
+    () => {
+        const r = isProperPrefix([], ['a']);
+        if (r !== true) {
+            throw r;
+        }
+    },
+    () => {
+        const r = isProperPrefix([], []);
+        if (r !== false) {
+            throw r;
+        }
+    },
+];
+export const proof = { normalizeTest, concatTest, joinTest, relativizeTest, toPosixTest, isProperPrefixTest };

package/fs/text/utf8/module.f.d.ts

@@ -46,6 +46,12 @@ export declare const utf8StateToError: (state: Utf8NonEmptyState) => I32;
 /**
  * Decodes a byte into a Unicode code point, using a given UTF-8 state.
  *
+ * Rejects overlong 3-/4-byte encodings (Unicode Table 3-7): a lead `E0` must
+ * be followed by a continuation `>= 0xA0`, and a lead `F0` by a continuation
+ * `>= 0x90`. It does not itself reject surrogates (`ED A0..BF`) or code
+ * points above `U+10FFFF` (`F4 90..BF`); {@link fromVec}'s
+ * `isValidCodePoint` pass filters those out of the raw code-point stream.
+ *
  * @param state - The current UTF-8 decoding state.
  * @param byte - A single byte to decode.
  * @returns A tuple containing:

package/fs/text/utf8/module.f.js

@@ -135,6 +135,12 @@ export const utf8StateToError = (state) => {
 /**
  * Decodes a byte into a Unicode code point, using a given UTF-8 state.
  *
+ * Rejects overlong 3-/4-byte encodings (Unicode Table 3-7): a lead `E0` must
+ * be followed by a continuation `>= 0xA0`, and a lead `F0` by a continuation
+ * `>= 0x90`. It does not itself reject surrogates (`ED A0..BF`) or code
+ * points above `U+10FFFF` (`F4 90..BF`); {@link fromVec}'s
+ * `isValidCodePoint` pass filters those out of the raw code-point stream.
+ *
  * @param state - The current UTF-8 decoding state.
  * @param byte - A single byte to decode.
  * @returns A tuple containing:
@@ -159,8 +165,15 @@ export const utf8ByteToCodePointOp = (byte, state) => {
                 if (s0 < lead3Tag) {
                     return [[((s0 & lead2Mask) << 6) + contPayload(byte)], null];
                 }
-                if (s0 < 0b1111_1000)
-                    return [[], [s0, byte]];
+                if (s0 < 0b1111_1000) {
+                    // Reject overlong 3-/4-byte encodings: after lead `E0` the
+                    // first continuation must be >= 0xA0, after lead `F0` it
+                    // must be >= 0x90 (Unicode Table 3-7).
+                    const overlong = s0 === lead3Tag && byte < 0b1010_0000 ||
+                        s0 === lead4Tag && byte < 0b1001_0000;
+                    if (!overlong)
+                        return [[], [s0, byte]];
+                }
                 break;
             }
             case 2: {

package/fs/text/utf8/proof.f.js

@@ -65,6 +65,45 @@ export const proof = {
             if (result !== '[-2147448800,-2147432416]') {
                 throw result;
             }
+        },
+        // Overlong 3-byte encodings (E0 80..9F ..) are rejected, not decoded.
+        () => {
+            const result = stringify(toArray(toCodePointList([224, 128, 128])));
+            if (result !== '[-2147483424,-2147483520,-2147483520]') {
+                throw result;
+            }
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([224, 159, 191])));
+            if (result !== '[-2147483424,-2147483489,-2147483457]') {
+                throw result;
+            }
+        },
+        // Overlong 4-byte encodings (F0 80..8F .. ..) are rejected, not decoded.
+        () => {
+            const result = stringify(toArray(toCodePointList([240, 128, 128, 128])));
+            if (result !== '[-2147483408,-2147483520,-2147483520,-2147483520]') {
+                throw result;
+            }
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([240, 143, 191, 191])));
+            if (result !== '[-2147483408,-2147483505,-2147483457,-2147483457]') {
+                throw result;
+            }
+        },
+        // Valid boundary cases still decode: E0 A0 80 -> U+0800, F0 90 80 80 -> U+10000.
+        () => {
+            const result = stringify(toArray(toCodePointList([224, 160, 128])));
+            if (result !== '[2048]') {
+                throw result;
+            }
+        },
+        () => {
+            const result = stringify(toArray(toCodePointList([240, 144, 128, 128])));
+            if (result !== '[65536]') {
+                throw result;
+            }
         }
     ],
     fromCodePointList: [
@@ -229,5 +268,19 @@ export const proof = {
                 throw 'expected empty string';
             }
         },
+        // Overlong 3-byte encoding (E0 80 80, would decode to U+0000) → null
+        () => {
+            const v = u8ListToVec(msb)([0xe0, 0x80, 0x80]);
+            if (fromVec(v) !== null) {
+                throw 'expected null for overlong 3-byte encoding';
+            }
+        },
+        // Overlong 4-byte encoding (F0 80 80 80, would decode to U+0000) → null
+        () => {
+            const v = u8ListToVec(msb)([0xf0, 0x80, 0x80, 0x80]);
+            if (fromVec(v) !== null) {
+                throw 'expected null for overlong 4-byte encoding';
+            }
+        },
     ]
 };

package/fs/types/result/module.f.d.ts

@@ -55,3 +55,7 @@ export declare const unwrap: <T, E>([kind, v]: Result<T, E>) => T;
  * Swaps the `ok` and `error` cases of a result.
  */
 export declare const invert: <T, E>([k, v]: Result<T, E>) => Result<E, T>;
+/**
+ * Maps the `ok` case of a result, passing an `error` through unchanged.
+ */
+export declare const mapOk: <T, R>(f: (value: T) => R) => <E>(r: Result<T, E>) => Result<R, E>;

package/fs/types/result/module.f.js

@@ -48,3 +48,7 @@ export const unwrap = ([kind, v]) => {
  * Swaps the `ok` and `error` cases of a result.
  */
 export const invert = ([k, v]) => k === 'ok' ? error(v) : ok(v);
+/**
+ * Maps the `ok` case of a result, passing an `error` through unchanged.
+ */
+export const mapOk = (f) => (r) => r[0] === 'ok' ? ok(f(r[1])) : r;

package/fs/types/result/proof.f.d.ts

@@ -2,4 +2,5 @@ export declare const proof: {
     example: () => void;
     invertTest: () => void;
     unwrapError: () => void;
+    mapOkTest: () => void;
 };