Updates

2026-04-05 04:33:14 -04:00
parent 4af98ef97b
commit 904ad7e7fd
48 changed files with 1905 additions and 219 deletions
@@ -0,0 +1,44 @@
+# POSIX syscall facade map (`ctx.bareOsSyscall` / `/proc/bare_os/syscalls.json`)
+
+[Reference index →](README.md)
+
+This document maps the **guest-visible** syscall-shaped surface to POSIX.1-2017 XSH-style names and to Bare OS implementation paths. The **machine-readable** source of truth is built at runtime into **`/proc/bare_os/syscalls.json`** (schema **8**) via [`buildBareOsSyscallsProcJson`](../../packages/bare-os-booter/lib/bare-os-syscalls-proc-json.js).
+
+## Source modules
+
+| Module | Role |
+| --- | --- |
+| [`bare-os-syscall-ops.js`](../../packages/bare-os-booter/lib/bare-os-syscall-ops.js) | **`BARE_OS_SYSCALL_OPS_DETAIL`** (stock **`ctx.bareOsSyscall`** op names), **`BARE_OS_POSIX_XSH_OPS_DETAIL`** (XSH-style names for traceability), **`BARE_OS_SYSCALL_OPS_DETAIL_FULL`** (concatenation for **`opsDetail`**) |
+| [`bare-os-syscalls-proc-json.js`](../../packages/bare-os-booter/lib/bare-os-syscalls-proc-json.js) | Proc JSON assembly: **`ops`**, **`opsDetail`**, **`posixXsh`**, **`socketMsgSurface`**, **`errnoHints`**, **`fdModel`** |
+| [`bare-os-posix-signals.js`](../../packages/bare-os-booter/lib/bare-os-posix-signals.js) | Signal name table surfaced in proc JSON |
+| [`bare-os-posix-errno.js`](../../packages/bare-os-booter/lib/bare-os-posix-errno.js) | **`errnoHints`** / errno alignment rows |
+| [`packages/bare-os-booter/index.js`](../../packages/bare-os-booter/index.js) | **`ctx.bareOsSyscall`** dispatcher implementing the stock ops |
+
+## Stock `ctx.bareOsSyscall` operations
+
+These names appear in **`BARE_OS_STOCK_SYSCALL_OPS`** and are invoked as **`ctx.bareOsSyscall('name', payload)`**. Each row in **`BARE_OS_SYSCALL_OPS_DETAIL`** includes **`category`** (**`fs`**, **`proc`**, **`ipc`**, **`signal`**, **`vfs_meta`**) and **`stability`** (**`stable`** / **`experimental`**).
+
+**Filesystem-shaped:** `readFile`, `writeFile`, `readdir`, `mkdir`, `stat`, `unlink`, `chmod`, `chdir`, `getcwd`, `readlink`, `symlink`, `exists`, `lstat`, `rmdir`, `rename`, `link`, `access`, `utimes`, `truncate`, `ftruncate`, `fsync`, `fdatasync`, `pathconf`, `fcntl`, `posixPoll`, `select`, `umask`, and experimental **`readv`**, **`writev`** (posix-pipe facades).
+
+**VFS meta (experimental):** `mount`, `umount`.
+
+**Signals:** `kill` (synthetic / guest process table — not host PIDs).
+
+**IPC / socket-shaped (mostly experimental):** `socket`, `bind`, `listen`, `accept`, `connect`, `send`, `recv`, `sendmsg`, `recvmsg`, `shutdown`, `getsockopt`, `setsockopt`, plus **`mq_open`**, **`mq_send`**, **`mq_receive`**. Socket rows document **`posixAlignment`** (**`ENOTSUP`**, **`partial`**) and map to **`ctx.bare`** TCP/UDP modules, Hyperswarm, or optional **`BARE_OS_POSIX_SOCKET_FD_BRIDGE`** behavior — see [`syscall-socket-contract.md`](syscall-socket-contract.md).
+
+## POSIX XSH logical names (`posixXsh`)
+
+**`BARE_OS_POSIX_XSH_OPS_DETAIL`** lists Issue 7–style names (**`open`**, **`close`**, **`read`**, **`write`**, **`pipe`**, **`dup`**, **`dup2`**, **`fcntl`**, **`poll`**, **`select`**, **`lseek`**, **`nanosleep`**, **`umask`**, socket family aliases, etc.) with **`posixAlignment`**: **`simulated`**, **`partial`**, or **`ENOTSUP`**. They are **not** separate **`ctx.bareOsSyscall`** op strings; they document how guest utilities and WASM shims should reason about behavior. The CSV of names is exposed as **`posixXsh.namesCsv`** in proc JSON.
+
+## Intentionally absent or non-kernel
+
+- **Real host `fork`, host PID namespaces, real kernel `waitpid`** — The process table is synthetic; see **`/proc/bare_os/process_table.json`**.
+- **Kernel TCP/UDP as host FDs** — Unless the socket FD bridge env is enabled, socket ops return **ENOSYS**-shaped results; P2P networking uses Hyperswarm, Hyperdrive replication, and **`ctx.bare`** stream modules instead of POSIX sockets as the primary transport.
+- **`lseek` on arbitrary guest FDs** — Marked **`ENOTSUP`** / **`ESPIPE`**-hinted: no universal byte cursor across VFS logical FDs.
+
+## Related documentation
+
+- [`environment-and-posix-appendix.md`](environment-and-posix-appendix.md) — errno vocabulary, **`BARE_OS_POSIX_*`** env vars
+- [`POSIX_DECLARED_PROFILE.md`](../architecture/POSIX_DECLARED_PROFILE.md) — declared profile version
+- [`posix-compliance-matrix.json`](posix-compliance-matrix.json) — CI matrix
+- [`conformance-matrix.md`](conformance-matrix.md) — narrative conformance