@amritk/nish-x86_64-linux 0.32.0 → 0.34.0

package/INSTALL.md

@@ -254,8 +254,8 @@ routes are
   # on the musl host, with its own clang and the runtime from this repository
   clang app.ll runtime/runtime.c runtime/runtime-os.c runtime/runtime-parallel.c \
     runtime/runtime-cross.c runtime/runtime-host.c runtime/runtime-net.c \
-    runtime/runtime-simd.c runtime/runtime-aes.c runtime/runtime-sha256.c runtime/runtime-term.c \
-    runtime/runtime-bytes.c runtime/runtime-checksum.c runtime/runtime-sandbox.c \
+    runtime/runtime-simd.c runtime/runtime-aes.c runtime/runtime-sha256.c runtime/runtime-chacha20.c \
+    runtime/runtime-term.c runtime/runtime-bytes.c runtime/runtime-checksum.c runtime/runtime-sandbox.c \
     runtime/runtime-shm.c runtime/runtime-region.c -lm -o app
   ```
 
@@ -392,7 +392,7 @@ it into `build/seed/`; `NISH_BOOTSTRAP=<path>` names one you already have and
 skips the download. §2a has what the build does with it.
 
 The published package ships `bin/` (the `nish` command, which is a launcher),
-`runtime/` (the C runtime — fifteen translation units, the wasm subset and their
+`runtime/` (the C runtime — sixteen translation units, the wasm subset and their
 header — and `runtime/sqlite/`, SQLite's vendored source),
 `scripts/build.sh` (the link pipeline), `std/` (the standard library) and
 `docs/AI.md` (the rules card). The
@@ -405,14 +405,14 @@ 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 fifteen files:
+on the `clang` line, and it is sixteen files:
 
 ```bash
 clang app.ll runtime/runtime.c runtime/runtime-os.c runtime/runtime-parallel.c \
   runtime/runtime-cross.c runtime/runtime-host.c runtime/runtime-net.c \
-  runtime/runtime-simd.c runtime/runtime-aes.c runtime/runtime-sha256.c runtime/runtime-term.c \
-  runtime/runtime-bytes.c runtime/runtime-checksum.c runtime/runtime-sandbox.c \
-  runtime/runtime-shm.c -lm -o app
+  runtime/runtime-simd.c runtime/runtime-aes.c runtime/runtime-sha256.c runtime/runtime-chacha20.c \
+  runtime/runtime-term.c runtime/runtime-bytes.c runtime/runtime-checksum.c runtime/runtime-sandbox.c \
+  runtime/runtime-shm.c runtime/runtime-region.c -lm -o app
 ```
 
 `runtime.c` is the part every program touches — the arena, strings, arrays,
@@ -427,7 +427,9 @@ 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-term.c` the stdin reads and terminal calls of `nish:term`,
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/nish-x86_64-linux",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "The nish native compiler for Linux on x86_64",
   "license": "MIT",
   "os": [

package/runtime/core.d.ts

@@ -16,14 +16,30 @@ import type { f32, f64, i32, u16, u32, u8 } from "./core/numbers.js";
  * `nish` does, but lets `===` and `<` through, which `nish` refuses. Under
  * Node it is a typed array made once and never written after.
  */
-export interface u8x16 { readonly __nishSimd: "u8x16"; readonly __lane: u8 }
-export interface u16x8 { readonly __nishSimd: "u16x8"; readonly __lane: u16 }
-export interface i32x4 { readonly __nishSimd: "i32x4"; readonly __lane: i32 }
-export interface u32x4 { readonly __nishSimd: "u32x4"; readonly __lane: u32 }
-export interface f32x4 { readonly __nishSimd: "f32x4"; readonly __lane: f32 }
-export interface f64x2 { readonly __nishSimd: "f64x2"; readonly __lane: f64 }
+export interface u8x16 { readonly __nishSimd: "u8x16"; readonly __lane: u8; readonly __mask: mask8x16 }
+export interface u16x8 { readonly __nishSimd: "u16x8"; readonly __lane: u16; readonly __mask: mask16x8 }
+export interface i32x4 { readonly __nishSimd: "i32x4"; readonly __lane: i32; readonly __mask: mask32x4 }
+export interface u32x4 { readonly __nishSimd: "u32x4"; readonly __lane: u32; readonly __mask: mask32x4 }
+export interface f32x4 { readonly __nishSimd: "f32x4"; readonly __lane: f32; readonly __mask: mask32x4 }
+export interface f64x2 { readonly __nishSimd: "f64x2"; readonly __lane: f64; readonly __mask: mask64x2 }
 /** Any of the six. */
 export type SimdVector = u8x16 | u16x8 | i32x4 | u32x4 | f32x4 | f64x2;
+/** The four with integer lanes. */
+export type IntegerVector = u8x16 | u16x8 | i32x4 | u32x4;
+/** The two with float lanes. */
+export type FloatVector = f32x4 | f64x2;
+/**
+ * One boolean per lane, which a lane-wise compare answers. Under Node an
+ * array of booleans. `nish` keeps a mask in a local, a parameter or a
+ * return of a function the module keeps, and nowhere else; it has no
+ * constructor.
+ */
+export interface mask8x16 { readonly __nishMask: "mask8x16" }
+export interface mask16x8 { readonly __nishMask: "mask16x8" }
+export interface mask32x4 { readonly __nishMask: "mask32x4" }
+export interface mask64x2 { readonly __nishMask: "mask64x2" }
+/** Any of the four. */
+export type SimdMask = mask8x16 | mask16x8 | mask32x4 | mask64x2;
 /** One value per lane, lane 0 first. */
 export declare function u8x16(
   a0: u8, a1: u8, a2: u8, a3: u8, a4: u8, a5: u8, a6: u8, a7: u8,
@@ -54,3 +70,64 @@ export declare function store<V extends SimdVector>(v: V, xs: V["__lane"][], i:
 export declare function extract<V extends SimdVector>(v: V, k: i32): V["__lane"];
 /** A new vector: `v` with lane `k` set to `x`. */
 export declare function replace<V extends SimdVector>(v: V, k: i32, x: V["__lane"]): V;
+/** Float lane arithmetic, lane by lane. An integer lane's form wraps. */
+export declare function add<V extends FloatVector>(a: V, b: V): V;
+export declare function sub<V extends FloatVector>(a: V, b: V): V;
+export declare function mul<V extends FloatVector>(a: V, b: V): V;
+export declare function div<V extends FloatVector>(a: V, b: V): V;
+export declare function sqrt<V extends FloatVector>(a: V): V;
+/** Integer lane arithmetic, wrapping at the lane width. */
+export declare function addWrapping<V extends IntegerVector>(a: V, b: V): V;
+export declare function subWrapping<V extends IntegerVector>(a: V, b: V): V;
+export declare function mulWrapping<V extends IntegerVector>(a: V, b: V): V;
+/** Negation and absolute value of float lanes: the sign bit. */
+export declare function neg<V extends FloatVector>(a: V): V;
+export declare function abs<V extends FloatVector>(a: V): V;
+/** The lesser and the greater lane: a float NaN lane answers NaN. */
+export declare function min<V extends SimdVector>(a: V, b: V): V;
+export declare function max<V extends SimdVector>(a: V, b: V): V;
+/** Bitwise, on integer lanes or lane by lane on two masks. */
+export declare function and<V extends IntegerVector | SimdMask>(a: V, b: V): V;
+export declare function or<V extends IntegerVector | SimdMask>(a: V, b: V): V;
+export declare function xor<V extends IntegerVector | SimdMask>(a: V, b: V): V;
+export declare function not<V extends IntegerVector | SimdMask>(a: V): V;
+/** Lane-wise compares, answering the vector's mask. A float compare is ordered (`ne` unordered). */
+export declare function eq<V extends SimdVector>(a: V, b: V): V["__mask"];
+export declare function ne<V extends SimdVector>(a: V, b: V): V["__mask"];
+export declare function lt<V extends SimdVector>(a: V, b: V): V["__mask"];
+export declare function le<V extends SimdVector>(a: V, b: V): V["__mask"];
+export declare function gt<V extends SimdVector>(a: V, b: V): V["__mask"];
+export declare function ge<V extends SimdVector>(a: V, b: V): V["__mask"];
+/** Lane `k` of `a` where lane `k` of `m` is set, else of `b`. */
+export declare function select<V extends SimdVector>(m: V["__mask"], a: V, b: V): V;
+/** Whether any lane, or every lane, is set. */
+export declare function any(m: SimdMask): boolean;
+export declare function all(m: SimdMask): boolean;
+/** Lane `k`'s flag in bit `k`. */
+export declare function bitmask(m: SimdMask): i32;
+/**
+ * The lanes added: a `u8x16` or `u16x8` in an `i32`, a float vector in lane
+ * order. An `i32x4` or `u32x4` total is `sumWrapping`.
+ */
+export declare function sum(v: u8x16 | u16x8): i32;
+export declare function sum(v: f32x4): f32;
+export declare function sum(v: f64x2): f64;
+export declare function sumWrapping(v: i32x4): i32;
+export declare function sumWrapping(v: u32x4): u32;
+/** Lanes picked from `a` then `b` by integer-literal indices, one per lane. */
+export declare function shuffle<V extends SimdVector>(a: V, b: V, ...lanes: i32[]): V;
+/**
+ * Shifts and rotates by an integer-literal count below the lane width:
+ * `shr` is logical on an unsigned lane and arithmetic on an `i32` lane.
+ */
+export declare function shl<V extends IntegerVector>(v: V, count: i32): V;
+export declare function shr<V extends IntegerVector>(v: V, count: i32): V;
+export declare function rotl<V extends IntegerVector>(v: V, count: i32): V;
+export declare function rotr<V extends IntegerVector>(v: V, count: i32): V;
+/** The same sixteen bytes read as another vector type. */
+export declare function asU8x16(v: SimdVector): u8x16;
+export declare function asU16x8(v: SimdVector): u16x8;
+export declare function asI32x4(v: SimdVector): i32x4;
+export declare function asU32x4(v: SimdVector): u32x4;
+export declare function asF32x4(v: SimdVector): f32x4;
+export declare function asF64x2(v: SimdVector): f64x2;

package/runtime/core.mjs

@@ -120,3 +120,93 @@ export function replace(v, k, x) {
   out[k] = x;
   return out;
 }
+
+// ---- `nish:simd` lane operations ---------------------------------------------
+// Each answers a fresh vector of its operands' type, and the typed array does
+// the wrapping: a `u8` sum stored into a `Uint8Array` keeps its low byte, as
+// `add <16 x i8>` does. A mask is an array of booleans, one a lane. `f32`
+// arithmetic rounds once, through the array, which for `+ - * /` and `sqrt` is
+// the single rounding the native lane does: the double result of two floats
+// rounds to the same float. `Math.min` and `Math.max` are `llvm.minimum` and
+// `llvm.maximum`: a NaN lane answers NaN and -0 orders below +0.
+
+const simdLanes = (a, f) => {
+  const out = new a.constructor(a.length);
+  for (let j = 0; j < a.length; j++) out[j] = f(a[j], j);
+  return out;
+};
+const simdMask = (a, f) => {
+  const out = new Array(a.length);
+  for (let j = 0; j < a.length; j++) out[j] = f(a[j], j);
+  return out;
+};
+const simdBits = (a) => a.BYTES_PER_ELEMENT * 8;
+
+export const add = (a, b) => simdLanes(a, (x, j) => x + b[j]);
+export const sub = (a, b) => simdLanes(a, (x, j) => x - b[j]);
+export const mul = (a, b) => simdLanes(a, (x, j) => x * b[j]);
+export const div = (a, b) => simdLanes(a, (x, j) => x / b[j]);
+export const neg = (a) => simdLanes(a, (x) => -x);
+export const abs = (a) => simdLanes(a, (x) => Math.abs(x));
+export const sqrt = (a) => simdLanes(a, (x) => Math.sqrt(x));
+// A typed array wraps on store, so the integer forms share the float bodies.
+export const addWrapping = (a, b) => simdLanes(a, (x, j) => x + b[j]);
+export const subWrapping = (a, b) => simdLanes(a, (x, j) => x - b[j]);
+// A 32-bit product loses its low bits as a double; `Math.imul` keeps them.
+export const mulWrapping = (a, b) => simdLanes(a, (x, j) => (simdBits(a) === 32 ? Math.imul(x, b[j]) : x * b[j]));
+export const min = (a, b) => simdLanes(a, (x, j) => Math.min(x, b[j]));
+export const max = (a, b) => simdLanes(a, (x, j) => Math.max(x, b[j]));
+
+/** `and`, `or`, `xor` and `not` take an integer vector or a mask. */
+export const and = (a, b) => (Array.isArray(a) ? simdMask(a, (x, j) => x && b[j]) : simdLanes(a, (x, j) => x & b[j]));
+export const or = (a, b) => (Array.isArray(a) ? simdMask(a, (x, j) => x || b[j]) : simdLanes(a, (x, j) => x | b[j]));
+export const xor = (a, b) => (Array.isArray(a) ? simdMask(a, (x, j) => x !== b[j]) : simdLanes(a, (x, j) => x ^ b[j]));
+export const not = (a) => (Array.isArray(a) ? simdMask(a, (x) => !x) : simdLanes(a, (x) => ~x));
+
+// `ne` is the unordered compare: a NaN lane is unequal to everything.
+export const eq = (a, b) => simdMask(a, (x, j) => x === b[j]);
+export const ne = (a, b) => simdMask(a, (x, j) => x !== b[j]);
+export const lt = (a, b) => simdMask(a, (x, j) => x < b[j]);
+export const le = (a, b) => simdMask(a, (x, j) => x <= b[j]);
+export const gt = (a, b) => simdMask(a, (x, j) => x > b[j]);
+export const ge = (a, b) => simdMask(a, (x, j) => x >= b[j]);
+
+export const select = (m, a, b) => simdLanes(a, (x, j) => (m[j] ? x : b[j]));
+export const any = (m) => m.some((x) => x);
+export const all = (m) => m.every((x) => x);
+export const bitmask = (m) => m.reduce((bits, x, j) => (x ? bits | (1 << j) : bits), 0);
+
+/**
+ * `sum`: a float vector's lanes added first to last from -0, rounding each
+ * step as `llvm.vector.reduce.fadd` does; a `u8` or `u16` vector's, which
+ * cannot overflow an `i32`.
+ */
+export const sum = (a) => {
+  let acc = -0;
+  for (const x of a) acc = a instanceof Float32Array ? Math.fround(acc + x) : acc + x;
+  return acc;
+};
+/** `sumWrapping`: a 32-bit vector's lanes added modulo 2^32. */
+export const sumWrapping = (a) => {
+  let acc = 0;
+  for (const x of a) acc = (acc + x) | 0;
+  return a instanceof Uint32Array ? acc >>> 0 : acc;
+};
+
+/** `shuffle(a, b, ...lanes)`: lane `k` of the 2N lanes `a` then `b`. */
+export const shuffle = (a, b, ...lanes) => simdLanes(a, (_, j) => (lanes[j] < a.length ? a[lanes[j]] : b[lanes[j] - a.length]));
+
+// A count is a constant below the lane width, so `x >>> (w - k)` is a real
+// shift; at k = 0 and w = 32 JavaScript's count wraps to 0, and the `|` keeps x.
+export const shl = (a, k) => simdLanes(a, (x) => x << k);
+export const shr = (a, k) => simdLanes(a, (x) => (a instanceof Int32Array ? x >> k : x >>> k));
+export const rotl = (a, k) => simdLanes(a, (x) => (x << k) | (x >>> (simdBits(a) - k)));
+export const rotr = (a, k) => simdLanes(a, (x) => (x >>> k) | (x << (simdBits(a) - k)));
+
+const simdAs = (Lanes) => (v) => new Lanes(v.buffer.slice(v.byteOffset, v.byteOffset + 16));
+export const asU8x16 = simdAs(Uint8Array);
+export const asU16x8 = simdAs(Uint16Array);
+export const asI32x4 = simdAs(Int32Array);
+export const asU32x4 = simdAs(Uint32Array);
+export const asF32x4 = simdAs(Float32Array);
+export const asF64x2 = simdAs(Float64Array);

package/runtime/nish.d.ts

@@ -856,14 +856,30 @@ declare module "nish:simd" {
    * `nish` does, but lets `===` and `<` through, which `nish` refuses. Under
    * Node it is a typed array made once and never written after.
    */
-  export interface u8x16 { readonly __nishSimd: "u8x16"; readonly __lane: u8 }
-  export interface u16x8 { readonly __nishSimd: "u16x8"; readonly __lane: u16 }
-  export interface i32x4 { readonly __nishSimd: "i32x4"; readonly __lane: i32 }
-  export interface u32x4 { readonly __nishSimd: "u32x4"; readonly __lane: u32 }
-  export interface f32x4 { readonly __nishSimd: "f32x4"; readonly __lane: f32 }
-  export interface f64x2 { readonly __nishSimd: "f64x2"; readonly __lane: f64 }
+  export interface u8x16 { readonly __nishSimd: "u8x16"; readonly __lane: u8; readonly __mask: mask8x16 }
+  export interface u16x8 { readonly __nishSimd: "u16x8"; readonly __lane: u16; readonly __mask: mask16x8 }
+  export interface i32x4 { readonly __nishSimd: "i32x4"; readonly __lane: i32; readonly __mask: mask32x4 }
+  export interface u32x4 { readonly __nishSimd: "u32x4"; readonly __lane: u32; readonly __mask: mask32x4 }
+  export interface f32x4 { readonly __nishSimd: "f32x4"; readonly __lane: f32; readonly __mask: mask32x4 }
+  export interface f64x2 { readonly __nishSimd: "f64x2"; readonly __lane: f64; readonly __mask: mask64x2 }
   /** Any of the six. */
   export type SimdVector = u8x16 | u16x8 | i32x4 | u32x4 | f32x4 | f64x2;
+  /** The four with integer lanes. */
+  export type IntegerVector = u8x16 | u16x8 | i32x4 | u32x4;
+  /** The two with float lanes. */
+  export type FloatVector = f32x4 | f64x2;
+  /**
+   * One boolean per lane, which a lane-wise compare answers. Under Node an
+   * array of booleans. `nish` keeps a mask in a local, a parameter or a
+   * return of a function the module keeps, and nowhere else; it has no
+   * constructor.
+   */
+  export interface mask8x16 { readonly __nishMask: "mask8x16" }
+  export interface mask16x8 { readonly __nishMask: "mask16x8" }
+  export interface mask32x4 { readonly __nishMask: "mask32x4" }
+  export interface mask64x2 { readonly __nishMask: "mask64x2" }
+  /** Any of the four. */
+  export type SimdMask = mask8x16 | mask16x8 | mask32x4 | mask64x2;
   /** One value per lane, lane 0 first. */
   export function u8x16(
     a0: u8, a1: u8, a2: u8, a3: u8, a4: u8, a5: u8, a6: u8, a7: u8,
@@ -894,6 +910,67 @@ declare module "nish:simd" {
   export function extract<V extends SimdVector>(v: V, k: i32): V["__lane"];
   /** A new vector: `v` with lane `k` set to `x`. */
   export function replace<V extends SimdVector>(v: V, k: i32, x: V["__lane"]): V;
+  /** Float lane arithmetic, lane by lane. An integer lane's form wraps. */
+  export function add<V extends FloatVector>(a: V, b: V): V;
+  export function sub<V extends FloatVector>(a: V, b: V): V;
+  export function mul<V extends FloatVector>(a: V, b: V): V;
+  export function div<V extends FloatVector>(a: V, b: V): V;
+  export function sqrt<V extends FloatVector>(a: V): V;
+  /** Integer lane arithmetic, wrapping at the lane width. */
+  export function addWrapping<V extends IntegerVector>(a: V, b: V): V;
+  export function subWrapping<V extends IntegerVector>(a: V, b: V): V;
+  export function mulWrapping<V extends IntegerVector>(a: V, b: V): V;
+  /** Negation and absolute value of float lanes: the sign bit. */
+  export function neg<V extends FloatVector>(a: V): V;
+  export function abs<V extends FloatVector>(a: V): V;
+  /** The lesser and the greater lane: a float NaN lane answers NaN. */
+  export function min<V extends SimdVector>(a: V, b: V): V;
+  export function max<V extends SimdVector>(a: V, b: V): V;
+  /** Bitwise, on integer lanes or lane by lane on two masks. */
+  export function and<V extends IntegerVector | SimdMask>(a: V, b: V): V;
+  export function or<V extends IntegerVector | SimdMask>(a: V, b: V): V;
+  export function xor<V extends IntegerVector | SimdMask>(a: V, b: V): V;
+  export function not<V extends IntegerVector | SimdMask>(a: V): V;
+  /** Lane-wise compares, answering the vector's mask. A float compare is ordered (`ne` unordered). */
+  export function eq<V extends SimdVector>(a: V, b: V): V["__mask"];
+  export function ne<V extends SimdVector>(a: V, b: V): V["__mask"];
+  export function lt<V extends SimdVector>(a: V, b: V): V["__mask"];
+  export function le<V extends SimdVector>(a: V, b: V): V["__mask"];
+  export function gt<V extends SimdVector>(a: V, b: V): V["__mask"];
+  export function ge<V extends SimdVector>(a: V, b: V): V["__mask"];
+  /** Lane `k` of `a` where lane `k` of `m` is set, else of `b`. */
+  export function select<V extends SimdVector>(m: V["__mask"], a: V, b: V): V;
+  /** Whether any lane, or every lane, is set. */
+  export function any(m: SimdMask): boolean;
+  export function all(m: SimdMask): boolean;
+  /** Lane `k`'s flag in bit `k`. */
+  export function bitmask(m: SimdMask): i32;
+  /**
+   * The lanes added: a `u8x16` or `u16x8` in an `i32`, a float vector in lane
+   * order. An `i32x4` or `u32x4` total is `sumWrapping`.
+   */
+  export function sum(v: u8x16 | u16x8): i32;
+  export function sum(v: f32x4): f32;
+  export function sum(v: f64x2): f64;
+  export function sumWrapping(v: i32x4): i32;
+  export function sumWrapping(v: u32x4): u32;
+  /** Lanes picked from `a` then `b` by integer-literal indices, one per lane. */
+  export function shuffle<V extends SimdVector>(a: V, b: V, ...lanes: i32[]): V;
+  /**
+   * Shifts and rotates by an integer-literal count below the lane width:
+   * `shr` is logical on an unsigned lane and arithmetic on an `i32` lane.
+   */
+  export function shl<V extends IntegerVector>(v: V, count: i32): V;
+  export function shr<V extends IntegerVector>(v: V, count: i32): V;
+  export function rotl<V extends IntegerVector>(v: V, count: i32): V;
+  export function rotr<V extends IntegerVector>(v: V, count: i32): V;
+  /** The same sixteen bytes read as another vector type. */
+  export function asU8x16(v: SimdVector): u8x16;
+  export function asU16x8(v: SimdVector): u16x8;
+  export function asI32x4(v: SimdVector): i32x4;
+  export function asU32x4(v: SimdVector): u32x4;
+  export function asF32x4(v: SimdVector): f32x4;
+  export function asF64x2(v: SimdVector): f64x2;
 }
 
 declare module "nish:io" {

package/runtime/nish.h

@@ -10,15 +10,16 @@
  * clock, `nish_platform` / `nish_arch` — and runtime-parallel.c, runtime-host.c,
  * runtime-net.c, runtime-simd.c (the byte searches that read a vector at a
  * time), runtime-aes.c (AES-GCM on the CPU's AES instructions),
- * runtime-sha256.c (SHA-256 on the CPU's SHA instructions), runtime-checksum.c
+ * runtime-sha256.c (SHA-256 on the CPU's SHA instructions), runtime-chacha20.c
+ * (ChaCha20's keystream on AVX2 or NEON vectors), runtime-checksum.c
  * (CRC-32 on its carry-less multiply or CRC instructions) and runtime-term.c
  * (stdin and the terminal, `nish:term`) split off
  * the same way since. They are separate so that each carries its own measured
  * code-size ceiling (docs/wp7-runtime.md, "Runtime additions and budget"); a
  * host links all of them, which `scripts/build.sh` does for you when handed
- * runtime.c, runtime-aes.c, runtime-sha256.c and runtime-checksum.c included: the
- * compiler calls their kernels from std/crypto/aes.ts, std/crypto/sha256.ts and
- * std/compress/checksum.ts, so `scripts/build.sh` pairs each of them with
+ * runtime.c, runtime-aes.c, runtime-sha256.c, runtime-chacha20.c and runtime-checksum.c
+ * included: the compiler calls their kernels from std/crypto/aes.ts,
+ * std/crypto/sha256.ts, std/crypto/chacha20poly1305.ts and std/compress/checksum.ts, so `scripts/build.sh` pairs each of them with
  * runtime.c and `src/run-cache.ts` caches them like the others. `tests/run.js` checks that every runtime function
  * declared in runtime.ts has a prototype in this file.
  *
@@ -400,6 +401,28 @@ int32_t nish_sha256_hw(void);
    guard, so the caller's fallback panics as the Nish function does. `w` (u32[],
    the message schedule the Nish code fills) is neither read nor written. */
 int32_t nish_sha256_compress(nish_array *h, const nish_array *w, const nish_array *src, int32_t at);
+/* ---- ChaCha20 on vectors ----------------------------------------------------
+ * runtime/runtime-chacha20.c: eight blocks at once on AVX2 and four in 128-bit
+ * vectors on x86-64, four in NEON on AArch64. The compiler calls the kernel in
+ * place of std/crypto/chacha20poly1305.ts's private `chacha20XorInto`, behind
+ * `nish_chacha20_hw`, and calls the Nish function itself when either answers 0.
+ * Constant time in the key, the nonce and the data. */
+/* 1 when this process runs the kernel, 0 when it runs the Nish code. Resolved
+   on the first call and fixed from then on: `NISH_CHACHA20=soft` pins 0; unset,
+   `hw` or any other value is the best this machine has: CPUID's AVX2 with the
+   OS saving the YMM registers (XGETBV) on x86-64, NEON on AArch64. Always 0 on
+   other targets, wasm32 among them. */
+int32_t nish_chacha20_hw(void);
+/* RFC 8439 §2.4's encryption of src[srcAt..srcAt + len) (u8[]) into
+   dst[dstAt..dstAt + len) (u8[]) under the ChaCha20 state state[0..16) (u32[]),
+   whose block counter state[12] advances one per 64-byte block, as
+   `chacha20XorInto` does; 1 when it ran. Answers 0 and writes nothing when
+   state.len < 16, len < 256, an offset is negative, a window is outside its
+   array, or the windows overlap without being the same bytes, so the Nish
+   function runs as it would have. The keystream it makes is wiped before it
+   returns; the state is the caller's. */
+int32_t nish_chacha20_xor(nish_array *state, const nish_array *src, int32_t src_at, int32_t len, nish_array *dst,
+                          int32_t dst_at);
 /* ---- CRC-32 on the CPU's carry-less multiply or CRC instructions ---------
  * runtime/runtime-checksum.c: PCLMULQDQ folding on x86-64, the ARMv8 CRC32
  * instructions on AArch64. The compiler calls the kernel in