functionalscript 0.44.0 → 0.45.0

package/fjs/crypto/vdf/module.f.d.mts

@@ -1,8 +1,27 @@
+/**
+ * Sloth verifiable delay function over a fixed 3072-bit safe prime.
+ *
+ * See `./types.ts` for the `Sloth` type-level API.
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```js
+ * import { sloth } from './module.f.mjs'
+ *
+ * const steps = 4n
+ * const x = 42n
+ * const y = sloth.eval(steps)(x)
+ * if (y === null || !sloth.verify(steps)(x)(y)) { throw y }
+ * ```
+ *
+ * @import { PrimeField } from '../../types/prime_field/types.ts'
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ * @import { Unary } from '../../types/bigint/types.ts'
+ * @import { Sloth } from './types.ts'
+ */
 import type { Sloth } from './types.ts';
-/** @import { PrimeField } from '../../types/prime_field/types.ts' */
-/** @import { Nullable } from '../../types/nullable/types.ts' */
-/** @import { Unary } from '../../types/bigint/types.ts' */
-/** @import { Sloth } from './types.ts' */
 /** Sloth VDF modulus (3072-bit safe prime, same as reference implementations). */
 export declare const p = 170082004324204494273811327264862981553264701145937538369570764779791492622392118654022654452947093285873855529044371650895045691292912712699015605832276411308653107069798639938826015099738961427172366594187783204437869906954750443653318078358839409699824714551430573905637228307966826784684174483831608534979n;
 /**

package/fjs/crypto/vdf/module.f.mjs

@@ -15,12 +15,14 @@
  * const y = sloth.eval(steps)(x)
  * if (y === null || !sloth.verify(steps)(x)(y)) { throw y }
  * ```
+ *
+ * @import { PrimeField } from '../../types/prime_field/types.ts'
+ * @import { Nullable } from '../../types/nullable/types.ts'
+ * @import { Unary } from '../../types/bigint/types.ts'
+ * @import { Sloth } from './types.ts'
  */
+
 import { modSqrt, prime_field } from '../../types/prime_field/module.f.mjs'
-/** @import { PrimeField } from '../../types/prime_field/types.ts' */
-/** @import { Nullable } from '../../types/nullable/types.ts' */
-/** @import { Unary } from '../../types/bigint/types.ts' */
-/** @import { Sloth } from './types.ts' */
 
 /** Sloth VDF modulus (3072-bit safe prime, same as reference implementations). */
 export const p =

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

@@ -2,12 +2,15 @@
  * Development utilities for indexing modules and loading FunctionalScript files.
  *
  * @module
+ *
+ * @import { Access, All, Env, Import, Readdir } from '../effects/node/types.ts'
+ * @import { Effect } from '../effects/types.ts'
+ * @import { Dir } from '../effects/node/virtual/types.ts'
+ * @import { Module, ModuleMap, LoadModuleOperations } from './types.ts'
  */
 import type { Env } from '../effects/node/types.ts';
 import type { Effect } from '../effects/types.ts';
 import type { ModuleMap, LoadModuleOperations } from './types.ts';
-/** @import { Dir } from '../effects/node/virtual/types.ts' */
-/** @import { Module, ModuleMap, LoadModuleOperations } from './types.ts' */
 /**
  * Returns `true` if the file should be loaded for proof discovery.
  *

package/fjs/dev/module.f.mjs

@@ -2,19 +2,20 @@
  * Development utilities for indexing modules and loading FunctionalScript files.
  *
  * @module
+ *
+ * @import { Access, All, Env, Import, Readdir } from '../effects/node/types.ts'
+ * @import { Effect } from '../effects/types.ts'
+ * @import { Dir } from '../effects/node/virtual/types.ts'
+ * @import { Module, ModuleMap, LoadModuleOperations } from './types.ts'
  */
 
 import { all, import_, readdir } from '../effects/node/module.f.mjs'
-/** @import { Access, All, Env, Import, Readdir } from '../effects/node/types.ts' */
 import { cmp as strCmp } from '../types/string/module.f.mjs'
 import { unwrap } from '../types/result/module.f.mjs'
 import { pure, step } from '../effects/module.f.mjs'
-/** @import { Effect } from '../effects/types.ts' */
 import { join, relativize, toPosix } from '../path/module.f.mjs'
 import { assert, assertEq } from '../asserts/module.f.mjs'
 import { emptyState, virtual } from '../effects/node/virtual/module.f.mjs'
-/** @import { Dir } from '../effects/node/virtual/types.ts' */
-/** @import { Module, ModuleMap, LoadModuleOperations } from './types.ts' */
 
 /**
  * Returns `true` if the file should be loaded for proof discovery.

package/fjs/dev/package_json/module.f.d.mts

@@ -26,6 +26,13 @@ export declare const validatePackageJson: import("../../types/rtti/common/types.
     readonly scripts: import("../../types/rtti/types.ts").Or<readonly [import("../../types/rtti/types.ts").Type1<"record", import("../../types/rtti/types.ts")._Type0<"string">>, undefined]>;
 }>;
 /**
+ * Parses `text` as JSON and validates it against {@link packageJsonSchema}.
+ *
+ * Both failures reach the caller as they were raised: a parse failure is a
+ * `string`, a schema failure a `ValidationError`, and `JsonTextError` is
+ * exactly that union — which is what `okThen` produces from the two steps'
+ * own error types, with no rewrapping to widen either one.
+ *
  * @param {string} text
  * @returns {Result<PackageJson, JsonTextError>}
  */

package/fjs/dev/package_json/module.f.mjs

@@ -12,7 +12,7 @@
 import { parse as parseJsonText } from '../../media/json/module.f.mjs'
 import { option, record, string } from '../../types/rtti/module.f.mjs'
 import { validate as rttiValidate } from '../../types/rtti/validate/module.f.mjs'
-import { error, ok } from '../../types/result/module.f.mjs'
+import { okThen } from '../../types/result/module.f.mjs'
 
 export const packageJsonSchema = /** @type {const} */ ({
     name: option(string),
@@ -26,12 +26,15 @@ export const packageJsonSchema = /** @type {const} */ ({
 export const validatePackageJson = rttiValidate(packageJsonSchema)
 
 /**
+ * Parses `text` as JSON and validates it against {@link packageJsonSchema}.
+ *
+ * Both failures reach the caller as they were raised: a parse failure is a
+ * `string`, a schema failure a `ValidationError`, and `JsonTextError` is
+ * exactly that union — which is what `okThen` produces from the two steps'
+ * own error types, with no rewrapping to widen either one.
+ *
  * @param {string} text
  * @returns {Result<PackageJson, JsonTextError>}
  */
-export const validatePackageJsonText = text => {
-    const [t, v] = parseJsonText(text)
-    if (t === 'error') { return error(v) }
-    const [t2, v2] = validatePackageJson(v)
-    return t2 === 'ok' ? ok(v2) : error(v2)
-}
+export const validatePackageJsonText = text =>
+    okThen(validatePackageJson)(parseJsonText(text))

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

@@ -2,6 +2,9 @@
  * Synchronizes local development configuration generated from canonical repository files.
  *
  * @module
+ *
+ * @import { Effect } from '../../effects/types.ts'
+ * @import { Mkdir, NodeProgram, ReadFile, WriteFile } from '../../effects/node/types.ts'
  */
 import type { Effect } from '../../effects/types.ts';
 import type { Mkdir, NodeProgram, ReadFile, WriteFile } from '../../effects/node/types.ts';

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

@@ -2,12 +2,13 @@
  * Synchronizes local development configuration generated from canonical repository files.
  *
  * @module
+ *
+ * @import { Effect } from '../../effects/types.ts'
+ * @import { Mkdir, NodeProgram, ReadFile, WriteFile } from '../../effects/node/types.ts'
  */
 
 import { history, historyStep, mapStep, step } from '../../effects/module.f.mjs'
-/** @import { Effect } from '../../effects/types.ts' */
 import { mkdir, readUtf8File, writeUtf8File } from '../../effects/node/module.f.mjs'
-/** @import { Mkdir, NodeProgram, ReadFile, WriteFile } from '../../effects/node/types.ts' */
 import { unwrap } from '../../types/result/module.f.mjs'
 
 const source = /** @type {const} */ ('.copilot/mcp.json')

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

@@ -1,3 +1,6 @@
+/**
+ * Proofs for local development configuration generation.
+ */
 export declare const proof: {
     syncMcp: () => void;
     main: () => void;

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

@@ -1,8 +1,7 @@
 /**
  * Proofs for local development configuration generation.
- *
- * @module
  */
+
 import { assert, assertEq } from '../../asserts/module.f.mjs'
 import { utf8 } from '../../text/module.f.mjs'
 import { readUtf8File } from '../../effects/node/module.f.mjs'

package/fjs/djs/parser/module.f.d.mts

@@ -72,4 +72,7 @@ export declare const proof: {
     endArray: {
         nonArrayTop: () => void;
     };
+    endObject: {
+        nonObjectTop: () => void;
+    };
 };

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

@@ -544,4 +544,22 @@ export const proof = {
             assertEq(result.state, 'result')
         },
     },
+    endObject: {
+        // `endObject` is only ever invoked while `state.top` is an object
+        // (the `'{'`/`'{k'`/`'{:'`/`'{v'`/`'{,'` value-states guarantee it),
+        // so its non-object guard is a defensive branch unreachable through
+        // `parseFromTokens`. Call it directly to cover that branch.
+        nonObjectTop: () => {
+            /** @type {_ParseValueState} */
+            const state = {
+                state: 'exportValue',
+                module: { refs: null, modules: null, consts: null },
+                valueState: '{,',
+                top: null,
+                stack: null,
+            }
+            const result = endObject(state)
+            assertEq(result.state, 'result')
+        },
+    },
 }

package/fjs/djs/parser/proof.f.d.mts

@@ -1,3 +1,6 @@
+/**
+ * @import { DjsTokenWithMetadata } from '../tokenizer/types.ts'
+ */
 export declare const proof: {
     valid: (() => void)[];
     invalid: (() => void)[];

package/fjs/djs/parser/proof.f.mjs

@@ -1,6 +1,9 @@
+/**
+ * @import { DjsTokenWithMetadata } from '../tokenizer/types.ts'
+ */
+
 import { parseFromTokens } from './module.f.mjs'
 import { tokenize } from '../tokenizer/module.f.mjs'
-/** @import { DjsTokenWithMetadata } from '../tokenizer/types.ts' */
 import { toArray } from '../../types/list/module.f.mjs'
 import { sort } from '../../types/object/module.f.mjs'
 import { stringToList } from '../../text/utf16/module.f.mjs'
@@ -439,6 +442,15 @@ export const proof = {
             assert(obj[0] === 'error', obj)
             assertEq(obj[1].message, 'duplicate id', obj)
         },
+        () => {
+            // No newline after the const's value: the parser hits `eof` while
+            // still in the newline-required state, instead of the following
+            // `nl` token every other `const` test provides.
+            const tokenList = tokenizeString('const a = 1')
+            const obj = parseFromTokens(tokenList)
+            assert(obj[0] === 'error', obj)
+            assertEq(obj[1].message, 'unexpected end', obj)
+        },
     ],
     validWithArgs:[
         () => {

package/fjs/djs/proof.f.d.mts

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

package/fjs/djs/proof.f.mjs

@@ -1,4 +1,7 @@
-/** @import { Vec } from '../types/bit_vec/types.ts' */
+/**
+ * @import { Vec } from '../types/bit_vec/types.ts'
+ */
+
 import { compile } from './module.f.mjs'
 import { virtual, emptyState } from '../effects/node/virtual/module.f.mjs'
 import { utf8, utf8ToString } from '../text/module.f.mjs'

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

@@ -16,6 +16,7 @@ const { entries } = Object
 import { compose, fn } from '../../types/function/module.f.mjs'
 import { serialize as bigintSerialize } from '../../types/bigint/module.f.mjs'
 import { objectWrap, arrayWrap, stringSerialize, numberSerialize, nullSerialize, boolSerialize } from '../../media/json/serializer/module.f.mjs'
+import { assertNotNullish } from '../../asserts/module.f.mjs'
 
 const colon = [':']
 
@@ -183,12 +184,12 @@ const addRef = djs => refs => {
 export const stringify = sort => djs => {
     const refs = countRefs(djs)
     const consts = getConstants(refs)(djs)
+    // `consts` only ever holds values `getConstants` found `shared` for, i.e.
+    // values with an entry already in `refs` — so `refs.get(entry)` here is
+    // always defined.
     /** @type {(entry: Unknown) => List<string>} */
     const constSerialize = entry => {
-        const refCounter = refs.get(entry)
-        if (refCounter === undefined) {
-            throw 'unexpected behavior'
-        }
+        const refCounter = assertNotNullish(refs.get(entry))
         return flat([['const c'], numberSerialize(refCounter[0]), [' = '], serializeWithConst(sort)(refs)(entry)(entry), ['\n']])
     }
     const constStrings = flatMap(constSerialize)(consts)

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

@@ -52,14 +52,12 @@ import { multiply } from '../../types/bigfloat/module.f.mjs'
 import {
     asterisk, backspace, ht, lf, ff, cr,
     quotationMark, solidus, reverseSolidus,
-    digitRange, digit0,
-    latinCapitalLetterA,
-    latinSmallLetterA, latinSmallLetterB, latinSmallLetterF,
+    hexDigitValue,
+    latinSmallLetterB, latinSmallLetterF,
     latinSmallLetterN, latinSmallLetterR, latinSmallLetterT, latinSmallLetterU,
-    range as asciiRange,
 } from '../../text/ascii/module.f.mjs'
 import { codePointListToString, stringToCodePointList } from '../../text/utf16/module.f.mjs'
-import { contains } from '../../types/range/module.f.mjs'
+import { mapUnwrap } from '../../types/nullable/module.f.mjs'
 import { concat, empty, filter, flat, flatMap, fold, map, stateScan, toArray } from '../../types/list/module.f.mjs'
 import { stringifyAsTree } from '../serializer/module.f.mjs'
 import { sort } from '../../types/object/module.f.mjs'
@@ -333,7 +331,13 @@ const filterFunc = tk => {
     }
 }
 
-const rangeCapitalAF = asciiRange('AF')
+/**
+ * A `\uXXXX` escape reaches the `unicode` state only after the grammar has
+ * accepted its four hex digits, so a non-hex code point here is a tokenizer
+ * bug rather than bad input — assert instead of decoding it to a garbage
+ * value, which is what the hand-rolled ternary chain used to do.
+ */
+const unwrapHexDigitValue = mapUnwrap(hexDigitValue)
 
 /** @typedef {
  *   | { readonly kind: 'normal' }
@@ -358,11 +362,7 @@ const stringDecodeScan = (cp, state) => {
                 default:  return [[cp], { kind: 'normal' }]
             }
         case 'unicode': {
-            // convert hex digit char to its numeric value: '0'-'9', 'A'-'F', 'a'-'f'
-            const digit = contains(...digitRange)(cp) ? cp - digit0
-                : contains(...rangeCapitalAF)(cp) ? cp - (latinCapitalLetterA - 10)
-                : cp - (latinSmallLetterA - 10)
-            const acc = (state.acc << 4) | digit
+            const acc = (state.acc << 4) | unwrapHexDigitValue(cp)
             return state.count === 3 ? [[acc], { kind: 'normal' }] : [null, { kind: 'unicode', acc, count: state.count + 1 }]
         }
         default:
@@ -511,10 +511,13 @@ export const tokenizeString = s => {
 // Finds `tag` in flatTokens and returns the metadata of the next code point after it.
 // numError/unterminated tags are followed by the poisoning char / EOF-hitting position
 // in the flattened AST walk order, so this pinpoints roughly where tokenization failed.
+//
+// The single call site only passes a `tag` it already confirmed via
+// `flatTokens.includes(tag)`, so `indexOf` here is never -1.
 /** @type {(tag: string, flatTokens: readonly _FlatToken[], fallback: TokenMetadata) => TokenMetadata} */
 const metadataAfterTag = (tag, flatTokens, fallback) => {
     const idx = flatTokens.indexOf(tag)
-    const found = idx < 0 ? undefined : flatTokens.slice(idx + 1).find((/** @type {_FlatToken} */ t) => t instanceof Array)
+    const found = flatTokens.slice(idx + 1).find((/** @type {_FlatToken} */ t) => t instanceof Array)
     return found === undefined ? fallback : found[1]
 }
 
@@ -592,11 +595,16 @@ const parseDjsDefaultState = input => {
 
 // Folds a leading '-' into the following number/bigint token, mirroring the old
 // fjs/djs/tokenizer's minus-state exactly.
+//
+// No `case '-'` here: the underlying `js/tokenizer` always merges two adjacent
+// `-` characters into a single `'--'` token (the decrement operator), so this
+// state — entered only after a single, unmerged `-` — can never itself see
+// another `'-'`-kind input. Such an input falls through to `default`, which
+// handles it exactly like any other non-number/bigint/eof token.
 /** @type {(input: JsToken) => readonly [List<DjsToken>, _DjsScanState]} */
 const parseDjsMinusState = input => {
     switch (input.kind) {
         case 'eof': return [[{ kind: 'error', message: 'invalid token' }, { kind: 'eof' }], { kind: 'def' }]
-        case '-': return [[{ kind: 'error', message: 'invalid token' }], { kind: '-' }]
         case 'bigint': return [[{ kind: 'bigint', value: -1n * input.value }], { kind: 'def' }]
         case 'number': return [[{ kind: 'number', bf: multiply(input.bf)(-1n), value: `-${input.value}` }], { kind: 'def' }]
         default: return [{ first: { kind: 'error', message: 'invalid token' }, tail: mapDjsToken(input) }, { kind: 'def' }]

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

@@ -1,3 +1,6 @@
+/**
+ * @import { Unknown } from '../types.ts'
+ */
 export declare const proof: {
     isValid: (() => void)[];
     tokenizer: (() => void)[];

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

@@ -1,4 +1,7 @@
-/** @import { Unknown } from '../types.ts' */
+/**
+ * @import { Unknown } from '../types.ts'
+ */
+
 import { descentParser } from '../../bnf/descent/module.f.mjs'
 import { stringToCodePointList, stringToList } from '../../text/utf16/module.f.mjs'
 import { toArray } from '../../types/list/module.f.mjs'
@@ -898,7 +901,10 @@ export const proof = {
             assertEq(stringify(/** @type {Unknown} */ (result)), '[{"metadata":{"column":2,"line":1,"path":""},"token":{"kind":"bigint","value":-1234567890n}},{"metadata":{"column":13,"line":1,"path":""},"token":{"kind":"eof"}}]')
         },
         () => {
-            // '-' followed by '-': one error, stays in minus-state waiting for what follows
+            // `js/tokenizer` merges '--' into one decrement-operator token, so
+            // this never enters (or re-enters) minus-state via a second '-';
+            // it's one error straight from the default state's unknown-token
+            // fallback, mapping the whole '--' token to a single error.
             const result = toArray(tokenize(stringToList('--'))(''))
             assertEq(stringify(/** @type {Unknown} */ (result)), '[{"metadata":{"column":1,"line":1,"path":""},"token":{"kind":"error","message":"invalid token"}},{"metadata":{"column":3,"line":1,"path":""},"token":{"kind":"eof"}}]')
         },
@@ -911,6 +917,12 @@ export const proof = {
             const result = toArray(tokenize(stringToList('-'))(''))
             assertEq(stringify(/** @type {Unknown} */ (result)), '[{"metadata":{"column":2,"line":1,"path":""},"token":{"kind":"error","message":"invalid token"}},{"metadata":{"column":2,"line":1,"path":""},"token":{"kind":"eof"}}]')
         },
+        () => {
+            // '-' followed by neither a number/bigint nor eof: one error for
+            // the dangling '-', then the following token maps through normally.
+            const result = toArray(tokenize(stringToList('-{'))(''))
+            assertEq(stringify(/** @type {Unknown} */ (result)), '[{"metadata":{"column":2,"line":1,"path":""},"token":{"kind":"error","message":"invalid token"}},{"metadata":{"column":2,"line":1,"path":""},"token":{"kind":"{"}},{"metadata":{"column":3,"line":1,"path":""},"token":{"kind":"eof"}}]')
+        },
         () => {
             const result = toArray(tokenize(stringToList('[-1234567890n]'))(''))
             assertEq(stringify(/** @type {Unknown} */ (result)), '[{"metadata":{"column":1,"line":1,"path":""},"token":{"kind":"["}},{"metadata":{"column":3,"line":1,"path":""},"token":{"kind":"bigint","value":-1234567890n}},{"metadata":{"column":14,"line":1,"path":""},"token":{"kind":"]"}},{"metadata":{"column":15,"line":1,"path":""},"token":{"kind":"eof"}}]')

package/fjs/djs/transpiler/module.f.d.mts

@@ -5,28 +5,17 @@
  *
  * @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 { Effect } from '../../effects/types.ts'
  * @import { ReadFile } from '../../effects/node/types.ts'
+ * @import { ParseContext } from './types.ts'
  */
 import type { Unknown } from '../types.ts';
 import type { Result } from '../../types/result/types.ts';
-import type { List } from '../../types/list/types.ts';
-import type { OrderedMap } from '../../types/ordered_map/types.ts';
 import type { ParseError } from '../parser/types.ts';
 import type { Effect } from '../../effects/types.ts';
 import type { ReadFile } from '../../effects/node/types.ts';
-export type ParseContext = {
-    readonly complete: OrderedMap<djsResult>;
-    readonly stack: List<string>;
-    readonly error: ParseError | null;
-};
-export type djsResult = {
-    djs: Unknown;
-};
 /**
  * Transpiles a DJS module graph rooted at `path` into a single `Unknown` value.
  *

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

@@ -5,12 +5,11 @@
  *
  * @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 { 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'
@@ -24,24 +23,6 @@ import { run } from '../ast/module.f.mjs'
 import { foldStep, pure, 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.
- *
- * - `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 {(context: ParseContext) => (path: string) => Unknown} */
 const mapDjs = context => path => {
     const res = at(path)(context.complete)

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

@@ -0,0 +1,25 @@
+/**
+ * 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';
+import type { ParseError } from '../parser/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).
+ * - `error`: the first parse error encountered, or `null` while everything is clean.
+ */
+export type ParseContext = {
+    readonly complete: OrderedMap<djsResult>;
+    readonly stack: List<string>;
+    readonly error: ParseError | null;
+};

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

@@ -1,3 +1,13 @@
+/**
+ * A fluent, method-chaining wrapper over the raw `Effect`.
+ *
+ * See `./types.ts` for the `Eff` type-level API.
+ *
+ * @module
+ *
+ * @import { Effect, Operation } from '../types.ts'
+ * @import { Eff } from './types.ts'
+ */
 import type { Effect, Operation } from '../types.ts';
 import type { Eff } from './types.ts';
 /**

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

@@ -4,10 +4,12 @@
  * See `./types.ts` for the `Eff` type-level API.
  *
  * @module
+ *
+ * @import { Effect, Operation } from '../types.ts'
+ * @import { Eff } from './types.ts'
  */
+
 import { history, historyStep, mapStep, pure } from '../module.f.mjs'
-/** @import { Effect, Operation } from '../types.ts' */
-/** @import { Eff } from './types.ts' */
 
 /**
  * Builds an `Eff` from two views of the same chain: `value`, the effect for the

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

@@ -1,3 +1,6 @@
+/**
+ * @import { Effect, OperationMap } from '../types.ts'
+ */
 export type _AddOp = readonly ['add', (a: number, b: number) => number];
 export declare const proof: {
     value: () => void;

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

@@ -1,8 +1,11 @@
+/**
+ * @import { Effect, OperationMap } from '../types.ts'
+ */
+
 import { do_, match, pure } from '../module.f.mjs'
 import { assert, assertEq } from '../../asserts/module.f.mjs'
 import { assertPure } from '../proof.f.mjs'
 import { eff } from './module.f.mjs'
-/** @import { Effect, OperationMap } from '../types.ts' */
 
 /** @typedef {readonly['add', (a: number, b: number) => number]} _AddOp */
 

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

@@ -1,7 +1,15 @@
+/**
+ * Effectful cons-list construction.
+ *
+ * See `./types.ts` for the type-level API.
+ *
+ * @module
+ *
+ * @import { Effect, Operation } from "../types.ts"
+ * @import { List, Next } from "./types.ts"
+ */
 import type { Effect, Operation } 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`).
  *

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

@@ -4,10 +4,12 @@
  * See `./types.ts` for the type-level API.
  *
  * @module
+ *
+ * @import { Effect, Operation } 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" */
 
 /**
  * The empty `List`: a pure end-of-stream marker (`undefined`).

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

@@ -14,12 +14,14 @@
  * 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>} */