@amritk/nish 0.10.0

package/runtime/nish.d.ts

@@ -0,0 +1,290 @@
+/**
+ * Ambient declarations for the Nish global surface.
+ *
+ * Every Nish program is legal TypeScript syntax — the compiler parses it
+ * with the official TypeScript parser and nothing else. This file is what
+ * makes it legal TypeScript *semantics* too: reference it from a `tsconfig.json`
+ * (or with `/// <reference path="..." />`) and `tsc --noEmit`, your editor and
+ * your language server all accept `Result<T, E>`, `Ok(...)`, `i32` and the rest
+ * without a red squiggle.
+ *
+ *   { "include": ["src/**\/*.ts", "node_modules/nish/runtime/nish.d.ts"] }
+ *
+ * **`nish` is still the authority.** TypeScript's structural checker is
+ * weaker than this compiler's in the places where Nish is deliberately
+ * stricter, and it cannot see the flow rules at all:
+ *
+ *   - the integer and float widths are aliases of `number` here, so `tsc`
+ *     lets an `i32` and an `f64` mix where `nish` refuses;
+ *   - `tsc` does not know that a `Result` may not be dropped, that
+ *     `orReturn()` returns early, or that the enclosing function has to
+ *     return a `Result` of its own for it to be legal at all;
+ *   - everything Phase 0 forbids (`any`, `throw`, `try`, prototypes,
+ *     arrow functions, ...) is ordinary TypeScript and passes `tsc` happily.
+ *
+ * So a program that `tsc` accepts may still be rejected by `nish`; the
+ * reverse should never happen, and a case where it does is a bug in this file.
+ * `docs/LANGUAGE.md` is the normative description.
+ */
+
+// ---- Numeric widths (docs/LANGUAGE.md -> Types) ------------------------------
+//
+// Nish treats these as distinct types that never mix implicitly. There is
+// no way to say that in TypeScript without branding them, and a brand would
+// break the literal syntax the language relies on (`let x: i32 = 5`), so they
+// are aliases and the width check is left to `nish`.
+
+type i32 = number;
+type i64 = number;
+type u8 = number;
+type u16 = number;
+type u32 = number;
+type u64 = number;
+type f32 = number;
+type f64 = number;
+
+// ---- Result (docs/LANGUAGE.md -> Result and error handling) ------------------
+//
+// Modelled as the tagged union TypeScript would use anyway, intersected with
+// the method surface. That is what lets `if (r.ok)` and `if (r.isOk())` narrow
+// `r` in `tsc` for the same reason and in the same places they narrow in
+// `nish`.
+
+/** The success arm of a `Result`, as the discriminant proves it. */
+type ResultOk<T> = { readonly ok: true; readonly value: T };
+/** The failure arm. */
+type ResultErr<E> = { readonly ok: false; readonly error: E };
+
+interface ResultMethods<T, E> {
+  /** True when this is the success arm; narrows `r` where it is a condition. */
+  isOk(): this is ResultOk<T> & ResultMethods<T, E>;
+  /** True when this is the failure arm; narrows `r` the other way. */
+  isErr(): this is ResultErr<E> & ResultMethods<T, E>;
+  /**
+   * The success payload, or an early `return Err(error)` from the enclosing
+   * function — Rust's `?`. `nish` additionally requires that function to
+   * return a `Result` whose error arm accepts `E`; `tsc` cannot check that.
+   */
+  orReturn(): T;
+  /** The success payload, or `fallback` when this is the failure arm. */
+  unwrapOr(fallback: T): T;
+  /** The success payload, or `message` on stderr and exit 1. */
+  expect(message: string): T;
+}
+
+/**
+ * The outcome of an operation that can fail. `T` may be `void` for an
+ * operation with nothing to hand back; `E` may not be.
+ */
+type Result<T, E> = (ResultOk<T> | ResultErr<E>) & ResultMethods<T, E>;
+
+/** The success value. Its `Result` type comes from the context, as `null`'s does. */
+declare function Ok<T, E>(value: T): Result<T, E>;
+declare function Ok<E>(): Result<void, E>;
+/** The failure value, likewise. */
+declare function Err<T, E>(error: E): Result<T, E>;
+
+// ---- console and process -----------------------------------------------------
+//
+// Declared here with *Nish's* signatures — one argument, no format string,
+// statement position — rather than borrowed from `lib.dom` or `@types/node`,
+// which describe something much wider. `Console` is an interface so that a
+// project which does pull `lib.dom` in merges with it instead of colliding;
+// `Process` is not that lucky, so a project that needs `@types/node` for other
+// reasons should drop this file's `process` rather than fight it.
+
+interface Console {
+  /** `x` and a newline to stdout. Statement position; exactly one argument. */
+  log(x: string | number | boolean): void;
+  /** The same, on stderr. */
+  error(x: string | number | boolean): void;
+}
+declare var console: Console;
+
+interface Process {
+  /**
+   * Terminate with `code`. Statement position, and a terminator: `never` is
+   * how TypeScript spells that, so a function ending in `process.exit(c)`
+   * satisfies its return type in `tsc` as it does in `nish`.
+   */
+  exit(code: i32): never;
+  /** The command line; `argv[0]` is the program path, as in C. Read-only. */
+  readonly argv: string[];
+  /** The operating system the program runs on: `"linux"`, `"darwin"`, or `"unknown"`. */
+  readonly platform: string;
+  /** The architecture: `"x64"`, `"arm64"`, or `"unknown"`. */
+  readonly arch: string;
+}
+declare var process: Process;
+
+// ---- Numeric conversions (there is no cast in Nish) ----------------------
+
+declare function toI32(x: number | boolean): i32;
+declare function toI64(x: number | boolean): i64;
+declare function toU8(x: number | boolean): u8;
+declare function toU16(x: number | boolean): u16;
+declare function toU32(x: number | boolean): u32;
+declare function toU64(x: number | boolean): u64;
+declare function toF32(x: number | boolean): f32;
+declare function toF64(x: number | boolean): f64;
+/** Reinterpret the 64 bits of an `f64`, never convert the value. */
+declare function f64ToBits(x: f64): i64;
+declare function bitsToF64(bits: i64): f64;
+
+// ---- Streams and files (globals: Nish has no package resolution) ---------
+
+/** `s` to stdout with no trailing newline and no conversion. */
+declare function write(s: string): void;
+/** `s` to stderr, likewise. */
+declare function writeError(s: string): void;
+/**
+ * `message` and a newline to stderr, then exit 1. Terminates control flow, so
+ * it is `never`: that is what lets `tsc` agree that a function ending in a
+ * `panic` returns, and that `x` is not null after `if (x === null) { panic(...); }`
+ * — the guard-then-panic shape `self/` uses everywhere in place of an assert.
+ */
+declare function panic(message: string): never;
+/**
+ * The whole file as a string; a path that cannot be read as one — missing, a
+ * directory, a parent that cannot be searched — prints `nish: cannot read
+ * <path>` and exits 1.
+ */
+declare function readFileSync(path: string): string;
+/** The same read, answering `null` for every path the other exits over. */
+declare function readFileSyncOrNull(path: string): string | null;
+declare function writeFileSync(path: string, data: string): void;
+declare function appendFileSync(path: string, data: string): void;
+/** One directory, not recursive; whether a directory is there afterwards. */
+declare function mkdirSync(path: string): boolean;
+/** Whether a directory is at `path` right now. One `stat`, and never an exit. */
+declare function isDirectorySync(path: string): boolean;
+/**
+ * The directory's entries, sorted ascending by bytes and without `.` or `..`,
+ * or `null` when it cannot be read. An empty directory is an empty array, so
+ * the null check is about the directory and not about its contents.
+ */
+declare function readdirSync(path: string): string[] | null;
+/**
+ * `path` with every symbolic link resolved, as an absolute normalised path —
+ * or `null` when it does not resolve, a path that does not exist included.
+ */
+declare function realpathSync(path: string): string | null;
+/** Run `argv[0]` through `PATH` and wait: the exit status, `128 + n` for a signal, `-1` for a failure. */
+declare function spawnSync(argv: string[]): number;
+/**
+ * The same run with each non-empty path receiving that stream, created or
+ * truncated; an empty string leaves that stream inherited.
+ */
+declare function spawnSyncTo(argv: string[], stdoutPath: string, stderrPath: string): number;
+/** One environment variable, or `null` when it is unset (an empty value is a set variable). */
+declare function getenv(name: string): string | null;
+/**
+ * A monotonic clock in nanoseconds, for timing a region of a program. The
+ * origin is arbitrary, so only the difference between two reads is meaningful.
+ */
+declare function monotonicNanos(): i64;
+
+// ---- The builtin modules (`nish:`) ---------------------------------------------
+//
+// The same builtins, importable. `nish:` resolves to no file — the import
+// renames a builtin rather than introducing one, and the compiler emits the
+// same IR for either spelling — but `tsc` still has to be told the modules
+// exist, or an editor reports every one of these imports as unresolved. The
+// signatures are deliberately the globals' own, repeated rather than aliased:
+// `export { readFileSync }` inside a `declare module` would re-export the
+// global and lose the doc comment an editor shows at the call site.
+//
+// `docs/LANGUAGE.md` -> Builtins -> Builtin modules is the normative list.
+
+declare module "nish:fs" {
+  export function readFileSync(path: string): string;
+  export function readFileSyncOrNull(path: string): string | null;
+  export function writeFileSync(path: string, data: string): void;
+  export function appendFileSync(path: string, data: string): void;
+  /** `true` when the directory was created, `false` when it already existed. */
+  export function mkdirSync(path: string): boolean;
+  export function isDirectorySync(path: string): boolean;
+  /**
+   * The directory's entries, sorted ascending by bytes and without `.` or
+   * `..`, or `null` when it cannot be read.
+   */
+  export function readdirSync(path: string): string[] | null;
+  export function realpathSync(path: string): string | null;
+}
+
+declare module "nish:process" {
+  /** The global `process.exit`: a terminator, which `never` is how `tsc` spells it. */
+  export function exit(code: i32): never;
+  export function getenv(name: string): string | null;
+  export function spawnSync(argv: string[]): number;
+  /**
+   * The same run with each non-empty path receiving that stream, created or
+   * truncated; an empty string leaves that stream inherited.
+   */
+  export function spawnSyncTo(argv: string[], stdoutPath: string, stderrPath: string): number;
+  /**
+   * A monotonic clock in nanoseconds. The origin is arbitrary, so only the
+   * difference between two reads is meaningful.
+   */
+  export function monotonicNanos(): i64;
+  /** The command line; `argv[0]` is the program path, as in C. Read-only. */
+  export const argv: readonly string[];
+  /** The operating system the program runs on: `"linux"`, `"darwin"`, or `"unknown"`. */
+  export const platform: string;
+  /** The architecture: `"x64"`, `"arm64"`, or `"unknown"`. */
+  export const arch: string;
+}
+
+declare module "nish:io" {
+  /** `s` to stdout with no trailing newline and no conversion. */
+  export function write(s: string): void;
+  /** The same, on stderr. */
+  export function writeError(s: string): void;
+  /** `message` to stderr, then exit 1. A terminator, as `process.exit` is. */
+  export function panic(message: string): never;
+}
+
+// ---- Arena (docs/LANGUAGE.md -> Arena) ---------------------------------------
+
+declare const Arena: {
+  /** The current bump address. */
+  mark(): i64;
+  /** Free everything allocated since `m`. */
+  release(m: i64): void;
+  /** Recycle everything in O(1), keeping the newest chunk. */
+  reset(): void;
+  /** Bytes bumped in the current chunk. */
+  used(): i64;
+};
+
+/**
+ * `CPtr` (WP27 S2): the address a `declare function` hands back, opaque and
+ * eight bytes wide. `docs/LANGUAGE.md` has the rules — it may be written in a
+ * `declare function` signature and on a local, compared with `null` or with
+ * another `CPtr`, and passed back to C, and that is all.
+ *
+ * An empty interface with a private brand rather than `unknown` or a type
+ * alias: `tsc` has to refuse the arithmetic and the dereference `nish` refuses,
+ * and it has to refuse assigning any other value to one. The brand is what makes
+ * it nominal, so a `{}` does not satisfy it; the name is never written, so the
+ * declaration costs a reader nothing.
+ */
+declare interface CPtr {
+  readonly __nishForeignPointer: unique symbol;
+}
+
+// ---- What this file cannot say ----------------------------------------------
+//
+// The typed-array aliases (`Int32Array`, `Float32Array`, `Float64Array`,
+// `BigInt64Array`) are *not* declared here. In Nish each one names the
+// element-typed array itself — `Int32Array` is `i32[]` — but redeclaring them
+// would collide with `lib.es5.d.ts` and break every other type in the standard
+// library. So `tsc` reads them as the JavaScript views it knows, which accept
+// indexing and `.length` but not an array literal; write `i32[]` where you
+// want both compilers to agree.
+//
+// `a.pop()` is `T` in Nish — an empty array panics, because there is no
+// `undefined` to answer with — and `T | undefined` in `lib.es5.d.ts`. Narrowing
+// the standard `Array<T>` would need a global augmentation that changed the
+// method for every array in the project, including a host's, so this one is
+// left as it is: `tsc` asks for a null check that `nish` does not need.

package/runtime/nish.h

@@ -0,0 +1,340 @@
+/* Nish runtime ABI, public C header.
+ *
+ * Include this from C drivers, N-API shims, or any other host that links the C
+ * runtime next to compiled Nish modules. Everything here is a contract shared
+ * with `self/runtime.ts` (the IR side) and the implementation, which is
+ * two translation units: `runtime/runtime.c` holds the core every program
+ * touches — the arena, strings, arrays, number formatting, the panics — and
+ * `runtime/runtime_os.c` holds everything that wraps a system call: the file
+ * functions, the directory and subprocess calls, `nish_getenv`, the monotonic
+ * clock, `nish_platform` / `nish_arch`. They are separate so that each carries
+ * its own measured code-size ceiling (docs/wp7-runtime.md, "Runtime additions
+ * and budget"); a host links both, which `scripts/build.sh` does for you when
+ * handed either. `tests/run.js` checks that every runtime function declared in
+ * runtime.ts has a prototype in this file.
+ *
+ * Headers generated by `nish --emit-header` include this one, so keep
+ * it C11-clean under -Wall -Wextra -Werror and usable from C++.
+ */
+#ifndef NISH_H
+#define NISH_H
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Bind a C declaration to an Nish symbol whose name C cannot spell (a
+ * keyword such as `double`): `int32_t double_(int32_t n) NISH_SYMBOL("double");`
+ * Generated headers use it; __USER_LABEL_PREFIX__ supplies the `_` Mach-O adds. */
+#define NISH_STRINGIFY_(x) #x
+#define NISH_STRINGIFY(x) NISH_STRINGIFY_(x)
+#define NISH_SYMBOL(name) __asm__(NISH_STRINGIFY(__USER_LABEL_PREFIX__) name)
+
+/* Thread-local storage for the arena and the RNG seed (WP20 T0). A host that
+ * includes this header must be compiled with the same `-DNISH_THREADS` the
+ * runtime was, because the storage class is part of the ABI: modules compiled
+ * with `nish --threads` reference `@nish_arena` as a `thread_local` global and
+ * ELF refuses to link that against a non-TLS definition. `scripts/build.sh
+ * --threads` passes the macro to every input, which is how `nish --threads
+ * --link` keeps the two halves in step. The same definition is in
+ * runtime/runtime.c and runtime/runtime_wasm.c. */
+#ifdef NISH_THREADS
+#define NISH_TLS _Thread_local
+#else
+#define NISH_TLS
+#endif
+
+/* ---- Strings ------------------------------------------------------------
+ * An Nish `string` is a pointer to this header: { u64 len, bytes[len], 0 }.
+ * `len` is the UTF-8 byte length (`s.length` in Nish). The bytes are
+ * NUL-terminated so `s->data` is a valid C string, but they may contain
+ * embedded NULs, so prefer `len` over strlen. Strings are immutable: a
+ * pointer can be shared freely and never needs copying.
+ *
+ * Literals live in the module's constant data; every other string is
+ * allocated in the arena and stays valid until `nish_reset_arena` or
+ * `nish_free_arena`. Never free a string yourself. */
+typedef struct nish_str {
+  uint64_t len;
+  char data[];
+} nish_str;
+
+/* ---- Arena --------------------------------------------------------------
+ * One bump allocator per process, or one per thread under `-DNISH_THREADS`
+ * (WP20 T0; the layout and every function below are the same either way).
+ * Compiled modules read this struct directly
+ * (the fast path is inlined into the IR), so its layout is ABI:
+ *   %struct.nish_arena = type { i8*, i64, i64, i8* }
+ * Fields: current chunk buffer, bump offset, chunk capacity, chunk list.
+ * `off` and `cap` are `uint64_t` and not `size_t` because that `i64` is what
+ * the inlined fast path bumps and compares on every target: under wasm32 a
+ * `size_t` pair would put them at bytes 4 and 8 while compiled code reads 8
+ * and 16. runtime.c and runtime_wasm.c static-assert these offsets. */
+struct nish_arena {
+  char *buf;
+  uint64_t off;
+  uint64_t cap;
+  void *chunks;
+};
+extern NISH_TLS struct nish_arena nish_arena;
+
+/* Bump allocation: 8-byte rounded and aligned, uninitialised. */
+void *nish_alloc_struct(uint64_t size);
+/* Slow path: push a new chunk (at least 64 KB) and bump from it. Called by
+ * the inlined fast path when the current chunk is full; rarely by hosts. */
+void *nish_arena_grow(uint64_t size);
+/* Recycle everything in O(1): keeps the newest chunk, frees the rest. Every
+ * arena string and object becomes invalid. Call it between batches. */
+void nish_reset_arena(void);
+/* Release every chunk. The arena is lazy, so it can be used again afterwards. */
+void nish_free_arena(void);
+/* Arena scopes (WP6). A mark is the current bump address (`buf + off`), or 0
+ * while the arena is empty; `nish_arena_release(mark)` frees everything
+ * allocated since that mark (chunks pushed after it are freed, a mark of 0
+ * behaves like `nish_reset_arena`). Releasing while an object, string or
+ * array allocated after the mark is still referenced is undefined behaviour.
+ * Compiled functions whose allocations provably die with them bracket their
+ * body with these two calls; `Arena.mark/release/used` expose them. */
+uint64_t nish_arena_mark(void);
+void nish_arena_release(uint64_t mark);
+/* Call-site reclaim (WP9): release back to `mark` but keep the newest block,
+ * moving it down to `mark` and answering its new address. Only a string may be
+ * kept, because a string is one flat block with no interior pointers; `p` must
+ * be the last allocation the arena handed out. Anything the guards cannot
+ * prove (a `p` outside the current chunk, a stale or newer mark, no room below
+ * it) leaves the arena untouched and answers `p`. Compiled callers use it to
+ * reclaim the temporaries a string-returning callee left behind. */
+void *nish_arena_keep(uint64_t mark, void *p);
+/* Bytes bumped in the current chunk (`Arena.used()`); a steady-state loop keeps it flat. */
+uint64_t nish_arena_used(void);
+
+/* ---- String operations ------------------------------------------------- */
+/* Copy `len` bytes into a new arena string (`bytes` need not be terminated). */
+nish_str *nish_str_new(const char *bytes, uint64_t len);
+/* `a + b` */
+nish_str *nish_str_concat(const nish_str *a, const nish_str *b);
+/* `a === b`: same bytes (pointer equality is a fast path, not a requirement). */
+bool nish_str_eq(const nish_str *a, const nish_str *b);
+/* `s.length`: the byte length. Compiled code loads the header directly. */
+uint64_t nish_str_len(const nish_str *s);
+/* Whether `sub` occurs at byte offset `at` (negative: never); `startsWith` / `endsWith`. */
+bool nish_str_at(const nish_str *s, int64_t at, const nish_str *sub);
+/* `s.indexOf(sub)`: the first byte offset where `sub` occurs, or -1. An empty
+   needle answers 0 and one longer than `s` answers -1, as in JavaScript. */
+int64_t nish_str_index_of(const nish_str *s, const nish_str *sub);
+/* `console.log(s)`: one write(2) of the bytes plus a newline to stdout. */
+void nish_print(const nish_str *s);
+/* `console.error` and the newline-free `write` / `writeError`: fd 1 or 2. */
+void nish_write(const nish_str *s, int32_t fd, bool newline);
+/* Number to string, as `${n}` does: decimal for integers, shortest round-trip (JS Number#toString) for f64. */
+nish_str *nish_str_from_i32(int32_t v);
+nish_str *nish_str_from_f64(double v);
+nish_str *nish_str_from_i64(int64_t v);
+/* Unsigned decimal (WP15). u8/u16/u32 are zero-extended by the caller, so one
+   symbol serves every unsigned width. */
+nish_str *nish_str_from_u64(uint64_t v);
+
+/* Process and file I/O (WP7). `nish_exit` never returns; the file functions
+ * print a message to stderr and exit(1) on a fatal error. Everything from here
+ * to the end of the clock section below is implemented in runtime_os.c, with
+ * `nish_random` and `nish_argv_init` the exceptions: neither asks the operating
+ * system anything (the clock only seeds the first, and the entry point hands the
+ * second its arguments), so both stay with the core. `nish_random` keeps one seed
+ * word, per process or — under `-DNISH_THREADS` — per thread. */
+double nish_random(void);
+void nish_exit(int32_t code);
+nish_str *nish_read_file(const nish_str *path);
+/* As above, but NULL instead of exiting when the file cannot be read. */
+nish_str *nish_read_file_or_null(const nish_str *path);
+void nish_write_file(const nish_str *path, const nish_str *data);
+void nish_append_file(const nish_str *path, const nish_str *data);
+
+/* ---- Arrays (WP4) -------------------------------------------------------
+ * An Nish `T[]` (also spelled `Int32Array` / `Float64Array` /
+ * `BigInt64Array` for i32 / f64 / i64 elements) is a pointer to this header:
+ *   %struct.nish_array = type { i64 len, i64 cap, i8* data }
+ * `data` holds `cap` elements of one fixed size (int32_t 4, double 8,
+ * int64_t 8, bool 1, pointers 8), 8-byte aligned when the runtime allocated
+ * it.
+ *
+ * WP15 section 2a: when the element type is an Nish `interface` — a record,
+ * fields and nothing else — `data` holds the records *themselves*, end to end,
+ * at exactly the stride and alignment clang gives the matching C struct. A
+ * `Point[]` is therefore a `struct Point *` and `((struct Point *)a->data)[i]`
+ * is element `i`, which is what lets a C host walk one with no marshalling.
+ * A `class` element, and a `T | null` element of any kind, is still one
+ * pointer per slot. `--emit-header` names the element type above each
+ * prototype and says which of the two it is.
+ *
+ * A generated header spells a parameter the callee only reads as
+ * `const nish_array *` and one it writes through (`a[i] = v`, `push`) as
+ * `nish_array *`; the element type is in the comment above each prototype.
+ *
+ * Passing a host buffer: build the header yourself (`nish_array a = { n, n,
+ * (char *)buf }`) and pass `&a`. The callee treats it like any array, so a
+ * `push` that grows it copies the elements into the arena and leaves your
+ * buffer behind; the callee must not retain the pointer beyond the call.
+ * A returned array lives in the arena (valid until the next reset/release):
+ * copy `len` elements out of `data` before recycling. */
+typedef struct nish_array { uint64_t len; uint64_t cap; char *data; } nish_array;
+/* A fresh arena array of `len` uninitialised elements (`len == cap`), for a
+ * host that wants the runtime to own the storage (the wasm loader does).
+ * `elem_size` is `sizeof` one element, so for a record element type it is
+ * `sizeof(struct Point)` and the block is a C array of them. */
+nish_array *nish_alloc_array(uint64_t elem_size, uint64_t len);
+/* The cold paths compiled code calls: `push` when len == cap, a failed bounds
+ * check. `nish_array_grow` moves `cap * elem_size` bytes into a fresh arena
+ * block and writes `data`/`cap`, so for a record element type it relocates the
+ * elements themselves — which is why the checker refuses to let a program hold
+ * a pointer to one across a `push` (WP15 section 2a). */
+void nish_array_grow(nish_array *a, uint64_t elem_size);
+void nish_panic_index(uint64_t idx, uint64_t len);
+/* The failed range check of `s.slice(start, end)` (WP15 section 4): prints the
+   half-open interval that was asked for and the byte length it left, then
+   exits 1. Signed, although the check itself compares unsigned, so that an
+   offset that went negative reads as `-1` and not as 2^64 - 1. `substring`
+   clamps instead and never reaches this. */
+void nish_panic_slice(int64_t start, int64_t end, int64_t len);
+
+/* `process.argv` (WP7): a `string[]` (elements are `nish_str *`) that the entry
+ * wrapper `main` builds once from argc/argv before calling the program; index 0
+ * is the executable path. Allocated with malloc, so arena resets never touch
+ * it. Hosts that call Nish code without a `main` never need it: a program
+ * without an entry point cannot read `process.argv` (compile error). */
+extern nish_array *nish_argv;
+void nish_argv_init(int32_t argc, char **argv);
+
+/* ---- Directories and subprocesses (WP14 D4) -----------------------------
+ * The calls a self-hosted driver needs to find its inputs and link its own
+ * output. Every one of them answers a value instead of exiting, exactly as
+ * `nish_read_file_or_null` does: Nish has no exceptions, so the caller
+ * owns the diagnostic. */
+/* `mkdirSync(path)`: create one directory, NOT recursive (mode 0777 & ~umask,
+ * like Node's `fs.mkdirSync(p)` with no options). True when a directory
+ * exists at `path` afterwards, whether this call created it or it was already
+ * there; false for every other failure, a plain file at `path` included. */
+bool nish_mkdir(const nish_str *path);
+/* `isDirectorySync(path)` (WP14 §7a): true when a directory exists at `path`
+   as this call runs, false for everything else — a missing path, a plain file,
+   a parent that cannot be searched. One `stat`, no allocation, no exit; it is
+   the `stat` half of `nish_mkdir`, which calls it. */
+bool nish_is_dir(const nish_str *path);
+/* `readdirSync(path)`: the entries of directory `path` as a `string[]` (the
+ * elements are `nish_str *`), **sorted ascending by bytes** (`strcmp`), with
+ * `.` and `..` dropped and every other dotfile kept. The runtime sorts because
+ * the language has no `sort` for the caller to reach for, and because a listing
+ * in the file system's own order differs between two machines running the same
+ * program. NULL when the directory cannot be read at all — the language's
+ * `string[] | null` — where a directory that exists and is empty answers an
+ * empty array, which is a different answer. The array and its strings live in
+ * the arena, so copy what you keep before the next reset or release. NULL
+ * under WASI: `fd_readdir` lists a preopened directory rather than a path, so
+ * porting this there is a different contract and not a translation. */
+nish_array *nish_readdir(const nish_str *path);
+/* `spawnSync(argv)`: run element 0 of `argv` (searched on `PATH`) with `argv`
+ * as its argument vector, wait for it, and answer its exit status, or
+ * `128 + n` when signal `n` killed it. -1 when `argv` is empty, when the
+ * child cannot be started or waited for, and always under WASI, which has no
+ * processes. The elements are `nish_str *`; the child receives their bytes,
+ * so an argument containing a NUL is truncated at it. */
+int32_t nish_spawn(const nish_array *argv);
+/* `spawnSyncTo(argv, stdoutPath, stderrPath)`: exactly `nish_spawn` — the same
+ * `PATH` search, the same wait, the same status, `128 + n` and -1 — except that
+ * each non-empty path receives that stream, created or truncated at 0644 as
+ * `nish_write_file` would leave it. An **empty** string leaves that stream
+ * inherited, so one call can capture stdout and let stderr through to the
+ * terminal. The child opens the files, so a failed open is a child that could
+ * not start and answers -1 rather than leaving this process redirected. The two
+ * paths must differ: each is opened separately with its own offset, so naming
+ * one file twice makes the streams overwrite each other instead of
+ * interleaving; capture them apart and concatenate to merge them. One `static`
+ * implementation in runtime_os.c backs both spawn builtins, which is what keeps
+ * the argument vector, the wait and the signal convention written once. */
+int32_t nish_spawn_to(const nish_array *argv, const nish_str *out, const nish_str *err);
+
+/* ---- The environment (WP19 R1) ------------------------------------------
+ * `getenv(name)`: the value of environment variable `name`, copied into the
+ * arena (so a later `setenv` cannot change a string the program still holds),
+ * or NULL when it is unset — the language's `string | null`. An empty value
+ * is a set variable and answers a zero-length string, not NULL. `name` is
+ * read and never retained; a NUL inside it truncates the lookup, as it does
+ * for every other path-like argument here. */
+nish_str *nish_getenv(const nish_str *name);
+
+/* ---- Symlinks (WP19 §5a item 4) -----------------------------------------
+ * `realpathSync(path)`: `path` with every symbolic link resolved and every
+ * `.`, `..` and repeated separator removed, as an absolute path copied into
+ * the arena — or NULL when it does not resolve, which the language reads as
+ * `string | null`. A path that does not exist is the ordinary NULL case and
+ * not an error: the caller is asking whether it resolves, and every component
+ * but the last must exist for POSIX `realpath` to answer at all.
+ *
+ * `path` is read and never retained. The answer is a fresh arena string, so
+ * it outlives the call the way every other string here does. */
+nish_str *nish_realpath(const nish_str *path);
+
+/* ---- What machine this is (WP14 §7a) ------------------------------------
+ * `process.platform` and `process.arch`, spelled as Node spells them:
+ * "linux" or "darwin", "x64" or "arm64", and "unknown" for anything this
+ * compiler has no target triple for, a WASI build included. Both answer a
+ * pointer into this library's own constant data, settled when it was compiled
+ * (a cross build compiles it for the target), so the strings survive every
+ * arena reset, never change, and must not be freed. */
+const nish_str *nish_platform(void);
+const nish_str *nish_arch(void);
+
+/* ---- The clock ----------------------------------------------------------
+ * `monotonicNanos()`: `CLOCK_MONOTONIC` in nanoseconds, which is what timing a
+ * run needs. Deliberately not the wall clock: a wall clock corrected mid-run
+ * can go backwards and make an elapsed time negative. The origin is arbitrary
+ * — only the difference between two reads means anything, and no reading is
+ * comparable across processes or machines — and an i64 of nanoseconds holds 292
+ * years of difference. Compiled code calls this as a *writing* function on
+ * purpose: `readnone` would let LLVM fold the two reads around a measured
+ * region into one and measure zero. */
+int64_t nish_monotonic_nanos(void);
+
+/* String to number (WP7), ASCII whitespace only. mode 0 is `parseFloat`
+ * (longest JS decimal literal or `Infinity`, else NaN), mode 1 is `Number`
+ * (the whole string, trimmed; blank is 0; `0x` hex accepted, as in JS),
+ * mode 2 is `parseInt` (base 10 via strtoll, 0 without digits) as a double
+ * that the compiler saturates into an i32 with `llvm.fptosi.sat`. */
+double nish_parse_number(const nish_str *s, int32_t mode);
+
+/* Checked integer division (Rust semantics): the failed-check path. */
+void nish_panic_div(bool by_zero);
+
+/* ---- Parallel work (WP20 T1 / wp29 stage P1), runtime/runtime_parallel.c ----
+ *
+ * One region of work, divided. `nish_parallel_range` calls `body(lo, hi, ctx)`
+ * once per chunk of a partition of `[0, len)`: contiguous chunks, at most one
+ * element apart in size, at most `nish_cpu_count()` of them and never more than
+ * `len / grain`, with chunk 0 running on the calling thread. It returns when
+ * every chunk has run.
+ *
+ * Under `-DNISH_THREADS` the other chunks run on their own threads, each with
+ * its own arena, which it frees before exiting. Without the macro -- and on
+ * WASI, which has no threads -- the whole range runs on the calling thread, so
+ * the entry point exists either way and the flag decides only whether the work
+ * is divided. A body that itself calls this runs its range on one thread: the
+ * nesting guard is thread-local and there is no scheduler here.
+ *
+ * Two preconditions the caller owns, because this file cannot check them and
+ * the language surface above it will:
+ *   - chunks run concurrently, so a body may read what the caller owns and may
+ *     write only through storage the caller lent it and no two chunks share;
+ *   - a body's result may not point into the arena, because a worker's arena is
+ *     freed when its thread exits while chunk 0's is the caller's own. */
+typedef void (*nish_par_body)(int64_t lo, int64_t hi, void *ctx);
+int64_t nish_cpu_count(void);
+void nish_parallel_range(nish_par_body body, void *ctx, int64_t len, int64_t grain);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* NISH_H */