Updates to MD
This commit is contained in:
Raven Scott
@@ -18,7 +18,7 @@ This document is the **normative contract** for how closely the stock Bare OS ke
|
||||
|
||||
Bare OS does **not** expose a C ABI. The following **observability contracts** stand in for “system calls”:
|
||||
|
||||
- **`/proc/bare_os/syscalls.json`** — Declares **fd model**, **signal model**, **errno hints**, **operation detail**, **`posixXsh`**, **`socketMsgSurface`**, and related adjuncts (schema **11** in stock builds; see [`docs/reference/posix-compliance-matrix.json`](../reference/posix-compliance-matrix.json)). **`ops`** lists invocable **`ctx.bareOsSyscall`** names (**`posix_fadvise`** as a simulated no-op hint; **`clock_gettime`** for REALTIME / MONOTONIC sketches alongside **`nanosleep`**); **`opsDetail`** also carries **POSIX.1 XSH** logical names (**`open`**, **`close`**, **`read`**, **`write`**, **`readv`**, **`writev`**, **`getsockopt`**, **`setsockopt`**, **`lseek`**, **`pipe`**, **`dup`**, **`dup2`**, **`fcntl`**, **`poll`**, **`select`**, **`umask`**, **`fsync`**, **`fdatasync`**, **`posix_fadvise`**, and **socket family** probes) with **`posixAlignment`** (**`simulated`**, **`partial`**, **`ENOTSUP`**) and **`mapsTo`** for traceability; stable **`susv4Refs`** string tokens (for example **`XSH/open`**) support audit cross-walks. The **`posixXsh`** object summarizes those XSH names (via **`bareOsPosixXshOpsCsv()`**); schema **3** pairs with syscall proc **11**. **`socketMsgSurface`** (schema **5**) documents **`sendmsg`** / **`recvmsg`** on the bridge: bounded **iovec** flattening for datagram and stream paths; binary ancillary control on **`sendmsg`** remains **`ENOTSUP`** with structured rejection metadata unless **`BARE_OS_POSIX_SOCKET_SCM_RIGHTS=1`**, in which case JSON-shaped **`cmsgs`** may request logical **`scmRightsLocalDup`** on **SOCK_STREAM** and **SOCK_DGRAM** bridge fds (guest logical FD duplication — not host **`SCM_RIGHTS`**); **`recvmsg`** reports **`controllen: 0`** on the receive path. **`fcntl`** supports **`F_GETFL`** / **`F_SETFL`** (Linux-shaped **`O_APPEND`** **`0x400`**, **`O_NONBLOCK`** **`0x800`**) and **cooperative advisory locks** via **`F_GETLK`** / **`F_SETLK`** / **`F_SETLKW`** using **`args.path`** (absolute) or **`args.fd`** whose logical target is an absolute path; contended **`F_SETLK`** returns **`EAGAIN`**. **`F_SETLKW`** also returns **`EAGAIN`** by default; with **`BARE_OS_POSIX_FCNTL_BLOCKING_WAIT`**, waiters are queued **FIFO per lock path** until the lock is free or **`BARE_OS_FCNTL_LOCK_WAIT_MS_MAX`** elapses (**`ETIMEDOUT`**; default **30000** ms, max **300000**). There is **no** cross-path global fairness and **no** host deadlock detection. Unknown FDs yield **`EBADF`**. **`readv`** / **`writev`** perform bounded scatter/gather on **`BARE_OS_POSIX_FD_SIM`** pipe read/write ends. **`poll`** / **`select`** share the same logical FD readiness probe when **`BARE_OS_POSIX_FD_SIM`** is enabled; with **`BARE_OS_POSIX_SOCKET_FD_BRIDGE=1`**, bridged **datagram** fds participate (**`SOCK_DGRAM`** via **`bareDgram`** when merged) with bounded **`recv`** / **`recvfrom`** queues (**`BARE_OS_POSIX_DGRAM_RECVQ_MAX`**, **`BARE_OS_POSIX_DGRAM_RECV_BLOCK_MS_MAX`**); passive **`SOCK_STREAM`** uses `**bind`/`listen`/`accept**` when **`bareTcp.Server`** is available. **Socket-shaped** syscalls default to **`ENOSYS`** / **`ENOTSUP`**; with **`BARE_OS_POSIX_SOCKET_FD_BRIDGE=1`**, **`socket`** + **`connect`** may use **`ctx.bare.bareTcp.Socket`** (**`SOCK_STREAM`**) or **`bareDgram`** (**`SOCK_DGRAM`**) when merged. The stock booter **caches** this JSON until warm read-cache invalidation.
|
||||
- **`/proc/bare_os/syscalls.json`** — Declares **fd model**, **signal model**, **errno hints**, **operation detail**, **`posixXsh`**, **`socketMsgSurface`**, and related adjuncts (schema **11** in stock builds; see [`docs/reference/posix-compliance-matrix.json`](../reference/posix-compliance-matrix.json)). **`ops`** lists invocable **`ctx.bareOsSyscall`** names (**`posix_fadvise`** as a simulated no-op hint; **`clock_gettime`** for REALTIME / MONOTONIC sketches alongside **`nanosleep`**); **`opsDetail`** also carries **POSIX.1 XSH** logical names (**`open`**, **`close`**, **`read`**, **`write`**, **`readv`**, **`writev`**, **`getsockopt`**, **`setsockopt`**, **`lseek`**, **`pipe`**, **`dup`**, **`dup2`**, **`fcntl`**, **`poll`**, **`select`**, **`umask`**, **`fsync`**, **`fdatasync`**, **`posix_fadvise`**, and **socket family** probes) with **`posixAlignment`** (**`simulated`**, **`partial`**, **`ENOTSUP`**) and **`mapsTo`** for traceability; stable **`susv4Refs`** string tokens (for example **`XSH/open`**) support audit cross-walks. The **`posixXsh`** object summarizes those XSH names (via `**bareOsPosixXshOpsCsv()**`); schema **3** pairs with syscall proc **11**. **`socketMsgSurface`** (schema **5**) documents **`sendmsg`** / **`recvmsg`** on the bridge: bounded **iovec** flattening for datagram and stream paths; binary ancillary control on **`sendmsg`** remains **`ENOTSUP`** with structured rejection metadata unless **`BARE_OS_POSIX_SOCKET_SCM_RIGHTS=1`**, in which case JSON-shaped **`cmsgs`** may request logical **`scmRightsLocalDup`** on **SOCK_STREAM** and **SOCK_DGRAM** bridge fds (guest logical FD duplication — not host **`SCM_RIGHTS`**); **`recvmsg`** reports **`controllen: 0`** on the receive path. **`fcntl`** supports **`F_GETFL`** / **`F_SETFL`** (Linux-shaped **`O_APPEND`** **`0x400`**, **`O_NONBLOCK`** **`0x800`**) and **cooperative advisory locks** via **`F_GETLK`** / **`F_SETLK`** / **`F_SETLKW`** using **`args.path`** (absolute) or **`args.fd`** whose logical target is an absolute path; contended **`F_SETLK`** returns **`EAGAIN`**. **`F_SETLKW`** also returns **`EAGAIN`** by default; with **`BARE_OS_POSIX_FCNTL_BLOCKING_WAIT`**, waiters are queued **FIFO per lock path** until the lock is free or **`BARE_OS_FCNTL_LOCK_WAIT_MS_MAX`** elapses (**`ETIMEDOUT`**; default **30000** ms, max **300000**). There is **no** cross-path global fairness and **no** host deadlock detection. Unknown FDs yield **`EBADF`**. **`readv`** / **`writev`** perform bounded scatter/gather on **`BARE_OS_POSIX_FD_SIM`** pipe read/write ends. **`poll`** / **`select`** share the same logical FD readiness probe when **`BARE_OS_POSIX_FD_SIM`** is enabled; with `**BARE_OS_POSIX_SOCKET_FD_BRIDGE=1**`, bridged **datagram** fds participate (**`SOCK_DGRAM`** via **`bareDgram`** when merged) with bounded **`recv`** / **`recvfrom`** queues (**`BARE_OS_POSIX_DGRAM_RECVQ_MAX`**, **`BARE_OS_POSIX_DGRAM_RECV_BLOCK_MS_MAX`**); passive **`SOCK_STREAM`** uses `**bind`/`listen`/`accept**` when **`bareTcp.Server`** is available. **Socket-shaped** syscalls default to **`ENOSYS`** / **`ENOTSUP`**; with **`BARE_OS_POSIX_SOCKET_FD_BRIDGE=1`**, **`socket`** + **`connect`** may use **`ctx.bare.bareTcp.Socket`** (**`SOCK_STREAM`**) or **`bareDgram`** (**`SOCK_DGRAM`**) when merged. The stock booter **caches** this JSON until warm read-cache invalidation.
|
||||
- **`/proc/bare_os/process_table.json`** — **schema 9** — **PGID** / **SID**-style fields, **`parentName`** (from **`ppid`**), **signal routing**, initd binding, per-row **`nice`** (`**-20`..`19**`, via **`ctx.bareOsRenice`**), **`accountingSource`** on metrics fields, optional per-row accounting (**`threads`**, **`cpuMs*`**, I/O counters, **`replicationHint`**) for the **logical** process table (not host PIDs). Companion **`/proc/bare_os/process_maps.json`** (**schema 2**, model **`bare-os-logical-v1`**) and **`/proc/bare_os/process_threads.json`** (**schema 2**) describe **logical** layouts (not Linux **`/proc/pid/maps`**).
|
||||
|
||||
**Explicit non-goals**
|
||||
@@ -45,7 +45,7 @@ Optional **`BARE_OS_SHELL_UNTIL=1`**: **`until`** compound loops (inverted test
|
||||
|
||||
**Authoritative command list:** [`packages/bare-os-coreutils/lib/commands.mjs`](../../packages/bare-os-coreutils/lib/commands.mjs).
|
||||
|
||||
Utilities are **Issue 7–inspired** JavaScript implementations. High-traffic tools (**`grep`**, **`sed`**, **`awk`**, **`xargs`**, **`expr`**, **`basenc`**) carry **bounded** resource limits via environment variables (see environment appendix). **`getconf`** exposes a **fixed** name table for symbolic constants; when the booter exposes **`ctx.bareOsGetconfSysconf`**, **`getconf -v`** / **`_SC_*`** names may resolve **dynamic** values documented in the environment appendix.
|
||||
Utilities are **Issue 7–inspired** JavaScript implementations. High-traffic tools (**`grep`**, **`sed`**, **`awk`**, **`xargs`**, **`expr`**, **`basenc`**) carry **bounded** resource limits via environment variables (see environment appendix). **`getconf`** exposes a **fixed** name table for symbolic constants; when the booter exposes **`ctx.bareOsGetconfSysconf`**, **`getconf -v`** / `**_SC_*`** names may resolve **dynamic** values documented in the environment appendix.
|
||||
|
||||
**Delegation:** Some basenames (**`curl`**, **`wget`**, **`git`**, **`systemctl`**, …) run through the **host delegate registry** before `PATH` resolution; `/bin` may contain **parity shims** that should not execute in a correctly configured session (see handbook ch.6).
|
||||
|
||||
@@ -53,11 +53,11 @@ Utilities are **Issue 7–inspired** JavaScript implementations. High-traffic to
|
||||
|
||||
## 4. VFS and paths
|
||||
|
||||
Two logical drives (**system** + **personal**) form one namespace; **`.bareos_empty`** marks empty directories. Synthetic trees: **`/proc`**, **`/sys`**, **`/run`**, **`/dev`**, session **`/tmp`**. **`/dev/shm/<name>`** holds **in-memory** named byte segments (not host **`shm_open`**); names match **`^[a-zA-Z0-9._-]{1,128}$`**. Optional **`/mirror/aux*`** for auxiliary read-only drives.
|
||||
Two logical drives (**system** + **personal**) form one namespace; **`.bareos_empty`** marks empty directories. Synthetic trees: **`/proc`**, **`/sys`**, **`/run`**, **`/dev`**, session **`/tmp`**. `**/dev/shm/<name>`** holds **in-memory** named byte segments (not host **`shm_open`**); names match `**^[a-zA-Z0-9._-]{1,128}$**`. Optional `**/mirror/aux*`** for auxiliary read-only drives.
|
||||
|
||||
**Rename:** No atomic cross-drive **`rename`**; **`mv`** implements copy + remove where needed (handbook ch.9). For a **single regular file** to a non-directory destination, **`/bin/mv`** stages bytes under a unique **`.bare-os-mv-tmp.*`** name in the **resolved destination directory** (same folder as the target after **`vfs.resolveLogical`**), writes the final name, removes the staging entry, then unlinks the source so a failed final write leaves the source path intact (best-effort staging cleanup).
|
||||
**Rename:** No atomic cross-drive **`rename`**; **`mv`** implements copy + remove where needed (handbook ch.9). For a **single regular file** to a non-directory destination, **`/bin/mv`** stages bytes under a unique `**.bare-os-mv-tmp.*`** name in the **resolved destination directory** (same folder as the target after **`vfs.resolveLogical`**), writes the final name, removes the staging entry, then unlinks the source so a failed final write leaves the source path intact (best-effort staging cleanup).
|
||||
|
||||
**`pathconf` / `getconf`:** Live **`getconf _PC_* /path`** delegates to **`ctx.bareOsPathconf`**. Union read prefixes (**`BARE_OS_VFS_UNION_PREFIXES`**) and read-only **mirror** paths (**`/mirror/…`**) adjust documented **`_PC_NO_TRUNC`** and **`_PC_CHOWN_RESTRICTED`** hints (not a certifiable pathconf implementation). Paths under the personal **account prefix** (**`BARE_OS_PERSONAL_ACCT_PREFIX`**, default **`/.bare-os/acct/`**) keep **`_PC_NO_TRUNC: 1`** so writable account-scoped data keeps stable truncation semantics even when union overlays would otherwise advertise **`0`** for overlay targets.
|
||||
**`pathconf` / `getconf`:** Live **`getconf _PC_* /path`** delegates to **`ctx.bareOsPathconf`**. Union read prefixes (**`BARE_OS_VFS_UNION_PREFIXES`**) and read-only **mirror** paths (`**/mirror/…**`) adjust documented **`_PC_NO_TRUNC`** and **`_PC_CHOWN_RESTRICTED`** hints (not a certifiable pathconf implementation). Paths under the personal **account prefix** (**`BARE_OS_PERSONAL_ACCT_PREFIX`**, default **`/.bare-os/acct/`**) keep **`_PC_NO_TRUNC: 1`** so writable account-scoped data keeps stable truncation semantics even when union overlays would otherwise advertise **`0`** for overlay targets.
|
||||
|
||||
**`/.bare` on the personal drive (acct prefix):** When **`BARE_OS_PERSONAL_ACCT_PREFIX`** is enabled, logical **`/.bare/`**** (including **`/.bare/account`** and **`/.bare/vault/`**) is stored under **`/.bare-os/acct/<session>/.bare/…`** on the personal Hyperdrive so each session subtree holds its own identity material; logical paths stay **`/.bare/…`** for utilities and **`ACCOUNT_PATH`**. Legacy blobs at the personal root **`/.bare/account`** remain visible when the prefix is **off** (existing installs); operators migrate with documented personal-root tools when enabling the prefix.
|
||||
|
||||
@@ -79,4 +79,4 @@ Bump **`BARE_OS_POSIX_PROFILE_VERSION`** in `bare-os-protocol` when **intentiona
|
||||
|
||||
**1.0.17** — Syscalls proc **schema 11** (**`susv4Refs`** on **`opsDetail`**, `**posixXsh` schema 3**); **`ctx`** API **1.53.0**; **`disk.os`** `**replication_operator_sketch` schema 7** (**`corestoreSnapshotUxHint`**, **`pkgIndexSurface`**, **`bare_os.pkg_index_get`** + **`BARE_OS_PKG_INDEX_PATH`**); optional **Protomux cap channel** (**`BARE_OS_PROTOMUX_CAP_CHANNEL`**, feature bit); **`metrics_live.replicationLive`** collaboration hints + optional **`BARE_OS_COLLAB_SESSION_NDJSON`**; **`security_posture`** blind-relay posture sketch; **`ctx.bareOsVerifyPathCapabilityEnvelopeTrusted`** + **`BARE_OS_PATH_CAPABILITY_TRUSTED_PUBKEYS_HEX`**; **`/proc/bare_os/boot_budget_summary.json`**; warm-cache adaptive **jitter** (**`BARE_OS_VFS_WARM_REPL_ADAPTIVE_JITTER_PCT`**); shell unset-only default expansion (**`BARE_OS_SHELL_POSIX_UNSET_ONLY_DEFAULT`**); **`pathcap-verify --trusted`**; **`pkg-swarm-index`** `**list` / `get`** against drive manifest or HRPC.
|
||||
|
||||
**1.0.16** — Stock **`pathcap-verify`**, **`pkg-swarm-index`**, optional **path-capability** VFS gate (**`BARE_OS_PATH_CAPABILITY_*`**), **`ctx.bareOsVerifyPathCapabilityEnvelope`**, `**disk.os` path manifest + `bare_os.search_local` hrpc**, **`metrics_live.replicationLive` schema 4** (**`warmReplAdaptive`**), boot budget transaction `**bootBudgetSchemaVersion` 2** (**`bootBudgetViolations`**), Wasm **`env.bare_os_ctx_api_version_peek`**, optional **`BARE_OS_POSIX_SOCKET_CONNECT_TIMEOUT_MS`** on bridge TCP **`connect`**, **`BARE_OS_SAVEVAULT_PRESNAPSHOT_HINT`** host event, optional **`BARE_OS_RC_PROPOSAL_MULTISIG_STRICT`** + **`rc.proposals/enabled`** audit rows (**`rc.proposal.multisig_*`**).
|
||||
**1.0.16** — Stock **`pathcap-verify`**, **`pkg-swarm-index`**, optional **path-capability** VFS gate (`**BARE_OS_PATH_CAPABILITY_***`), **`ctx.bareOsVerifyPathCapabilityEnvelope`**, `**disk.os` path manifest + `bare_os.search_local` hrpc**, **`metrics_live.replicationLive` schema 4** (**`warmReplAdaptive`**), boot budget transaction `**bootBudgetSchemaVersion` 2** (**`bootBudgetViolations`**), Wasm **`env.bare_os_ctx_api_version_peek`**, optional **`BARE_OS_POSIX_SOCKET_CONNECT_TIMEOUT_MS`** on bridge TCP **`connect`**, **`BARE_OS_SAVEVAULT_PRESNAPSHOT_HINT`** host event, optional **`BARE_OS_RC_PROPOSAL_MULTISIG_STRICT`** + **`rc.proposals/enabled`** audit rows (`**rc.proposal.multisig_*`**).
|
||||
|
||||
Reference in New Issue
Block a user