functionalscript 0.44.0 → 0.46.0

package/fjs/djs/transpiler/module.f.mjs

@@ -5,12 +5,13 @@
  *
  * @import { Unknown } from '../types.ts'
  * @import { Result } from '../../types/result/types.ts'
- * @import { List } from '../../types/list/types.ts'
- * @import { OrderedMap } from '../../types/ordered_map/types.ts'
  * @import { ParseError } from '../parser/types.ts'
  * @import { AstModule } from '../ast/types.ts'
+ * @import { Operation } from '../../effects/types.ts'
+ * @import { IoChannel } from '../../effects/node/types.ts'
  * @import { Effect } from '../../effects/types.ts'
  * @import { ReadFile } from '../../effects/node/types.ts'
+ * @import { ParseContext } from './types.ts'
  */
 
 import { error, ok } from '../../types/result/module.f.mjs'
@@ -20,27 +21,20 @@ import { setReplace, at } from '../../types/ordered_map/module.f.mjs'
 import { stringToList } from '../../text/utf16/module.f.mjs'
 import { concat as pathConcat } from '../../path/module.f.mjs'
 import { parseFromTokens } from '../parser/module.f.mjs'
+import { parse as jsonParse } from '../../media/json/module.f.mjs'
 import { run } from '../ast/module.f.mjs'
-import { foldStep, pure, step } from '../../effects/module.f.mjs'
+import { pure } from '../../effects/module.f.mjs'
+import { catchStep, foldStep, mapStep, pureError, pureOk, step } from '../../effects/module.f.mjs'
 import { readUtf8File } from '../../effects/node/module.f.mjs'
 
 /**
- * State threaded through the recursive transpilation of a DJS module graph.
+ * Reads a file, reporting any failure as the one `ParseError` a caller can act
+ * on. Both readers want this and neither wants the node channel's vocabulary.
  *
- * - `complete`: modules that have been fully parsed and evaluated, keyed by path.
- * - `stack`: import chain currently being resolved (used to detect circular dependencies).
- * - `error`: the first parse error encountered, or `null` while everything is clean.
- * @typedef {{
- *   readonly complete: OrderedMap<djsResult>
- *   readonly stack: List<string>
- *   readonly error: ParseError | null
- * }} ParseContext
- */
-
-/**
- * The evaluated DJS value produced for one successfully transpiled module.
- * @typedef {{ djs: Unknown }} djsResult
+ * @type {<O extends Operation>(e: Effect<O, string, IoChannel>) => Effect<O, string, ParseError>}
  */
+const notFound = e =>
+    catchStep(e, () => pureError({ message: 'file not found', metadata: null }))
 
 /** @type {(context: ParseContext) => (path: string) => Unknown} */
 const mapDjs = context => path => {
@@ -52,82 +46,95 @@ const mapDjs = context => path => {
     return res.djs
 }
 
-/** @type {(path: string) => Effect<ReadFile, Result<AstModule, ParseError>>} */
+/**
+ * `catchStep` rather than a branch on the read's `Result`: however the read
+ * failed — missing file, unreadable, a runner without `readFile` — the answer
+ * a transpiler gives is the same `ParseError`, so the node channel is
+ * translated once here rather than travelling any further.
+ *
+ * @type {(path: string) => Effect<ReadFile, AstModule, ParseError>}
+ */
 const parseModule = path => step(
-    readUtf8File(path),
-    result => {
-        if (result[0] === 'error') {
-            return pure(error({ message: 'file not found', metadata: null }))
-        }
-        const tokens = tokenize(stringToList(result[1]))(path)
-        return pure(parseFromTokens(tokens))
-    })
+    notFound(readUtf8File(path)),
+    text => pure(parseFromTokens(tokenize(stringToList(text))(path))))
 
-/** @type {(path: string) => (parseModuleResult: Result<AstModule, ParseError>) => (context: ParseContext) => Effect<ReadFile, ParseContext>} */
-const transpileWithImports = path => parseModuleResult => context => {
-    if (parseModuleResult[0] === 'ok') {
-        const dir = pathConcat(path)('..')
-        const pathsCombine = listMap(pathConcat(dir))(parseModuleResult[1][0])
-        const pathsArray = toArray(pathsCombine)
-        const contextWithStack = { ...context, stack: { first: path, tail: context.stack } }
-        const x0 = foldStep(pure(pathsArray), contextWithStack, foldNextModuleOp)
-        return step(
-            x0,
-            contextWithImports => {
-                if (contextWithImports.error !== null) {
-                    return pure(contextWithImports)
-                }
-                const args = toArray(listMap(mapDjs(contextWithImports))(pathsCombine))
-                const djs = { djs: run(parseModuleResult[1][1])(args) }
-                return pure({
-                    ...contextWithImports,
-                    stack: drop(1)(contextWithImports.stack),
-                    complete: setReplace(path)(djs)(contextWithImports.complete),
-                })
+/** @type {(path: string) => (module: AstModule) => (context: ParseContext) => Effect<ReadFile, ParseContext, ParseError>} */
+const transpileWithImports = path => module => context => {
+    const dir = pathConcat(path)('..')
+    const pathsCombine = listMap(pathConcat(dir))(module[0])
+    const pathsArray = toArray(pathsCombine)
+    const contextWithStack = { ...context, stack: { first: path, tail: context.stack } }
+    const x0 = foldStep(pureOk(pathsArray), contextWithStack, foldNextModuleOp)
+    return step(
+        x0,
+        contextWithImports => {
+            const args = toArray(listMap(mapDjs(contextWithImports))(pathsCombine))
+            const djs = { djs: run(module[1])(args) }
+            return pureOk({
+                ...contextWithImports,
+                stack: drop(1)(contextWithImports.stack),
+                complete: setReplace(path)(djs)(contextWithImports.complete),
             })
-    }
-    return pure({ ...context, error: parseModuleResult[1] })
+        })
 }
 
-/** @type {(path: string) => (context: ParseContext) => Effect<ReadFile, ParseContext>} */
+/** @type {(path: string) => (context: ParseContext) => Effect<ReadFile, ParseContext, ParseError>} */
 const foldNextModuleOp = path => context => {
-    if (context.error !== null) {
-        return pure(context)
-    }
-
     if (includes(path)(context.stack)) {
-        return pure({ ...context, error: { message: 'circular dependency', metadata: null } })
+        return pureError({ message: 'circular dependency', metadata: null })
     }
 
     if (at(path)(context.complete) !== null) {
-        return pure(context)
+        return pureOk(context)
     }
 
     return step(
         parseModule(path),
-        parseModuleResult => transpileWithImports(path)(parseModuleResult)(context))
+        module => transpileWithImports(path)(module)(context))
 }
 
+/** @type {(path: string) => Effect<ReadFile, Unknown, ParseError>} */
+const transpileModule = path => mapStep(
+    foldNextModuleOp(path)({ stack: null, complete: null }),
+    context => at(path)(context.complete)?.djs)
+
 /**
- * Transpiles a DJS module graph rooted at `path` into a single `Unknown` value.
+ * A JSON document is a value, not a module: it imports nothing and names
+ * nothing, so it needs no AST and no evaluation — `fjs/media/json` reads it
+ * and the value is the result.
  *
- * Reads each file via the `ReadFile` effect, resolves imports recursively, and
- * evaluates the AST. Returns `['ok', value]` on success, or `['error', ParseError]`
- * on a parse failure or circular dependency.
+ * That reader reports its errors without a position, so the `ParseError` has
+ * no metadata and `fjs/djs`'s `compile` names the file instead of a line and
+ * column.
  *
- * @type {(path: string) => Effect<ReadFile, Result<Unknown, ParseError>>}
+ * @type {(path: string) => Effect<ReadFile, Unknown, ParseError>}
  */
-export const transpile = path => step(
-    foldNextModuleOp(path)({ stack: null, complete: null, error: null }),
-    /** @type {(context: ParseContext) => Effect<ReadFile, Result<Unknown, ParseError>>} */
-    (context) => {
-        if (context.error !== null) {
-            return pure(error(context.error))
-        }
-        const result = at(path)(context.complete)?.djs
-        return pure(ok(result))
+const transpileJson = path => step(
+    notFound(readUtf8File(path)),
+    text => {
+        const json = jsonParse(text)
+        return pure(json[0] === 'error'
+            ? error({ message: json[1], metadata: null })
+            : ok(json[1]))
     })
 
+/**
+ * Transpiles the file at `path` into a single `Unknown` value.
+ *
+ * The extension names its language: a `.json` file is a JSON document, read by
+ * `fjs/media/json`, and anything else is a FunctionalScript module, whose
+ * imports are resolved recursively — each of them a module too, whatever it is
+ * called ([spec: the `__proto__` key](../../../spec/README.md#the-__proto__-key)).
+ *
+ * Returns `['ok', value]` on success, or `['error', ParseError]` on a parse
+ * failure, a missing file, or a circular dependency.
+ *
+ * @type {(path: string) => Effect<ReadFile, Unknown, ParseError>}
+ */
+export const transpile = path => path.endsWith('.json')
+    ? transpileJson(path)
+    : transpileModule(path)
+
 // ── Tests ────────────────────────────────────────────────────────────────────
 
 export const proof = {
@@ -136,6 +143,6 @@ export const proof = {
         // has already resolved into `context.complete`, so the `res === null`
         // guard is an internal-invariant check unreachable through `transpile`'s
         // public API. Call it directly with an empty `complete` map to cover it.
-        mapDjsUnresolvedImport: () => mapDjs({ complete: null, stack: null, error: null })('missing.djs'),
+        mapDjsUnresolvedImport: () => mapDjs({ complete: null, stack: null })('missing.djs'),
     },
 }

package/fjs/djs/transpiler/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Types for the DJS transpiler.
+ *
+ * @module
+ */
+import type { Unknown } from '../types.ts';
+import type { List } from '../../types/list/types.ts';
+import type { OrderedMap } from '../../types/ordered_map/types.ts';
+/** The evaluated DJS value produced for one successfully transpiled module. */
+export type djsResult = {
+    djs: Unknown;
+};
+/**
+ * State threaded through the recursive transpilation of a DJS module graph.
+ *
+ * - `complete`: modules that have been fully parsed and evaluated, keyed by path.
+ * - `stack`: import chain currently being resolved (used to detect circular dependencies).
+ *
+ * There is no `error` field. It used to hold "the first parse error
+ * encountered, or `null` while everything is clean" — a hand-rolled error
+ * channel that every step had to set, and that three separate places had to
+ * test before doing any work. It is the effect's channel now
+ * (`Effect<ReadFile, ParseContext, ParseError>`), so `step` short-circuits and
+ * a context that exists is a context that is still good.
+ */
+export type ParseContext = {
+    readonly complete: OrderedMap<djsResult>;
+    readonly stack: List<string>;
+};

package/fjs/djs/types.d.ts

@@ -4,10 +4,16 @@
  *
  * @module
  */
-import type { Primitive as JsonPrimitive } from '../media/json/types.ts';
+import type { Primitive as JsonPrimitive, TreeMapEntries } from '../media/json/types.ts';
 export type Object = {
     readonly [k in string]?: Unknown;
 };
 export type Array = readonly Unknown[];
 export type Primitive = JsonPrimitive | bigint | undefined;
 export type Unknown = Primitive | Object | Array;
+/**
+ * How the serializer orders an object's entries — `sort` for canonical
+ * output, `identity` to keep insertion order. The same alias JSON and
+ * extended JSON instantiate, at DJS's leaf set.
+ */
+export type _MapEntries = TreeMapEntries<Primitive>;

package/fjs/effects/list/module.f.d.mts

@@ -1,24 +1,35 @@
-import type { Effect, Operation } from "../types.ts";
+/**
+ * Effectful cons-list construction.
+ *
+ * See `./types.ts` for the type-level API.
+ *
+ * @module
+ *
+ * @import { Operation } from "../types.ts"
+ * @import { Effect } from "../types.ts"
+ * @import { List, Next } from "./types.ts"
+ */
+import type { Operation } from "../types.ts";
+import type { Effect } from "../types.ts";
 import type { List, Next } from "./types.ts";
-/** @import { Effect, Operation } from "../types.ts" */
-/** @import { List, Next } from "./types.ts" */
 /**
  * The empty `List`: a pure end-of-stream marker (`undefined`).
  *
- * The explicit `Effect<O, Next<O, T>>` return type lets the contextual type drive the
- * check, so the recursive payload type-checks without a cast. Construct streams through
- * these two combinators.
+ * The explicit `Effect<O, Next<O, T, E>, E>` return type lets the contextual
+ * type drive the check, so the recursive payload type-checks without a cast.
+ * Construct streams through these two combinators, and end a stream that
+ * *failed* with `pureError` rather than with either of them.
  *
- * Note: we use `Effect<O, Next<O, T>>` because TypeScript can't convert `pure(...)` to
- *       `List<O, T>`.
+ * Note: the expanded type is written out because TypeScript cannot convert
+ *       `pureOk(...)` to `List<O, T, E>`.
  *
- * @type {<O extends Operation, T>() => Effect<O, Next<O, T>>}
+ * @type {<O extends Operation, T, E>() => Effect<O, Next<O, T, E>, E>}
  */
-export declare const empty: <O extends Operation, T>() => Effect<O, Next<O, T>>;
+export declare const empty: <O extends Operation, T, E>() => Effect<O, Next<O, T, E>, E>;
 /**
  * Prepends `first` to a {@link List} `tail`, as a pure cons cell. `tail` is an
  * ordinary argument, so it is built before the cell is — see {@link Next}.
  *
- * @type {<O extends Operation, T>(first: T, tail: List<O, T>) => Effect<O, Next<O, T>>}
+ * @type {<O extends Operation, T, E>(first: T, tail: List<O, T, E>) => Effect<O, Next<O, T, E>, E>}
  */
-export declare const nonEmpty: <O extends Operation, T>(first: T, tail: List<O, T>) => Effect<O, Next<O, T>>;
+export declare const nonEmpty: <O extends Operation, T, E>(first: T, tail: List<O, T, E>) => Effect<O, Next<O, T, E>, E>;

package/fjs/effects/list/module.f.mjs

@@ -4,31 +4,35 @@
  * See `./types.ts` for the type-level API.
  *
  * @module
+ *
+ * @import { Operation } from "../types.ts"
+ * @import { Effect } from "../types.ts"
+ * @import { List, Next } from "./types.ts"
  */
-import { pure } from "../module.f.mjs"
-/** @import { Effect, Operation } from "../types.ts" */
-/** @import { List, Next } from "./types.ts" */
+
+import { pureOk } from "../module.f.mjs"
 
 /**
  * The empty `List`: a pure end-of-stream marker (`undefined`).
  *
- * The explicit `Effect<O, Next<O, T>>` return type lets the contextual type drive the
- * check, so the recursive payload type-checks without a cast. Construct streams through
- * these two combinators.
+ * The explicit `Effect<O, Next<O, T, E>, E>` return type lets the contextual
+ * type drive the check, so the recursive payload type-checks without a cast.
+ * Construct streams through these two combinators, and end a stream that
+ * *failed* with `pureError` rather than with either of them.
  *
- * Note: we use `Effect<O, Next<O, T>>` because TypeScript can't convert `pure(...)` to
- *       `List<O, T>`.
+ * Note: the expanded type is written out because TypeScript cannot convert
+ *       `pureOk(...)` to `List<O, T, E>`.
  *
- * @type {<O extends Operation, T>() => Effect<O, Next<O, T>>}
+ * @type {<O extends Operation, T, E>() => Effect<O, Next<O, T, E>, E>}
  */
 export const empty = () =>
-    pure(undefined)
+    pureOk(undefined)
 
 /**
  * Prepends `first` to a {@link List} `tail`, as a pure cons cell. `tail` is an
  * ordinary argument, so it is built before the cell is — see {@link Next}.
  *
- * @type {<O extends Operation, T>(first: T, tail: List<O, T>) => Effect<O, Next<O, T>>}
+ * @type {<O extends Operation, T, E>(first: T, tail: List<O, T, E>) => Effect<O, Next<O, T, E>, E>}
  */
 export const nonEmpty = (first, tail) =>
-    pure({ first, tail })
+    pureOk({ first, tail })

package/fjs/effects/list/types.d.ts

@@ -3,10 +3,11 @@
  *
  * @module
  */
-import type { Effect, Operation } from '../types.ts';
-export type NonEmpty<O extends Operation, T> = {
+import type { Operation } from '../types.ts';
+import type { Effect, NotImplemented } from '../types.ts';
+export type NonEmpty<O extends Operation, T, E> = {
     readonly first: T;
-    readonly tail: List<O, T>;
+    readonly tail: List<O, T, E>;
 };
 /**
  * The payload of a `List` effect: the next cons cell, or `undefined` at
@@ -19,8 +20,27 @@ export type NonEmpty<O extends Operation, T> = {
  * streaming comes from cells produced inside a command's continuation, where
  * the tail is not reached until a runner performs the command.
  *
- * `Effect<O, Next<O, T>>` is used directly in places where `List<O, T>` cannot
- * be written as a return type (see `empty`).
+ * `Effect<O, Next<O, T, E>, E>` is used directly in places where
+ * `List<O, T, E>` cannot be written as a return type (see `empty`).
  */
-export type Next<O extends Operation, T> = NonEmpty<O, T> | undefined;
-export type List<O extends Operation, T> = Effect<O, Next<O, T>>;
+export type Next<O extends Operation, T, E> = NonEmpty<O, T, E> | undefined;
+/**
+ * A stream of `T`s, pulled one cell at a time, which may fail with `E`.
+ *
+ * **The failure belongs to the cell, not to the item.** A producer that cannot
+ * deliver ends the stream by failing it, so there is no such thing as a stream
+ * that continues after an error and no tail to construct after one. Putting the
+ * failure in `T` instead — `List<O, IoResult<Vec>>`, as this used to be — made
+ * an `error` item and an `undefined` end-of-stream two values of one union that
+ * every consumer had to keep apart by hand, and left a failing producer
+ * obliged to supply a tail nobody would ever pull.
+ *
+ * It also made short-circuiting unfactorable: a combinator generic in `T`
+ * cannot look inside it, so every consumer hand-wrote the same
+ * `if (t === 'error') return …`. With the failure in the cell, `step` does it.
+ *
+ * The cost is that a stream can no longer report one bad item and carry on.
+ * Nothing wanted that; a reader that did would carry a `Result` in `T`
+ * deliberately, which remains expressible and now means what it says.
+ */
+export type List<O extends Operation, T, E = NotImplemented> = Effect<O, Next<O, T, E>, E>;

package/fjs/effects/memory/module.f.d.mts

@@ -7,19 +7,21 @@
  * generation strategy.
  *
  * Memory effects compose with other effects by unioning operation types, for
- * example `Effect<IoOp | MemOp, T>` for a program that performs both I/O and
+ * example `Effect<IoOp | MemOp, T, E>` for a program that performs both I/O and
  * memory operations.
  *
  * See `./types.ts` for the `Key`/`MemCreate`/`MemRead`/`MemWrite`/`MemOp`
  * type-level API.
  *
  * @module
+ *
+ * @import { Nominal } from '../../types/nominal/types.ts'
+ * @import { Effect } from '../types.ts'
+ * @import { Key, MemCreate, MemRead, MemWrite, _MemKeyHash } from './types.ts'
  */
 import type { Nominal } from '../../types/nominal/types.ts';
 import type { Effect } from '../types.ts';
 import type { Key, MemCreate, MemRead, MemWrite, _MemKeyHash } from './types.ts';
-/** @import { Effect } from '../types.ts' */
-/** @import { Key, MemCreate, MemRead, MemWrite, _MemKeyHash } from './types.ts' */
 /** @type {(n: Nominal<'MemKey', _MemKeyHash, string>) => string} */
 export declare const asBase: (n: Nominal<'MemKey', _MemKeyHash, string>) => string;
 /** @type {(b: string) => Nominal<'MemKey', _MemKeyHash, string>} */
@@ -29,4 +31,5 @@ export declare const create: <T>(value: T) => Effect<MemCreate, Key<T>>;
 /** Reads the current contents of a typed memory slot. */
 export declare const read: <T>(key: Key<T>) => Effect<MemRead, T>;
 /** Replaces the current contents of a typed memory slot. */
+/** @type {<T>(key: Key<T>, value: T) => Effect<MemWrite, void>} */
 export declare const write: <T>(key: Key<T>, value: T) => Effect<MemWrite, void>;

package/fjs/effects/memory/module.f.mjs

@@ -7,20 +7,21 @@
  * generation strategy.
  *
  * Memory effects compose with other effects by unioning operation types, for
- * example `Effect<IoOp | MemOp, T>` for a program that performs both I/O and
+ * example `Effect<IoOp | MemOp, T, E>` for a program that performs both I/O and
  * memory operations.
  *
  * See `./types.ts` for the `Key`/`MemCreate`/`MemRead`/`MemWrite`/`MemOp`
  * type-level API.
  *
  * @module
+ *
+ * @import { Nominal } from '../../types/nominal/types.ts'
+ * @import { Effect } from '../types.ts'
+ * @import { Key, MemCreate, MemRead, MemWrite, _MemKeyHash } from './types.ts'
  */
 
 import { asBase as nominalAsBase, asNominal as nominalAsNominal } from '../../types/nominal/module.f.mjs'
-/** @import { Nominal } from '../../types/nominal/types.ts' */
 import { do_ } from '../module.f.mjs'
-/** @import { Effect } from '../types.ts' */
-/** @import { Key, MemCreate, MemRead, MemWrite, _MemKeyHash } from './types.ts' */
 
 /** @type {(n: Nominal<'MemKey', _MemKeyHash, string>) => string} */
 export const asBase = nominalAsBase
@@ -39,6 +40,5 @@ export const read =
     (do_('memRead'))
 
 /** Replaces the current contents of a typed memory slot. */
-export const write =
-    /** @type {<T>(key: Key<T>, value: T) => Effect<MemWrite, void>} */
-    (do_('memWrite'))
+/** @type {<T>(key: Key<T>, value: T) => Effect<MemWrite, void>} */
+export const write = do_('memWrite')

package/fjs/effects/memory/proof.f.d.mts

@@ -1,3 +1,7 @@
+/**
+ * @import { MemOperationMap } from '../mock/types.ts'
+ * @import { Key, MemOp } from './types.ts'
+ */
 export type _MemoryState = {
     readonly next: number;
     readonly values: {

package/fjs/effects/memory/proof.f.mjs

@@ -1,12 +1,16 @@
+/**
+ * @import { MemOperationMap } from '../mock/types.ts'
+ * @import { Key, MemOp } from './types.ts'
+ */
+
 import { assert, assertEq } from '../../asserts/module.f.mjs'
+import { ok } from '../../types/result/module.f.mjs'
 import { run } from '../mock/module.f.mjs'
-/** @import { MemOperationMap } from '../mock/types.ts' */
-import { pure, step } from '../module.f.mjs'
+import { pureOk, step } from '../module.f.mjs'
 import {
     asBase, asNominal,
     create, read, write,
 } from './module.f.mjs'
-/** @import { Key, MemOp } from './types.ts' */
 
 /**
  * @typedef {{
@@ -27,20 +31,22 @@ const mock = {
         return [{
             next: state.next + 1,
             values: { ...state.values, [id]: value },
-        }, key]
+        }, ok(key)]
     },
     memRead: key => state =>
-        [state, state.values[asBase(key)]],
+        [state, ok(state.values[asBase(key)])],
     memWrite: (key, value) => state => {
         const id = asBase(key)
         assert(id in state.values, id)
         return [{
             ...state,
             values: { ...state.values, [id]: value },
-        }, undefined]
+        }, ok(undefined)]
     },
 }
 
+// `step`: each link runs only because the previous one returned `ok`,
+// and a runner that omitted a handler would propagate rather than be ignored.
 const program = step(
     create(1),
     key => {
@@ -55,7 +61,8 @@ const program = step(
 export const proof = {
     roundTrip: () => {
         const [state, result] = run(mock)(initial)(program)
-        assertEq(result, 42)
+        assert(result[0] === 'ok', result)
+        assertEq(result[1], 42)
         assertEq(state.values.k0, 42, state)
     },
     allocatesFreshKeys: () => {
@@ -63,8 +70,10 @@ export const proof = {
             create('a'),
             a => step(
                 create('b'),
-                b => pure(/** @type {const} */ ([asBase(a), asBase(b)]))))
-        const [state, [a, b]] = run(mock)(initial)(effect)
+                b => pureOk(/** @type {const} */ ([asBase(a), asBase(b)]))))
+        const [state, result] = run(mock)(initial)(effect)
+        assert(result[0] === 'ok', result)
+        const [a, b] = result[1]
         assertEq(a, 'k0')
         assertEq(b, 'k1')
         assertEq(state.values.k0, 'a', state)

package/fjs/effects/memory/types.d.ts

@@ -5,14 +5,15 @@
  */
 import type { Phantom } from '../../types/phantom/types.ts';
 import type { Nominal } from '../../types/nominal/types.ts';
+import type { OpResult } from '../node/types.ts';
 /** Nominal brand version for memory keys. */
 export type _MemKeyHash = '3f114fa6036a8da026b827f0c3e6d901f5e81ad9a320e431ccce31451892d286';
 /** Opaque handle for a value stored by the memory interpreter. */
 export type Key<T> = Phantom<Nominal<'MemKey', _MemKeyHash, string>, T>;
 /** Allocates a fresh memory slot and initializes it with `value`. */
-export type MemCreate = readonly ['memCreate', <T>(value: T) => Key<T>];
+export type MemCreate = readonly ['memCreate', <T>(value: T) => OpResult<Key<T>>];
 /** Reads the current value stored at `key`. */
-export type MemRead = readonly ['memRead', <T>(key: Key<T>) => T];
+export type MemRead = readonly ['memRead', <T>(key: Key<T>) => OpResult<T>];
 /** Replaces the current value stored at `key`. */
-export type MemWrite = readonly ['memWrite', <T>(key: Key<T>, value: T) => void];
+export type MemWrite = readonly ['memWrite', <T>(key: Key<T>, value: T) => OpResult<void>];
 export type MemOp = MemCreate | MemRead | MemWrite;

package/fjs/effects/mock/module.f.d.mts

@@ -1,6 +1,30 @@
-import type { Operation } from '../types.ts';
-import type { MemOperationMap, RunInstance } from './types.ts';
-/** @import { Operation } from '../types.ts' */
-/** @import { MemOperationMap, RunInstance } from './types.ts' */
+/**
+ * Mock effect runtimes for testing effectful programs.
+ *
+ * See `./types.ts` for the `MemOperationMap`/`RunInstance` type-level API.
+ *
+ * @module
+ *
+ * @import { Commands, Effect, MatchResult, Operation } from '../types.ts'
+ * @import { MemOperationMap, PartialMemOperationMap, RunInstance } from './types.ts'
+ */
+import type { Commands, Operation } from '../types.ts';
+import type { MemOperationMap, PartialMemOperationMap, RunInstance } from './types.ts';
 /** @type {<O extends Operation, S>(o: MemOperationMap<O, S>) => RunInstance<O, S>} */
 export declare const run: <O extends Operation, S>(o: MemOperationMap<O, S>) => RunInstance<O, S>;
+/**
+ * {@link run} for a runner that implements only part of `O`.
+ *
+ * A command in `commands` with no handler answers `error(notImplemented)`
+ * through the ordinary continuation, so a program that asks for something this
+ * runner lacks gets its control back and decides what to do. A command outside
+ * `commands` still panics — see `partialMatch`.
+ *
+ * **The injector lives here rather than at the call site.** `partialMatch`
+ * cannot build one because the shape of an answer is the runner's, not the
+ * operation's; this loop's is `(state) => [state, …]`, and writing it once here
+ * is the whole reason each runner supplies its own.
+ *
+ * @type {<O extends Operation, S>(commands: Commands<O>) => (o: PartialMemOperationMap<O, S>) => RunInstance<O, S>}
+ */
+export declare const partialRun: <O extends Operation, S>(commands: Commands<O>) => (o: PartialMemOperationMap<O, S>) => RunInstance<O, S>;