functionalscript 0.39.0 → 0.41.0

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

@@ -12,5 +12,7 @@ export declare const proof: {
         configuredPackageVersion: () => void;
         missingPackageJson: () => void;
     };
+    nixFlakes: () => void;
+    nixFlakeJob: () => void;
     ubuntu: () => void;
 };

package/fjs/ci/proof.f.js

@@ -1,5 +1,6 @@
 import { ci, main } from './module.f.js';
-import { functionalscript } from './config/module.f.js';
+import { functionalscript, node } from './config/module.f.js';
+import { nodeNixJobs } from './node/module.f.js';
 import { utf8, utf8ToString } from '../text/module.f.js';
 import { empty as emptyVec, isVec } from '../types/bit_vec/module.f.js';
 import { test, ubuntu, parseGitHubAction } from './common/module.f.js';
@@ -19,15 +20,22 @@ const makeState = (rust, packageJson) => ({
         ...(rust ? { 'Cargo.toml': [emptyVec] } : {}),
     },
 });
-const workflow = (state) => {
-    const dotGithub = state.root['.github'];
-    assert(typeof dotGithub === 'object' && !Array.isArray(dotGithub), dotGithub);
-    const workflows = dotGithub['workflows'];
-    assert(typeof workflows === 'object' && !Array.isArray(workflows), workflows);
-    const file = workflows['ci.yml'];
+const subDir = (dir, name) => {
+    const entity = dir[name];
+    assert(typeof entity === 'object' && !Array.isArray(entity), entity);
+    return entity;
+};
+const text = (dir, name) => {
+    const file = dir[name];
     assert(!(!Array.isArray(file) || file.length === 0), file);
-    return unwrap(parseGitHubAction(jsonParse(utf8ToString(file[0]))));
+    return utf8ToString(file[0]);
 };
+const path = (dir, names) => names.reduce(subDir, dir);
+const workflow = (state) => {
+    const workflows = path(state.root, ['.github', 'workflows']);
+    return unwrap(parseGitHubAction(jsonParse(text(workflows, 'ci.yml'))));
+};
+const flake = (state, id) => text(path(state.root, ['nix', 'generated', id]), 'flake.nix');
 const run = (rust, nodeExtra = () => []) => {
     const [state, result] = virtual(makeState(rust))(ci({ nodeExtra }));
     assertEq(result, 0);
@@ -75,7 +83,6 @@ export const proof = {
             'node22',
             'node24',
             'node26',
-            'playwright',
         ]) {
             assert(hasRunInJob(id, 'npm ci')(gha), `expected npm ci in ${id}`);
         }
@@ -135,6 +142,37 @@ export const proof = {
             assert(hasRun(`npm install -g functionalscript@${functionalscript}`)(gha), 'expected configured-version install');
         },
     },
+    nixFlakes: () => {
+        const [state, result] = virtual(makeState(false))(main());
+        assertEq(result, 0);
+        for (const { id, packages } of nodeNixJobs) {
+            const [nodePackage] = packages;
+            assert(flake(state, id).includes(`pkgs.${nodePackage}`), `expected ${nodePackage} in the ${id} flake`);
+        }
+    },
+    nixFlakeJob: () => {
+        const gha = run(false);
+        const job = gha.jobs['nix-flakes'];
+        assert(job !== undefined, 'expected the temporary flake job');
+        assert(job.steps.some(step => step.uses?.startsWith('cachix/install-nix-action@') === true), 'expected a pinned Nix installer');
+        // Exactly one check per unmigrated flake: none goes unchecked, and no
+        // check outlives the flake it was written for. A migrated job checks its
+        // own flake by running through it, so it is not covered here.
+        assertEq(job.steps.filter(step => step.run !== undefined).length, nodeNixJobs.length);
+        for (const { id } of nodeNixJobs) {
+            assert(hasRunInJob('nix-flakes', `nix develop ./nix/generated/${id} --command node --version`)(gha), `expected the ${id} flake to be instantiated`);
+        }
+        // Since the flakes no longer assert their own version, this job is the
+        // only place the Nix runtime is tied to the version `setup-node` installs.
+        for (const version of [node.node22, node.node24, node.default]) {
+            assert(hasRunInJob('nix-flakes', `= v${version}`)(gha), `expected the flake job to check Node ${version}`);
+        }
+        // The canonical Node jobs keep their current runtime setup until they
+        // are migrated one at a time.
+        for (const { id } of nodeNixJobs) {
+            assert(!hasRunInJob(id, 'nix develop')(gha), `unexpected nix develop in ${id}`);
+        }
+    },
     ubuntu: () => {
         const job = ubuntu([test({ run: 'echo hi' })]);
         assert(job['runs-on'] !== undefined, 'expected runs-on');

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

@@ -42,4 +42,5 @@ export type LoadModuleOperations = Access | Import | All | Readdir;
 export declare const loadModuleMap: (env: Env) => Effect<LoadModuleOperations, ModuleMap>;
 export declare const proof: {
     isSourceFile: () => void;
+    allFilesSkipsNodeModules: () => void;
 };

package/fjs/dev/module.f.js

@@ -8,7 +8,8 @@ import { cmp as strCmp } from '../types/string/module.f.js';
 import { unwrap } from '../types/result/module.f.js';
 import { pure, step } from '../effects/module.f.js';
 import { join, relativize, toPosix } from '../path/module.f.js';
-import { assert } from '../asserts/module.f.js';
+import { assert, assertEq } from '../asserts/module.f.js';
+import { emptyState, virtual } from '../effects/node/virtual/module.f.js';
 /**
  * Returns `true` if the file should be loaded for proof discovery.
  *
@@ -72,7 +73,7 @@ export const loadModuleMap = (env) => {
     const s = initCwd === undefined ? '.' : toPosix(initCwd);
     const prefix = s === '.' ? '' : s;
     // TODO: there are multiple `all` effects here,
-    //       we should consider optimize them by ALIQ technique or something similar.
+    //       we should consider optimizing them by ALIQ technique or something similar.
     //       For example, we should be able to write it like `allFiles(s).flatMap(loadFile)`,
     //       then an effect runner can batch all file loading operations together.
     const x0 = step(allFiles(s, shouldLoad), files => all(...files.map(loadFile)));
@@ -90,4 +91,14 @@ export const proof = {
         assert(!isSourceFile('readme.md'));
         assert(!isSourceFile('module.json'));
     },
+    allFilesSkipsNodeModules: () => {
+        // `node_modules` is skipped without descending into it, even though
+        // it contains a file that would otherwise match the predicate.
+        const root = {
+            'node_modules': { 'pkg.f.ts': [] },
+            'a.f.ts': [],
+        };
+        const [, result] = virtual({ ...emptyState, root })(allFiles('.', shouldLoad));
+        assertEq(result.join(','), './a.f.ts');
+    },
 };

package/fjs/dev/update/module.f.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Synchronizes local development configuration generated from canonical repository files.
+ *
+ * @module
+ */
+import { type Effect } from '../../effects/module.f.ts';
+import { type Mkdir, type NodeProgram, type ReadFile, type WriteFile } from '../../effects/node/module.f.ts';
+/** Regenerates VS Code's local MCP configuration from the canonical Copilot configuration. */
+export declare const syncMcp: () => Effect<Mkdir | ReadFile | WriteFile, void>;
+/** Runs all local development configuration generators. */
+export declare const main: NodeProgram;

package/fjs/dev/update/module.f.js

@@ -0,0 +1,20 @@
+/**
+ * Synchronizes local development configuration generated from canonical repository files.
+ *
+ * @module
+ */
+import { history, historyStep, mapStep, step } from '../../effects/module.f.js';
+import { mkdir, readUtf8File, writeUtf8File } from '../../effects/node/module.f.js';
+import { unwrap } from '../../types/result/module.f.js';
+const source = '.copilot/mcp.json';
+const targetDirectory = '.vscode';
+const target = '.vscode/mcp.json';
+/** Regenerates VS Code's local MCP configuration from the canonical Copilot configuration. */
+export const syncMcp = () => {
+    const sourceText = history(mapStep(readUtf8File(source), unwrap));
+    const targetDirectoryReady = historyStep(sourceText, () => mapStep(mkdir(targetDirectory, { recursive: true }), unwrap));
+    const targetWritten = step(targetDirectoryReady, ([, text]) => writeUtf8File(target, text));
+    return mapStep(targetWritten, unwrap);
+};
+/** Runs all local development configuration generators. */
+export const main = () => mapStep(syncMcp(), () => 0);

package/fjs/dev/update/proof.f.d.ts

@@ -0,0 +1,7 @@
+export declare const proof: {
+    syncMcp: () => void;
+    main: () => void;
+    throw: {
+        missingSource: () => readonly [import("../../effects/node/virtual/module.f.ts").State, void];
+    };
+};

package/fjs/dev/update/proof.f.js

@@ -0,0 +1,35 @@
+/**
+ * Proofs for local development configuration generation.
+ *
+ * @module
+ */
+import { assert, assertEq } from '../../asserts/module.f.js';
+import { utf8 } from '../../text/module.f.js';
+import { readUtf8File } from '../../effects/node/module.f.js';
+import { defaultNodeProgramOptions, emptyState, virtual } from '../../effects/node/virtual/module.f.js';
+import { main, syncMcp } from './module.f.js';
+import { step } from '../../effects/module.f.js';
+const mcp = '{"servers":{}}';
+const initial = {
+    ...emptyState,
+    root: {
+        '.copilot': {
+            'mcp.json': [utf8(mcp)],
+        },
+    },
+};
+export const proof = {
+    syncMcp: () => {
+        const generatedMcp = step(syncMcp(), () => readUtf8File('.vscode/mcp.json'));
+        const [, [tag, result]] = virtual(initial)(generatedMcp);
+        assert(tag === 'ok', result);
+        assertEq(result, mcp);
+    },
+    main: () => {
+        const [, result] = virtual(initial)(main(defaultNodeProgramOptions));
+        assertEq(result, 0);
+    },
+    throw: {
+        missingSource: () => virtual(emptyState)(syncMcp()),
+    },
+};

package/fjs/djs/ast/module.f.d.ts

@@ -4,12 +4,59 @@
  * @module
  */
 import type { Primitive, Array, Unknown } from '../module.f.ts';
+/**
+ * A parsed DJS module: its imported module specifiers, in source order, and
+ * its body.
+ *
+ * The specifier list indexes `['aref', i]`.
+ */
 export type AstModule = [readonly string[], AstBody];
+/** A value in a module body: a primitive, a reference, an array, or an object. */
 export type AstConst = Primitive | AstModuleRef | AstArray | AstObject;
+/**
+ * A reference to a value defined outside this `AstConst`.
+ *
+ * - `['aref', i]` — the `i`-th argument of the body, i.e. the `i`-th imported
+ *   module of the enclosing `AstModule`.
+ * - `['cref', i]` — the `i`-th entry of the enclosing `AstBody`.
+ *
+ * Both indices are absolute and zero-based, **not** offsets from the
+ * referencing entry: in the body `[a, b, ['cref', 0]]` the reference resolves
+ * to `a`, not to the nearest preceding entry `b`.
+ *
+ * A `cref` index must be smaller than the index of the entry holding it —
+ * `run` evaluates a body left to right, so a reference to the current or a
+ * later entry is unsatisfiable. It is not rejected: it resolves to the most
+ * recently evaluated entry instead.
+ */
 export type AstModuleRef = ['aref' | 'cref', number];
+/** An array value; its elements are evaluated in order. */
 export type AstArray = ['array', readonly AstConst[]];
+/** An object value, keyed by property name. */
 export type AstObject = {
     readonly [k in string]?: AstConst;
 };
+/**
+ * The constants of a module body, in declaration order. The **last** entry is
+ * the value the module yields; the preceding entries exist to be named by
+ * `['cref', i]`.
+ *
+ * A body describes the function
+ *
+ * ```js
+ * (...args) => { const c0 = ...; const c1 = ...; return <last> }
+ * ```
+ *
+ * where `args` are the imported modules.
+ */
 export type AstBody = readonly AstConst[];
+/**
+ * Evaluates a module body against its imported modules and returns the value
+ * the module yields — the last entry of the body.
+ *
+ * Entries are evaluated left to right, so a `cref` resolves to an already
+ * evaluated entry. A reference is shared, not copied: two properties holding
+ * the same `['cref', i]` deserialize to the same object, which is what lets a
+ * DJS module denote a graph rather than a tree.
+ */
 export declare const run: (body: AstBody) => (args: Array) => Unknown;

package/fjs/djs/ast/module.f.js

@@ -42,6 +42,15 @@ const toDjs = state => ast => {
         }
     }
 };
+/**
+ * Evaluates a module body against its imported modules and returns the value
+ * the module yields — the last entry of the body.
+ *
+ * Entries are evaluated left to right, so a `cref` resolves to an already
+ * evaluated entry. A reference is shared, not copied: two properties holding
+ * the same `['cref', i]` deserialize to the same object, which is what lets a
+ * DJS module denote a graph rather than a tree.
+ */
 export const run = body => args => {
     const state = fold(foldOp)({ body, args, consts: null })(body);
     return last(null)(state.consts);

package/fjs/djs/tokenizer/module.f.js

@@ -364,7 +364,7 @@ export const tokenizeString = s => {
     }
     const m = descentParser(jsGrammar());
     const cpm = codePointsWithMetadata('')(cp);
-    const [ast, ok, len] = m('', cpm);
+    const { ast, success: ok, idx: len } = m('', cpm);
     if (!ok || len !== cp.length)
         return 'error';
     const flatTokens = toArray(getTokensFromAstRule(ast));
@@ -394,7 +394,7 @@ export const tokenizeJs = input => path => {
         return [{ token: { kind: 'eof' }, metadata: initial }];
     const m = descentParser(jsGrammar());
     const cpm = codePointsWithMetadata(path)(cp);
-    const [ast, ok, len] = m('', cpm);
+    const { ast, success: ok, idx: len } = m('', cpm);
     const finalMetadata = fold(advanceMetadata)(initial)(cp);
     if (!ok || len !== cp.length) {
         const errorMetadata = len < cpm.length ? cpm[len][1] : finalMetadata;

package/fjs/djs/tokenizer/proof.f.d.ts

@@ -8,6 +8,7 @@ export declare const proof: {
     keywords: (() => void)[];
     comments: (() => void)[];
     metadata: (() => void)[];
+    errorPosition: (() => void)[];
     djsTokenize: (() => void)[];
     largeInputs: (() => void)[];
 };

package/fjs/djs/tokenizer/proof.f.js

@@ -8,13 +8,21 @@ import { sort } from '../../types/object/module.f.js';
 // DjsTokenWithMetadata carries bigint fields (bf, bigint value) that JSON.stringify can't
 // serialize — reuse the same djs stringifyAsTree serializer tokenizeString uses internally.
 const stringify = stringifyAsTree(sort);
+// 'line:column' of the error token `s` tokenizes to, or 'no error'. Collapsing the
+// position to one string keeps an expectation readable as the caret a reader would
+// draw, instead of two separate assertions per case.
+const errorAt = (s) => {
+    const found = toArray(tokenizeJs(stringToList(s))('a.js'))
+        .find(t => t.token.kind === 'error');
+    return found === undefined ? 'no error' : `${found.metadata.line}:${found.metadata.column}`;
+};
 export const proof = {
     isValid: [() => {
             const m = descentParser(jsGrammar());
             const expect = (s, expected) => {
                 const cp = toArray(stringToCodePointList(s));
                 const mr = descentParserCpOnly(m, '', cp);
-                const success = mr[1] && mr[2] === cp.length;
+                const success = mr.success && mr.idx === cp.length;
                 assertEq(success, expected, JSON.stringify([s, mr]));
             };
             expect('"', false);
@@ -51,7 +59,7 @@ export const proof = {
             const m = descentParser(jsGrammar());
             const cp = toArray(stringToCodePointList('tr'));
             const mr = descentParserCpOnly(m, '', cp);
-            const seq = mr[0].sequence[0];
+            const seq = mr.ast.sequence[0];
             assert(!(seq instanceof Array), JSON.stringify(mr));
             assertEq(seq.tag, 'id', JSON.stringify(mr));
         },
@@ -59,7 +67,7 @@ export const proof = {
             const m = descentParser(jsGrammar());
             const cp = toArray(stringToCodePointList('"tr"'));
             const mr = descentParserCpOnly(m, '', cp);
-            const seq = mr[0].sequence[0];
+            const seq = mr.ast.sequence[0];
             assert(!(seq instanceof Array), JSON.stringify(mr));
             assertEq(seq.tag, 'string', JSON.stringify(mr));
         },
@@ -67,7 +75,7 @@ export const proof = {
             const m = descentParser(jsGrammar());
             const cp = toArray(stringToCodePointList('56.7e+5'));
             const mr = descentParserCpOnly(m, '', cp);
-            const seq = mr[0].sequence[0];
+            const seq = mr.ast.sequence[0];
             assert(!(seq instanceof Array), JSON.stringify(mr));
             assertEq(seq.tag, 'number', JSON.stringify(mr));
         },
@@ -75,7 +83,7 @@ export const proof = {
             const m = descentParser(jsGrammar());
             const cp = toArray(stringToCodePointList('56n'));
             const mr = descentParserCpOnly(m, '', cp);
-            const seq = mr[0].sequence[0];
+            const seq = mr.ast.sequence[0];
             assert(!(seq instanceof Array), JSON.stringify(mr));
             assertEq(seq.tag, 'number', JSON.stringify(mr));
         },
@@ -83,7 +91,7 @@ export const proof = {
             const m = descentParser(jsGrammar());
             const cp = toArray(stringToCodePointList('*'));
             const mr = descentParserCpOnly(m, '', cp);
-            const seq = mr[0].sequence[0];
+            const seq = mr.ast.sequence[0];
             assert(!(seq instanceof Array), JSON.stringify(mr));
             assertEq(seq.tag, '*', JSON.stringify(mr));
         },
@@ -91,7 +99,7 @@ export const proof = {
             const m = descentParser(jsGrammar());
             const cp = toArray(stringToCodePointList('**'));
             const mr = descentParserCpOnly(m, '', cp);
-            const seq = mr[0].sequence[0];
+            const seq = mr.ast.sequence[0];
             assert(!(seq instanceof Array), JSON.stringify(mr));
             assertEq(seq.tag, '**', JSON.stringify(mr));
         },
@@ -99,7 +107,7 @@ export const proof = {
             const m = descentParser(jsGrammar());
             const cp = toArray(stringToCodePointList('=>'));
             const mr = descentParserCpOnly(m, '', cp);
-            const seq = mr[0].sequence[0];
+            const seq = mr.ast.sequence[0];
             assert(!(seq instanceof Array), JSON.stringify(mr));
             assertEq(seq.tag, '=>', JSON.stringify(mr));
         },
@@ -107,7 +115,7 @@ export const proof = {
             const m = descentParser(jsGrammar());
             const cp = toArray(stringToCodePointList('=='));
             const mr = descentParserCpOnly(m, '', cp);
-            const seq = mr[0].sequence[0];
+            const seq = mr.ast.sequence[0];
             assert(!(seq instanceof Array), JSON.stringify(mr));
             assert(!(seq.tag !== '=='), JSON.stringify(mr));
         },
@@ -115,7 +123,7 @@ export const proof = {
             const m = descentParser(jsGrammar());
             const cp = toArray(stringToCodePointList('==='));
             const mr = descentParserCpOnly(m, '', cp);
-            const seq = mr[0].sequence[0];
+            const seq = mr.ast.sequence[0];
             assert(!(seq instanceof Array), JSON.stringify(mr));
             assert(!(seq.tag !== '==='), JSON.stringify(mr));
         },
@@ -123,7 +131,7 @@ export const proof = {
             const m = descentParser(jsGrammar());
             const cp = toArray(stringToCodePointList('='));
             const mr = descentParserCpOnly(m, '', cp);
-            const seq = mr[0].sequence[0];
+            const seq = mr.ast.sequence[0];
             assert(!(seq instanceof Array), JSON.stringify(mr));
             assertEq(seq.tag, '=', JSON.stringify(mr));
         },
@@ -131,7 +139,7 @@ export const proof = {
             const m = descentParser(jsGrammar());
             const cp = toArray(stringToCodePointList(' '));
             const mr = descentParserCpOnly(m, '', cp);
-            const seq = mr[0].sequence[0];
+            const seq = mr.ast.sequence[0];
             assert(!(seq instanceof Array), JSON.stringify(mr));
             assertEq(seq.tag, ' ', JSON.stringify(mr));
         },
@@ -139,7 +147,7 @@ export const proof = {
             const m = descentParser(jsGrammar());
             const cp = toArray(stringToCodePointList('\n'));
             const mr = descentParserCpOnly(m, '', cp);
-            const seq = mr[0].sequence[0];
+            const seq = mr.ast.sequence[0];
             assert(!(seq instanceof Array), JSON.stringify(mr));
             assertEq(seq.tag, '\n', JSON.stringify(mr));
         },
@@ -147,7 +155,7 @@ export const proof = {
             const m = descentParser(jsGrammar());
             const cp = toArray(stringToCodePointList('/\n'));
             const mr = descentParserCpOnly(m, '', cp);
-            const seq = mr[0].sequence[0];
+            const seq = mr.ast.sequence[0];
             assert(!(seq instanceof Array), JSON.stringify(mr));
             assertEq(seq.tag, '/', JSON.stringify(mr));
         },
@@ -155,7 +163,7 @@ export const proof = {
             const m = descentParser(jsGrammar());
             const cp = toArray(stringToCodePointList('//\n'));
             const mr = descentParserCpOnly(m, '', cp);
-            const seq = mr[0].sequence[0];
+            const seq = mr.ast.sequence[0];
             assert(!(seq instanceof Array), JSON.stringify(mr));
             assertEq(seq.tag, 'comment', JSON.stringify(mr));
         },
@@ -163,7 +171,7 @@ export const proof = {
             const m = descentParser(jsGrammar());
             const cp = toArray(stringToCodePointList('/*1*/'));
             const mr = descentParserCpOnly(m, '', cp);
-            const seq = mr[0].sequence[0];
+            const seq = mr.ast.sequence[0];
             assert(!(seq instanceof Array), JSON.stringify(mr));
             assertEq(seq.tag, 'comment', JSON.stringify(mr));
         }
@@ -1056,6 +1064,52 @@ export const proof = {
             assertEq(JSON.stringify(result), '[{"token":{"kind":"error","message":"invalid token"},"metadata":{"path":"a.js","line":1,"column":2}}]');
         },
     ],
+    // Where an error token is reported. The `tokenizer` group above checks that
+    // these inputs are rejected at all, through the metadata-free
+    // `tokenizeString`; here the same shapes go through `tokenizeJs` so the
+    // position is pinned too.
+    errorPosition: [
+        () => {
+            // input that tokenizes cleanly produces no error token at all —
+            // without this the helper's own no-error branch never runs
+            assertEq(errorAt('x'), 'no error');
+            assertEq(errorAt('{ "a": 1 }'), 'no error');
+        },
+        () => {
+            // a character no rule accepts: reported where it stands
+            assertEq(errorAt('ᄑ'), '1:1');
+        },
+        () => {
+            // after a good prefix, the position advances past it
+            assertEq(errorAt('x @'), '1:3');
+        },
+        () => {
+            // line as well as column, once newlines have been consumed
+            assertEq(errorAt('a\nb\n@'), '3:1');
+            assertEq(errorAt('x\n\n  @y'), '3:3');
+        },
+        () => {
+            // a number poisoned by a trailing character points at that character
+            assertEq(errorAt('00'), '1:2');
+        },
+        () => {
+            // a number cut short points just past the input
+            assertEq(errorAt('1.'), '1:3');
+        },
+        () => {
+            // Unterminated tokens anchor at the token's *start*, not where the
+            // input ran out: the grammar matches them and tags them
+            // 'unterminated', so this is the structural-error path, not a failed
+            // match. See ./todo/error-position-range.md.
+            assertEq(errorAt('"value'), '1:1');
+            assertEq(errorAt('"a\nb"'), '1:1');
+        },
+        () => {
+            // an unterminated block comment is the exception: its content is
+            // consumed, so the report lands at the end of input
+            assertEq(errorAt('/* c'), '1:5');
+        },
+    ],
     // DJS-level: keyword remapping and '-'-folding on top of tokenizeJs. Doesn't re-test
     // JS-level token shapes already covered above/elsewhere in this file.
     djsTokenize: [

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

@@ -379,6 +379,26 @@ export type MatchResult<O extends Operation, T, R> = readonly ['done', T] | read
  * with the continuation. The one world-specific step — `await` for async
  * runners, state threading for sync ones — is left to the caller, so every
  * interpreter loop is this skeleton plus a single eliminator line.
+ *
+ * **The handler is looked up with `at`, never with `map[command]`.**
+ * `OperationMap<O, R>` pins `command` to `O[0]` at the type level, but a `Do`
+ * node's `command` is runtime data — it can reach an interpreter from a decoded
+ * payload or a deserialized continuation, where no type ever constrained it.
+ * `map` is an ordinary object, so a plain index read resolves an inherited name
+ * (`'constructor'`, `'toString'`, `'hasOwnProperty'`) to the `Object.prototype`
+ * member instead of `undefined`, and the line below would then call it with the
+ * node's payload: a value the type system promised was `(...payload) => R` turns
+ * out to be an arbitrary inherited function, chosen by the same input that
+ * supplies its arguments. `at` reads through `getOwnPropertyDescriptor`, which
+ * only ever sees own properties, so such a command yields `null` and never a
+ * callable.
+ *
+ * A `null` handler is an invariant violation, not an outcome: every `O1 extends
+ * O` the signature admits has its command in `map`, so reaching it means the
+ * node's `command` was never the `O1[0]` it claimed to be. It therefore throws
+ * (`assert`) rather than widening {@link MatchResult} with a variant no
+ * type-correct caller could ever observe — a runner cannot resume a command it
+ * has no handler for, so there is nothing for a recovery branch to do.
  */
 export declare const match: <O extends Operation, R>(map: OperationMap<O, R>) => <O1 extends O, T>(e: Effect<O1, T>) => MatchResult<O1, T, R>;
 export type ToAsyncOperationMap<O extends Operation> = {

package/fjs/effects/module.f.js

@@ -94,7 +94,9 @@
  *
  * @module
  */
+import { assert } from '../asserts/module.f.js';
 import { fold } from '../types/list/module.f.js';
+import { at } from '../types/object/module.f.js';
 export const pure = (v) => () => v;
 /**
  * Composes effects: run `e`, then continue with `f` applied to its result.
@@ -278,11 +280,33 @@ export const runPure = (e) => typeof e === 'function' ? [e()] : [];
  * with the continuation. The one world-specific step — `await` for async
  * runners, state threading for sync ones — is left to the caller, so every
  * interpreter loop is this skeleton plus a single eliminator line.
+ *
+ * **The handler is looked up with `at`, never with `map[command]`.**
+ * `OperationMap<O, R>` pins `command` to `O[0]` at the type level, but a `Do`
+ * node's `command` is runtime data — it can reach an interpreter from a decoded
+ * payload or a deserialized continuation, where no type ever constrained it.
+ * `map` is an ordinary object, so a plain index read resolves an inherited name
+ * (`'constructor'`, `'toString'`, `'hasOwnProperty'`) to the `Object.prototype`
+ * member instead of `undefined`, and the line below would then call it with the
+ * node's payload: a value the type system promised was `(...payload) => R` turns
+ * out to be an arbitrary inherited function, chosen by the same input that
+ * supplies its arguments. `at` reads through `getOwnPropertyDescriptor`, which
+ * only ever sees own properties, so such a command yields `null` and never a
+ * callable.
+ *
+ * A `null` handler is an invariant violation, not an outcome: every `O1 extends
+ * O` the signature admits has its command in `map`, so reaching it means the
+ * node's `command` was never the `O1[0]` it claimed to be. It therefore throws
+ * (`assert`) rather than widening {@link MatchResult} with a variant no
+ * type-correct caller could ever observe — a runner cannot resume a command it
+ * has no handler for, so there is nothing for a recovery branch to do.
  */
 export const match = (map) => (e) => {
     if (typeof e === 'function') {
         return ['done', e()];
     }
     const { command, payload, continuation } = e;
-    return ['cont', map[command](...payload), continuation];
+    const handler = at(command)(map);
+    assert(handler !== null, command);
+    return ['cont', handler(...payload), continuation];
 };

package/fjs/effects/node/module.d.ts

@@ -4,9 +4,9 @@ import { type NodeProgram } from './module.f.ts';
  * resolving to its exit code **without** terminating the process.
  *
  * Use this when the caller must stay alive afterwards — e.g. when proofs are
- * registered under an external test runner (Node `--test`, Bun, Playwright)
- * that owns the process lifecycle. For a standalone CLI entry point that should
- * exit with the program's code, use {@link run} instead.
+ * registered under an external test runner (Node `--test`, Bun, Deno) that owns
+ * the process lifecycle. For a standalone CLI entry point that should exit with
+ * the program's code, use {@link run} instead.
  */
 export declare const runEffect: (p: NodeProgram) => Promise<number>;
 /**