feat(booter): cache syscalls proc JSON, net tuning hints, /dev/shm unlink, POSIX/docs sync
- Cache /proc/bare_os/syscalls.json until warm read cache clear; invalidate with vfs.bareOsClearWarmReadCaches - net_summary: optional udxTuning / hyperswarmTuning from BARE_OS_UDX_* / BARE_OS_HYPERSWARM_* JSON - Metric: operator.corestore_snapshot_hint on bareOsCorestoreSnapshotHint - pathconf: _PC_NAME_MAX 128 under /dev/shm - vfs: fix unlink for /dev/shm segments; add roundtrip test - protocol: bareOsIsAllowedSeedRpcMethodShort + tests - getconf: _POSIX_SHARED_MEMORY_OBJECTS, _POSIX_MESSAGE_PASSING, _POSIX_ASYNCHRONOUS_IO + test - microbench: syscall suite (syscalls proc JSON stringify) - JSON Schema bare-os-syscalls.schema.json schemaVersion 5; posix-conformance-matrix ops = getconf - Docs: blind-relay security note, compat matrix (1.38.0 / 1.0.4), handbook 04/09, appendix, OTA note - Pear: document host coupling in compatibility-matrix (no pear-runtime manifest entry)
This commit is contained in:
Raven Scott
@@ -6,7 +6,7 @@ This document is the **normative contract** for how closely the stock Bare OS ke
|
||||
|
||||
| Constant | Value |
|
||||
| -------- | ----- |
|
||||
| `BARE_OS_POSIX_PROFILE_VERSION` | `1.0.3` |
|
||||
| `BARE_OS_POSIX_PROFILE_VERSION` | `1.0.4` |
|
||||
| `BARE_OS_POSIX_PROFILE_ID` | `bare-os-posix-like` |
|
||||
| `BARE_OS_POSIX_PROFILE_REFERENCE` | Open Group Issue 7 index URL |
|
||||
|
||||
@@ -18,8 +18,8 @@ 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**, and **operation detail** (schema version in-file). **`ops`** lists invocable **`ctx.bareOsSyscall`** names; **`opsDetail`** also carries **POSIX.1 XSH** logical names (**`open`**, **`close`**, **`read`**, **`write`**, **`lseek`**, **`pipe`**, **`dup`**, **`dup2`**, **`fcntl`**, **`poll`**) with **`posixAlignment`** (**`simulated`**, **`partial`**, **`ENOTSUP`**) and **`mapsTo`** for traceability. The **`posixXsh`** object summarizes those XSH names. **`fcntl`** is implemented as **`ctx.bareOsSyscall('fcntl', { fd, cmd, arg })`** with **`F_GETFL`** / **`F_SETFL`** (Linux-shaped **`O_APPEND`** **`0x400`**, **`O_NONBLOCK`** **`0x800`**). **`poll`** is approximated by **`ctx.bareOsPosixPoll`** / **`posixPoll`** on simulated pipe FDs. Unsupported operations are listed with **ENOTSUP** / **ENOSYS**-style semantics where applicable.
|
||||
- **`/proc/bare_os/process_table.json`** — **PGID** / **SID**-style fields, **signal routing**, and initd binding for the **logical** process table (not host PIDs).
|
||||
- **`/proc/bare_os/syscalls.json`** — Declares **fd model**, **signal model**, **errno hints**, and **operation detail** (schema version in-file). **`ops`** lists invocable **`ctx.bareOsSyscall`** names; **`opsDetail`** also carries **POSIX.1 XSH** logical names (**`open`**, **`close`**, **`read`**, **`write`**, **`lseek`**, **`pipe`**, **`dup`**, **`dup2`**, **`fcntl`**, **`poll`**, **`select`**, and **socket family** probes) with **`posixAlignment`** (**`simulated`**, **`partial`**, **`ENOTSUP`**) and **`mapsTo`** for traceability. The **`posixXsh`** object summarizes those XSH names. **`fcntl`** is implemented as **`ctx.bareOsSyscall('fcntl', { fd, cmd, arg })`** with **`F_GETFL`** / **`F_SETFL`** (Linux-shaped **`O_APPEND`** **`0x400`**, **`O_NONBLOCK`** **`0x800`**); unknown FDs yield **`EBADF`**. **`poll`** / **`select`** share the same logical FD readiness probe (**`ctx.bareOsPosixPoll`** / **`posixPoll`** / **`select`** syscall facade) on simulated pipe FDs when **`BARE_OS_POSIX_FD_SIM`** is enabled. **Socket-shaped** syscalls (**`socket`**, **`bind`**, **`listen`**, **`accept`**, **`connect`**, **`send`**, **`recv`**, **`shutdown`**) return a documented **`ENOSYS`** / **`ENOTSUP`**-aligned probe (guests use Hyperswarm / **`ctx.bare` TCP/UDP modules instead). The stock booter **caches** this JSON until warm read-cache invalidation. Unsupported operations are listed with **ENOTSUP** / **ENOSYS**-style semantics where applicable.
|
||||
- **`/proc/bare_os/process_table.json`** — **PGID** / **SID**-style fields, **`parentName`** (from **`ppid`**), **signal routing**, and initd binding for the **logical** process table (not host PIDs).
|
||||
|
||||
**Explicit non-goals**
|
||||
|
||||
@@ -49,7 +49,7 @@ 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`**. 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).
|
||||
|
||||
|
||||
@@ -61,4 +61,4 @@ Re-run a full-repo scan before each release and append a dated section here when
|
||||
| **Protocol doc** | [docs/reference/package-bare-os-protocol.md](../../docs/reference/package-bare-os-protocol.md): **`msgRead`** described as wire shape for Protomux message 0, not an incomplete placeholder. |
|
||||
| **P2 man placeholder row** | Remains for ongoing man ↔ behavior drift; re-triage per release. |
|
||||
| **Protomux / Hyperswarm lock contract** | Booter test + [`packages/bare-os-booter/fixtures/protomux-hyperswarm-lock.json`](../../packages/bare-os-booter/fixtures/protomux-hyperswarm-lock.json) pin resolved **`package-lock.json`** versions; bump both when upgrading the wire stack. |
|
||||
| **Bundle marker / throw allowlists** | Root **`pretest`** still runs **`verify-bundle-markers.mjs`** and **`verify-bundle-throws.mjs`** after **`bare-os-bare-libs`** build; shrinking entries requires a coordinated upstream bundle pass and ticketed deltas — do not delete allowlist lines without regenerating bundles and recording residual risk here. |
|
||||
| **Bundle marker / throw allowlists** | **`bundle-marker-allowlist.json`** and **`bundle-throw-allowlist.json`** are **empty**. Upstream stream-base-class and ICO encode **`Error`** strings are rewritten during **`sanitize-bare-bundles.mjs`** (invoked from **`bare-os-bare-libs`** build) so **`verify-bundle-throws`** passes with no per-file exemptions. Re-run **`npm run build -w bare-os-bare-libs`** after manifest/catalog changes. |
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"generatedAt": "2026-04-05T03:18:48.758Z",
|
||||
"generatedAt": "2026-04-05T03:36:27.146Z",
|
||||
"normativeManifest": "packages/bare-os-booter/lib/bare-module-manifest.json",
|
||||
"buildTool": "packages/bare-os-bare-libs/build.mjs",
|
||||
"bundles": [
|
||||
@@ -158,7 +158,7 @@
|
||||
"ctxKey": "bareDev",
|
||||
"package": "bare-dev",
|
||||
"path": "/lib/bare/bundles/bareDev.js",
|
||||
"bytes": 2203809
|
||||
"bytes": 2203887
|
||||
},
|
||||
{
|
||||
"ctxKey": "bareDgram",
|
||||
@@ -284,7 +284,7 @@
|
||||
"ctxKey": "bareIco",
|
||||
"package": "bare-ico",
|
||||
"path": "/lib/bare/bundles/bareIco.js",
|
||||
"bytes": 3595
|
||||
"bytes": 3602
|
||||
},
|
||||
{
|
||||
"ctxKey": "bareImageResample",
|
||||
@@ -350,7 +350,7 @@
|
||||
"ctxKey": "bareMedia",
|
||||
"package": "bare-media",
|
||||
"path": "/lib/bare/bundles/bareMedia.js",
|
||||
"bytes": 635604
|
||||
"bytes": 635611
|
||||
},
|
||||
{
|
||||
"ctxKey": "bareModule",
|
||||
|
||||
@@ -1,21 +1,5 @@
|
||||
{
|
||||
"schemaVersion": 2,
|
||||
"description": "Vendored bundles that intentionally contain new Error(...) messages with 'not implemented' / abstract-base-class semantics from upstream Bare/Node-compat streams. Re-run after bare-os-bare-libs rebuild; trim when upstream removes throws.",
|
||||
"entries": [
|
||||
{
|
||||
"bundleFile": "bareDev.js",
|
||||
"rationale": "Duplex/transform stream base classes from upstream use _read/_write/_transform and abstract readByte/seek errors when subclasses omit hooks — standard Node stream pattern, not Bare OS stubs.",
|
||||
"triggerCondition": "Subclass Readable/Writable/Duplex without overriding _read/_write/_transform; RandomAccessReader subclasses without readByte/seek"
|
||||
},
|
||||
{
|
||||
"bundleFile": "bareMedia.js",
|
||||
"rationale": "Image pipeline defers ICO encoder path; throws only when ICO output is requested.",
|
||||
"triggerCondition": "ICO encoding write path when encoder not shipped in bundle"
|
||||
},
|
||||
{
|
||||
"bundleFile": "bareIco.js",
|
||||
"rationale": "ICO encode entrypoint matches bareMedia deferral; decode works, encode is unsupported until upstream implements.",
|
||||
"triggerCondition": "ICO encode API invoked"
|
||||
}
|
||||
]
|
||||
"description": "Vendored bundles exempt from verify-bundle-throws (Error messages matching stub/incomplete patterns). Target: empty — upstream stream/ICO messages are normalized in scripts/sanitize-bare-bundles.mjs during bare-os-bare-libs build.",
|
||||
"entries": []
|
||||
}
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -19,6 +19,7 @@ Bare OS aligns with the **Holepunch** toolchain for shipping JavaScript as **Bar
|
||||
- **System image**: `kernel/` is staged to the **system Hyperdrive** by **`bare-os-seeder`**; the booter never falls back to a git checkout for production boot.
|
||||
- **Ctx / API semver**: bump **`BARE_OS_CTX_API_VERSION`** when guest-visible `ctx` behavior changes; record it in [compatibility-matrix.md](../reference/compatibility-matrix.md).
|
||||
- **Offline / LKG**: document **`BARE_OS_OFFLINE_LKG_BOOT`** and related env in [environment appendix](../reference/environment-and-posix-appendix.md).
|
||||
- **Warm cache + proc**: **`bareOsVfsBatchWrite`** clears **`/bin`** / **`/lib/bare`** warm read caches and increments **`vfs.warm_read_cache_invalidate_batch`**; the same path clears the **cached** **`/proc/bare_os/syscalls.json`** text so replication swaps cannot serve stale syscall metadata. **`ctx.bareOsCorestoreSnapshotHint()`** increments **`operator.corestore_snapshot_hint`** for operator dashboards.
|
||||
|
||||
## Reproducibility checklist
|
||||
|
||||
|
||||
@@ -14,7 +14,7 @@ Single place to compare **protocol**, **booter `ctx` API**, **feature-bit docume
|
||||
|
||||
## Version artifacts
|
||||
|
||||
**`bareOsCtxApiVersion`** (current stock: **`1.37.0`**) — Defined in [`packages/bare-os-booter/lib/bare-os-ctx-api.js`](../../packages/bare-os-booter/lib/bare-os-ctx-api.js). This is the semver string for the documented **`ctx`** contract; bump it when stable guest-visible behavior changes.
|
||||
**`bareOsCtxApiVersion`** (current stock: **`1.38.0`**) — Defined in [`packages/bare-os-booter/lib/bare-os-ctx-api.js`](../../packages/bare-os-booter/lib/bare-os-ctx-api.js). This is the semver string for the documented **`ctx`** contract; bump it when stable guest-visible behavior changes.
|
||||
|
||||
**`BARE_OS_KERNEL_FEATURE_BITS_DOC`** (current stock: **`15`**) — Exported from [`packages/bare-os-protocol/lib/kernel-feature-bits.js`](../../packages/bare-os-protocol/lib/kernel-feature-bits.js). It versions the feature-bit documentation and related governance; keep it aligned with [`developer-guide/adr/001-kernel-feature-bits-governance.md`](../../developer-guide/adr/001-kernel-feature-bits-governance.md).
|
||||
|
||||
@@ -24,9 +24,9 @@ Single place to compare **protocol**, **booter `ctx` API**, **feature-bit docume
|
||||
|
||||
**Protocol package** — Workspace version in [`bare-os-protocol` `package.json`](../../packages/bare-os-protocol/package.json). Pair it with seeder and booter releases when you change wire behavior.
|
||||
|
||||
**POSIX-like profile** — **`BARE_OS_POSIX_PROFILE_VERSION`** (**`1.0.0`**) and **`BARE_OS_POSIX_PROFILE_ID`** (**`bare-os-posix-like`**) in [`bare-os-protocol/lib/bare-os-posix-profile.js`](../../packages/bare-os-protocol/lib/bare-os-posix-profile.js). Surfaced under **`/proc/bare_os_features`** as **`capabilitySurface.posixProfile`** and in **`/proc/bare_os/syscalls.json`** (schema **4**).
|
||||
**POSIX-like profile** — **`BARE_OS_POSIX_PROFILE_VERSION`** (**`1.0.4`**) and **`BARE_OS_POSIX_PROFILE_ID`** (**`bare-os-posix-like`**) in [`bare-os-protocol/lib/bare-os-posix-profile.js`](../../packages/bare-os-protocol/lib/bare-os-posix-profile.js). Surfaced under **`/proc/bare_os_features`** as **`capabilitySurface.posixProfile`** and in **`/proc/bare_os/syscalls.json`**.
|
||||
|
||||
**`/proc/bare_os/syscalls.json`** — Schema **4** extends schema **3** with **`fdModel`** (logical FD table pointers) and **`signalModel`** (synthetic signal vocabulary). Schema **3** added **`opsDetail`**, **`errnoHints`**, and **`posixProfile`**. Example payload: [`kernel/etc/bare-os/syscalls.example.json`](../../kernel/etc/bare-os/syscalls.example.json); JSON Schema: [`docs/schemas/bare-os-syscalls.schema.json`](../schemas/bare-os-syscalls.schema.json).
|
||||
**`/proc/bare_os/syscalls.json`** — Schema **5** adds socket-family syscall **probes** (**`ENOSYS`** / **`ENOTSUP`** alignment in **`opsDetail`**), extends **`posixXsh`**, and documents **`fdModel.posixLike.socketFamily`**. Earlier schemas added **`fdModel`**, **`signalModel`**, **`opsDetail`**, **`errnoHints`**, and **`posixProfile`**. The stock booter **caches** the JSON text until **`vfs.bareOsClearWarmReadCaches()`** / **`ctx.bareOsInvalidateWarmReadCaches()`** (same invalidation path as **`/bin`** warm cache). Example payload: [`kernel/etc/bare-os/syscalls.example.json`](../../kernel/etc/bare-os/syscalls.example.json); JSON Schema: [`docs/schemas/bare-os-syscalls.schema.json`](../schemas/bare-os-syscalls.schema.json).
|
||||
|
||||
**Boot policy pins** — [`kernel/etc/bare-os/boot.policy.example.json`](../../kernel/etc/bare-os/boot.policy.example.json) shows **`extensionSignerPinsV3`**, **`extensionSignerPinsV4`**, and **`kernelExtensionHashPins`** for **`kernel.ext.d`** governance, plus semver gates (**`requireCtxApiMin`**, **`requireBooterSemver`**, **`requireProtocolPackageMin`**, …). Keep this file aligned with [`docs/schemas/boot.policy.schema.json`](../schemas/boot.policy.schema.json) when adding fields.
|
||||
|
||||
@@ -36,6 +36,7 @@ Single place to compare **protocol**, **booter `ctx` API**, **feature-bit docume
|
||||
|
||||
- **Seeder** must answer **`bare_os.capabilities`** with **`kernelCapabilityWords`** (wire **v2**, **`kernelCapabilityWireVersion`: 2**) when using a current **`bare-os-protocol`** build. **`BARE_OS_SEED_CAP_STRICT`** requires that object and full stock coverage per semantic key.
|
||||
- **Offline LKG** booters skip the swarm peer wait when **`BARE_OS_OFFLINE_LKG_BOOT=1`** and **`BARE_OS_LKG_SYSTEM_KEY_HEX`** is set; the system drive must already contain **`/boot/init.js`** in Corestore.
|
||||
- **Pear host** — Couple **`pear-runtime`** / **`pear-runtime-updater`** with this tree’s **`bare-os-protocol`** and **`bareOsCtxApiVersion`** (see [PEAR-RUN.md](../../PEAR-RUN.md)); the stock **`bare-module-manifest.json`** does **not** list **`pear-runtime`** because it is not an npm-resolvable guest bundle—hosts wire it via imports and **`BARE_OS_PEAR_RUNTIME_VERSION`** when needed.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
// Auto-generated by scripts/gen-ctx-client-helper.mjs — do not edit by hand.
|
||||
|
||||
/** Canonical `ctx` API semver from `packages/bare-os-booter/lib/bare-os-ctx-api.js`. */
|
||||
export const BARE_OS_CTX_API_CLIENT_VERSION = '1.37.0' as const
|
||||
export const BARE_OS_CTX_API_CLIENT_VERSION = '1.38.0' as const
|
||||
|
||||
/** Relative path to the hand-maintained TypeScript contract (schema source of truth). */
|
||||
export const BARE_OS_CTX_DTS_SOURCE = 'packages/bare-os-booter/lib/bare-os-ctx.d.ts' as const
|
||||
|
||||
@@ -81,6 +81,9 @@ The list below is one **bullet per variable** in the form **name — component
|
||||
- `BARE_OS_VFS_HYPERBLOBS_DEDUP` — Booter / features proc — When **`1`** / **`true`**, surfaces an operator hint under **`/proc/bare_os/features`** that host mirror / hyperblob pipelines may use content-defined chunking; the guest VFS does not enable hyperblobs by itself.
|
||||
- `BARE_OS_XARGS_MAX_PROCS` — **`/bin/xargs`** — Raises the cap for **`-P`** parallelism (still bounded by a hard maximum of **32** and by delegate concurrency when **`runBinCommand`** uses workers); default effective cap **8** when unset.
|
||||
- `BARE_OS_PEER_FIREWALL_E2E_JSON` — Booter / replication proc — Optional operator JSON merged into **`/proc/bare_os/replication`** for peer-firewall end-to-end checks (**invalid JSON yields an error object** in proc).
|
||||
- `BARE_OS_NET_TRANSPORT_STATS_JSON` — Booter — Optional JSON merged into **`/proc/bare_os/net_summary.json`** as **`transport`** (Holepunch UDX / punch outcomes when the host supplies a sketch).
|
||||
- `BARE_OS_UDX_TUNING_JSON` — Booter — Optional JSON surfaced under **`/proc/bare_os/net_summary.json`** as **`udxTuning`** (operator-only; guest does not apply kernel tuning).
|
||||
- `BARE_OS_HYPERSWARM_TUNING_JSON` — Booter — Optional JSON surfaced under **`/proc/bare_os/net_summary.json`** as **`hyperswarmTuning`** (operator-only).
|
||||
- `BARE_OS_PEAR_SECURE_ENCLAVE_JSON` — Booter / security posture — Non-secret JSON pointer for optional Pear secure-enclave key storage hints; treat as opaque unless host policy attests hardware backing (see [vault threat model](vault-threat-model.md)).
|
||||
- `BARE_OS_ACCOUNT_KEY_ROTATION_STATE_JSON` — Booter / security posture — Non-secret JSON for signing continuity across overlapping trust windows during account key rotation (not private keys).
|
||||
- `BARE_OS_TIMER_EVERY_MS_MONOTONIC` — bare-cron / timers — When **`1`** / **`true`**, **`EveryMs=`** timer units may use monotonic scheduling where supported.
|
||||
@@ -172,7 +175,8 @@ The list below is one **bullet per variable** in the form **name — component
|
||||
|
||||
**Normative declared profile:** [POSIX_DECLARED_PROFILE.md](../architecture/POSIX_DECLARED_PROFILE.md) (version **`BARE_OS_POSIX_PROFILE_VERSION`** in `bare-os-protocol`).
|
||||
|
||||
- **VFS** — Two-drive unified paths; **`$HOME`** maps to the personal Hyperdrive; writable mounts under **`/mnt`** when HDMS allows. **`mkdir`/`rmdir`**, **`chmod`** (octal + symbolic subset), **`symlink`/`readlink`**, **`stat`/`lstat`**, **`rm`** recursive, **`watch()`** on Hyperdrive paths (optional host **`BARE_OS_VFS_WATCH=0`** to disable). Synthetic **`/proc`**, **`/sys`**, **`/run`**, **`/dev`** for introspection (quotas JSON, boot JSON, initd snapshot, union policy, seed handshake, virtual registry, etc.). Optional union read overlays (**`BARE_OS_VFS_UNION_PREFIXES`**) with optional write deny (**`BARE_OS_VFS_UNION_WRITE_DENY`**). Empty dirs use **`.bareos_empty`** (same idea as `git-fs-adapter`).
|
||||
- **VFS** — Two-drive unified paths; **`$HOME`** maps to the personal Hyperdrive; writable mounts under **`/mnt`** when HDMS allows. **`mkdir`/`rmdir`**, **`chmod`** (octal + symbolic subset), **`symlink`/`readlink`**, **`stat`/`lstat`**, **`rm`** recursive, **`watch()`** on Hyperdrive paths (optional host **`BARE_OS_VFS_WATCH=0`** to disable). Synthetic **`/proc`**, **`/sys`**, **`/run`**, **`/dev`** for introspection (quotas JSON, boot JSON, initd snapshot, union policy, seed handshake, virtual registry, etc.); **`/dev/shm/<name>`** holds in-memory named segments (**`getconf _POSIX_SHARED_MEMORY_OBJECTS`** is **`1`**). Optional union read overlays (**`BARE_OS_VFS_UNION_PREFIXES`**) with optional write deny (**`BARE_OS_VFS_UNION_WRITE_DENY`**). Empty dirs use **`.bareos_empty`** (same idea as `git-fs-adapter`).
|
||||
- **Proc budget** — Stock booter **caches** **`/proc/bare_os/syscalls.json`** text until **`vfs.bareOsClearWarmReadCaches()`** (shared invalidation with **`/bin`** / **`/lib/bare`** warm read cache, including **`bareOsVfsBatchWrite`** bin/lib puts).
|
||||
- **Shell** — Pipelines, **`;`**, **`&&`** / \*\*` — — `**, redirects, quoting, **`$VAR`**, **`$?`**, optional **`${VAR:-word}`** / **`${VAR#prefix}`** when **`BARE*OS_SHELL_PARAM_EXPANSION=1`**, **`jobs`** / **`fg`** / **`wait`**, optional background **`&`** segments, builtins including bounded **`if`**, **`while`**, **`for`**, **`case`** (caps **`BARE_OS_SHELL_LOOP_MAX`**, **`BARE_OS_SHELL_CASE_MAX_BRANCHES`**). Optional bounded **`$(…)`** when **`BARE_OS_SHELL_CMDSUBST=1`**; optional larger pipeline capture via **`BARE_OS_SHELL_STREAMING`** / **`BARE_OS_SHELL_STREAMING_MULT`**. Branching uses **`ctx.exitCode`**. Bounded pipeline capture (**`BARE_OS_PIPELINE*\*`**, **`ctx.bareOsRuntimeCaps`**); optional boot-snippet allowlist (**`BARE_OS_BOOT_ALLOWLIST`** + **`/etc/bare-os/boot.allow`**). No subshells or full POSIX **`sh`\*\*.
|
||||
- **Ownership** — Display and permission checks use **`UID`/`GID`** and mode bits; **`chown`/`chgrp`** update **`metadata.bareOs`** on the **personal** writable tree (not a multi-user host kernel).
|
||||
- **Utilities** — Tier-1 JS **`/bin`** (**~113** commands; see [§12.10](package-bare-os-coreutils-and-ci.md#1210-package-bare-os-coreutils)): text tools include **`paste`**, **`split`**, **`tac`**, **`rev`**, **`expand`**, **`unexpand`**, **`fold`**, **`fmt`**, **`comm`**, **`cmp`**, **`join`**, **`pr`**, **`yes`** (line-capped via **`BARE_OS_YES_MAX_LINES`** / **`getconf`**), **`shuf`** (capped via **`BARE_OS_SHUF_MAX_LINES`**), **`tsort`**, **`factor`**, **`expr`** (integer-focused subset), **`numfmt`** (**`--to=iec`** / **`--to=si`**). Checksums: **`md5sum`** (bundled MD5), **`sha1sum`**, **`sha256sum`**, **`sha512sum`** (Web Crypto where available), **`sum`**, **`base32`**, **`basenc`** (**`--base16`**). Files: **`truncate`**, **`unlink`**, **`install`**, **`df`** (synthetic Hyperdrive row; **`-h`** human sizes), **`sync`** (no-op), **`timeout`** (wall-clock cap; exit **124** on timeout when **`BARE_OS_FEATURE_ABORT_TIMEOUT`** is advertised). Session stubs: **`arch`**, **`groups`**, **`hostid`**, **`nproc`**, **`uptime`**, **`users`**, **`who`**. Plus earlier parity: **`man`**, **`sed`** (including **`-z`**, **`BARE_OS_SED_NULL_MAX_RECORDS`**), **`awk`**, **`grep`** (**`-r`** with **`--include`/`--exclude`/`--exclude-dir`**, **`BARE_OS_GREP_FILTER_MAX`**), **`cp`** (**`-u`/`-v`/`-p`**), **`mv`**, **`find`** (**`-regex`**, **`-exec`/`-ok`**, **`BARE_OS_FIND_EXEC_MAX`**), **`mktemp`**, **`git-pear`**, **`cksum`**, **`getconf`** (static name table plus live **`vfs.env`** overrides for caps; **`-a`**), **`xargs`** (**`-P`** cap raised via **`BARE_OS_XARGS_MAX_PROCS`**, hard max **32**), **`getfacl`** / **`setfacl`** (POSIX-style ACL **view/edit** against synthetic **`/.bare_acl.json`** sidecars; see handbook ch.9), **`dircolors`**, **`theme`**, **`ls`**, **`uniq`**, **`realpath`**, **`base64`**, **`rm`** **`-d`**, **`stat`** **`%F`**. **`dir`** / **`vdir`** call **`ls`**. Large **`sed`/`awk`** are not byte-identical to GNU on all inputs. **`mkfifo`** → **`/run/bare-os/ipc/`**; optional logical process groups via **`ctx.bareOsIpc.assignProcessGroup`** / **`signalProcessGroup`** (POSIX **`setpgid`** / **`killpg`** analog for IPC routing). Machine-readable per-command POSIX hints: stock **`/etc/bare-os/posix_utilities.json`** (path echoed in **`/proc/bare_os_features`** and **`metrics_live`**). Online help: **`/share/man/man.json`** and **`man`**.
|
||||
|
||||
@@ -10,7 +10,7 @@ Bare OS splits **hand-authored kernel code** from **vendored Holepunch runtime b
|
||||
|--------|--------|--------|
|
||||
| **First-party guest kernel** | [`kernel/init.js`](../../kernel/init.js), [`kernel/lib/boot/`](../../kernel/lib/boot/), [`kernel/lib/init/`](../../kernel/lib/init/), [`kernel/bin/`](../../kernel/bin/) (built from coreutils), [`kernel/etc/`](../../kernel/etc/) | Must not contain `TODO` / `FIXME` / `XXX` / `HACK` / `throw new Error("Not implemented")` as unfinished work. Enforced by [`scripts/verify-runtime-no-incomplete-markers.mjs`](../../scripts/verify-runtime-no-incomplete-markers.mjs) (with configured excludes). |
|
||||
| **Host booter + protocol** | [`packages/bare-os-booter/lib/`](../../packages/bare-os-booter/lib/), [`packages/bare-os-booter/index.js`](../../packages/bare-os-booter/index.js), [`packages/bare-os-protocol/lib/`](../../packages/bare-os-protocol/lib/) | Same as first-party: no `node:` specifiers ([`scripts/verify-bare-imports.mjs`](../../scripts/verify-bare-imports.mjs)); no incomplete markers. Tests under `packages/bare-os-booter/test/` may use `node:` for the host harness. |
|
||||
| **Vendored IIFE bundles** | [`kernel/lib/bare/bundles/*.js`](../../kernel/lib/bare/bundles/) (mirrored in [`packages/bare-os-seeder/kernel/lib/bare/bundles/`](../../packages/bare-os-seeder/kernel/lib/bare/bundles/)) | Produced by [`packages/bare-os-bare-libs`](../../packages/bare-os-bare-libs); upstream Holepunch graphs. Markers and `not implemented` throws are gated by [`docs/audit/bundle-marker-allowlist.json`](../audit/bundle-marker-allowlist.json) and [`docs/audit/bundle-throw-allowlist.json`](../audit/bundle-throw-allowlist.json) until bundles are sanitized or regenerated. **Goal:** shrink both allowlists to empty. |
|
||||
| **Vendored IIFE bundles** | [`kernel/lib/bare/bundles/*.js`](../../kernel/lib/bare/bundles/) (mirrored in [`packages/bare-os-seeder/kernel/lib/bare/bundles/`](../../packages/bare-os-seeder/kernel/lib/bare/bundles/)) | Produced by [`packages/bare-os-bare-libs`](../../packages/bare-os-bare-libs); post-processed by [`scripts/sanitize-bare-bundles.mjs`](../../scripts/sanitize-bare-bundles.mjs). [`docs/audit/bundle-marker-allowlist.json`](../audit/bundle-marker-allowlist.json) and [`docs/audit/bundle-throw-allowlist.json`](../audit/bundle-throw-allowlist.json) are **empty** by policy; CI **`verify-bundle-*`** must pass without exemptions. |
|
||||
| **Maintenance scripts** | [`scripts/*.mjs`](../../scripts/) | May use `node:fs` / `node:path`; not shipped on the Hyperdrive image. |
|
||||
|
||||
**Seeder parity:** [`kernel/`](../../kernel/) and [`packages/bare-os-seeder/kernel/`](../../packages/bare-os-seeder/kernel/) must be byte-identical ([`scripts/verify-kernel-seeder-parity.mjs`](../../scripts/verify-kernel-seeder-parity.mjs)). After editing `kernel/`, sync the seeder tree before commit.
|
||||
|
||||
@@ -4,7 +4,7 @@ Former **DOCUMENTATION.md** §10. [Reference index →](README.md)
|
||||
|
||||
## POSIX profile
|
||||
|
||||
**`bare-os-protocol/lib/bare-os-posix-profile.js`** defines **`BARE_OS_POSIX_PROFILE_VERSION`** (**`1.0.0`**), **`BARE_OS_POSIX_PROFILE_ID`**, and **`BARE_OS_POSIX_PROFILE_REFERENCE`** (Open Group Issue 7 index). Re-exported from the package root. Booter mirrors these values under **`/proc/bare_os_features`** and **`/proc/bare_os/syscalls.json`**.
|
||||
**`bare-os-protocol/lib/bare-os-posix-profile.js`** defines **`BARE_OS_POSIX_PROFILE_VERSION`** (**`1.0.4`**), **`BARE_OS_POSIX_PROFILE_ID`**, and **`BARE_OS_POSIX_PROFILE_REFERENCE`** (Open Group Issue 7 index). Re-exported from the package root. Booter mirrors these values under **`/proc/bare_os_features`** and **`/proc/bare_os/syscalls.json`**.
|
||||
|
||||
## 10. Package: `bare-os-protocol`
|
||||
|
||||
@@ -28,7 +28,7 @@ Re-exports from `./constants.js`: `PROTOCOL_NAME`, `TOPIC_STRING`, `BLOCK_SIZE`,
|
||||
|
||||
Re-exports from `./lib/channel.js`: `setupSeedChannel`.
|
||||
|
||||
Re-exports from `./lib/seed-rpc-methods.js`: `BARE_OS_SEED_RPC_METHODS`, `BARE_OS_SEED_RPC_METHOD_SHORT_NAMES`, `BARE_OS_SEED_RPC_METHOD_SHORT_NAME_SET`.
|
||||
Re-exports from `./lib/seed-rpc-methods.js`: `BARE_OS_SEED_RPC_METHODS`, `BARE_OS_SEED_RPC_METHOD_SHORT_NAMES`, `BARE_OS_SEED_RPC_METHOD_SHORT_NAME_SET`, `bareOsIsAllowedSeedRpcMethodShort` (strict client-side allowlist helper matching **`channel.js`**).
|
||||
|
||||
Re-exports **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_*`** stock masks and **`BARE_OS_FEATURE5_*`** … **`FEATURE11_*`** from `./lib/kernel-feature-bits.js` (alongside earlier words). Re-exports wire v2 helpers from **`./lib/kernel-capability-wire.js`** (**`kernelCapabilityWords`** shape, **`BARE_OS_KERNEL_CAPABILITY_WORD_KEYS`**, …). **`BARE_OS_PROTOCOL_PACKAGE_VERSION`** is published from `./lib/protocol-meta.js` for **`ctx.bareOsProtocolPackageVersion`** comparisons.
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"schema": 1,
|
||||
"profileId": "bare-os-posix-like",
|
||||
"note": "Machine-readable summary; normative detail remains in handbook ch.9 and environment POSIX appendix.",
|
||||
"note": "Machine-readable summary; normative detail remains in handbook ch.9 and environment POSIX appendix. Schema 5: socket syscall probes + process_table v5.",
|
||||
"utilities": {
|
||||
"tier1_bin": "high",
|
||||
"sed_awk_grep": "issue7_inspired_js_engines",
|
||||
@@ -21,9 +21,9 @@
|
||||
"lib_bare_cache": "BARE_OS_VFS_LIB_BARE_CACHE with bin cache"
|
||||
},
|
||||
"synthetic_proc": {
|
||||
"syscalls_json_schema": 4,
|
||||
"process_table_schema": 4,
|
||||
"syscalls_json_schema": 5,
|
||||
"process_table_schema": 5,
|
||||
"paths": ["/proc/bare_os/syscalls.json", "/proc/bare_os/process_table.json"],
|
||||
"posix_xsh_surface": "open,close,read,write,lseek,pipe,dup,dup2,fcntl,poll,select,umask in syscalls.json opsDetail + posixXsh.namesCsv; ctx.bareOsSyscall fcntl+posixPoll+select+umask; ctx.bareOsPosixPoll"
|
||||
"posix_xsh_surface": "open,close,read,write,lseek,pipe,dup,dup2,fcntl,poll,select,umask,socket,bind,listen,accept,connect,send,recv,shutdown in syscalls.json; socket family returns ENOSYS-shaped results; ctx.bareOsSyscall fcntl+posixPoll+select+umask; ctx.bareOsPosixPoll"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -8,9 +8,12 @@
|
||||
"/proc/bare_os/syscalls.json"
|
||||
],
|
||||
"bareOsSyscallOps": [
|
||||
"accept",
|
||||
"access",
|
||||
"bind",
|
||||
"chdir",
|
||||
"chmod",
|
||||
"connect",
|
||||
"exists",
|
||||
"fcntl",
|
||||
"fdatasync",
|
||||
@@ -19,6 +22,7 @@
|
||||
"getcwd",
|
||||
"kill",
|
||||
"link",
|
||||
"listen",
|
||||
"lstat",
|
||||
"mkdir",
|
||||
"mount",
|
||||
@@ -27,9 +31,13 @@
|
||||
"readFile",
|
||||
"readdir",
|
||||
"readlink",
|
||||
"recv",
|
||||
"rename",
|
||||
"rmdir",
|
||||
"select",
|
||||
"send",
|
||||
"shutdown",
|
||||
"socket",
|
||||
"stat",
|
||||
"symlink",
|
||||
"truncate",
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
"type": "object",
|
||||
"required": ["schemaVersion", "ops"],
|
||||
"properties": {
|
||||
"schemaVersion": { "type": "integer", "const": 4 },
|
||||
"schemaVersion": { "type": "integer", "const": 5 },
|
||||
"ctxApiVersion": { "type": "string" },
|
||||
"posixProfile": {
|
||||
"type": "object",
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
# Blind relay, pairing, and P2P hardening
|
||||
|
||||
Bare OS follows a **zero-trust default** for **blind** Holepunch-style relays, **pairing** sketches, and **geo / topology** hints: stock **`/proc/bare_os`** JSON for **`blind_relay_router`**, **`blind_pairing_sketch`**, and **`relay_geo_hint`** is **stubbed** with **`exposed: false`** unless the operator explicitly enables **`BARE_OS_PROC_BLIND_PEER_RELAY_HINTS`**.
|
||||
|
||||
## Operator controls
|
||||
|
||||
- **`BARE_OS_PROC_BLIND_PEER_RELAY_HINTS`** — When set to **`1`** / **`true`** / **`yes`**, the booter may merge **non-secret** operator JSON from related **`BARE_OS_*`** env keys into those proc surfaces (see [`bare-os-pear-corestore-hrpc.js`](../../packages/bare-os-booter/lib/bare-os-proc-pear-corestore-hrpc.js) and companion proc builders).
|
||||
- **Seed RPC** — Method names are **allowlisted** in [`seed-rpc-methods.js`](../../packages/bare-os-protocol/lib/seed-rpc-methods.js). Unknown methods fail closed with **`bare_os.rpc_unknown_method`**. Clients can mirror the same rule with **`bareOsIsAllowedSeedRpcMethodShort`** (exported from **`bare-os-protocol`**).
|
||||
- **Capabilities / handshake** — **`BARE_OS_SEED_CAP_STRICT`** and **`BARE_OS_SEED_CAP_FAIL`** tighten seeder capability checks; keep them aligned with your release train (see [compatibility matrix](../reference/compatibility-matrix.md)).
|
||||
|
||||
## What the guest does not do
|
||||
|
||||
The guest **does not** open blind relay circuits, perform pairing handshakes, or resolve geo routing from proc stubs alone. Those steps belong on the **host** or **seeder** with explicit policy, keys, and network access.
|
||||
|
||||
## See also
|
||||
|
||||
- [Developer guide — Security and trust](../../developer-guide/09-security-and-trust.md)
|
||||
- [Environment appendix — `BARE_OS_PROC_BLIND_PEER_RELAY_HINTS`](../reference/environment-and-posix-appendix.md)
|
||||
- Booter tests: **`blind relay / pairing / geo proc JSON stubbed`** in [`packages/bare-os-booter/test.js`](../../packages/bare-os-booter/test.js)
|
||||
Reference in New Issue
Block a user