@elaraai/east 1.0.84 → 1.0.85

package/dist/src/runner_io.d.ts

@@ -0,0 +1,370 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * What a unit reads and writes: the files it names, through a {@link UnitIO}.
+ *
+ * `executeUnit` (`runner_exec.ts`) does a unit's work over a UnitIO rather
+ * than over a file system, so one implementation runs wherever a unit's files
+ * are: east-node's `exec` hands it this machine's files, and a browser an
+ * {@link InMemoryUnitIO} holding the unit and every file it names. A UnitIO is
+ * addressed by the paths the unit names, and reads and writes synchronously,
+ * since a compiled East body reads its lazily opened inputs without awaiting.
+ *
+ * The readers here load what a run unit names through a UnitIO: its program,
+ * by its file's extension, and its inputs, each decoded whole or opened lazily
+ * over its file as the unit's `decode` says, a manifest's segments read from
+ * the files beside it (see `runner_protocol.ts`). A unit whose host places
+ * segments as they are read (`fetch`) has its UnitIO asked for each segment
+ * file before it is read.
+ */
+import { type EastTypeValue } from "./type_of_type.js";
+import { AsyncEastIR, EastIR } from "./eastir.js";
+import type { Unit, UnitDecode } from "./runner_protocol.js";
+/**
+ * The files a unit's work reads and writes, by the paths the unit names.
+ *
+ * @remarks
+ * A relative path is relative to the unit, as the runner protocol has it; a
+ * host that resolves the unit's paths first ({@link resolveUnitPaths}) hands
+ * the IO absolute ones. Every method is synchronous: a lazily opened input is
+ * read from inside compiled East code, which does not await.
+ *
+ * `executeUnit` works over any implementation. east-node's is this machine's
+ * files; {@link InMemoryUnitIO} holds a unit and its files in memory, for a
+ * host with no file system — a browser's Web Worker.
+ */
+export interface UnitIO {
+    /**
+     * Reads a whole file.
+     *
+     * @param path - the file
+     * @returns its bytes
+     * @throws {Error} When there is no file at `path`.
+     */
+    read(path: string): Uint8Array;
+    /**
+     * Reads a file's size.
+     *
+     * @param path - the file
+     * @returns its size in bytes
+     * @throws {Error} When there is no file at `path`; a directory is none.
+     */
+    size(path: string): number;
+    /**
+     * Reads a range of a file.
+     *
+     * @param path - the file
+     * @param offset - the first byte's offset
+     * @param length - how many bytes to read
+     * @returns the `length` bytes from `offset`, fewer only where the file ends
+     *   first
+     * @throws {Error} When there is no file at `path`.
+     */
+    readRange(path: string, offset: number, length: number): Uint8Array;
+    /**
+     * Makes a staged manifest's segment file there to read. When it is absent
+     * and the unit says its host places segments as they are read (`fetch`), the
+     * host is asked for it — in the runner protocol, by creating
+     * `<segment file>.want` — and this returns once the host has placed it.
+     * Otherwise an absent segment stays absent, and reading it fails as reading
+     * any absent file does.
+     *
+     * @param path - the segment's file, `<manifest>.segments/<hash>.beast2`
+     * @param fetch - whether the unit's host places segments as they are read
+     * @throws {Error} When the host says why it cannot place the segment.
+     */
+    segment(path: string, fetch: boolean): void;
+    /**
+     * Lists a directory.
+     *
+     * @param path - the directory
+     * @returns the names of the files and directories directly in it
+     * @throws {Error} When there is no directory at `path`.
+     */
+    list(path: string): string[];
+    /**
+     * Makes a directory, and any parent it lacks. A directory already there is
+     * left as it is.
+     *
+     * @param path - the directory
+     * @throws {Error} When a file is where the directory, or a parent of it,
+     *   would be.
+     */
+    makeDirectory(path: string): void;
+    /**
+     * Writes a whole file, replacing whatever file was there.
+     *
+     * @param path - the file, whose directory must be there
+     * @param bytes - its bytes
+     * @throws {Error} When the file's directory is not there, or a directory is
+     *   at `path`.
+     */
+    write(path: string, bytes: Uint8Array): void;
+}
+/**
+ * A {@link UnitIO} holding a unit and every file it names in memory: the IO a
+ * host with no file system gives `executeUnit`, a browser's Web Worker among
+ * them.
+ *
+ * @remarks
+ * Files are held by their paths, normalized (`./a/../b` is `b`), and a
+ * directory is there when a held file is in it or it was made. Writes copy the
+ * bytes they are given, so the files an execution writes are the IO's own,
+ * and {@link files} holds them once it is done — a host collects the unit's
+ * outputs from there.
+ *
+ * The IO holds every file the unit names, segments included, so it never asks
+ * a host for a segment: {@link segment} has nothing to do, and a segment that
+ * is not held is read as any absent file, and fails at once.
+ *
+ * @example
+ * ```ts
+ * const io = new InMemoryUnitIO([
+ *   ["unit.beast2", encodeBeast2For(UnitType)(unit)],
+ *   ["program.beast2", encodeEastIR(program)],
+ *   ["x.beast2", encodeBeast2For(IntegerType)(7n)],
+ * ]);
+ * const result = await executeUnit(unit, io, { platforms: () => [] });
+ * io.files.get("out.beast2");  // the output the unit names, as its runner wrote it
+ * ```
+ */
+export declare class InMemoryUnitIO implements UnitIO {
+    private readonly held;
+    /** Every directory there is: both roots, each held file's parents, and each
+     *  one made. */
+    private readonly directories;
+    /**
+     * @param files - the unit and every file it names, by the paths the unit
+     *   names them by
+     */
+    constructor(files?: Iterable<readonly [string, Uint8Array]>);
+    /** Every file the IO holds, by its normalized path: the files it was given,
+     *  and those written since. */
+    get files(): ReadonlyMap<string, Uint8Array>;
+    /** @inheritDoc */
+    read(path: string): Uint8Array;
+    /** @inheritDoc */
+    size(path: string): number;
+    /** @inheritDoc */
+    readRange(path: string, offset: number, length: number): Uint8Array;
+    /** Every segment is held already, so there is none to ask for. */
+    segment(_path: string, _fetch: boolean): void;
+    /** @inheritDoc */
+    list(path: string): string[];
+    /** @inheritDoc */
+    makeDirectory(path: string): void;
+    /** @inheritDoc */
+    write(path: string, bytes: Uint8Array): void;
+}
+/**
+ * Resolves every path a unit names — its program, inputs, parts, outputs,
+ * functions, the files an intake reads and writes, and its result — keeping
+ * the rest of the unit as it is.
+ *
+ * @remarks
+ * What east-c's `east_unit_read` does as it reads a unit: a host whose unit
+ * names paths relative to the unit file resolves them against that file's
+ * directory once, so its UnitIO and its messages see the paths the files are
+ * at.
+ *
+ * @param unit - the unit
+ * @param resolve - resolves one path the unit names
+ * @returns the unit, naming every file by its resolved path
+ *
+ * @example
+ * ```ts
+ * const unit = decodeBeast2For(UnitType)(readFileSync(unitPath));
+ * const base = dirname(resolve(unitPath));
+ * const resolved = resolveUnitPaths(unit, (path) => resolve(base, path));
+ * ```
+ */
+export declare function resolveUnitPaths(unit: Unit, resolve: (path: string) => string): Unit;
+/** The encodings a file a unit names can hold, told apart by its extension. */
+export type UnitFileFormat = "beast2" | "east" | "json";
+/**
+ * The encoding a file a unit names holds, by its extension: `.beast2` or
+ * `.beast` a beast2 blob, `.east` East text, `.json` JSON.
+ *
+ * @param path - the file
+ * @returns its encoding
+ * @throws {Error} When the extension is none of those, naming it.
+ */
+export declare function unitFileFormat(path: string): UnitFileFormat;
+/**
+ * Loads a unit's program: an IR file holding an East function or async
+ * function, in any encoding a unit may name ({@link unitFileFormat}).
+ *
+ * @remarks
+ * A beast2 program carries its source map, so an error it raises names where
+ * its source was written; East text and JSON carry none.
+ *
+ * @param io - the unit's files
+ * @param path - the program's file
+ * @returns the program, ready to compile
+ * @throws {Error} When the extension is not one a unit may name, the file
+ *   cannot be read or decoded as IR, or the IR is not a function.
+ */
+export declare function loadUnitProgram(io: UnitIO, path: string): EastIR<any[], any> | AsyncEastIR<any[], any>;
+/**
+ * A staged manifest's segment file: `<manifest>.segments/<hash>.beast2`, the
+ * layout every runner's opener reads and a store takes in by linking.
+ *
+ * @param manifest - the manifest's file
+ * @param hash - the segment's SHA-256, as the manifest names it
+ * @returns the segment's file
+ * @internal
+ */
+export declare function segmentPath(manifest: string, hash: string): string;
+/**
+ * Reads exactly `length` bytes of a file from `offset`, failing a range the
+ * file ends inside, as a positioned reader does.
+ *
+ * @param io - the unit's files
+ * @param path - the file
+ * @param offset - the first byte's offset
+ * @param length - how many bytes to read
+ * @returns the bytes
+ * @throws {Error} When the file ends before the range does.
+ * @internal
+ */
+export declare function readUnitRange(io: UnitIO, path: string, offset: number, length: number): Uint8Array;
+/**
+ * The bytes an input {@link openUnitInputLazy} opened has read so far: its
+ * geometry (tail and head), every fence it probed and each segment frame it
+ * decoded, across its file and, for a manifest, every segment file it read.
+ *
+ * @param value - an input's value
+ * @returns the byte count, or `undefined` for a value not opened lazily
+ */
+export declare function lazyInputBytesRead(value: unknown): number | undefined;
+/**
+ * The bytes an input stands for: the collection a manifest names — the
+ * manifest and every segment file — or any other file's own size.
+ *
+ * @remarks
+ * What a runner's verbose account weighs an input at. A manifest is a few
+ * dozen bytes per segment whatever the collection weighs, so its file's size
+ * would say nothing of what the input holds. The manifest is recognised
+ * through ranged reads, so a large blob is never read to learn that it is not
+ * one.
+ *
+ * @param io - the unit's files
+ * @param path - the input's file
+ * @returns the byte count
+ * @throws {Error} When the extension is not one a unit may name, or there is
+ *   no file at `path`.
+ */
+export declare function unitInputBytes(io: UnitIO, path: string): number;
+/**
+ * Loads an input decoded whole, and frozen: deeply immutable from
+ * construction, a mutating builtin throwing the uniform copy-first error, and
+ * compared by value under East `Is`, as every task input is.
+ *
+ * @remarks
+ * A beast2 file is self-describing; a manifest is the collection it names,
+ * its segments spliced from the files beside it, each asked for first when the
+ * unit's host places segments as they are read. East text and JSON decode as
+ * `type`.
+ *
+ * @param io - the unit's files
+ * @param path - the input's file
+ * @param type - the parameter's type
+ * @param fetch - whether the unit's host places segments as they are read
+ * @returns the input's value
+ * @throws {Error} When the extension is not one a unit may name, or the file,
+ *   or a segment its manifest names, cannot be read or decoded.
+ */
+export declare function loadUnitInput(io: UnitIO, path: string, type: EastTypeValue, fetch: boolean): unknown;
+/** How a unit's inputs are read, beyond the unit itself. */
+export interface UnitInputOptions {
+    /** Whether the unit's host places segments as they are read: the unit's
+     *  `fetch`. */
+    fetch: boolean;
+    /** The host's resident memory now, in bytes: what a lazily opened input
+     *  weighs a read of it whole by (`beast2LazyStats`), and what an input
+     *  decoded whole is said to add. Without it, both come to 0. */
+    resident?: () => number;
+    /** The decoded weight, in bytes, each lazily opened input's pager keeps of
+     *  the segments its keyed and index reads decode (v5/SPEC.md, "The pager's
+     *  cache"): 256 MiB without it. A runner sets it from
+     *  `EAST_PAGED_CACHE_BYTES`, as east-c's pager reads that variable, so a
+     *  test runs every runner in the one-segment mode alike. */
+    cacheBytes?: number;
+}
+/**
+ * Opens an input lazily, frozen, when it can be: a beast2 v5 collection blob
+ * carrying a segment index, or a manifest over its segment files. Its size,
+ * iteration and keyed reads are served a segment at a time; any other
+ * operation reads it whole, once, when it first needs it, to the eager value's
+ * exact semantics.
+ *
+ * @remarks
+ * The file is never read whole: the value pages segment frames from it through
+ * ranged reads, and a manifest's segments are read from their own files, each
+ * asked for as it is first read when the unit's host places segments as they
+ * are read. A unit whose host does not, and whose manifest names a segment not
+ * there, is refused here, so its input decodes whole and fails there.
+ *
+ * Frozen is what makes a lazy open safe for any nested element shape, since a
+ * frozen value cannot be written through; an element holding a Ref or a
+ * function still cannot be, and is refused ({@link isBeast2LazySafe}).
+ *
+ * @param io - the unit's files
+ * @param path - the input's file
+ * @param options - the unit's `fetch`, the host's resident-memory gauge, and
+ *   the decoded weight the input's pager keeps
+ * @returns the lazy collection value, or `undefined` when the input cannot be
+ *   opened lazily — another encoding, a version 4 or index-less blob, a root
+ *   that is no collection, segments that alias one another, an unsafe element
+ *   shape, or a file that is not there — for the caller to decode it whole
+ */
+export declare function openUnitInputLazy(io: UnitIO, path: string, options: UnitInputOptions): unknown | undefined;
+/**
+ * What a runner hears of its inputs as they open: the account `-v` gives of
+ * each.
+ */
+export interface UnitInputReport {
+    /**
+     * Input `index` opened lazily.
+     *
+     * @param index - the input's position
+     */
+    openedLazily(index: number): void;
+    /**
+     * Input `index` was decoded whole before the program ran.
+     *
+     * @param index - the input's position
+     * @param residentBytes - what its decode added to resident memory, by the
+     *   host's gauge: 0 without one, and below 0 when memory freed across the
+     *   decode left the host smaller
+     */
+    decodedWhole(index: number, residentBytes: number): void;
+}
+/** How a program's inputs open: the unit's `fetch`, the host's gauge, and who
+ *  hears how each opened. */
+export interface UnitInputsOptions extends UnitInputOptions {
+    /** Hears how each input opened; without it, nothing is measured for it. */
+    report?: UnitInputReport;
+}
+/**
+ * Opens a program's inputs as the unit's `decode` says, every one frozen.
+ *
+ * @remarks
+ * With `lazy`, each collection input opens lazily whatever it weighs
+ * ({@link openUnitInputLazy}); one that cannot, and every input with `whole`,
+ * is decoded whole before the program runs ({@link loadUnitInput}), what that
+ * added to resident memory measured for a report.
+ *
+ * @param io - the unit's files
+ * @param paths - the input files, in parameter order
+ * @param types - the parameters' types
+ * @param decode - how the collection inputs are read
+ * @param options - the unit's `fetch`, the host's gauge, the decoded weight a
+ *   lazy input's pager keeps, and the report
+ * @returns the inputs, in parameter order
+ * @throws {Error} When an input decoded whole cannot be read or decoded.
+ */
+export declare function openUnitInputs(io: UnitIO, paths: readonly string[], types: readonly EastTypeValue[], decode: UnitDecode, options: UnitInputsOptions): unknown[];
+//# sourceMappingURL=runner_io.d.ts.map

package/dist/src/runner_io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner_io.d.ts","sourceRoot":"","sources":["../../src/runner_io.ts"],"names":[],"mappings":"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"}