functionalscript 0.30.0 → 0.31.1

package/fs/djs/module.f.js

@@ -2,8 +2,7 @@ import { transpile } from "./transpiler/module.f.js";
 import { stringify, stringifyAsTree } from "./serializer/module.f.js";
 import { sort } from "../types/object/module.f.js";
 import { pure } from "../effects/module.f.js";
-import { writeFile, error, } from "../effects/node/module.f.js";
-import { utf8 } from "../text/module.f.js";
+import { writeUtf8File, error, } from "../effects/node/module.f.js";
 export const compile = args => {
     if (args.length < 2) {
         return error('Error: Requires 2 or more arguments')
@@ -20,7 +19,7 @@ export const compile = args => {
         const content = outputFileName.endsWith('.json')
             ? stringifyAsTree(sort)(result[1])
             : stringify(sort)(result[1]);
-        return writeFile(outputFileName, utf8(content))
+        return writeUtf8File(outputFileName, content)
             .step(() => pure(0));
     });
 };

package/fs/djs/serializer/module.f.js

@@ -7,10 +7,20 @@ import { serialize as bigintSerialize } from "../../types/bigint/module.f.js";
 import { objectWrap, arrayWrap, stringSerialize, numberSerialize, nullSerialize, boolSerialize } from "../../json/serializer/module.f.js";
 const colon = [':'];
 export const undefinedSerialize = ['undefined'];
+/**
+ * Returns the value's `RefCounter` only if it is *shared* (referenced more
+ * than once) — otherwise `undefined`. Names the single predicate that drives
+ * const hoisting in both `getConstants` (decide which values become consts)
+ * and `serializeWithConst` (emit a `c<N>` reference to one).
+ */
+const sharedRef = (refs) => (v) => {
+    const rc = refs.get(v);
+    return rc !== undefined && rc[1] > 1 ? rc : undefined;
+};
 const getConstants = refs => {
+    const shared = sharedRef(refs);
     const checkSelf = djs => state => {
-        const refCounter = refs.get(djs);
-        if (refCounter !== undefined && refCounter[1] > 1 && !state.added.has(djs)) {
+        if (shared(djs) !== undefined && !state.added.has(djs)) {
             return {
                 added: new Set([...state.added, djs]),
                 consts: { head: state.consts, tail: [djs] }
@@ -95,16 +105,19 @@ const buildSerialize = refLookup => sort => {
     return f;
 };
 export const serializeWithoutConst = buildSerialize(noRef);
-const serializeWithConst = sort => refs => root => buildSerialize(value => {
-    if (value === root) {
+const serializeWithConst = sort => refs => {
+    const shared = sharedRef(refs);
+    return root => buildSerialize(value => {
+        if (value === root) {
+            return null;
+        }
+        const rc = shared(value);
+        if (rc !== undefined) {
+            return [`c${rc[0]}`];
+        }
         return null;
-    }
-    const refCounter = refs.get(value);
-    if (refCounter !== undefined && refCounter[1] > 1) {
-        return [`c${refCounter[0]}`];
-    }
-    return null;
-})(sort);
+    })(sort);
+};
 const countRefsOp = djs => refs => {
     switch (typeof djs) {
         case 'boolean':

package/fs/djs/transpiler/module.f.js

@@ -13,8 +13,7 @@ import { concat as pathConcat } from "../../path/module.f.js";
 import { parseFromTokens } from "../parser/module.f.js";
 import { run } from "../ast/module.f.js";
 import { foldStep, pure } from "../../effects/module.f.js";
-import { readFile } from "../../effects/node/module.f.js";
-import { utf8ToString } from "../../text/module.f.js";
+import { readUtf8File } from "../../effects/node/module.f.js";
 const mapDjs = context => path => {
     const res = at(path)(context.complete);
     if (res === null) {
@@ -22,11 +21,11 @@ const mapDjs = context => path => {
     }
     return res.djs;
 };
-const parseModule = path => readFile(path).step(result => {
+const parseModule = path => readUtf8File(path).step(result => {
     if (result[0] === 'error') {
         return pure(error({ message: 'file not found', metadata: null }));
     }
-    const tokens = tokenize(stringToList(utf8ToString(result[1])))(path);
+    const tokens = tokenize(stringToList(result[1]))(path);
     return pure(parseFromTokens(tokens));
 });
 const transpileWithImports = path => parseModuleResult => context => {

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

@@ -0,0 +1,37 @@
+/**
+ * Typed key-value memory effects for state that persists across effect steps.
+ *
+ * A memory key is opaque at runtime and carries the value type at compile time,
+ * so a key returned by {@link create} can only be read and written with values
+ * of the same type. The concrete interpreter owns the actual storage and key
+ * 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
+ * memory operations.
+ *
+ * @module
+ */
+import type { Phantom } from '../../types/phantom/module.f.ts';
+import { type Nominal } from '../../types/nominal/module.f.ts';
+import { type Effect } from '../module.f.ts';
+/** Nominal brand version for memory keys. */
+type MemKeyHash = '3f114fa6036a8da026b827f0c3e6d901f5e81ad9a320e431ccce31451892d286';
+/** Opaque handle for a value stored by the memory interpreter. */
+export type Key<T> = Phantom<Nominal<'MemKey', MemKeyHash, string>, T>;
+export declare const asBase: (n: Nominal<"MemKey", "3f114fa6036a8da026b827f0c3e6d901f5e81ad9a320e431ccce31451892d286", string>) => string;
+export declare const asNominal: (b: string) => Nominal<"MemKey", "3f114fa6036a8da026b827f0c3e6d901f5e81ad9a320e431ccce31451892d286", string>;
+/** Allocates a fresh memory slot and initializes it with `value`. */
+export type MemCreate = readonly ['memCreate', <T>(value: T) => Key<T>];
+/** Reads the current value stored at `key`. */
+export type MemRead = readonly ['memRead', <T>(key: Key<T>) => T];
+/** Replaces the current value stored at `key`. */
+export type MemWrite = readonly ['memWrite', <T>(key: Key<T>, value: T) => void];
+export type MemOp = MemCreate | MemRead | MemWrite;
+/** Creates a new typed memory slot with `value` as its initial contents. */
+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>(ket: Key<T>) => Effect<MemRead, T>;
+/** Replaces the current contents of a typed memory slot. */
+export declare const write: <T>(key: Key<T>, value: T) => Effect<MemWrite, void>;
+export {};

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

@@ -0,0 +1,24 @@
+/**
+ * Typed key-value memory effects for state that persists across effect steps.
+ *
+ * A memory key is opaque at runtime and carries the value type at compile time,
+ * so a key returned by {@link create} can only be read and written with values
+ * of the same type. The concrete interpreter owns the actual storage and key
+ * 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
+ * memory operations.
+ *
+ * @module
+ */
+import { asBase as nominalAsBase, asNominal as nominalAsNominal } from "../../types/nominal/module.f.js";
+import { do_ } from "../module.f.js";
+export const asBase = (nominalAsBase);
+export const asNominal = (nominalAsNominal);
+/** Creates a new typed memory slot with `value` as its initial contents. */
+export const create = do_('memCreate');
+/** Reads the current contents of a typed memory slot. */
+export const read = do_('memRead');
+/** Replaces the current contents of a typed memory slot. */
+export const write = do_('memWrite');

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

@@ -0,0 +1,6 @@
+export declare const proof: {
+    roundTrip: () => void;
+    allocatesFreshKeys: () => void;
+    typeTest: () => void;
+    throw: () => void;
+};

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

@@ -0,0 +1,64 @@
+import { run } from "../mock/module.f.js";
+import { pure } from "../module.f.js";
+import { asBase, asNominal, create, read, write, } from "./module.f.js";
+const initial = { next: 0, values: {} };
+const mock = {
+    memCreate: value => state => {
+        const id = `k${state.next}`;
+        const key = asNominal(id);
+        return [{
+                next: state.next + 1,
+                values: { ...state.values, [id]: value },
+            }, key];
+    },
+    memRead: key => state => [state, state.values[asBase(key)]],
+    memWrite: (key, value) => state => {
+        const id = asBase(key);
+        if (!(id in state.values)) {
+            throw id;
+        }
+        return [{
+                ...state,
+                values: { ...state.values, [id]: value },
+            }, undefined];
+    },
+};
+const program = create(1).step(key => read(key).step(value => write(key, value + 41).step(() => read(key))));
+export const proof = {
+    roundTrip: () => {
+        const [state, result] = run(mock)(initial)(program);
+        if (result !== 42) {
+            throw result;
+        }
+        if (state.values.k0 !== 42) {
+            throw state;
+        }
+    },
+    allocatesFreshKeys: () => {
+        const effect = create('a').step(a => create('b').step(b => pure([
+            asBase(a),
+            asBase(b),
+        ])));
+        const [state, [a, b]] = run(mock)(initial)(effect);
+        if (a !== 'k0') {
+            throw a;
+        }
+        if (b !== 'k1') {
+            throw b;
+        }
+        if (state.values.k0 !== 'a') {
+            throw state;
+        }
+        if (state.values.k1 !== 'b') {
+            throw state;
+        }
+    },
+    typeTest: () => {
+        // const e = create(1).step(k => write(k, 'bad').step(() => read(k)))
+        create(1).step(k => write(k, 5).step(() => read(k)));
+    },
+    throw: () => {
+        const key = asNominal('missing');
+        run(mock)(initial)(write(key, 1));
+    },
+};

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

@@ -3,9 +3,14 @@
  *
  * @module
  */
-import type { Effect, Operation, Pr } from "../module.f.ts";
+import { type Effect, type Operation, type Pr } from "../module.f.ts";
+/**
+ * A synchronous, state-threading operation map. An entry takes the command's
+ * payload (fixed when the command is issued) and returns a state transition —
+ * the curried `state` parameter is data the runner supplies on each step.
+ */
 export type MemOperationMap<O extends Operation, S> = {
-    readonly [K in O[0]]: (state: S, ...payload: Pr<O, K>[0]) => readonly [S, Pr<O, K>[1]];
+    readonly [K in O[0]]: (...payload: Pr<O, K>[0]) => (state: S) => readonly [S, Pr<O, K>[1]];
 };
 export type RunInstance<O extends Operation, S> = (state: S) => <O1 extends O, T>(effect: Effect<O1, T>) => readonly [S, T];
 export declare const run: <O extends Operation, S>(o: MemOperationMap<O, S>) => RunInstance<O, S>;

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

@@ -1,16 +1,20 @@
+/**
+ * Mock effect runtimes for testing effectful programs.
+ *
+ * @module
+ */
+import { match } from "../module.f.js";
 export const run = (o) => state => effect => {
+    const next = match(o);
     let s = state;
     let e = effect;
     while (true) {
-        const { value } = e;
-        if (value.length === 1) {
-            const [v] = value;
-            return [s, v];
+        const r = next(e);
+        if (r[0] === 'done') {
+            return [s, r[1]];
         }
-        const [cmd, payload, cont] = value;
-        const operation = o[cmd];
-        const [ns, m] = operation(s, ...payload);
+        const [ns, m] = r[1](s);
         s = ns;
-        e = cont(m);
+        e = r[2](m);
     }
 };

package/fs/effects/module.d.ts

@@ -1,2 +1,2 @@
-import type { Effect, Operation, ToAsyncOperationMap } from "./module.f.ts";
+import { type Effect, type Operation, type ToAsyncOperationMap } from "./module.f.ts";
 export declare const asyncRun: <O extends Operation>(map: ToAsyncOperationMap<O>) => <T, E extends Effect<O, T>>(effect: Effect<O, T>) => Promise<T>;

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

@@ -36,6 +36,47 @@ export declare const foldStep: <O extends Operation, T, S>(f: (item: T) => (stat
  * results. The `void` accumulator sibling of `foldStep`.
  */
 export declare const forEachStep: <O extends Operation, T>(f: (item: T) => Effect<O, void>) => (items: List<T>) => Effect<O, void>;
+/**
+ * The decoded form of an effect's next step: either a final `result`, or a
+ * `command` to perform with its `payload` and the `continuation` to resume
+ * with the command's output.
+ */
+export type Decoded<O extends Operation, T> = {
+    readonly done: true;
+    readonly result: T;
+} | {
+    readonly done: false;
+    readonly command: Do<O, T>[0];
+    readonly payload: Do<O, T>[1];
+    readonly continuation: Do<O, T>[2];
+};
+/**
+ * Decodes an effect's next step: a pure result, or a command to perform.
+ *
+ * This is the only function that knows how `Value` is laid out (a length-1
+ * tuple for `Pure`, a `[command, payload, continuation]` tuple for `Do`).
+ * Interpreters and proofs must go through `decode` (or `match`) instead of
+ * inspecting the tuple, so the representation can change without touching
+ * them.
+ */
+export declare const decode: <O extends Operation, T>({ value }: Effect<O, T>) => Decoded<O, T>;
+/**
+ * An operation map whose entries take a command's payload and return some
+ * output `R`. Generalizes `ToAsyncOperationMap` (`R = Promise<…>`) and the
+ * curried `MemOperationMap` (`R = (state) => [state, …]`).
+ */
+export type OperationMap<O extends Operation, R> = {
+    readonly [K in O[0]]: (...payload: Pr<O, K>[0]) => R;
+};
+export type MatchResult<O extends Operation, T, R> = readonly ['done', T] | readonly ['cont', R, Do<O, T>[2]];
+/**
+ * Decodes an effect's next step and dispatches its command to `map`,
+ * returning either the final result or the operation's output `R` paired
+ * 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.
+ */
+export declare const match: <O extends Operation, R>(map: OperationMap<O, R>) => <O1 extends O, T>(effect: Effect<O1, T>) => MatchResult<O1, T, R>;
 export type ToAsyncOperationMap<O extends Operation> = {
     readonly [K in O[0]]: (...payload: Pr<O, K>[0]) => Promise<Pr<O, K>[1]>;
 };

package/fs/effects/module.f.js

@@ -29,3 +29,28 @@ export const foldStep = (f) => (init) => (items) => fold(item => acc => acc.step
  * results. The `void` accumulator sibling of `foldStep`.
  */
 export const forEachStep = (f) => (items) => foldStep((item) => () => f(item))(undefined)(items);
+/**
+ * Decodes an effect's next step: a pure result, or a command to perform.
+ *
+ * This is the only function that knows how `Value` is laid out (a length-1
+ * tuple for `Pure`, a `[command, payload, continuation]` tuple for `Do`).
+ * Interpreters and proofs must go through `decode` (or `match`) instead of
+ * inspecting the tuple, so the representation can change without touching
+ * them.
+ */
+export const decode = ({ value }) => value.length === 1
+    ? { done: true, result: value[0] }
+    : { done: false, command: value[0], payload: value[1], continuation: value[2] };
+/**
+ * Decodes an effect's next step and dispatches its command to `map`,
+ * returning either the final result or the operation's output `R` paired
+ * 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.
+ */
+export const match = (map) => (effect) => {
+    const d = decode(effect);
+    return d.done
+        ? ['done', d.result]
+        : ['cont', map[d.command](...d.payload), d.continuation];
+};

package/fs/effects/module.js

@@ -1,12 +1,11 @@
+import { match } from "./module.f.js";
 export const asyncRun = (map) => async (effect) => {
+    const next = match(map);
     while (true) {
-        const { value } = effect;
-        if (value.length === 1) {
-            return value[0];
+        const r = next(effect);
+        if (r[0] === 'done') {
+            return r[1];
         }
-        const [command, payload, continuation] = value;
-        const operation = map[command];
-        const result = await operation(...payload);
-        effect = continuation(result);
+        effect = r[2](await r[1]);
     }
 };

package/fs/effects/node/memory/module.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Node.js interpreter helpers for memory effects.
+ *
+ * @module
+ */
+import type { Effect, ToAsyncOperationMap } from '../../module.f.ts';
+import { type MemOp } from '../../memory/module.f.ts';
+export type MemoryOperationMap = ToAsyncOperationMap<MemOp>;
+export type Uuid = () => string;
+/**
+ * Creates a stateful operation map backed by an immutable `Map` snapshot.
+ *
+ * Each returned operation map owns its own store. Reusing the same map across
+ * multiple `asyncRun` calls preserves memory across those calls; creating a new
+ * map starts with an empty store. Keys are generated with `crypto.randomUUID()`
+ * by default.
+ */
+export declare const memoryOperationMap: (uuid?: Uuid) => MemoryOperationMap;
+/** Runs a memory-only effect using a fresh memory store. */
+export declare const run: <T>(effect: Effect<MemOp, T>) => Promise<T>;

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

@@ -0,0 +1,44 @@
+/**
+ * Node.js interpreter helpers for memory effects.
+ *
+ * @module
+ */
+import { randomUUID } from 'node:crypto';
+import { asyncRun } from "../../module.js";
+import { asBase, asNominal } from "../../memory/module.f.js";
+const missingKey = (id) => new Error(`memory key not found: ${id}`);
+/**
+ * Creates a stateful operation map backed by an immutable `Map` snapshot.
+ *
+ * Each returned operation map owns its own store. Reusing the same map across
+ * multiple `asyncRun` calls preserves memory across those calls; creating a new
+ * map starts with an empty store. Keys are generated with `crypto.randomUUID()`
+ * by default.
+ */
+export const memoryOperationMap = (uuid = randomUUID) => {
+    const store = new Map();
+    return {
+        memCreate: async (value) => {
+            const id = uuid();
+            const key = asNominal(id);
+            store.set(id, value);
+            return key;
+        },
+        memRead: async (key) => {
+            const id = asBase(key);
+            if (!store.has(id)) {
+                throw missingKey(id);
+            }
+            return store.get(id);
+        },
+        memWrite: async (key, value) => {
+            const id = asBase(key);
+            if (!store.has(id)) {
+                throw missingKey(id);
+            }
+            store.set(id, value);
+        },
+    };
+};
+/** Runs a memory-only effect using a fresh memory store. */
+export const run = (effect) => asyncRun(memoryOperationMap())(effect);

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

@@ -0,0 +1,10 @@
+/**
+ * Node.js interpreter proofs for memory effects.
+ *
+ * @module
+ */
+export declare const proof: {
+    nodeInterpreter: () => Promise<void>;
+    reusedOperationMapPersists: () => Promise<void>;
+    missingKeyThrows: () => Promise<void>;
+};

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

@@ -0,0 +1,35 @@
+/**
+ * Node.js interpreter proofs for memory effects.
+ *
+ * @module
+ */
+import { asyncRun } from "../../module.js";
+import { asNominal, create, read, write, } from "../../memory/module.f.js";
+import { memoryOperationMap, run } from "./module.js";
+export const proof = {
+    nodeInterpreter: async () => {
+        const result = await run(create(1).step(key => write(key, 2).step(() => read(key))));
+        if (result !== 2) {
+            throw result;
+        }
+    },
+    reusedOperationMapPersists: async () => {
+        const runner = asyncRun(memoryOperationMap());
+        const key = await runner(create(1));
+        await runner(write(key, 2));
+        const result = await runner(read(key));
+        if (result !== 2) {
+            throw result;
+        }
+    },
+    missingKeyThrows: async () => {
+        const key = asNominal('missing');
+        const result = await run(read(key)).then(() => undefined, error => error);
+        if (!(result instanceof Error)) {
+            throw result;
+        }
+        if (result.message !== 'memory key not found: missing') {
+            throw result;
+        }
+    },
+};

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

@@ -1,6 +1,6 @@
 import { type NodeProgram } from './module.f.ts';
 /**
- * Runs a `NodeProgram` against the real Node `io` and process arguments,
+ * Runs a `NodeProgram` against the real Node globals and process arguments,
  * resolving to its exit code **without** terminating the process.
  *
  * Use this when the caller must stay alive afterwards — e.g. when proofs are

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

@@ -1,8 +1,19 @@
 import type { Vec } from '../../types/bit_vec/module.f.ts';
+import type { MemOp } from '../memory/module.f.ts';
 import type { Nominal } from '../../types/nominal/module.f.ts';
-import type { Result } from '../../types/result/module.f.ts';
+import { type Result } from '../../types/result/module.f.ts';
+import type { StringMap } from '../../types/object/module.f.ts';
 import { type Effect, type Func, type Operation, type ToAsyncOperationMap } from '../module.f.ts';
 export type IoResult<T> = Result<T, unknown>;
+/**
+ * True if `e` is a "file or directory does not exist" (`ENOENT`) error.
+ *
+ * Node's filesystem rejections are `Error`s carrying `code: 'ENOENT'`; the
+ * virtual interpreter mirrors that shape for absent paths. Lets callers swallow
+ * only the missing-path case (e.g. a fresh store) while propagating genuine
+ * failures (permissions, corruption) rather than masking them.
+ */
+export declare const isNotFound: (e: unknown) => boolean;
 export type All = ['all', <T>(...effects: Effect<never, T>[]) => readonly T[]];
 /**
  * To run the operation `O` should be known by the runner/engine.
@@ -22,6 +33,14 @@ export type Mkdir = readonly ['mkdir', (path: string, options?: MakeDirectoryOpt
 export declare const mkdir: Func<Mkdir>;
 export type ReadFile = readonly ['readFile', (path: string) => IoResult<Vec>];
 export declare const readFile: Func<ReadFile>;
+/**
+ * Reads a file as UTF-8 text.
+ *
+ * Preserves the `IoResult` instead of unwrapping so callers can pattern-match
+ * on errors (e.g. convert them into domain-specific errors) or `unwrap` at the
+ * call site.
+ */
+export declare const readUtf8File: (path: string) => Effect<ReadFile, IoResult<string>>;
 /**
  * Represents a directory entry (file or directory) in the filesystem
  * @see https://nodejs.org/api/fs.html#class-fsdirent
@@ -38,6 +57,8 @@ export type Readdir = readonly ['readdir', (path: string, options: ReaddirOption
 export declare const readdir: Func<Readdir>;
 export type WriteFile = readonly ['writeFile', (path: string, data: Vec) => IoResult<void>];
 export declare const writeFile: Func<WriteFile>;
+/** Writes a string to `path` as UTF-8 bytes. */
+export declare const writeUtf8File: (path: string, content: string) => Effect<WriteFile, IoResult<void>>;
 export type Rm = readonly ['rm', (path: string) => IoResult<void>];
 export declare const rm: Func<Rm>;
 export type ExecResult = {
@@ -50,9 +71,7 @@ export type Access = readonly ['access', (path: string) => IoResult<void>];
 export declare const access: Func<Access>;
 export type Fs = Mkdir | ReadFile | Readdir | WriteFile | Rm | Exec | Access;
 export type Server = Nominal<'server', `160855c4f69310fece3273c1853ac32de43dee1eb41bf59d821917f8eebe9272`, unknown>;
-export type Headers = {
-    readonly [k in string]: string;
-};
+export type Headers = StringMap<string, string>;
 export type IncomingMessage = {
     readonly method: string;
     readonly url: string;
@@ -72,9 +91,7 @@ export declare const listen: Func<Listen>;
 export type Http = CreateServer | Listen;
 export type Forever = ['forever', () => never];
 export declare const forever: Func<Forever>;
-export type Module = {
-    readonly [k in string]: unknown;
-};
+export type Module = StringMap<string, unknown>;
 export type Import = ['import', (path: string) => IoResult<Module>];
 export declare const import_: Func<Import>;
 /** Named output streams accepted by the `Write` effect. */
@@ -92,6 +109,34 @@ export type Console = (s: string) => Effect<Write, void>;
 export declare const log: Console;
 /** Writes a line to `stderr`. Replaces the retired `Error` effect. */
 export declare const error: Console;
+/** Named input streams accepted by the `Read` effect. */
+export type ReadConsoles = 'stdin';
+/**
+ * Reads a single byte from a named input stream — the byte-granular dual of
+ * {@link write}. Resolves to the byte value (`0`–`255`) or `null` at end of
+ * input (EOF). One byte at a time: the effect carries no buffering or line
+ * policy, so higher-level framing (see {@link readLine}) lives in pure code
+ * rather than the interpreter. Back-pressure is naturally sequential — the next
+ * `read` is only issued once the previous byte is consumed.
+ */
+export type Read = readonly ['read', (stream: ReadConsoles) => number | null];
+/** Emits a `Read` effect, yielding the next input byte or `null` at EOF. */
+export declare const read: Func<Read>;
+/**
+ * Reads one line from `stream` as a pure combinator over the byte-level
+ * {@link read}: accumulates bytes until a `\n` terminator or EOF, then
+ * UTF-8-decodes them. The terminator is consumed but excluded from the result.
+ *
+ * Reading a single byte per step means a line never over-reads past its
+ * terminator, so no leftover-byte buffer has to survive between calls — each
+ * `readLine` is self-contained. Yields `null` only at EOF with nothing
+ * buffered; a final line lacking a trailing newline is returned in full.
+ *
+ * Bytes accumulate into a cons-list by prepending (O(1) per byte) and are
+ * reversed and decoded once at the terminator, so a large line costs O(n)
+ * rather than the O(n²) of copying a growing array on every byte.
+ */
+export declare const readLine: (stream: ReadConsoles) => Effect<Read, string | null>;
 export type Now = readonly ['now', () => number];
 export declare const now: Func<Now>;
 /**
@@ -159,7 +204,7 @@ export type TestContext = {
 /** Effect operation that registers a named test with the active `TestContext`. */
 export type Test = readonly ['test', (ctx: TestContext, name: string, expectFailure: boolean, test: (t: TestContext) => Effect<Test | All | Await, void>) => void];
 export declare const test: Func<Test>;
-export type NodeOp = All | Await | Fetch | Fs | Http | Forever | Import | Now | Sandbox | Write | Test;
+export type NodeOp = All | Await | Fetch | Fs | Http | Forever | Import | MemOp | Now | Read | Sandbox | Write | Test;
 export type NodeEffect<T> = Effect<NodeOp, T>;
 /**
  * Writes an error line to `stderr` and yields exit code `1`. The canonical
@@ -192,6 +237,7 @@ export type Engine = 'node' | 'bun' | 'playwright';
 export type NodeProgramOptions = {
     readonly args: readonly string[];
     readonly env: Env;
+    readonly home: string;
     readonly std: {
         readonly [k in WriteConsoles]: {
             readonly isTTY: boolean;