@amritk/nish-aarch64-darwin 0.35.0 → 0.37.0

package/INSTALL.md

@@ -52,7 +52,12 @@ export PATH="$(brew --prefix llvm@18)/bin:$PATH"   # add to your shell profile
 ```
 
 Xcode's `clang` (`xcode-select --install`) also works for native binaries;
-the Homebrew LLVM is needed for the `wasm` and `wasi` profiles (`wasm-ld`).
+the Homebrew LLVM is needed for the `wasm`, `wasm-host` and `wasi` profiles (`wasm-ld`).
+
+`wasm-opt` (binaryen: `apt-get install binaryen`, `brew install binaryen`) is
+optional. When it is on `PATH`, `scripts/build.sh --profile wasm-host` runs
+`wasm-opt -Oz` on the module, and the build line says whether it ran. Without
+it the module is complete, just not as small.
 
 <a id="wasi-optional-for---profile-wasi" style="scroll-margin-top: 65px"></a>
 
@@ -150,13 +155,15 @@ tarball's SHA-256 with the release's `SHA256SUMS` (or with the digest pinned
 for releases that predate it) and refuses a mismatch. For releases after
 0.21.0 it also checks the release's **build provenance attestation** when a
 signed-in GitHub CLI is present whose `gh attestation verify` takes the
-options below. The attestation
-is a Sigstore-signed statement, made by `actions/attest-build-provenance` in
-the release workflow, that every file in `SHA256SUMS` was built by
-`.github/workflows/release.yml` at the release's tag on a GitHub-hosted
-runner. A failed verification refuses the install; with no `gh`, a signed-out
-one or one too old for those options, the check is skipped with a note saying so, and the
-SHA-256 still applies. The same command by hand, on a tarball you downloaded:
+options below.
+
+The attestation is a Sigstore-signed statement, made by
+`actions/attest-build-provenance` in the release workflow, that every file in
+`SHA256SUMS` was built by `.github/workflows/release.yml` at the release's tag
+on a GitHub-hosted runner. A failed verification refuses the install; with no
+`gh`, a signed-out one or one too old for those options, the check is skipped
+with a note saying so, and the SHA-256 still applies. The same command by hand,
+on a tarball you downloaded:
 
 ```bash
 gh attestation verify nish-<version>-<asset>.tar.gz \
@@ -400,11 +407,13 @@ header — and `runtime/sqlite/`, SQLite's vendored source),
 `docs/AI.md` (the rules card). The
 compiler itself is not in it: it arrives as one prebuilt
 `@amritk/nish-<asset>` package per platform, and `bin/nish` hands over to
-whichever one npm installed. That package carries its own copy of all of
-these, and its `docs/AI.md` is the one an agent's `nish --help` names. `nish` locates the runtime, the script and `std/`
-relative to its own install directory, so a global install works from any
-working directory — and the binary runs from inside its own platform package
-for exactly that reason.
+whichever one npm installed.
+
+That package carries its own copy of all of these, and its `docs/AI.md` is the
+one an agent's `nish --help` names. `nish` locates the runtime, the script and
+`std/` relative to its own install directory, so a global install works from
+any working directory — and the binary runs from inside its own platform
+package for exactly that reason.
 
 Building the IR yourself rather than through `--link` means naming the runtime
 on the `clang` line, and it is sixteen files:
@@ -420,26 +429,31 @@ clang app.ll runtime/runtime.c runtime/runtime-os.c runtime/runtime-parallel.c \
 `runtime.c` is the part every program touches — the arena, strings, arrays,
 number formatting, the panics — and `runtime-os.c` wraps the system calls:
 files, directories, subprocesses, `getenv`, the monotonic clock.
-`runtime-parallel.c` divides work across threads for `nish/threads` (a
-program built with `--threads`, as every importer of `nish/threads` is, also
-needs `-DNISH_THREADS=1 -pthread` on the line), `runtime-cross.c` copies
-the strings and arrays a task answers, a channel sends or a `Mutex` keeps out
-of the arena they were made in, `runtime-host.c` holds the wall clock,
-entropy, file times and signals, `runtime-net.c` the sockets of `nish:net`,
-`runtime-simd.c` and `runtime-aes.c` the vector text search and AES-GCM,
-`runtime-sha256.c` the SHA-256 block kernel `nish/crypto/sha256` hands its
-blocks to on a CPU with the SHA instructions (`NISH_SHA256=soft` keeps the
-portable path), `runtime-chacha20.c` the ChaCha20 keystream `nish/crypto/chacha20poly1305`
-hands a message of 256 bytes or more to on a CPU with AVX2 or NEON (`NISH_CHACHA20=soft`
-keeps the portable path), `runtime-term.c` the stdin reads and terminal calls of `nish:term`,
-`runtime-bytes.c` the byte-class runs of `nish/bytes`, which `nish/json` steps
-over, `runtime-checksum.c` the CRC-32 kernels of `nish/compress/checksum`,
-`runtime-sandbox.c` the confinement a `--sandbox` build applies, and
-`runtime-shm.c` the shared-memory regions of `nish/sync/shm`.
-They are separate so that each carries its own measured size ceiling
-([docs/wp7-runtime.md](https://github.com/amritk/nish/blob/main/docs/wp7-runtime.md)); nothing in the core calls into the
-others, so a line that names only `runtime.c` and `runtime-os.c` still links a
-program that uses none of the other nine. `scripts/build.sh` compiles the other
+
+`runtime-parallel.c` divides work across threads for `nish/threads` (a program
+built with `--threads`, as every importer of `nish/threads` is, also needs
+`-DNISH_THREADS=1 -pthread` on the line), `runtime-cross.c` copies the strings
+and arrays a task answers, a channel sends or a `Mutex` keeps out of the arena
+they were made in, `runtime-host.c` holds the wall clock, entropy, file times
+and signals, `runtime-net.c` the sockets of `nish:net`, `runtime-simd.c` and
+`runtime-aes.c` the vector text search and AES-GCM, `runtime-sha256.c` the
+SHA-256 block kernel `nish/crypto/sha256` hands its blocks to on a CPU with the
+SHA instructions (`NISH_SHA256=soft` keeps the portable path),
+`runtime-chacha20.c` the ChaCha20 keystream `nish/crypto/chacha20poly1305`
+hands a message of 256 bytes or more to on a CPU with AVX2 or NEON
+(`NISH_CHACHA20=soft` keeps the portable path), `runtime-term.c` the stdin
+reads and terminal calls of `nish:term`, `runtime-bytes.c` the byte-class runs
+of `nish/bytes`, which `nish/json` steps over, `runtime-checksum.c` the CRC-32
+kernels of `nish/compress/checksum`, `runtime-sandbox.c` the confinement a
+`--sandbox` build applies, and `runtime-shm.c` the shared-memory regions of
+`nish/sync/shm`. They are separate so that each carries its own measured size
+ceiling
+([docs/wp7-runtime.md](https://github.com/amritk/nish/blob/main/docs/wp7-runtime.md));
+nothing in the core calls into the others, so a line that names only
+`runtime.c` and `runtime-os.c` still links a program that uses none of the
+other nine.
+
+`scripts/build.sh` compiles the other
 nine beside any
 `runtime.c` it is handed, so a build that goes through it — every `--link`,
 and every `--profile` recipe in these documents — needs to name only the one.
@@ -468,19 +482,19 @@ The seed builds stage1, stage1 builds stage2, and stage2 is installed as
 own IR is only reported beside them, because a codegen change since the
 release is expected to move it. `--stages 1` stops one link sooner.
 
-`build/nish` is then the compiler you run: it takes the same `-o`, `--link`
-and `--profile` spellings as an installed `nish`, because it is the same
-program, and makes every directory in the way of the IR, a sidecar or the
-binary itself. It looks for `scripts/build.sh` and the `runtime/*.c` files
-one level up from wherever it was invoked (and one level up from the file a
-symbolic link to it names), so it wants a checkout or an installed package
-around it the way `nish` does. It falls back to the working directory only
-when the compiler itself lies inside that directory, so a checkout you merely
-`cd` into cannot hand it a `scripts/build.sh` to run. Keep `bin/nish` beside
-`scripts/`, `runtime/` and `std/`, as every install above does, and keep that
-directory's parent writable only by you: the package root is the parent of
-the compiler's directory, so a compiler at `/tmp/x/nish` would trust
-`/tmp/scripts/build.sh` (CLI-9 in [docs/security/cli.md](security/cli.md)).
+`build/nish` is then the compiler you run: it takes the same `-o`, `--link` and
+`--profile` spellings as an installed `nish`, because it is the same program,
+and makes every directory in the way of the IR, a sidecar or the binary itself.
+It looks for `scripts/build.sh` and the `runtime/*.c` files one level up from
+wherever it was invoked (and one level up from the file a symbolic link to it
+names), so it wants a checkout or an installed package around it the way `nish`
+does. It falls back to the working directory only when the compiler itself lies
+inside that directory, so a checkout you merely `cd` into cannot hand it a
+`scripts/build.sh` to run. Keep `bin/nish` beside `scripts/`, `runtime/` and
+`std/`, as every install above does, and keep that directory's parent writable
+only by you: the package root is the parent of the compiler's directory, so a
+compiler at `/tmp/x/nish` would trust `/tmp/scripts/build.sh` (CLI-9 in
+[docs/security/cli.md](security/cli.md)).
 
 Because the seed is the last release, `src/` may only *use* in its own
 source the constructs that release compiles. A new construct is implemented
@@ -532,24 +546,24 @@ nish run hello.ts
 `nish run [options] <file.ts> [args ...]` compiles the file, links it into
 `$XDG_CACHE_HOME/nish/run` (or `~/.cache/nish/run`) when that program has not
 been linked before, and starts it with the arguments after the file. The first
-run of a new edit pays for one link, and later runs start the cached binary.
-It needs clang only for that link. It needs `HOME` or `XDG_CACHE_HOME` set
-to an absolute path (a relative one is ignored, as if it were unset), and
-refuses the run without one rather than keep a binary in a shared directory.
-The first run that builds into the cache makes its root `0700`, so no other
-user can plant a binary in it ([docs/security/cli.md](security/cli.md)).
+run of a new edit pays for one link, and later runs start the cached binary. It
+needs clang only for that link. It needs `HOME` or `XDG_CACHE_HOME` set to an
+absolute path (a relative one is ignored, as if it were unset), and refuses the
+run without one rather than keep a binary in a shared directory. The first run
+that builds into the cache makes its root `0700`, so no other user can plant a
+binary in it ([docs/security/cli.md](security/cli.md)).
 
 Every link with the debug, speed or size profile, `nish run`'s and `--link`'s
 alike, keeps the compiled C runtime in `$XDG_CACHE_HOME/nish/runtime` (or
 `~/.cache/nish/runtime`), one entry per profile, `-g`, `--threads`, `CC` and
 the version that compiler reports, made `0700` the same way. The first link
-compiles the runtime's six files at once into it, and every later link
-compiles only the program's modules, also at once, and links against the
-entry: a `hello.ts` debug link goes from about half a second to about a
-tenth. `--link` with no absolute `HOME` or `XDG_CACHE_HOME`, or with a root
-it cannot make private, compiles the runtime itself as it always did; the
-wasi profile and `scripts/build.sh` called directly never use the cache.
-Removing the directory is always safe.
+compiles the runtime's six files at once into it, and every later link compiles
+only the program's modules, also at once, and links against the entry: a
+`hello.ts` debug link goes from about half a second to about a tenth. `--link`
+with no absolute `HOME` or `XDG_CACHE_HOME`, or with a root it cannot make
+private, compiles the runtime itself as it always did; the wasi profile and
+`scripts/build.sh` called directly never use the cache. Removing the directory
+is always safe.
 
 <a id="4-exit-codes" style="scroll-margin-top: 65px"></a>
 

package/docs/AI.md

@@ -1480,6 +1480,13 @@ export const main = (): i32 => {
 ```
 
 - **No body, and it cannot be `export`ed.**
+- **Not in a `--target wasm32` build, nor an `--emit-dts` one with no
+  `--target`** (NL2666; `--target wasm32-wasi` keeps it): there a function the page
+  supplies is imported from a host module, the page's own TypeScript file
+  named by `--host`, and becomes a wasm import from module `host`. Only
+  scalars, enums, `HostHandle<"kind">` (a nominal `i32` for an object the
+  page keeps) and buffer windows (an array, then `at: u32, n: u32`) cross; `import { Canvas, fill } from "./host.ts"`, no `type`
+  modifier.
 - **A class with a `CPtr` field is a handle class: open one with `using`.**
   `using f = new File(p)` closes `f` once at every exit of its block (falling
   off the end, `return`, `break`, `continue`, `orReturn()`), so never call the
@@ -1513,12 +1520,51 @@ emitted and no initialiser runs** — every use lowers to the value itself.
   array, class or interface constant would need an allocation, and there is no
   code to run it.
 - The initialiser is literals, other constants (declared anywhere, or
-  imported), and arithmetic over them. A call, a `new`, a local — anything else
-  — is rejected.
+  imported), and arithmetic over them. A call, a local — anything else — is
+  rejected. The one `new` allowed is module storage, below.
 - Folding uses the language's own arithmetic, so an overflowing fold is an
   error rather than a wrap, and `1 / 0` in a constant is refused at compile
   time.
 
+### Module storage
+
+```ts nish:ok
+const SCORES = new Int32Array(4);
+
+const sum = (xs: Int32Array): i32 => {
+  let total: i32 = 0;
+  for (let i = 0; i < xs.length; i++) {
+    total += xs[i];
+  }
+  return total;
+};
+
+export const main = (): i32 => {
+  SCORES[0] = 30;
+  SCORES[3] = 4;
+  console.log(`${sum(SCORES)} ${SCORES[1]}`);   // 34 0
+  return 0;
+};
+```
+
+A top-level `const` holding `new Array<T>(n)` or a typed-array `new` of a
+constant length is **module storage**: a static, zero-filled array that keeps
+its values between calls, with no initialiser that runs. It is the only
+state a module keeps (there is no top-level `let`).
+
+- The length is a constant from 1 to 16,777,216, at most 256 MiB in all. The element is pointer-free:
+  a number, `boolean`, an enum or range whose zero is a member, a
+  `HostHandle`, or an interface no class implements with fields of those.
+- **It never grows or moves**: no method call on it (`push`, `pop`, `sort`,
+  NL2688) and no `length =`. Keep a count beside it.
+- **Its name is a place, not a value**: index it and read `length`; never bind,
+  store or return it. Lend it only to a parameter spelled with a typed-array
+  name (`xs: Int32Array`) or to a host function's buffer window. A record
+  element is a place too: `bodies[i].x = 1` and `bodies[i] = bodies[j]` are
+  fine, `const b = bodies[i]` is refused; pass the index.
+- Under `--profile wasm-host` the page reads and writes it through `layout`
+  and `views()` in the `.d.ts`. The rules: `LANGUAGE.md` → "Module storage".
+
 ### Classes and interfaces
 
 ```ts nish:ok
@@ -3019,8 +3065,8 @@ export const first = (xs: i32[]): i32 => uncheckedGet(xs, 0);
 A package that must not touch the network says so in `package.json`,
 `"nish": { "capabilities": { "deny": ["net"] } }`, and `--deny net` or an
 allowlist such as `--allow fs.read,exit` says the same on the command line.
-The `"nish"` field holds `noPanic` and `capabilities` and nothing else, each
-written once; anything more is refused (NL3036) rather than skipped. A
+The `"nish"` field holds `noPanic`, `capabilities` and `host` and nothing
+else, each written once; anything more is refused (NL3036) rather than skipped. A
 program whose `main` — or, in a library or a header build, any export —
 reaches more is refused (NL2459), spanned at the first call and naming the
 whole chain to the builtin; nothing changes in a program

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/nish-aarch64-darwin",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "description": "The nish native compiler for macOS on ARM64",
   "license": "MIT",
   "os": [

package/runtime/async.d.mts

@@ -45,5 +45,7 @@ export declare function awaitAll<A, B, C, D, E, F, G, H>(
   g: Promise<G>,
   h: Promise<H>,
 ): Promise<[A, B, C, D, E, F, G, H]>;
+/** `true` once `ms` milliseconds have passed; `false` at once for a negative `ms`. */
+export declare function sleep(ms: number): Promise<boolean>;
 /** Waits for every task `spawn` started, the tasks those tasks start included. */
 export declare function settleTasks(): Promise<void>;

package/runtime/async.mjs

@@ -19,6 +19,13 @@ export const spawn = (task) => {
 
 export const awaitAll = (...tasks) => Promise.all(tasks);
 
+// `sleep` is a timer: `true` once `ms` milliseconds have passed, `false` for a
+// negative `ms`, as natively. `readable` and `writable` have no counterpart in
+// Node, whose descriptors are not polled from JavaScript, so `--emit-ts`
+// refuses them (NL4017) and this file does not export them.
+export const sleep = (ms) =>
+  ms < 0 ? Promise.resolve(false) : new Promise((resolve) => setTimeout(() => resolve(true), ms));
+
 export const settleTasks = async () => {
   for (let i = 0; i < pending.length; i++) {
     await pending[i];