@ai-ecoverse/slicc-kernel 1.124.13 → 1.125.0

package/README.md

@@ -265,7 +265,7 @@ An empty path is `ENOENT` in every path call (`path_open`, `path_filestat_get`,
 On top of preview1 a WASI program gets:
 
 - **Threads**: `wasi.thread-spawn` (wasm32-wasip1-threads) and WASIX `thread_spawn_v2` start a worker per thread on the process's shared memory, sized from the module's own import (a 2 GiB maximum when the engine cannot reserve more). The threads share one descriptor table, and a file written, created, renamed or removed in one thread shows its new size and metadata to `stat` in every other thread at once, under any of its names (a symlink, a hard link, a new name after a rename in the same process), also when another thread renames a file over that name meanwhile, since the kernel reports which file an open or a change reached; this holds among the kernel's own processes, not against other tabs, `hostfs` writers or programs that aren't WASI; another process's changes show at close and after a `spawn` or `wait`, as with close-to-open caching, so a file another process renames while this one holds it open may show its old size under the new name until then; `exit` or a trap in any thread ends the process. At most 64 threads per process; `SLICC_WASM_THREADS` sets another cap, up to 256.
-- **WASIX** (a module importing `wasix_32v1`): fork and setjmp/longjmp through Asyncify (the module is built with `wasm-opt --asyncify`), with the unwound frames kept in the unused part of the program's stack, below its stack pointer (for a position-independent program, the stack the kernel's linker gives it), so a fork from deep in the stack leaves the program's data alone, and a forked child's thread-locals (`errno` included) where the parent left them: the kernel reruns the module's `__wasm_init_tls` at the parent's TLS base (and puts back the block it overwrites), which also sets the internal globals that hold thread-local addresses (a position-independent program's, a side module's, and those of a variable in the `global-dynamic` TLS model), exec, `posix_spawn`, `waitpid` (with `WNOHANG`, and `WUNTRACED` for a child that stops; WASIX has no `WCONTINUED`), pipes, `dup2`, signal handlers and interval timers, terminal modes, and dynamic linking: a position-independent main module loads side modules with `dlopen` from `LD_LIBRARY_PATH`, its runtime path, `/lib`, `/usr/lib` and `/usr/local/lib`. Each thread has its own copy of the function table, so the kernel hands out its slots (a side module's range, a `dlsym`'d function, a closure): threads loading or looking up at the same time never get the same slot. As in glibc, one `dlopen` at a time runs in a process, constructors included: a `dlopen` from a library's constructor goes ahead in its own thread, and another thread's `dlopen` waits, then finds the library loaded and gets the same handle. A thread waiting there still ends or stops with its process, but a signal handler it has runs once that `dlopen` returns. The lock is let go when a `dlopen` fails (an exception, a trap or `pthread_exit` out of a constructor included) and when its thread ends; a forked child starts with it free. A forked child also gets the side modules its parent had loaded, at the same addresses and table slots, with the slot and closure counters and the parent's thread-local blocks: they are linked again in the child before it resumes, without running their constructors or their data relocations again, since their data is already in the copied memory. The same goes for the main module of a position-independent program: its data relocations ran once, in the parent, so a pointer the parent changed before the fork (`int *p = &a; p = &b;`) is still changed in the child (#777). A side-module function on the stack when `fork` is called (a callback into the main module that forks) is not instrumented by Asyncify, so it runs again when the stack is rewound, in the parent and in the child, and libffi frames there can trap; side modules would need building with Asyncify for that, which the toolchain does not do yet. In such a program, `dlopen(NULL)`, and `dlopen` of the program's own file (also by a path that resolves to it through symlinks), give a handle for the program that is already running (no second copy is loaded); a program that isn't position-independent gets an error from `dlopen(NULL)`, as from any `dlopen`; `dlsym` on it searches the program, then the loaded libraries, and `dlclose` of it does nothing. A function already in the table (the program's own, or a library's) keeps its slot, so `dlsym(handle, "strlen") == strlen`. Each WASIX thread has its own Asyncify driver too, so a thread can `longjmp` through Asyncify and `fork` (#710). The unwound frames go at the bottom of the thread's own stack (the `stack` and `stack_size` its libc passes to `wasi_thread_start`), never on the main thread's. A thread whose start args don't look like wasix-libc's (a `stack_size` under 4096 or over the memory, a stack top that isn't 16-aligned or not right above the args) gets no driver, so `fork` there is `ENOSYS` as before, rather than an unwind buffer at a bad address. A child forked from a thread runs as that thread: it's rewound through `wasi_thread_start`, can fork again, and ends when the thread's function returns. A program built with exceptions (every position-independent one) does `setjmp` with exceptions rather than Asyncify, so there only `fork` uses the driver. A kernel timer can be longer than `setTimeout`'s 2^31-1 ms (about 24.8 days): an `alarm`, an interval timer, or a `select`, `poll_oneoff` or `epoll_wait` timeout waits its whole time, re-armed in steps of at most 2^31-1 ms, instead of firing at once or spinning (#767). A WASI or WASIX program that a signal ends (`SIGKILL`, or a signal whose default terminates it) stops at its next kernel call. The kernel first lets the calls it is already serving finish and the program write its files back: it ends the process once the program has made no file call for 2 s, and 5 s after the signal at the latest. A call the program makes after the kill is answered `EINTR` at once and doesn't extend the wait, so a program that swallows the kill and keeps retrying (python writing a fatal error to stderr) still ends (#755).
+- **WASIX** (a module importing `wasix_32v1`): fork and setjmp/longjmp through Asyncify (the module is built with `wasm-opt --asyncify`), with the unwound frames kept in the unused part of the program's stack, below its stack pointer (for a position-independent program, the stack the kernel's linker gives it), so a fork from deep in the stack leaves the program's data alone, and a forked child's thread-locals (`errno` included) where the parent left them: the kernel reruns the module's `__wasm_init_tls` at the parent's TLS base (and puts back the block it overwrites), which also sets the internal globals that hold thread-local addresses (a position-independent program's, a side module's, and those of a variable in the `global-dynamic` TLS model), exec, `posix_spawn`, `waitpid` (with `WNOHANG`, and `WUNTRACED` for a child that stops; WASIX has no `WCONTINUED`), pipes, `dup2`, signal handlers and interval timers, terminal modes, and dynamic linking: a position-independent main module loads side modules with `dlopen` from `LD_LIBRARY_PATH`, its runtime path, `/lib`, `/usr/lib` and `/usr/local/lib`. Each thread has its own copy of the function table, so the kernel hands out its slots (a side module's range, a `dlsym`'d function, a closure): threads loading or looking up at the same time never get the same slot. As in glibc, one `dlopen` at a time runs in a process, constructors included: a `dlopen` from a library's constructor goes ahead in its own thread, and another thread's `dlopen` waits, then finds the library loaded and gets the same handle. A thread waiting there still ends or stops with its process, but a signal handler it has runs once that `dlopen` returns. The lock is let go when a `dlopen` fails (an exception, a trap or `pthread_exit` out of a constructor included) and when its thread ends; a forked child starts with it free. A forked child also gets the side modules its parent had loaded, at the same addresses and table slots, with the slot and closure counters and the parent's thread-local blocks: they are linked again in the child before it resumes, without running their constructors or their data relocations again, since their data is already in the copied memory. The same goes for the main module of a position-independent program: its data relocations ran once, in the parent, so a pointer the parent changed before the fork (`int *p = &a; p = &b;`) is still changed in the child (#777). A side-module function on the stack when `fork` is called (a callback into the main module that forks) is not instrumented by Asyncify, so it runs again when the stack is rewound, in the parent and in the child, and libffi frames there can trap; side modules would need building with Asyncify for that, which the toolchain does not do yet. In such a program, `dlopen(NULL)`, and `dlopen` of the program's own file (also by a path that resolves to it through symlinks), give a handle for the program that is already running (no second copy is loaded); a program that isn't position-independent gets an error from `dlopen(NULL)`, as from any `dlopen`; `dlsym` on it searches the program, then the loaded libraries, and `dlclose` of it does nothing. A function already in the table (the program's own, or a library's) keeps its slot, so `dlsym(handle, "strlen") == strlen`. Each WASIX thread has its own Asyncify driver too, so a thread can `longjmp` through Asyncify and `fork` (#710). The unwound frames go at the bottom of the thread's own stack (the `stack` and `stack_size` its libc passes to `wasi_thread_start`), never on the main thread's. A thread whose start args don't look like wasix-libc's (a `stack_size` under 4096 or over the memory, a stack top that isn't 16-aligned or not right above the args) gets no driver, so `fork` there is `ENOSYS` as before, rather than an unwind buffer at a bad address. A child forked from a thread runs as that thread: it's rewound through `wasi_thread_start`, can fork again, and ends when the thread's function returns. A program built with exceptions (every position-independent one) does `setjmp` with exceptions rather than Asyncify, so there only `fork` uses the driver. A kernel timer can be longer than `setTimeout`'s 2^31-1 ms (about 24.8 days): an `alarm`, an interval timer, or a `select`, `poll_oneoff` or `epoll_wait` timeout waits its whole time, re-armed in steps of at most 2^31-1 ms, instead of firing at once or spinning (#767). A `poll_oneoff` read event's `nbytes` is the number of bytes a read would get at once, as `FIONREAD` counts them, for a pipe, a FIFO, a socket, a terminal and a pty master; on a hangup it's 0 when nothing is left, so a libc can report `POLLHUP` without `POLLIN`, as Linux does (#1053). Other descriptors, regular files included, answer 1. A WASI or WASIX program that a signal ends (`SIGKILL`, or a signal whose default terminates it) stops at its next kernel call. The kernel first lets the calls it is already serving finish and the program write its files back: it ends the process once the program has made no file call for 2 s, and 5 s after the signal at the latest. A call the program makes after the kill is answered `EINTR` at once and doesn't extend the wait, so a program that swallows the kill and keeps retrying (python writing a fatal error to stderr) still ends (#755).
 - **epoll and eventfd** (WASIX `epoll_create`, `epoll_ctl`, `epoll_wait` and `fd_event`, which tokio's reactor uses through the WASIX mio fork):
   - **Where they live:** an epoll instance and an eventfd are kernel descriptors, so they survive `dup`, `fork` and `exec` (unless close-on-exec) and are shared by a process's threads.
   - **What epoll watches:** sockets (listening, connecting, connected, loopback and uplink), pipes, terminals, `kernel.run`'s stdin, eventfds and other epoll instances (a cycle of instances is `ELOOP`).
@@ -358,6 +358,20 @@ The module's default export (or its `main` export) is called with a context and
 - `fdStatus(fd)` (`{ type, tty, seekable }`, `type` being `file`, `pipe`, `tty`, `socket`, `device` or `directory`) and `isatty(fd)`, to tell `< file` from a pipe;
 - `open(path, { read, write, append, create, exclusive, truncate, nonblock, signal })`, which returns a file with `read(position, length)`, `write(position, bytes)`, `size()`, `truncate(size)`, `sync()` and `close()`. Reads and writes go through the kernel's paged files at those positions, so a large file is never read whole; **A FIFO** ([#935](https://github.com/ai-ecoverse/slicc-kernel/issues/935)) opens through the kernel's FIFO open, as fifo(7) says. A read-open waits for a writer and a write-open for a reader, unless the open is `read` and `write` both. `nonblock: true` gives a read-open at once and a write-open with no reader `ENXIO`, and `signal` aborts a waiting open with its reason. Its file reads and writes the pipe: `read(0, length)` and `write(0, bytes)`, any other position is `ESPIPE`, `size()` is `0`, and `truncate` is `EINVAL`. A socket node is `ENXIO`.
 - `fs`: `stat`, `lstat`, `exists`, `readdir`, `mkdir` (with parents, or, with `{ recursive: false }`, as Node's `fs.mkdir` without `recursive`: `EEXIST` for an existing entry and `ENOENT` for a missing parent, atomically among the processes of one kernel, so it can serve as a lock there, but not between two kernels on one origin, such as two tabs ([#519](https://github.com/ai-ecoverse/slicc-kernel/issues/519)); `sync.fs.mkdir` takes the same option), `rm` (recursive), `unlink`, `rename`, `symlink`, `readlink`, `statfs`, `chmod(path, mode)`, and `readFile`/`writeFile` for small files. `chmod` takes the permission bits (`0` to `0o7777`, `EINVAL` otherwise) and follows a symlink; as `chmod(2)`, only the file's owner or root may (`EPERM`), so a program can make a script it wrote runnable by path. `sync.fs.chmod` is the same, synchronously. `statfs(path)` answers `{ type, bsize, blocks, bfree, bavail, files, ffree, quota, usage }`: the fields of Node's `StatFs`, plus `quota` and `usage` in bytes (what jsh 0.17 reads). The values come from the same source as an Emscripten program's `statfs`/`df`: the driver of the mount the path is on, or, on the root file system, the origin's storage estimate (`navigator.storage.estimate()`). `bsize` is 4096, `bfree` and `bavail` are what's left of the quota, and `type`, `files` and `ffree` are 0, since the kernel doesn't know them. Where there's no estimate (the Node entry's root), every count is 0. A missing path is `ENOENT`. `sync.fs` has it too. `rm` removes a whole tree in one kernel call (on the OPFS root, one recursive removal and one metadata delete: 50,000 files take about 3 s in Chrome, where `rm -r` takes about 25 s) with the result of a file-by-file removal: symlinks inside the tree are removed, never followed; a tree holding a protected path is refused with `EROFS` and nothing is removed; a mount inside the tree is emptied and its mount point answers `EBUSY`, while the rest is removed; under `users`, what the user may remove is removed and the call then fails with the first `EACCES`/`EPERM`; files a process holds open stay readable to it;
+- **`fs.watch(path, options?, onEvent)`** resolves with `{ close() }` ([#1031](https://github.com/ai-ecoverse/slicc-kernel/issues/1031)). `sync.fs.watch` returns the watcher directly and is in place when it returns, so it sees every change made after the call. This is the shape for Node's synchronous `fs.watch`.
+  - **What it reports:** a file reports its own changes. A directory reports its direct entries, or with `{ recursive: true }`, everything below it.
+  - **Events:** each one is `{ type, filename }`, in the order the operations happened.
+    - `'rename'`: an entry appeared or went away (create, `mkdir`, `unlink`, `rm`, both names of a `rename`, `link`, `symlink`).
+    - `'change'`: an existing entry's data or metadata changed (a write, `truncate`, `chmod`, `chown`, `utimes`). A write that creates a file gives `'rename'` and then `'change'`, as on Linux.
+    - `filename` is the entry's name relative to the watched directory (`sub/a.txt` when recursive), or the file's basename for a file watch.
+  - **Overflow:** a watch holds 1,000 events between reads. Beyond that, the rest are dropped, and `{ overflow: true }` follows the ones kept.
+  - **The watched path itself:** when it is removed or renamed away (or an ancestor is), the watch gets one `'rename'` with its own name, then `{ ended: true }`, and ends. `close()` is safe at any time and idempotent, and nothing is delivered after it returns.
+  - **Errors at watch time:** a path the program may not read (under `users`) is `EACCES`, and one that doesn't exist is `ENOENT`. Permission is checked first, so a path under a directory the program can't search is `EACCES` whether or not it exists. A process holds at most 8,192 watches; past that, `ENOSPC`.
+  - **Permissions per event:** under `users`, a program only hears about paths it may reach. An event about `P` below the watched directory is delivered only if the program's user can search every directory down to `P`'s parent and read that parent, as Node's recursive watch would need in order to add a watch there. The check runs when the program takes the events, so another user's `0700` directory stays silent until it's opened up. A consequence is that events inside a directory that is gone by the time the program takes them are dropped: after `rm -r sub` the program sees `rename sub` but not `sub/a`. A watcher should rescan on a directory's `rename`, as Node users do anyway.
+  - **Who counts as a writer:** every process in the kernel, the embedder (`kernel.writeFile` and the like) and the mounts that report changes. A `hostfs` change from the host comes as `'change'`, since the host doesn't say which kind it was.
+  - **Not reported:** another kernel's changes on the same origin (another tab), as inotify on a shared file system doesn't see other hosts.
+  - **Lifetime:** a watch ends with its process and doesn't keep the program alive.
+  - **The older watches** (`kernel.watch`, a client's `fs.watch` with `{ paths }`) are unchanged.
 - `/dev`, in `open`, `fs` and their `sync` forms, as a WASI or Emscripten program sees it, with the same modes and owners as under `users`: `null`, `zero`, `full`, `random`, `urandom` and `tty` (character devices, `0666`, root's), `stdin`, `stdout` and `stderr` (links to `/proc/self/fd/0`, `1`, `2`), `fd` (a link to `/proc/self/fd`, so `/dev/fd/N` is descriptor N) and the kernel's terminals `/dev/ttyN` and `/dev/pts/N` (with users on, owned by the session's user or the master's opener, `0620`). `/dev/shm` is the kernel's shared tmpfs (see [Mounts](#mounts)), read and written like any other mount; `/dev/ptmx` isn't there. `stat` through `/dev/stdin`, `/dev/stdout` or `/dev/fd/N` describes the program's own descriptor (the file it is redirected to, a pipe, a terminal), `readlink` of `/dev/fd/N` names it (`pipe:[N]` and `socket:[N]` for a pipe or a socket), and a closed descriptor is `ENOENT`. Opening a device gives a kernel descriptor on it; opening `/dev/std*` or `/dev/fd/N` opens the file again with the flags asked for when the descriptor is on a file (as Linux reopens `/proc/self/fd/N`, so `append` appends and `truncate` truncates), and otherwise duplicates the descriptor; `/dev/tty` is the program's controlling terminal (`ENXIO` without one); and `/dev/ttyN` and `/dev/pts/N` are opened by name through the kernel, so a terminal that isn't the user's is `EACCES` under `enforce`. A file on anything but a regular file reads and writes as a stream (the position is ignored) and only in the directions it was opened for (`EBADF` otherwise), its `size()` is 0 and `truncate` is `EINVAL`. `readFile` reads a device or a descriptor to its end, up to 64 MiB, and fails with `EFBIG` past that (where Node's `readFile` throws `ERR_FS_FILE_TOO_LARGE`), so `readFile('/dev/zero')` fails instead of hanging, while a bounded `read` of it works. Other paths pay only a prefix check: they make the same kernel calls as before. Removing a `/dev` entry fails (see [`/dev`](#dev-entries)), and so does a new name directly in `/dev` or `/proc`;
 - `/proc`, in `fs`, `open` and their `sync` forms, the same as a WASI program's (see [`/proc`](#proc)): `stat`, `lstat`, `exists`, `readdir`, `readlink` and `readFile` answer it, and `/proc/self` is the program's own pid. It's read-only, so every change in it is `EROFS`: `writeFile`, `mkdir`, `rm`, `unlink`, `chmod`, a `rename`, `link` or `symlink` into or out of it, and an `open` for writing, creating or truncating. A file opened in it is a snapshot read at the open, with no descriptor (`fd` is `-1`): its `read` and `size` answer from the snapshot until it's closed, and `write` and `truncate` are `EBADF`. Other paths pay only a prefix check;
 - `signals`: `on(signal, handler)` catches a signal (by number or as `'SIGINT'`), `ignore(signal)` ignores it and `reset(signal)` restores its default action. A call blocked in a read or write is restarted after a handler runs; signals without a handler keep their default actions, so an uncaught `SIGINT` ends the program with 130 and `SIGKILL` always does;
@@ -1073,7 +1087,7 @@ Every change is certified in its pull request, before it merges (`cert-review-pr
 
 The tools in `tools/cert-review/`:
 
-- **delta** (`delta.mjs`): lists the pull requests merged between the two tags (their merge commits, plus `pr` for a planted branch). Each gets its conventional-commit kind (`fix`, `feat`, `perf` and `revert` are behaviour changes) and the integration test files and titles it adds or changes. The titles are read from the pull request's patch: the added `test(…)` lines and the hunk headers git puts above changed lines. Escapes are decoded as JavaScript does. A title git cut short matches as a prefix, and each `${…}` in a template-literal title matches anything there, so `` `a forked child of a ${kind} WASIX program…` `` matches the rows it ran as. A title made only of placeholders is skipped.
+- **delta** (`delta.mjs`): lists the pull requests merged between the two tags (their merge commits, plus `pr` for a planted branch). Each is a behaviour change **by the paths it changes**, with the same rule the plan uses (`behaviourFiles`: `src/`, `build.mjs`, `package.json` and its lock, the build and publish workflows, the reviewer…), whatever its title says (#1036 and #1041 were titled "A2 …"), and it gets its conventional-commit kind and the integration test files and titles it adds or changes. Every behaviour change with tests gets its NEGATIVE: its tests run on the previous tree. A `fix` must fail there (`no-negative` otherwise); any other kind is `negative` or `passes`. A behaviour change whose NEGATIVE has no result (`prev-not-run`), or whose changed tests the delta can't name (`no-titles`), makes the record INCOMPLETE. The delta names the test around every changed line: a title on the `test(` line or the line after it (as biome wraps a long one), a template literal, a title in the context lines above the change, and, when the hunk header shows only `test(`, the title read from the file at the merge commit. A pull request that changes only `package.json` and `package-lock.json`, and in `package.json` only the versions in `dependencies`, `devDependencies` and `optionalDependencies` (delta.mjs compares the file before and after its merge), is decided `manifest` with no test gap: it passed the required `cert-review` in the merge queue, as identical dist or with a full review, so the release line doesn't repeat it. A scripts, exports or new-dependency change stays a behaviour change, with `no-test` when it has no tests. The titles are read from the pull request's patch: the added `test(…)` lines and the hunk headers git puts above changed lines. Escapes are decoded as JavaScript does. A title git cut short matches as a prefix, and each `${…}` in a template-literal title matches anything there, so `` `a forked child of a ${kind} WASIX program…` `` matches the rows it ran as. A title made only of placeholders is skipped.
 - **suite** (`suite.mjs`, `reporter.mjs`) runs on the bench pool, without secrets. It takes the tag's tree with its own dependencies and Chromium, and replaces `dist/` with the **published npm tarball** (for a planted branch, its own `npm pack`). The test command runs in a session of its own (`detached`), and `suite.mjs` notes a `SIGINT` (`ignored` in its summary) instead of dying of it. That way a stray signal to the step's process group can't cut the run short, while a `SIGTERM` (a real cancel) still ends it. The log is written as the run goes, and a `SIGTERM` still writes the summary with the results so far (`exit: 'signal SIGTERM'`). A run that left only its `.jsonl` (the runner was lost) is read from that, as `exit: 'no summary'`. The NEGATIVE step runs even when the release suite's step failed. Before it reports, `suite.mjs` re-runs once just the test files that left no result (no rows, a cancelled row, or a file-level failure, such as a lost process), with a second `node --test` over those files, and merges their results (`retried`, `firstExit`, `unfinished` in the summary). That holds for the release suite and for each NEGATIVE run. A fix whose test passes on its baseline stays `no-negative`.
   - The candidate job runs the pull request's whole `test/integration/` suite on its packed build.
   - The base job runs `main`'s own suite on `main`'s packed build, then the NEGATIVE (#861): `main`'s tree, with all of the pull request's `test/**` changes applied (test files, helpers and fixtures), on `main`'s build. So a fix in `tools/` fails there just as a fix in `src/` does. A test file that fails to load on `main` (a module or export that only the pull request adds) leaves no result for its titles, which is `prev-not-run`, never a NEGATIVE.
@@ -1091,7 +1105,7 @@ The tools in `tools/cert-review/`:
 - **record** (`record.mjs`), in code, with read-only permissions:
   - It re-downloads the tarball and checks `dist.integrity` (sha512) and the sha256, the SLSA v1 provenance (the tarball is its subject; `release.yml`, `refs/heads/main`, a GitHub-hosted builder; commit = `gitHead` = the tag), `npm audit signatures`, and that the commit is on `main`. A problem there, a `compat-crash`, or a planted build is a FAIL whatever the review says.
   - It adds the **known issues as of the release**: every issue labelled `known-issue` (open or closed) and every one in `known.json`, unless it was fixed before the release. An issue in another repository, whether listed or named by the reviewer, counts only while it is open. That holds when `known.json`'s `fixedIn` names an earlier or equal version, or the merged pull request that closed it is an ancestor of the tag, or it was closed (with no closing pull request) before the release commit. An issue closed as not planned or as a duplicate is dropped.
-  - The line is `certified @ai-ecoverse/slicc-kernel@<v> sha256=<…> (ci: <run>; known: …)`. Any test gaps from the findings (`no-test`, `no-negative`, `prev-not-run`, `no-titles`, `not-run`) are appended in code as `test gaps: #<pr> <kind>`, so a fix without a NEGATIVE is never certified silently.
+  - The line is `certified @ai-ecoverse/slicc-kernel@<v> sha256=<…> (ci: <run>; known: …)`. Any test gaps from the findings (`no-test`, `no-negative`, `no-titles`, `not-run`) are appended in code as `test gaps: #<pr> <kind>`, so a fix without a NEGATIVE is never certified silently.
 - **verify** (`verify.mjs`) is the `release / verify on npm` job above.
 
 ### Certification in the pull request (`cert-review`)

package/dist/kernel-worker.js

@@ -4028,7 +4028,12 @@ function openPipe(capacity) {
         }
       },
       close: () => pipe.closeRead(),
-      poll: () => ({ readable: pipe.readReady, writable: false, hangup: pipe.writersGone }),
+      poll: () => ({
+        readable: pipe.readReady,
+        writable: false,
+        hangup: pipe.writersGone,
+        nread: pipe.buffered
+      }),
       changed: (signal) => pipe.changed(signal),
       identity: pipe
     }),
@@ -4816,7 +4821,8 @@ var KernelSocket = class _KernelSocket {
       readable: this.readShut || rx.readReady,
       writable: this.writeShut || tx.writeReady,
       hangup: rx.writersGone && tx.readersGone,
-      rdhup: rx.writersGone
+      rdhup: rx.writersGone,
+      nread: this.readShut ? 0 : rx.buffered
     };
   }
   changed(signal) {
@@ -4876,8 +4882,8 @@ var KernelSocket = class _KernelSocket {
     if (this.state !== "open") throw new KernelError("EINVAL");
     if (addr.family !== this.domain) throw new KernelError("EAFNOSUPPORT");
     this.failed = void 0;
-    const route = viaUplink && addr.family === "inet" ? this.net.uplinkFor(addr.host) : void 0;
-    if (route) return this.dial(addr, route);
+    const route2 = viaUplink && addr.family === "inet" ? this.net.uplinkFor(addr.host) : void 0;
+    if (route2) return this.dial(addr, route2);
     const target = this.net.target(addr, name2);
     if (!this.local) {
       if (addr.family === "inet") {
@@ -4933,9 +4939,9 @@ var KernelSocket = class _KernelSocket {
     }
   }
   switch;
-  connectSecure(addr, route, secure2) {
+  connectSecure(addr, route2, secure2) {
     if (this.state !== "open") throw new KernelError("EISCONN");
-    return this.dial(addr, route, secure2);
+    return this.dial(addr, route2, secure2);
   }
   upgradeSecure(make) {
     if (this.state !== "connected") throw new KernelError("ENOTCONN");
@@ -4943,7 +4949,7 @@ var KernelSocket = class _KernelSocket {
     if (this.switch.upgraded || this.writeShut || this.readShut) throw new KernelError("EINVAL");
     return this.switch.upgrade(make);
   }
-  dial(addr, route, secure2) {
+  dial(addr, route2, secure2) {
     this.state = "connecting";
     const abort = new AbortController();
     this.dialing = abort;
@@ -4951,13 +4957,13 @@ var KernelSocket = class _KernelSocket {
     const timer = setTimeout(() => {
       timedOut = true;
       abort.abort(new KernelError("ETIMEDOUT"));
-    }, route.timeoutMs ?? DIAL_TIMEOUT_MS);
+    }, route2.timeoutMs ?? DIAL_TIMEOUT_MS);
     const abandoned = new Promise((_, reject) => {
       abort.signal.addEventListener("abort", () => reject(abort.signal.reason), { once: true });
     });
     const { host, port } = addr;
     const dialled = new Promise(
-      (resolve2) => resolve2(route.uplink.dial({ network: "tcp", host, port, signal: abort.signal }))
+      (resolve2) => resolve2(route2.uplink.dial({ network: "tcp", host, port, signal: abort.signal }))
     );
     dialled.then(
       (conn) => abort.signal.aborted && conn.close(),
@@ -5106,14 +5112,14 @@ var LoopbackNet = class {
     if (!this.origins) throw new KernelError("ENETUNREACH");
     void this.origins(conn, origin).catch(() => conn.close());
   }
-  useUplink(route) {
-    this.route = route;
+  useUplink(route2) {
+    this.route = route2;
   }
   tlsClient;
   uplinkFor(host) {
-    const route = this.route;
-    if (!route) return void 0;
-    return this.destination(host) === "uplink" ? route : void 0;
+    const route2 = this.route;
+    if (!route2) return void 0;
+    return this.destination(host) === "uplink" ? route2 : void 0;
   }
   destination(host) {
     return (this.route?.routes ?? LOCAL_ONLY).classify(host);
@@ -6626,7 +6632,7 @@ function satisfies(version, range2) {
 }
 
 // src/version.ts
-var KERNEL_VERSION = true ? "1.124.13" : "0.0.0-dev";
+var KERNEL_VERSION = true ? "1.125.0" : "0.0.0-dev";
 var OS_RELEASE = "6.0.0-slicc";
 function procVersion() {
   return `Linux version ${OS_RELEASE} (slicc-kernel ${KERNEL_VERSION}) #1 SMP PREEMPT_DYNAMIC
@@ -9419,6 +9425,8 @@ async function physicalPathAsync(fs, path) {
 }
 
 // src/fs/watch.ts
+var WATCH_NOTES_LIMIT = 1e3;
+var baseOf2 = (path) => path.slice(path.lastIndexOf("/") + 1);
 var WATCH_BATCH_LIMIT = 1e3;
 var under3 = (path, dir) => dir === "/" || path.startsWith(`${dir}/`);
 var parentOf6 = (path) => path.slice(0, path.lastIndexOf("/")) || "/";
@@ -9428,8 +9436,39 @@ function touches(watcher, changed) {
   );
 }
 var REALS_KEPT = 4096;
+function noted(watch, note) {
+  if (watch.ended) return;
+  if ("ended" in note) {
+    watch.notes.push(note);
+    watch.ended = true;
+    watch.wake?.();
+    return;
+  }
+  if (watch.overflowed) return;
+  if (watch.notes.length >= WATCH_NOTES_LIMIT) {
+    watch.overflowed = true;
+    watch.notes.push({ overflow: true });
+  } else watch.notes.push(note);
+  watch.wake?.();
+}
+function route(watch, type, path) {
+  for (const root of watch.roots) if (routed(watch, root, type, path)) return;
+}
+function routed(watch, root, type, path) {
+  if (path === root || type === "rename" && root !== "/" && under3(root, path)) {
+    noted(watch, { type, filename: baseOf2(root) });
+    if (type === "rename") noted(watch, { ended: true });
+    return true;
+  }
+  if (parentOf6(path) === root) noted(watch, { type, filename: baseOf2(path) });
+  else if (watch.recursive && under3(path, root)) {
+    noted(watch, { type, filename: path.slice(root === "/" ? 1 : root.length + 1) });
+  } else return false;
+  return true;
+}
 var FsWatchers = class {
   watchers = /* @__PURE__ */ new Set();
+  typed = /* @__PURE__ */ new Set();
   taps = [];
   reals = /* @__PURE__ */ new Map();
   reshapes = [];
@@ -9456,7 +9495,65 @@ var FsWatchers = class {
       this.watchers.delete(watcher);
     };
   }
+  typedWatch(root, recursive, alias) {
+    const main = normalizePath(root);
+    const other = alias === void 0 ? main : normalizePath(alias);
+    const watch = {
+      roots: other === main ? [main] : [main, other],
+      recursive,
+      notes: [],
+      overflowed: false,
+      ended: false,
+      wake: void 0
+    };
+    this.typed.add(watch);
+    const close = () => {
+      this.typed.delete(watch);
+      watch.ended = true;
+      watch.wake?.();
+    };
+    return {
+      close,
+      next: async (signal) => {
+        while (watch.notes.length === 0 && !watch.ended && !signal.aborted) {
+          await new Promise((resolve2) => {
+            const done4 = () => {
+              watch.wake = void 0;
+              signal.removeEventListener("abort", done4);
+              resolve2();
+            };
+            watch.wake = done4;
+            signal.addEventListener("abort", done4, { once: true });
+          });
+        }
+        const notes = watch.notes.splice(0);
+        watch.overflowed = false;
+        if (watch.ended) this.typed.delete(watch);
+        return notes.length === 0 && watch.ended ? [{ ended: true }] : notes;
+      }
+    };
+  }
+  covers(path) {
+    for (const watch of this.typed) {
+      for (const root of watch.roots) {
+        if (path === root || parentOf6(path) === root || watch.recursive && under3(path, root))
+          return true;
+      }
+    }
+    return false;
+  }
+  emit(type, paths) {
+    if (this.typed.size === 0) return;
+    for (const path of paths) {
+      const at = normalizePath(path);
+      for (const watch of [...this.typed]) route(watch, type, at);
+    }
+  }
   changed(...paths) {
+    this.report(paths);
+    this.emit("change", paths);
+  }
+  report(paths) {
     for (const tap of this.taps) tap(paths);
     for (const watcher of this.watchers) {
       for (const path of paths) {
@@ -9476,11 +9573,15 @@ var FsWatchers = class {
     watcher.notify(paths.length > WATCH_BATCH_LIMIT ? { overflow: true } : { paths });
   }
   wrap(fs) {
-    const after = (run2, changed) => async (...args) => {
+    const after = (run2, changed, type) => async (...args) => {
+      let done4 = false;
       try {
         await run2(...args);
+        done4 = true;
       } finally {
-        this.changed(...changed(...args));
+        const paths = changed(...args);
+        this.report(paths);
+        if (done4) this.emit(type, paths);
       }
     };
     const reals = this.reals;
@@ -9499,15 +9600,21 @@ var FsWatchers = class {
       reals.set(at, real);
       return real;
     };
-    const content = (run2) => async (...args) => {
+    const content = (run2, types) => async (...args) => {
+      const at = normalizePath(args[0]);
+      const fresh2 = this.covers(at) && !await fs.exists(at).catch(() => true);
+      let done4 = false;
       try {
         await run2(...args);
+        done4 = true;
       } finally {
-        const at = normalizePath(args[0]);
         const real = await realOf(at);
-        this.changed(...real === at ? [at] : [at, real]);
+        const paths = real === at ? [at] : [at, real];
+        this.report(paths);
+        if (done4) for (const type of types(fresh2)) this.emit(type, paths);
       }
     };
+    const written2 = (fresh2) => fresh2 ? ["rename", "change"] : ["change"];
     const reshaping = (run2) => async (...args) => {
       this.reshaped();
       try {
@@ -9517,8 +9624,8 @@ var FsWatchers = class {
       }
     };
     const overrides = {
-      writeFile: content(fs.writeFile.bind(fs)),
-      ...fs.createExclusive ? { createExclusive: content(fs.createExclusive.bind(fs)) } : {},
+      writeFile: content(fs.writeFile.bind(fs), written2),
+      ...fs.createExclusive ? { createExclusive: content(fs.createExclusive.bind(fs), () => ["rename"]) } : {},
       mkdir: async (path, options) => {
         const created3 = [];
         if (options?.recursive) {
@@ -9528,33 +9635,39 @@ var FsWatchers = class {
             if (created3.length > 0 || !await fs.exists(ancestor)) created3.push(ancestor);
           }
         }
+        const fresh2 = !options?.recursive || !(this.covers(path) && await fs.exists(path));
+        let done4 = false;
         try {
           await fs.mkdir(path, options);
+          done4 = true;
         } finally {
-          this.changed(...created3, path);
+          this.report([...created3, path]);
+          if (done4) this.emit("rename", fresh2 ? [...created3, path] : created3);
         }
       },
-      rm: reshaping(after(fs.rm.bind(fs), (path) => [path])),
-      rename: reshaping(after(fs.rename.bind(fs), (from, to) => [from, to])),
+      rm: reshaping(after(fs.rm.bind(fs), (path) => [path], "rename")),
+      rename: reshaping(after(fs.rename.bind(fs), (from, to) => [from, to], "rename")),
       link: reshaping(
         after(
           (from, to, follow2) => fs.link(from, to, follow2),
-          (_from, to) => [to]
+          (_from, to) => [to],
+          "rename"
         )
       ),
-      symlink: reshaping(after(fs.symlink.bind(fs), (_target, path) => [path])),
-      chmod: after(fs.chmod.bind(fs), (path) => [path]),
-      ...fs.chown ? { chown: after(fs.chown.bind(fs), (path) => [path]) } : {},
-      utimes: after(fs.utimes.bind(fs), (path) => [path]),
+      symlink: reshaping(after(fs.symlink.bind(fs), (_target, path) => [path], "rename")),
+      chmod: after(fs.chmod.bind(fs), (path) => [path], "change"),
+      ...fs.chown ? { chown: after(fs.chown.bind(fs), (path) => [path], "change") } : {},
+      utimes: after(fs.utimes.bind(fs), (path) => [path], "change"),
       lutimes: after(
         (path, atime, mtime) => lutimesOf(fs, path, atime, mtime),
-        (path) => [path]
+        (path) => [path],
+        "change"
       )
     };
     const ranged2 = rangedOps(fs);
     if (ranged2) {
-      overrides.pwrite = content(ranged2.pwrite);
-      overrides.truncate = content(ranged2.truncate);
+      overrides.pwrite = content(ranged2.pwrite, () => ["change"]);
+      overrides.truncate = content(ranged2.truncate, () => ["change"]);
     }
     return new Proxy(fs, {
       get(target, key, receiver) {
@@ -10162,7 +10275,8 @@ var FifoTable = class {
       poll: () => ({
         readable: reads && pipe.readReady,
         writable: writes && pipe.writeReady,
-        hangup: reads ? pipe.writersGone : pipe.readersGone
+        hangup: reads ? pipe.writersGone : pipe.readersGone,
+        ...reads ? { nread: pipe.buffered } : {}
       }),
       changed: (signal) => pipe.changed(signal)
     });
@@ -10561,8 +10675,8 @@ var MountTable = class {
         ...error ? { error } : {}
       })
     );
-    const noted = [...this.notes.values()].filter((note) => !this.mounts.has(note.target));
-    return [...mounted, ...noted.map((note) => ({ ...note, options: { ...note.options } }))];
+    const noted2 = [...this.notes.values()].filter((note) => !this.mounts.has(note.target));
+    return [...mounted, ...noted2.map((note) => ({ ...note, options: { ...note.options } }))];
   }
   listed() {
     return this.list().filter((entry) => !this.system.has(entry.target));
@@ -16031,7 +16145,8 @@ var KernelTty = class {
       poll: () => ({
         readable: this.readable.length > 0 || this.hungUp,
         writable: true,
-        hangup: this.hungUp
+        hangup: this.hungUp,
+        nread: this.readable.reduce((n, chunk2) => n + (chunk2?.length ?? 0), 0)
       }),
       changed: (signal) => this.changed(signal),
       close: () => {
@@ -16227,7 +16342,8 @@ var PtyPair = class {
       poll: () => ({
         readable: this.queue.length > 0 || this.slaveGone,
         writable: true,
-        hangup: this.slaveGone
+        hangup: this.slaveGone,
+        nread: this.queue.reduce((n, chunk2) => n + chunk2.length, 0)
       }),
       changed: (signal) => this.changed(signal),
       close: () => this.closeMaster(),
@@ -16509,13 +16625,17 @@ async function runChild(req, deps) {
 // src/kernel/select.ts
 function ready(fds, read, write) {
   const hangup = /* @__PURE__ */ new Set();
+  const nread = {};
   const pick = (list, dir) => list.filter((fd) => {
     const state = pollFile(fds.get(fd).file);
     if (state.hangup) hangup.add(fd);
-    return state[dir] || state.hangup;
+    const picked = state[dir] || state.hangup;
+    if (picked && dir === "readable" && state.nread !== void 0) nread[fd] = state.nread;
+    return picked;
   });
   const out = { read: pick(read, "readable"), write: pick(write, "writable") };
   if (hangup.size > 0) out.hangup = [...hangup];
+  if (Object.keys(nread).length > 0) out.nread = nread;
   return out;
 }
 function interruption(signal) {
@@ -17510,14 +17630,14 @@ async function connectSecure(proc, socket, host, port, req) {
   const servername = serverName(req.servername || host);
   if (isLoopbackHost(servername) || isLoopbackHost(host)) throw new KernelError("ENOTSUP");
   const address = await uplinkAddress(proc, host);
-  const route = proc.net.uplinkFor(address);
-  if (!route)
+  const route2 = proc.net.uplinkFor(address);
+  if (!route2)
     throw new KernelError("ENOTSUP", "TLS in the kernel needs a destination the uplink routes");
   const support = supportOf(proc.net);
   let info;
   const { make, abandon } = secure(await prepare(support, req, servername));
   try {
-    await socket.connectSecure({ family: "inet", host: address, port }, route, async (conn) => {
+    await socket.connectSecure({ family: "inet", host: address, port }, route2, async (conn) => {
       info = await conn.upgrade(make);
     });
   } finally {
@@ -18728,6 +18848,65 @@ function vfsFile(fs, opts, nodes) {
   });
 }
 
+// src/kernel/watch-ops.ts
+var WATCH_OPS = ["watch-open", "watch-next", "watch-close"];
+var WATCHING = new Set(WATCH_OPS);
+function isWatchSyscall(req) {
+  return WATCHING.has(req.op);
+}
+var WATCHES_MAX = 8192;
+var parentOf8 = (path) => path.slice(0, path.lastIndexOf("/")) || "/";
+function visibleTo2(watch, root, visible) {
+  return {
+    close: () => watch.close(),
+    next: async (signal) => {
+      const notes = await watch.next(signal);
+      const seen = /* @__PURE__ */ new Map();
+      const shown = await Promise.all(
+        notes.map(async (note) => {
+          if (!("filename" in note) || !note.filename.includes("/")) return true;
+          const dir = parentOf8(`${root === "/" ? "" : root}/${note.filename}`);
+          if (!seen.has(dir)) seen.set(dir, visible(dir));
+          return seen.get(dir);
+        })
+      );
+      return notes.filter((_note, i) => shown[i]);
+    }
+  };
+}
+var ProcessWatches = class {
+  open = /* @__PURE__ */ new Map();
+  nextId = 1;
+  source;
+  constructor(source) {
+    this.source = source;
+  }
+  async syscall(req, cancelled) {
+    if (req.op === "watch-open") {
+      if (!this.source) throw new KernelError("ENOSYS");
+      if (this.open.size >= WATCHES_MAX) throw new KernelError("ENOSPC");
+      const watch2 = await this.source.open(req.path, req.recursive === true);
+      const id2 = this.nextId++;
+      this.open.set(id2, watch2);
+      return { ok: true, kind: "json", json: id2 };
+    }
+    const watch = this.open.get(req.id);
+    if (req.op === "watch-close") {
+      watch?.close();
+      this.open.delete(req.id);
+      return { ok: true, kind: "void" };
+    }
+    if (!watch) return { ok: true, kind: "json", json: [{ ended: true }] };
+    const notes = await watch.next(cancelled);
+    if (notes.some((note) => "ended" in note)) this.open.delete(req.id);
+    return { ok: true, kind: "json", json: notes };
+  }
+  closeAll() {
+    for (const watch of this.open.values()) watch.close();
+    this.open.clear();
+  }
+};
+
 // src/kernel/process.ts
 function aborted(signal) {
   return new Promise((_, reject) => {
@@ -18854,7 +19033,8 @@ var SYSCALL_OPS = /* @__PURE__ */ new Set([
   ...SEM_OPS,
   ...HTTP_OPS,
   ...PTY_OPS,
-  ...HOST_OPS
+  ...HOST_OPS,
+  ...WATCH_OPS
 ]);
 function isWasmSyscall(req) {
   const op = req.op;
@@ -18906,6 +19086,7 @@ function timeLeft(req, started) {
 }
 var WasmProcess = class {
   exited = false;
+  watches;
   children;
   deathSignals = /* @__PURE__ */ new Map();
   caught = 0;
@@ -18936,6 +19117,7 @@ var WasmProcess = class {
     this.pid = pid;
     this.fds = fds;
     this.options = options;
+    this.watches = new ProcessWatches(options.watches);
     this.inherited = options.ignored ?? 0;
     this.umask = options.umask ?? DEFAULT_UMASK2;
     this.cred = copyCred(options.cred ?? ROOT);
@@ -19193,6 +19375,7 @@ var WasmProcess = class {
         });
       }
       if (isHttpSyscall(req)) return await this.httpSyscall(req);
+      if (isWatchSyscall(req)) return await this.watches.syscall(req, cancelled);
       if (isHostSyscall(req)) {
         return await hostSyscall(req, {
           pid: this.pid,
@@ -20333,6 +20516,7 @@ var WasmProcess = class {
     this.options.locks?.release(this.pid);
     for (const owner of this.lockOwners) this.options.locks?.release(owner);
     this.asyncOps.close();
+    this.watches.closeAll();
     for (const [target, sig] of this.deathSignals) this.sendDeath(target, sig);
     this.deathSignals.clear();
     for (const pid of this.children.pids()) this.options.onReap?.(pid);
@@ -20594,6 +20778,7 @@ function processOptions(opts, header3, hooks, created3) {
     locks: opts.locks,
     fifos: opts.fifos,
     ...opts.sems ? { sems: opts.sems } : {},
+    watches: opts.watches,
     onReap: opts.onReap,
     resolver: opts.resolver,
     ...notifiers(header3),
@@ -25811,6 +25996,7 @@ var Launcher = class {
       locks: this.locks,
       fifos: this.fifos,
       sems: this.sems,
+      watches: this.watchSource(pid),
       resolver: this.resolver,
       onReap: (child) => this.reaped(child, pid),
       ...req.fork ? { fork: req.fork } : {},
@@ -26354,6 +26540,23 @@ var Launcher = class {
       mounts: this.mounts.list().map((entry) => entry.target).filter((target) => this.mounts.mounted(target) !== void 0)
     });
   }
+  watchSource(pid) {
+    return {
+      open: async (path, recursive) => {
+        const at = normalizePath(path);
+        const g = this.execGuard(this.credOf(pid), pid);
+        if (g) await readable(g, "watch", at);
+        const st = await this.fs.stat(at);
+        const real = await this.fs.realpath?.(at, true).catch(() => at) ?? at;
+        const watch = this.watchers.typedWatch(real, recursive && st.isDirectory, at);
+        if (!g || g.cred.euid === 0) return watch;
+        return visibleTo2(watch, real, async (dir) => {
+          const walked = await access(g.fs, g.cred, dir, R_OK | X_OK, { directory: true });
+          return walked.denied === void 0 && walked.missing !== true;
+        });
+      }
+    };
+  }
   watchFiles(paths, notify) {
     this.fileWatches ??= new FileWatches(this.watchers, this.rootFs);
     return this.fileWatches.watch(paths, notify);