functionalscript 0.45.0 → 0.46.0

package/fjs/module.f.mjs

@@ -11,11 +11,10 @@ import { compile } from './djs/module.f.mjs'
 import { main as testMain } from './emergent_testing/module.f.mjs'
 import { commands as casCommands } from './cas/cli/module.f.mjs'
 import { main as ciMain } from './ci/module.f.mjs'
-import { import_ } from './effects/node/module.f.mjs'
+import { errorExit, errorMessage, exitStep, import_ } from './effects/node/module.f.mjs'
 import { dispatch } from './cli/module.f.mjs'
 import { casMcpServer } from './mcp/module.f.mjs'
-import { pure, step } from './effects/module.f.mjs'
-import { unwrap } from './types/result/module.f.mjs'
+import { resultStep } from './effects/module.f.mjs'
 
 /** @type {Commands<NodeOp>} */
 const commands = [
@@ -37,9 +36,17 @@ const commands = [
     {
         names: ['mcp', 'm'],
         description: 'Run an MCP server over stdio exposing the CAS and Evo (subjects/heads) as tools',
-        handler: ({ home }) => step(
-            casMcpServer(home),
-            () => pure(0)),
+        // `exitStep`, not `resultStep(…, () => pureOk(0))`: the server's
+        // bootstrap can fail, and a continuation that ignores its result would
+        // report a server that never started as a clean exit.
+        //
+        // The types do *not* rule that out. `Program`'s exit code being a
+        // `Result` catches the old spelling — `() => pure(0)` hands back a bare
+        // number, which no longer fits — but `() => pureOk(0)` still compiles,
+        // because discarding a result you were handed is exactly what a
+        // continuation is allowed to do. This comment guards a mistake that is
+        // still available.
+        handler: ({ home }) => exitStep(casMcpServer(home)),
     },
     {
         names: ['ci', 'i'],
@@ -49,11 +56,25 @@ const commands = [
     {
         names: ['run', 'r'],
         description: 'Run a FunctionalScript module as a NodeProgram',
+        // Both ways this can fail are the command line, not a defect: the
+        // named file may not import, and a module that does import may export
+        // no `main`. Neither deserves a stack trace, so both are reported on
+        // `stderr` and exit `1` — the same answer an unknown command gets a
+        // few lines up, and the same one every other command now gives.
         handler: options => {
             const [file, ...args] = options.args
-            return step(
+            return resultStep(
                 import_(file),
-                x => (/** @type {NodeProgram} */ (unwrap(x).main))({ ...options, args }))
+                r => {
+                    if (r[0] === 'error') {
+                        return errorExit(`${file}: ${errorMessage(r[1])}`)
+                    }
+                    const { main } = r[1]
+                    if (typeof main !== 'function') {
+                        return errorExit(`${file}: not a NodeProgram — no exported \`main\` function`)
+                    }
+                    return /** @type {NodeProgram} */ (main)({ ...options, args })
+                })
         },
     },
 ]

package/fjs/nanvm/proof.f.mjs

@@ -121,8 +121,8 @@ const eqProof = (() => {
     })
     /** @type {(c: EqCase) => readonly[string, () => void]} */
     const leaf = c => [c.name, () => {
-        const a = /** @type {any} */(operand(c.a))
-        const b = /** @type {any} */(operand(c.b))
+        const a = operand(c.a)
+        const b = operand(c.b)
         assertEq(a === b, c.eq, [a, c.eq ? '===' : '!==', b])
         assertEq(b === a, c.eq)
     }]
@@ -157,7 +157,7 @@ const jsOnly = {
     },
     throw: {
         toStringThrows: () => String({ toString: () => { throw 'Custom error' } }),
-        toStringNotAFunction: () => String(/** @type {any} */({ toString: 'hello' })),
+        toStringNotAFunction: () => String({ toString: 'hello' }),
         toStringNotPrimitive: () => String({ toString: () => [] }),
         /** `throws` describes a case's outcome; it is not a value to build. */
         throwsIsNotAValue: () => value(() => ['throw']),

package/fjs/nanvm/rust/module.f.mjs

@@ -78,7 +78,7 @@ export const valueExpr = v => {
         case 'bigint': { return `bigint_any(${i64Literal(v)})` }
     }
     if (Array.isArray(v)) {
-        const items = /** @type {readonly Value[]} */(v)
+        const items = v
         return items.length === 0
             ? 'Array::default().to_any()'
             : `[${items.map(valueExpr).join(', ')}].to_array().to_any()`

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

@@ -8,16 +8,16 @@
  *
  * @module
  *
+ * @import { IoChannel, Mkdir, NodeProgram, WriteFile } from '../../effects/node/types.ts'
  * @import { Effect } from '../../effects/types.ts'
- * @import { Mkdir, NodeProgram, WriteFile } from '../../effects/node/types.ts'
  */
+import type { IoChannel, Mkdir, NodeProgram, WriteFile } from '../../effects/node/types.ts';
 import type { Effect } from '../../effects/types.ts';
-import type { Mkdir, NodeProgram, WriteFile } from '../../effects/node/types.ts';
 /**
  * Regenerates `nanvm-lib/tests/test/generated.rs` from the shared test data.
  *
- * @type {() => Effect<Mkdir | WriteFile, void>}
+ * @type {() => Effect<Mkdir | WriteFile, void, IoChannel>}
  */
-export declare const generateRustTests: () => Effect<Mkdir | WriteFile, void>;
+export declare const generateRustTests: () => Effect<Mkdir | WriteFile, void, IoChannel>;
 /** @type {NodeProgram} */
 export declare const main: NodeProgram;

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

@@ -8,26 +8,25 @@
  *
  * @module
  *
+ * @import { IoChannel, Mkdir, NodeProgram, WriteFile } from '../../effects/node/types.ts'
  * @import { Effect } from '../../effects/types.ts'
- * @import { Mkdir, NodeProgram, WriteFile } from '../../effects/node/types.ts'
  */
 
-import { mapStep, step } from '../../effects/module.f.mjs'
-import { mkdir, writeUtf8File } from '../../effects/node/module.f.mjs'
-import { unwrap } from '../../types/result/module.f.mjs'
+
+import { exitStep, mkdir, writeUtf8File } from '../../effects/node/module.f.mjs'
+import { step } from '../../effects/module.f.mjs'
 import { data } from '../module.f.mjs'
 import { directory, generate, path } from '../rust/module.f.mjs'
 
 /**
  * Regenerates `nanvm-lib/tests/test/generated.rs` from the shared test data.
  *
- * @type {() => Effect<Mkdir | WriteFile, void>}
+ * @type {() => Effect<Mkdir | WriteFile, void, IoChannel>}
  */
 export const generateRustTests = () => {
-    const directoryReady = mapStep(mkdir(directory, { recursive: true }), unwrap)
-    const written = step(directoryReady, () => writeUtf8File(path, generate(data)))
-    return mapStep(written, unwrap)
+    const directoryReady = mkdir(directory, { recursive: true })
+    return step(directoryReady, () => writeUtf8File(path, generate(data)))
 }
 
 /** @type {NodeProgram} */
-export const main = () => mapStep(generateRustTests(), () => 0)
+export const main = () => exitStep(generateRustTests())

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

@@ -4,8 +4,9 @@
  * @module
  */
 
+import { exitCode } from '../../effects/node/module.f.mjs'
 import { assert, assertEq } from '../../asserts/module.f.mjs'
-import { step } from '../../effects/module.f.mjs'
+import { step as ioStep } from '../../effects/module.f.mjs'
 import { readUtf8File } from '../../effects/node/module.f.mjs'
 import {
     defaultNodeProgramOptions,
@@ -20,13 +21,13 @@ export const proof = {
     generateRustTests: () => {
         // The target directory does not exist in `emptyState`, so this also
         // covers the `mkdir` the writer does before the file write.
-        const written = step(generateRustTests(), () => readUtf8File(path))
+        const written = ioStep(generateRustTests(), () => readUtf8File(path))
         const [, [tag, result]] = virtual(emptyState)(written)
         assert(tag === 'ok', result)
         assertEq(result, generate(data))
     },
     main: () => {
         const [, result] = virtual(emptyState)(main(defaultNodeProgramOptions))
-        assertEq(result, 0)
+        assertEq(exitCode(result), 0)
     },
 }

package/fjs/proof.f.d.mts

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

package/fjs/proof.f.mjs

@@ -3,10 +3,12 @@
  * @import { Dir } from './effects/node/virtual/types.ts'
  */
 
+import { exitCode } from './effects/node/module.f.mjs'
 import { assert, assertEq } from './asserts/module.f.mjs'
-import { pure } from './effects/module.f.mjs'
+import { pureError, pureOk } from './effects/module.f.mjs'
 import { defaultNodeProgramOptions, emptyState, virtual } from './effects/node/virtual/module.f.mjs'
 import { main } from './module.f.mjs'
+import { vec8 } from './types/bit_vec/module.f.mjs'
 
 /** @type {(args: readonly string[]) => NodeProgramOptions} */
 const makeOptions = args => ({ ...defaultNodeProgramOptions, args })
@@ -14,18 +16,20 @@ const makeOptions = args => ({ ...defaultNodeProgramOptions, args })
 const run = (/** @type {Dir} */ root) => (/** @type {readonly string[]} */ args) =>
     virtual({ ...emptyState, root })(main(makeOptions(args)))
 
+// A program whose exit code is its argument count — non-zero, so it leaves
+// through the error branch like any other failing program.
 /** @type {NodeProgram} */
-const appMain = ({ args }) => pure(args.length)
+const appMain = ({ args }) => args.length === 0 ? pureOk(0) : pureError(args.length)
 
 export const proof = {
     help: () => {
         const [state, code] = run({})(['help'])
-        assertEq(code, 0)
+        assertEq(exitCode(code), 0)
         assert(state.stdout.includes('compile'), 'expected command list in stdout')
     },
     compileRequiresArgs: () => {
         const [state, code] = run({})(['compile'])
-        assertEq(code, 1)
+        assertEq(exitCode(code), 1)
         assert(state.stderr.length !== 0, 'expected error in stderr')
     },
     runModule: () => {
@@ -33,7 +37,7 @@ export const proof = {
         const root = { 'app.f.ts': () => ({ main: appMain }) }
         const [, code] = run(root)(['run', 'app.f.ts', 'x', 'y'])
         // `run` strips the command and file name, so `main` sees two arguments
-        assertEq(code, 2)
+        assertEq(exitCode(code), 2)
     },
     mcp: () => {
         // stdin is empty in the virtual environment, so the server sees EOF
@@ -41,11 +45,33 @@ export const proof = {
         // The store is empty too, so `casMcpServer`'s Evo cache scan
         // (`initEvo`) also runs and finds nothing.
         const [, code] = run({})(['mcp'])
-        assertEq(code, 0)
+        assertEq(exitCode(code), 0)
     },
-    throw: {
-        runImportError: () => {
-            run({})(['run', 'missing.f.ts'])
-        },
+    mcpCorruptStore: () => {
+        // The headline new error path, end to end: `.cas` exists but is a
+        // file, so `initEvo`'s scan cannot list it. The server never starts,
+        // and the failure travels out of the bootstrap to the command's
+        // `exitStep` — a message on stderr and exit 1, where it used to be a
+        // panic from inside `buildCache`.
+        const [state, code] = run({ '.cas': [vec8(0x2An)] })(['mcp'])
+        assertEq(exitCode(code), 1)
+        assert(state.stderr !== '', ['expected the storage error on stderr', state.stderr])
+    },
+    // A file that will not import is the user's command line, not a defect:
+    // it is reported with the name they typed and exits 1, where it used to
+    // panic out of the effect runner.
+    runImportError: () => {
+        const [state, code] = run({})(['run', 'missing.f.ts'])
+        assertEq(exitCode(code), 1)
+        assert(state.stderr.startsWith('missing.f.ts: '), state.stderr)
+    },
+    // The file imports but is not a program. Same answer, different reason —
+    // and the reason is the half of it worth saying.
+    runNotANodeProgram: () => {
+        /** @type {Dir} */
+        const root = { 'app.f.ts': () => ({ notMain: 1 }) }
+        const [state, code] = run(root)(['run', 'app.f.ts'])
+        assertEq(exitCode(code), 1)
+        assert(state.stderr.includes('not a NodeProgram'), state.stderr)
     },
 }

package/fjs/protocol/json_rpc/module.f.d.mts

@@ -2,7 +2,7 @@
  * JSON-RPC 2.0 envelopes and a pure dispatcher.
  *
  * The envelopes are rtti schemas, so one declaration yields both a runtime
- * decoder (`validate(request)`) and the static type (`Ts<typeof request>`) — no
+ * decoder (`parse(request)`) and the static type (`Ts<typeof request>`) — no
  * drift between them. The dispatcher is pure: it maps an already-parsed request
  * value to a response value (or `null` for a notification) and performs no I/O.
  *
@@ -77,7 +77,7 @@ export declare const response: import("../../types/rtti/types.ts").Or<[{
     readonly id: import("../../types/rtti/types.ts").Or<[import("../../types/rtti/types.ts")._Type0<"string">, import("../../types/rtti/types.ts")._Type0<"number">, null]>;
 }]>;
 /** Decodes an untrusted value as a JSON-RPC request / notification. */
-export declare const decodeRequest: import("../../types/rtti/common/types.ts").Validate<{
+export declare const decodeRequest: import("../../types/rtti/parse/types.ts").Parse<{
     readonly jsonrpc: "2.0";
     readonly method: import("../../types/rtti/types.ts")._Type0<"string">;
     readonly params: import("../../types/rtti/types.ts").Or<readonly [() => readonly ['or', typeof import("../../media/json/rtti/module.f.mjs").primitive, typeof import("../../media/json/rtti/module.f.mjs").object, typeof import("../../media/json/rtti/module.f.mjs").array], undefined]>;

package/fjs/protocol/json_rpc/module.f.mjs

@@ -2,7 +2,7 @@
  * JSON-RPC 2.0 envelopes and a pure dispatcher.
  *
  * The envelopes are rtti schemas, so one declaration yields both a runtime
- * decoder (`validate(request)`) and the static type (`Ts<typeof request>`) — no
+ * decoder (`parse(request)`) and the static type (`Ts<typeof request>`) — no
  * drift between them. The dispatcher is pure: it maps an already-parsed request
  * value to a response value (or `null` for a notification) and performs no I/O.
  *
@@ -20,7 +20,7 @@
 
 import { at } from '../../types/object/module.f.mjs'
 import { number, string, or, option } from '../../types/rtti/module.f.mjs'
-import { validate } from '../../types/rtti/validate/module.f.mjs'
+import { parse } from '../../types/rtti/parse/module.f.mjs'
 import { unknown } from '../../media/json/rtti/module.f.mjs'
 
 export const jsonrpc = /** @type {const} */ ('2.0')
@@ -63,7 +63,7 @@ export const errorResponse = /** @type {const} */ ({ jsonrpc, error, id: _id })
 export const response = or(successResponse, errorResponse)
 
 /** Decodes an untrusted value as a JSON-RPC request / notification. */
-export const decodeRequest = validate(request)
+export const decodeRequest = parse(request)
 
 /**
  * Builds an `RpcError` with the given `code` and `message` (no `data`).

package/fjs/protocol/json_rpc/proof.f.mjs

@@ -4,7 +4,7 @@
 
 import { assert, assertEq } from '../../asserts/module.f.mjs'
 import { ok, error } from '../../types/result/module.f.mjs'
-import { validate } from '../../types/rtti/validate/module.f.mjs'
+import { parse } from '../../types/rtti/parse/module.f.mjs'
 import {
     error as errorSchema,
     decodeRequest,
@@ -44,9 +44,9 @@ export const proof = {
             notObject: () => assert(!isOk(decodeRequest(42))),
         },
         error: {
-            ok: () => assert(isOk(validate(errorSchema)({ code: -1, message: 'x' }))),
-            withData: () => assert(isOk(validate(errorSchema)({ code: -1, message: 'x', data: [1, 2] }))),
-            missingMessage: () => assert(!isOk(validate(errorSchema)({ code: -1 }))),
+            ok: () => assert(isOk(parse(errorSchema)({ code: -1, message: 'x' }))),
+            withData: () => assert(isOk(parse(errorSchema)({ code: -1, message: 'x', data: [1, 2] }))),
+            missingMessage: () => assert(!isOk(parse(errorSchema)({ code: -1 }))),
         },
     },
     errors: {

package/fjs/protocol/mcp/module.f.d.mts

@@ -7,7 +7,7 @@
  * - `tools/list` — advertise available tools
  * - `tools/call` — invoke a tool and return text content
  *
- * Each schema is both a runtime decoder (`validate(schema)`) and a static
+ * Each schema is both a runtime decoder (`parse(schema)`) and a static
  * TypeScript type (`Ts<typeof schema>`). Transport framing (stdio) and the
  * JSON-RPC dispatcher are in `fjs/protocol/json_rpc/module.f.mjs`.
  *
@@ -15,19 +15,15 @@
  *
  * @import { Unknown } from '../../media/json/types.ts'
  * @import { Ts } from '../../types/rtti/ts/types.ts'
- * @import { Operation, Effect } from '../../effects/types.ts'
+ * @import { Effect, Operation } from '../../effects/types.ts'
  * @import { Key, MemOp } from '../../effects/memory/types.ts'
  * @import { Response, Id, RpcError } from '../json_rpc/types.ts'
  * @import { Type } from '../../types/rtti/types.ts'
- * @import {
- *   Implementation, ServerCapabilities, InitializeResult, Tool,
- *   ToolsListParams, ToolsCallResult, McpHandlers, ToolEntry,
- *   InitializedState, McpSessionState, McpConfig,
- * } from './types.ts'
+ * @import { Implementation, ServerCapabilities, InitializeResult, Tool, ToolsListParams, ToolsCallResult, McpHandlers, ToolEntry, McpSessionState, McpConfig } from './types.ts'
  */
 import type { Unknown } from '../../media/json/types.ts';
 import type { Ts } from '../../types/rtti/ts/types.ts';
-import type { Operation, Effect } from '../../effects/types.ts';
+import type { Effect, Operation } from '../../effects/types.ts';
 import type { Key, MemOp } from '../../effects/memory/types.ts';
 import type { Response } from '../json_rpc/types.ts';
 import type { Type } from '../../types/rtti/types.ts';
@@ -162,10 +158,10 @@ export declare const toolsCallResult: {
  * @param {string} name - The tool name (used in `tools/call` requests)
  * @param {string} description - Human-readable description for `tools/list`
  * @param {T} inputRtti - Runtime type info for input validation
- * @param {(args: Ts<T>) => Effect<O, ToolsCallResult>} handle - Handler receiving validated arguments of type `Ts<inputRtti>`
+ * @param {(args: Ts<T>) => Effect<O, ToolsCallResult, never>} handle - Handler receiving validated arguments of type `Ts<inputRtti>`
  * @returns {ToolEntry<O>} A `ToolEntry` ready to be added to a registry
  */
-export declare const toolEntry: <T extends Type, O extends Operation>(name: string, description: string, inputRtti: T, handle: (args: Ts<T>) => Effect<O, ToolsCallResult>) => ToolEntry<O>;
+export declare const toolEntry: <T extends Type, O extends Operation>(name: string, description: string, inputRtti: T, handle: (args: Ts<T>) => Effect<O, ToolsCallResult, never>) => ToolEntry<O>;
 /**
  * Helper to create a successful single-text-block tool result.
  *
@@ -200,12 +196,13 @@ export declare const notInitialized: import("../../types/rtti/ts/types.ts").Stru
     readonly data: import("../../types/rtti/types.ts").Or<readonly [() => readonly ['or', typeof import("../../media/json/rtti/module.f.mjs").primitive, typeof import("../../media/json/rtti/module.f.mjs").object, typeof import("../../media/json/rtti/module.f.mjs").array], undefined]>;
 }>;
 /** Initial session state — always start here. */
+/** @type {McpSessionState} */
 export declare const uninitializedState: McpSessionState;
 /**
  * State-machine step for an MCP session using memory effects.
  *
  * Given configuration, handlers, and a memory key holding the session state,
- * returns a function `(value) => Effect<MemOp | O, Response | null>`.
+ * returns a function `(value) => Effect<MemOp | O, Response | null, never>`.
  *
  * Rules:
  * - `ping` returns an empty success regardless of session state; non-object
@@ -222,6 +219,6 @@ export declare const uninitializedState: McpSessionState;
  *   to the handler; invalid params → -32602.
  *
  * @param {McpConfig} config
- * @returns {<O extends Operation>(handlers: McpHandlers<O>) => (stateKey: Key<McpSessionState>) => (value: Unknown) => Effect<MemOp | O, Response | null>}
+ * @returns {<O extends Operation>(handlers: McpHandlers<O>) => (stateKey: Key<McpSessionState>) => (value: Unknown) => Effect<MemOp | O, Response | null, never>}
  */
-export declare const mcpStep: ({ protocolVersion, capabilities, serverInfo, }: McpConfig) => <O extends Operation>(handlers: McpHandlers<O>) => (stateKey: Key<McpSessionState>) => (value: Unknown) => Effect<MemOp | O, Response | null>;
+export declare const mcpStep: ({ protocolVersion, capabilities, serverInfo, }: McpConfig) => <O extends Operation>(handlers: McpHandlers<O>) => (stateKey: Key<McpSessionState>) => (value: Unknown) => Effect<MemOp | O, Response | null, never>;