bare-operating-system/docs/architecture/POSIX_DECLARED_PROFILE.md

# Declared POSIX-like profile (Bare OS)

This document is the **normative contract** for how closely the stock Bare OS kernel and userland follow [IEEE Std 1003.1-2017](https://pubs.opengroup.org/onlinepubs/9699919799/) / Open Group **Issue 7**. It is **not** a conformance claim: the runtime is a **single JavaScript address space** over **Hyperdrive-backed VFS** with **simulated** pipelines and **no `fork`**.

**Identifiers** (mirrored under `/proc/bare_os_features` and related JSON) are defined in [`packages/bare-os-protocol/lib/bare-os-posix-profile.js`](../../packages/bare-os-protocol/lib/bare-os-posix-profile.js):

| Constant | Value |
| -------- | ----- |
| `BARE_OS_POSIX_PROFILE_VERSION` | `1.0.19` |
| `BARE_OS_POSIX_PROFILE_ID` | `bare-os-posix-like` |
| `BARE_OS_POSIX_PROFILE_REFERENCE` | Open Group Issue 7 index URL |

**Narrative catalogs:** [handbook ch.9 — POSIX-style utilities](../../handbook/09-posix-utilities-shell-and-vfs.md) · [environment / POSIX appendix §14a](../reference/environment-and-posix-appendix.md#14a-posix-userland-appendix-implemented-vs-gaps).

---

## 1. System interfaces (XBD/XSH-style expectations)

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/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**

- Real **preemptive multiprocessing**, **fork**, **exec** of binaries, or **kernel threads** in the guest.
- **FIFO special files** on Hyperdrive; **`mkfifo`** creates **in-memory** IPC under `/run/bare-os/ipc/` (see booter IPC module).
- Bit-identical **errno** values to Linux for every edge case; scripts should rely on **documented** exit codes and proc JSON.

---

## 2. Shell (XCU `sh`)

Stock shell is **line-oriented** with bounded **`if`**, **`while`**, **`for`**, optional **`case`**, lists (`;`, `&&`, `||`), and **`|`** pipelines (**simulated**, not kernel pipes). **Default pipeline exit status** follows POSIX **last stage**; set **`BARE_OS_SHELL_PIPEFAIL=1`** for bash-like **first failing stage** status. See handbook ch.9 §3 and §8.5.

Optional **`BARE_OS_SHELL_POSIX_MODE=1`** enables **subshell-free** grouped lists **`( compound-list )`** as a single statement (same logical session).

**Unsupported (by design):** forked subshells / process-level isolation, full POSIX grammar, job control with real background process groups, here-documents beyond documented limits.

Optional **`BARE_OS_SHELL_UNTIL=1`**: **`until`** compound loops (inverted test vs **`while`**) with the same iteration cap as **`BARE_OS_SHELL_LOOP_MAX`**.

---

## 3. Utilities (XCU)

**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.

**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).

---

## 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.

**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.

**`/.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.

---

## 5. Signals and exit statuses

Signal names accepted by **`kill`** and shell builtins follow POSIX **names** where listed in proc JSON. **`ctx.bareOsSendSignal`** and **`/bin/kill`** also accept a **negative** numeric operand as a logical **process group id** (**`pgid`**) for **shell background jobs** (active rows only; **`kill -0 -pgid`** checks existence). **Exit codes** for pipelines and **`timeout`** follow documented stock behavior (see handbook and booter tests).

---

## 6. Profile evolution

Bump **`BARE_OS_POSIX_PROFILE_VERSION`** in `bare-os-protocol` when **intentional** utility, shell, VFS, or proc-contract behavior changes. Update this file, handbook ch.9, and §14a in the same change set.

**1.0.19** — **`ctx.bareOsRenice`** stores **logical nice** on **`process_table.json`** rows (no host scheduler). `**socketMsgSurface` schema 6** documents **`iovecSemantics`** and **`recvmsg`** **`susv4Refs`**. **`disk.os`** `**replication_operator_sketch` schema 8** adds **`hyperdhtAddressSketch`** (**`BARE_OS_HYPERDHT_ADDRESS_JSON`**) and `**pkgIndexSurface` / `pkg_index_get` schema 2** echoes. **`corestoreSnapshotUxHint` schema 4** adds **`recommendedWorkflow`**. `**security_posture` schema 7** adds **`replicationOperatorSketchCrossRef`**. `**pear_stage_pointer` schema 2** links **`pear-runtime-updater`**. Boot **`/proc/bare_os/boot_budget_summary.json`** may merge **`replicationLiveCoalesced`** after kernel handoff. Shell **`wait`** uses background job **`lastExitCode`**. Swarm **`BARE_OS_SWARM_ATTEMPT_BURST_PER_SEC`** caps connection attempts per rolling second (policy engine). Dynamic `**getconf`/`sysconf**` adds **`_SC_MONOTONIC_CLOCK_RES`** ( **`bare-hrtime`** when present), trace/timer negated constants, **`vault_save`** audit includes **`pathcapTrustedKeyCount`**.

**1.0.18** — **`awk`**: **`getline var < path`** reads from the guest VFS with per-path line caching; POSIX math builtins **`atan2`**, **`cos`**, **`sin`**, **`exp`**, **`log`**, **`sqrt`**; unary **`-`**; **`substr(s, start)`** two-argument suffix form; async evaluation path in the engine for I/O-capable builtins. Man page and handbook §7 updated. **`expr`**: POSIX **`: `** match-length operator (ECMA **`RegExp`** body under **`^(?:…)`**). **`test`**: **`FILE1 -nt FILE2`**, **`FILE1 -ot FILE2`**, **`FILE1 -ef FILE2`** using **`mtimeMs`** and optional `**dev`/`ino`**.

**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_*`**).