Further MD Fixes
This commit is contained in:
Raven Scott
@@ -14,7 +14,7 @@ This directory holds the split **file-by-file inventory** that used to live in t
|
||||
| Operator narrative | [Handbook](../../handbook/README.md) |
|
||||
| Contributor / `ctx` / Pear | [Developer guide](../../developer-guide/README.md) |
|
||||
| Day-to-day use | [Users manual](../../users-manual/README.md) |
|
||||
| **`agent**` (HTTPS assistant) + HTTP policy | [HTTP: curl and wget](http-curl-and-wget.md) · guest `**man agent`** · [Users manual ch.4](../../users-manual/04-shell-path-and-scripts.md) |
|
||||
| **`agent`** (HTTPS assistant) + HTTP policy | [HTTP: curl and wget](http-curl-and-wget.md) · guest `**man agent`** · [Users manual ch.4](../../users-manual/04-shell-path-and-scripts.md) |
|
||||
| File-level inventory | This directory (`docs/reference/`) |
|
||||
| JSON Schemas | [schemas/README.md](../schemas/README.md) |
|
||||
| Kernel contract (boundaries) | [`docs/architecture/KERNEL_CONTRACT.md`](../architecture/KERNEL_CONTRACT.md) |
|
||||
|
||||
@@ -24,11 +24,11 @@ sequenceDiagram
|
||||
Booter->>Booter: AsyncFunction start ctx from init.js
|
||||
```
|
||||
|
||||
After replication, the booter records **`vfs**` → `**ctx**` → `**repl**` → `**initd**` → `**kernel_invoke`** (see [`KERNEL_CONTRACT`](../architecture/KERNEL_CONTRACT.md)) before the stock **`start(ctx)**` loop opens the interactive shell unless `**BARE_OS_SKIP_REPL`** applies.
|
||||
After replication, the booter records **`vfs`** → **`ctx`** → **`repl`** → **`initd`** → **`kernel_invoke`** (see [`KERNEL_CONTRACT`](../architecture/KERNEL_CONTRACT.md)) before the stock **`start(ctx)**` loop opens the interactive shell unless **`BARE_OS_SKIP_REPL`** applies.
|
||||
|
||||
### Swarm `disk.os` bridge (post-`initd`)
|
||||
|
||||
[`createBareOsDiskOsBridge`](../../packages/bare-os-booter/lib/bare-os-disk-os-bridge.js) is assigned to **`disk.os**`. `**bare_os.replication_operator_sketch**` includes `**corestoreSnapshotPackageRef**` (schema **1** object) pointing operators at the upstream `**corestore-snapshot**` module and the env pair `**BARE_OS_CORESTORE_SNAPSHOT_JSON**` / `**BARE_OS_CORESTORE_STATS_JSON**` used by `**corestoreSnapshotUxHint**`. Peer `**searchLocal**` aggregates path substring matches from the **system** Hyperdrive and every `**SwarmDisk.auxiliaryDrives**` entry (read-only mirrors under `**/mirror/aux***`), dedupes, and caps results. The system drive may ship `**/etc/bare-os/path-manifest.json**` (or `**BARE_OS_DISK_OS_PATH_MANIFEST**`) so common paths match **without** a full recursive `**list()**` on the primary drive; `**BARE_OS_DISK_OS_SEARCH_MANIFEST_ONLY**` skips primary listing when a complete manifest is maintained. Optional host env `**BARE_OS_DISK_OS_SEARCH_THROTTLE_MS**` (0–500) yields between **auxiliary** drive scans. Whitelisted RPC `**bare_os.disk_os_hints**` (**schema 3**) exposes advisory `**mirrorDriveHintV2**`, `**httpDhtProxyHint**`, and `**pathSearchLocal**` metrics — operators only; guests do not auto-apply mirror hints. Stock `**ctx.bareOsHrpcRequest**` includes `**bare_os.search_local**` (`**payload.query**`) returning `**paths**` from `**disk.os.searchLocal**`. `**bare_os.replication_operator_sketch**` returns **schema 7** JSON (seed replication status, `**swarmPeerCount**`, Hyperswarm `**connectionBudget**`, protomux operator sketch, `**pkgIndexSurface**`, `**corestoreSnapshotUxHint**`, pause/backpressure env mirrors, optional `**hyperblobsDedupSketch**` / `**corestoreOperatorSketch**` / `**peerPrioritySketch**`). `**bare_os.pkg_index_get**` reads the static drive manifest (`**BARE_OS_PKG_INDEX_PATH**`). `**bare_os.replication_operator_intent**` appends an audit row when `**BARE_OS_DISK_OS_OPERATOR_INTENT_RPC=1**` and the booter wires `**auditBatch`**.
|
||||
[`createBareOsDiskOsBridge`](../../packages/bare-os-booter/lib/bare-os-disk-os-bridge.js) is assigned to **`disk.os`**. **`bare_os.replication_operator_sketch`** includes **`corestoreSnapshotPackageRef`** (schema **1** object) pointing operators at the upstream **`corestore-snapshot`** module and the env pair **`BARE_OS_CORESTORE_SNAPSHOT_JSON`** / **`BARE_OS_CORESTORE_STATS_JSON`** used by **`corestoreSnapshotUxHint`**. Peer **`searchLocal`** aggregates path substring matches from the **system** Hyperdrive and every **`SwarmDisk.auxiliaryDrives`** entry (read-only mirrors under **`/mirror/aux*`**), dedupes, and caps results. The system drive may ship **`/etc/bare-os/path-manifest.json`** (or **`BARE_OS_DISK_OS_PATH_MANIFEST`**) so common paths match **without** a full recursive `**list()**` on the primary drive; **`BARE_OS_DISK_OS_SEARCH_MANIFEST_ONLY`** skips primary listing when a complete manifest is maintained. Optional host env **`BARE_OS_DISK_OS_SEARCH_THROTTLE_MS`** (0–500) yields between **auxiliary** drive scans. Whitelisted RPC **`bare_os.disk_os_hints`** (**schema 3**) exposes advisory **`mirrorDriveHintV2`**, **`httpDhtProxyHint`**, and **`pathSearchLocal`** metrics — operators only; guests do not auto-apply mirror hints. Stock **`ctx.bareOsHrpcRequest`** includes **`bare_os.search_local`** (**`payload.query`**) returning **`paths`** from **`disk.os.searchLocal`**. **`bare_os.replication_operator_sketch`** returns **schema 7** JSON (seed replication status, **`swarmPeerCount`**, Hyperswarm **`connectionBudget`**, protomux operator sketch, **`pkgIndexSurface`**, **`corestoreSnapshotUxHint`**, pause/backpressure env mirrors, optional **`hyperblobsDedupSketch`** / **`corestoreOperatorSketch`** / **`peerPrioritySketch`**). **`bare_os.pkg_index_get`** reads the static drive manifest (**`BARE_OS_PKG_INDEX_PATH`**). **`bare_os.replication_operator_intent`** appends an audit row when **`BARE_OS_DISK_OS_OPERATOR_INTENT_RPC=1`** and the booter wires **`auditBatch`**.
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Use **`ctx.bareOsEmitBlindPeerHint`** (capability word 2 — see [kernel-extensions.md](./kernel-extensions.md)) after the booter has joined Hyperswarm and personal drive state is available.
|
||||
|
||||
1. Set **`BARE_OS_BLIND_PEER_HINT_JSON`** (or the env name documented beside the capability bit) to a JSON object describing the desired pairing sketch (non-secret labels only).
|
||||
2. Invoke **`ctx.bareOsEmitBlindPeerHint(payload)**` from a trusted `**kernel.ext.d**` script or `**/etc/bare-os/rc.local**` line via `**execLine`**.
|
||||
3. Read **`/proc/bare_os/blind_pairing_sketch.json**` (when exposed) or seed RPC `**bare_os.capabilities`** adjunct fields to confirm the hint was merged into operator snapshots.
|
||||
2. Invoke **`ctx.bareOsEmitBlindPeerHint(payload)**` from a trusted **`kernel.ext.d`** script or **`/etc/bare-os/rc.local`** line via **`execLine`**.
|
||||
3. Read **`/proc/bare_os/blind_pairing_sketch.json`** (when exposed) or seed RPC **`bare_os.capabilities`** adjunct fields to confirm the hint was merged into operator snapshots.
|
||||
|
||||
Cross-check upstream [**`blind-peer**`](https://github.com/holepunchto/blind-peer) and [`**blind-relay-service`**](https://github.com/holepunchto/blind-relay-service) for wire compatibility.
|
||||
Cross-check upstream [**`blind-peer`**](https://github.com/holepunchto/blind-peer) and [**`blind-relay-service`**](https://github.com/holepunchto/blind-relay-service) for wire compatibility.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Kernel capability words (authoritative map)
|
||||
|
||||
Seed RPC **`bare_os.capabilities**`, `**/proc/bare_os_features**`, and guest `**ctx**` (`**bareOsAdvertisedKernelCapabilityWords**` / `**bareOsSeedKernelCapabilityWords**`) use **wire v2**: eleven unsigned 32-bit masks live under one JSON object `**kernelCapabilityWords**` with **semantic camelCase** keys below. Numeric values and **bit positions** match the legacy v1 layout (top-level `**bits**`, `**bits2**`, … `**bits11`**); only the JSON shape changed.
|
||||
Seed RPC **`bare_os.capabilities`**, **`/proc/bare_os_features`**, and guest **`ctx`** (**`bareOsAdvertisedKernelCapabilityWords`** / **`bareOsSeedKernelCapabilityWords`**) use **wire v2**: eleven unsigned 32-bit masks live under one JSON object **`kernelCapabilityWords`** with **semantic camelCase** keys below. Numeric values and **bit positions** match the legacy v1 layout (top-level **`bits`**, **`bits2`**, … **`bits11`**); only the JSON shape changed.
|
||||
|
||||
- `primary` — `PRIMARY` — `BARE_OS_KERNEL_FEATURES_STOCK_WORD_PRIMARY` — `minKernelCapabilitiesPrimary` — (core tree; not a single module)
|
||||
- `extendedSeedingPlatform` — `EXTENDED_SEEDING_PLATFORM` — `BARE_OS_KERNEL_FEATURES_STOCK_WORD_EXTENDED_SEEDING_PLATFORM` — `requireKernelCapabilitiesExtendedSeedingPlatform` — —
|
||||
@@ -14,7 +14,7 @@ Seed RPC **`bare_os.capabilities**`, `**/proc/bare_os_features**`, and guest `**
|
||||
- `pearInspectLoggerTls` — `PEAR_INSPECT_LOGGER_TLS` — `BARE_OS_KERNEL_FEATURES_STOCK_WORD_PEAR_INSPECT_LOGGER_TLS` — `requireKernelCapabilitiesPearInspectLoggerTls` — `bare-os-proc-pear-inspect-logger-tls.js`
|
||||
- `hypercorePackHrpcLifecycle` — `HYPERCORE_PACK_HRPC_LIFECYCLE` — `BARE_OS_KERNEL_FEATURES_STOCK_WORD_HYPERCORE_PACK_HRPC_LIFECYCLE` — `requireKernelCapabilitiesHypercorePackHrpcLifecycle` — `bare-os-proc-hypercore-pack-hrpc-lifecycle.js`
|
||||
|
||||
**Offline LKG:** `boot.policy.json` boolean **`offlineLkgRequireHypercorePackHrpcLifecycle**` sets host env `**BARE_OS_OFFLINE_LKG_REQUIRE_HYPERCORE_PACK_HRPC_LIFECYCLE=1`** (strict class hints for the eleventh word).
|
||||
**Offline LKG:** `boot.policy.json` boolean **`offlineLkgRequireHypercorePackHrpcLifecycle`** sets host env **`BARE_OS_OFFLINE_LKG_REQUIRE_HYPERCORE_PACK_HRPC_LIFECYCLE=1`** (strict class hints for the eleventh word).
|
||||
|
||||
**Probe env (telemetry):**
|
||||
|
||||
@@ -24,8 +24,8 @@ Seed RPC **`bare_os.capabilities**`, `**/proc/bare_os_features**`, and guest `**
|
||||
|
||||
**Proc visibility:** `BARE_OS_HIDE_PROC_HYPERCORE_PACK_HRPC_LIFECYCLE` (`0` / `false` / `off`) omits eleventh-word **`/proc`** JSON entries from directory listings, resolution, and the proc index.
|
||||
|
||||
**Guest `ctx` (1.22.0+):** use frozen **`bareOsAdvertisedKernelCapabilityWords**` and `**bareOsSeedKernelCapabilityWords**` with the same keys as the table above (e.g. `**hypercorePackHrpcLifecycle`** for the eleventh word).
|
||||
**Guest `ctx` (1.22.0+):** use frozen **`bareOsAdvertisedKernelCapabilityWords`** and **`bareOsSeedKernelCapabilityWords`** with the same keys as the table above (e.g. **`hypercorePackHrpcLifecycle`** for the eleventh word).
|
||||
|
||||
**CI contract:** Required booter **`index.js**` substrings and `**kernel-feature-bits.js`** exports are listed in [`../../packages/bare-os-protocol/lib/stock-booter-capability-contract.json`](../../packages/bare-os-protocol/lib/stock-booter-capability-contract.json) (verified by [`scripts/verify-ctx-api-feature-bits.mjs`](../../scripts/verify-ctx-api-feature-bits.mjs)).
|
||||
**CI contract:** Required booter **`index.js`** substrings and **`kernel-feature-bits.js`** exports are listed in [`../../packages/bare-os-protocol/lib/stock-booter-capability-contract.json`](../../packages/bare-os-protocol/lib/stock-booter-capability-contract.json) (verified by [`scripts/verify-ctx-api-feature-bits.mjs`](../../scripts/verify-ctx-api-feature-bits.mjs)).
|
||||
|
||||
See also [kernel-capabilities-index.md](./kernel-capabilities-index.md) and [ADR 001](../../developer-guide/adr/001-kernel-feature-bits-governance.md).
|
||||
|
||||
@@ -14,31 +14,31 @@ Single place to compare **protocol**, **booter `ctx` API**, **feature-bit docume
|
||||
|
||||
## Version artifacts
|
||||
|
||||
**`bareOsCtxApiVersion**` (current stock: `**1.54.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.54.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: `**16`**) — 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).
|
||||
**`BARE_OS_KERNEL_FEATURE_BITS_DOC`** (current stock: **`16`**) — 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).
|
||||
|
||||
**Capability words (wire v2)** — Surfaces on **`bare_os.capabilities**` RPC and under `**/proc/bare_os_features**`. The stock tree uses a top-level `**kernelCapabilityWords**` object with eleven `**uint32**` masks named `**primary**`, `**extendedSeedingPlatform**`, `**rlimitsDelegatesShell**`, `**offlineNetExtensions**`, `**hostTransportDelegates**`, `**replicationOperatorSurface**`, `**pearCorestoreHrpc**`, `**bareRuntimeProtoMux**`, `**bareModuleCryptoStaging**`, `**pearInspectLoggerTls**`, and `**hypercorePackHrpcLifecycle**`. Bit positions match the legacy top-level `**bits**` … `**bits11`** fields for migration.
|
||||
**Capability words (wire v2)** — Surfaces on **`bare_os.capabilities`** RPC and under **`/proc/bare_os_features`**. The stock tree uses a top-level **`kernelCapabilityWords`** object with eleven **`uint32`** masks named **`primary`**, **`extendedSeedingPlatform`**, **`rlimitsDelegatesShell`**, **`offlineNetExtensions`**, **`hostTransportDelegates`**, **`replicationOperatorSurface`**, **`pearCorestoreHrpc`**, **`bareRuntimeProtoMux`**, **`bareModuleCryptoStaging`**, **`pearInspectLoggerTls`**, and **`hypercorePackHrpcLifecycle`**. Bit positions match the legacy top-level **`bits`** … **`bits11`** fields for migration.
|
||||
|
||||
**Lifecycle / telemetry NDJSON** — **`BARE_OS_LIFECYCLE_SCHEMA_VERSION`** in [`bare-os-lifecycle-schema.js`](../../packages/bare-os-booter/lib/bare-os-lifecycle-schema.js) (current stock: **`10`**). Guest and host mirrors use this when emitting structured lifecycle lines.
|
||||
|
||||
**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.19**`) 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`**.
|
||||
**POSIX-like profile** — **`BARE_OS_POSIX_PROFILE_VERSION`** (**`1.0.19`**) 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 **11** (see also [handbook ch.9 §2.3](../../handbook/09-posix-utilities-shell-and-vfs.md#23-pseudo-proc-sys-run-dev-and-session-tmp)) adds `**susv4Refs**` tokens on `**opsDetail**` and bumps `**posixXsh` schema** to **3**; schema **10** added **`posix_fadvise**` as a simulated `**ctx.bareOsSyscall**` no-op and retains `**clock_gettime**` (REALTIME / MONOTONIC sketch); earlier schema fields remain: cooperative `**fcntl**` advisory locks (optional `**BARE_OS_POSIX_FCNTL_BLOCKING_WAIT**` for `**F_SETLKW**`-shaped waits), optional `**BARE_OS_POSIX_SOCKET_FD_BRIDGE**` `**socket`/`connect**` (`**SOCK_STREAM**` via `**bareTcp**`, `**SOCK_DGRAM**` via `**bareDgram**` when merged) with bounded `**send`/`sendmsg`/`recv`/`recvfrom`/`recvmsg**` on bridged datagram fds (`**BARE_OS_POSIX_DGRAM_RECVQ_MAX**`, `**BARE_OS_POSIX_DGRAM_RECV_BLOCK_MS_MAX**`), `**socketMsgSurface**` schema **5** (`**sendmsg`/`recvmsg**` partial on bridge; binary ancillary `**ENOTSUP**`; optional `**logicalScmRightsOnSend**` when `**BARE_OS_POSIX_SOCKET_SCM_RIGHTS**`; `**recvmsg**` `**controllen` 0**), and retains socket-family **probes** plus **`posixXsh**`. 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; `**boot/init.js**` and `**lib/init/**` batch puts also invalidate). 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 **11** (see also [handbook ch.9 §2.3](../../handbook/09-posix-utilities-shell-and-vfs.md#23-pseudo-proc-sys-run-dev-and-session-tmp)) adds **`susv4Refs`** tokens on **`opsDetail`** and bumps `**posixXsh` schema** to **3**; schema **10** added **`posix_fadvise`** as a simulated **`ctx.bareOsSyscall`** no-op and retains **`clock_gettime`** (REALTIME / MONOTONIC sketch); earlier schema fields remain: cooperative **`fcntl`** advisory locks (optional **`BARE_OS_POSIX_FCNTL_BLOCKING_WAIT`** for **`F_SETLKW`**-shaped waits), optional **`BARE_OS_POSIX_SOCKET_FD_BRIDGE`** `**socket`/`connect**` (**`SOCK_STREAM`** via **`bareTcp`**, **`SOCK_DGRAM`** via **`bareDgram`** when merged) with bounded `**send`/`sendmsg`/`recv`/`recvfrom`/`recvmsg**` on bridged datagram fds (**`BARE_OS_POSIX_DGRAM_RECVQ_MAX`**, **`BARE_OS_POSIX_DGRAM_RECV_BLOCK_MS_MAX`**), **`socketMsgSurface`** schema **5** (`**sendmsg`/`recvmsg**` partial on bridge; binary ancillary **`ENOTSUP`**; optional **`logicalScmRightsOnSend`** when **`BARE_OS_POSIX_SOCKET_SCM_RIGHTS`**; **`recvmsg`** `**controllen` 0**), and retains socket-family **probes** plus **`posixXsh`**. 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; **`boot/init.js`** and **`lib/init/`** batch puts also invalidate). 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/process_table.json**` — Schema **8** (see `**fdModel.processTableSchema**` inside `**syscalls.json**` and [handbook ch.9 §2.3](../../handbook/09-posix-utilities-shell-and-vfs.md#23-pseudo-proc-sys-run-dev-and-session-tmp)); documents logical jobs, PGID/SID-style fields, initd binding, signal routing, and optional per-row accounting (`**threads**`, `**cpuMs***`, I/O stubs, `**replicationHint`** on failed net-related initd units).
|
||||
**`/proc/bare_os/process_table.json`** — Schema **8** (see **`fdModel.processTableSchema`** inside **`syscalls.json`** and [handbook ch.9 §2.3](../../handbook/09-posix-utilities-shell-and-vfs.md#23-pseudo-proc-sys-run-dev-and-session-tmp)); documents logical jobs, PGID/SID-style fields, initd binding, signal routing, and optional per-row accounting (**`threads`**, **`cpuMs*`**, I/O stubs, **`replicationHint`** on failed net-related initd units).
|
||||
|
||||
**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.
|
||||
**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.
|
||||
|
||||
---
|
||||
|
||||
## Peer assumptions
|
||||
|
||||
- **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.
|
||||
- **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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -3,14 +3,14 @@
|
||||
## Current version
|
||||
|
||||
- **`ctx.bareOsCtxApiVersion`** — semver string defined in [`bare-os-ctx-api.js`](../../packages/bare-os-booter/lib/bare-os-ctx-api.js).
|
||||
- **`BARE_OS_REQUIRE_CTX_API_MIN**` / `**BARE_OS_BOOT_ABI_STRICT`** — guest kernel may refuse boot if the booter is too old (see [environment appendix §14](environment-and-posix-appendix.md#14-environment-variables-complete-list)).
|
||||
- **`BARE_OS_REQUIRE_CTX_API_MIN`** / **`BARE_OS_BOOT_ABI_STRICT`** — guest kernel may refuse boot if the booter is too old (see [environment appendix §14](environment-and-posix-appendix.md#14-environment-variables-complete-list)).
|
||||
|
||||
## Rules for contributors
|
||||
|
||||
1. **Additive changes** (new optional `ctx` methods, new env passthrough keys) — bump **patch** when behavior is backward compatible for existing kernels.
|
||||
2. **Breaking changes** (renamed methods, stricter required behavior, removed hooks) — bump **minor** or **major** per semver; update stock `kernel/init.js` and docs in the same change.
|
||||
3. **Deprecation** — document in this file and in [`package-bare-os-booter.md`](package-bare-os-booter.md); keep a compatibility shim for at least one release when feasible.
|
||||
4. **Protocol alignment** — capability words and wire formats belong in **`bare-os-protocol**`; bump `**BARE_OS_PROTOCOL_PACKAGE_VERSION`** consumers when wire or strict matrix changes.
|
||||
4. **Protocol alignment** — capability words and wire formats belong in **`bare-os-protocol`**; bump **`BARE_OS_PROTOCOL_PACKAGE_VERSION`** consumers when wire or strict matrix changes.
|
||||
|
||||
## Release checklist (same PR as `ctx` edits)
|
||||
|
||||
@@ -18,7 +18,7 @@
|
||||
2. Update [`developer-guide/02-the-context-object.md`](../../developer-guide/02-the-context-object.md) and [`bare-os-ctx.d.ts`](../../packages/bare-os-booter/lib/bare-os-ctx.d.ts) for any new fields or methods.
|
||||
3. Run **`node scripts/gen-ctx-client-helper.mjs`** and refresh any consumer that vendors the emitted header.
|
||||
4. Add or extend **`packages/bare-os-booter/test.js`** (and workspace tests) for behavior that must not regress.
|
||||
5. Run root **`npm test**` so `**pretest`** (`verify-ctx-api-feature-bits`, `verify-bare-imports`, …) passes.
|
||||
5. Run root **`npm test**` so **`pretest`** (`verify-ctx-api-feature-bits`, `verify-bare-imports`, …) passes.
|
||||
|
||||
## Related
|
||||
|
||||
|
||||
@@ -13,297 +13,297 @@ Former **DOCUMENTATION.md** §14, §14a. [Reference index →](README.md)
|
||||
|
||||
## 14. Environment variables (complete list)
|
||||
|
||||
**Host package policy:** Booter and seeder **`lib/**/*.js`** sources are checked by [`scripts/verify-pear-no-static-node-import.mjs`](../../scripts/verify-pear-no-static-node-import.mjs) so Pear/Bare bundles avoid **`node:**` specifiers (except the allowlisted Node-only boot manifest verifier). Prefer `**bare-***` modules in guest paths and `**#host-*`** aliases on the host; see [Developer guide ch.1 — Host source policy](../../developer-guide/01-two-runtimes-host-vs-image.md#host-source-policy-bare-first).
|
||||
**Host package policy:** Booter and seeder **`lib/**`/*.js`** sources are checked by [`scripts/verify-pear-no-static-node-import.mjs`](../../scripts/verify-pear-no-static-node-import.mjs) so Pear/Bare bundles avoid **`node:`** specifiers (except the allowlisted Node-only boot manifest verifier). Prefer **`bare-*`** modules in guest paths and `**#host-*`** aliases on the host; see [Developer guide ch.1 — Host source policy](../../developer-guide/01-two-runtimes-host-vs-image.md#host-source-policy-bare-first).
|
||||
|
||||
The list below is one **bullet per variable** in the form **name — component — meaning**. Values shown as defaults are what the stock tree assumes when the variable is unset; always confirm in source when debugging a forked image.
|
||||
|
||||
- `BARE_OS_KERNEL_ROOT` — Seeder — Absolute path to kernel tree (default: `repo/kernel`)
|
||||
- `BARE_OS_SEED_CORESTORE_SNAPSHOT_TAG` — Seeder — Optional tag string; when set (and **`BARE_OS_SEED_SNAPSHOT_HINTS_JSON**` is unset), the seeder builds `**snapshotHintsJson**` for `**bare_os.snapshot_hints**` so the booter can surface it under `**/proc/bare_os/snapshot_hints.json`** after RPC.
|
||||
- `BARE_OS_SEED_SNAPSHOT_HINTS_JSON` — Seeder — Optional JSON string; when set, passed verbatim as **`snapshotHintsJson**` (wins over `**BARE_OS_SEED_CORESTORE_SNAPSHOT_TAG`**).
|
||||
- `BARE_OS_CORESTORE_SNAPSHOT_WORKFLOW_JSON` — Booter — Optional JSON merged into **`/proc/bare_os/snapshot_hints.json**` and `**ctx.bareOsReadSnapshotHintsJson()**` as `**corestoreSnapshotWorkflow**` (keep shape aligned with seeder `**snapshot_hints**` / corestore-snapshot tooling; parse errors set `**corestoreSnapshotWorkflowParseError`**).
|
||||
- `BARE_OS_SEED_CORESTORE_SNAPSHOT_TAG` — Seeder — Optional tag string; when set (and **`BARE_OS_SEED_SNAPSHOT_HINTS_JSON`** is unset), the seeder builds **`snapshotHintsJson`** for **`bare_os.snapshot_hints`** so the booter can surface it under **`/proc/bare_os/snapshot_hints.json`** after RPC.
|
||||
- `BARE_OS_SEED_SNAPSHOT_HINTS_JSON` — Seeder — Optional JSON string; when set, passed verbatim as **`snapshotHintsJson`** (wins over **`BARE_OS_SEED_CORESTORE_SNAPSHOT_TAG`**).
|
||||
- `BARE_OS_CORESTORE_SNAPSHOT_WORKFLOW_JSON` — Booter — Optional JSON merged into **`/proc/bare_os/snapshot_hints.json`** and `**ctx.bareOsReadSnapshotHintsJson()**` as **`corestoreSnapshotWorkflow`** (keep shape aligned with seeder **`snapshot_hints`** / corestore-snapshot tooling; parse errors set **`corestoreSnapshotWorkflowParseError`**).
|
||||
- `BARE_OS_CORESTORE_SNAPSHOT_JSON` — Booter / host — Optional non-secret JSON merged into **`disk.os` `bare_os.replication_snapshot`** (**schema 2**) alongside seeder snapshot hints / manifest slice / chain for operator visibility (bounded payload; same family as corestore-snapshot-style tooling).
|
||||
- `BARE_OS_HRPC_ALLOWLIST_JSON` — Booter — Optional allowlist for stock **`ctx.bareOsHrpcRequest**`: JSON **array** of `**service.method**` strings or **object** with route keys and truthy values; wildcards `**"*"**` / `**kernel.*`** supported. Invalid JSON fails the first hrpc call. Schema: [`docs/schemas/bare-os-hrpc-allowlist.schema.json`](../schemas/bare-os-hrpc-allowlist.schema.json).
|
||||
- `BARE_OS_BLIND_RELAY_TOPOLOGY_JSON` — Booter — Optional JSON summarized under **`/proc/bare_os/swarm.json**` → `**blindRelayTopology`** (PII-free operator sketch).
|
||||
- `BARE_OS_MIRROR_DRIVE_COMPOSITION_HINT_JSON` — Booter — Optional JSON summarized under **`/proc/bare_os/replication**` → `**mirrorDriveCompositionHint`** (mirror-drive–style aux composition hints).
|
||||
- `BARE_OS_MIRROR_DRIVE_OVERLAY_JSON` — Booter — Optional non-secret JSON merged into **`bareOsMirrorDriveExportSketch**` (**schema 2**) and `**/proc/bare_os/union`** export hints for read-through mirror-drive overlay composition (writes to overlay paths remain policy-defined / often **EROFS**-shaped).
|
||||
- `BARE_OS_REPLICATION_PLAN_JSON` — Booter — Optional JSON merged into **`/proc/bare_os/replication**` as `**guestReplicationPlan`** (operator warm-replication hints).
|
||||
- `BARE_OS_PEAR_DOCTOR_STATE_JSON` / `BARE_OS_PEAR_INSPECT_PROBE` / `BARE_OS_PEAR_DOCTOR_MODULE` — Booter — Feed **`/proc/bare_os_pear_doctor_state.json**` (**schema 2**) for pear-runtime / pear-inspect parity (`**pearDoctorModuleHint**`, `**pearInspectProbe**`, `**runtimeVersion**` via `**BARE_OS_PEAR_RUNTIME_VERSION`**).
|
||||
- `BARE_OS_HRPC_ALLOWLIST_JSON` — Booter — Optional allowlist for stock **`ctx.bareOsHrpcRequest`**: JSON **array** of **`service.method`** strings or **object** with route keys and truthy values; wildcards `**"*"**` / **`kernel.*`** supported. Invalid JSON fails the first hrpc call. Schema: [`docs/schemas/bare-os-hrpc-allowlist.schema.json`](../schemas/bare-os-hrpc-allowlist.schema.json).
|
||||
- `BARE_OS_BLIND_RELAY_TOPOLOGY_JSON` — Booter — Optional JSON summarized under **`/proc/bare_os/swarm.json`** → **`blindRelayTopology`** (PII-free operator sketch).
|
||||
- `BARE_OS_MIRROR_DRIVE_COMPOSITION_HINT_JSON` — Booter — Optional JSON summarized under **`/proc/bare_os/replication`** → **`mirrorDriveCompositionHint`** (mirror-drive–style aux composition hints).
|
||||
- `BARE_OS_MIRROR_DRIVE_OVERLAY_JSON` — Booter — Optional non-secret JSON merged into **`bareOsMirrorDriveExportSketch`** (**schema 2**) and **`/proc/bare_os/union`** export hints for read-through mirror-drive overlay composition (writes to overlay paths remain policy-defined / often **EROFS**-shaped).
|
||||
- `BARE_OS_REPLICATION_PLAN_JSON` — Booter — Optional JSON merged into **`/proc/bare_os/replication`** as **`guestReplicationPlan`** (operator warm-replication hints).
|
||||
- `BARE_OS_PEAR_DOCTOR_STATE_JSON` / `BARE_OS_PEAR_INSPECT_PROBE` / `BARE_OS_PEAR_DOCTOR_MODULE` — Booter — Feed **`/proc/bare_os_pear_doctor_state.json`** (**schema 2**) for pear-runtime / pear-inspect parity (**`pearDoctorModuleHint`**, **`pearInspectProbe`**, **`runtimeVersion`** via **`BARE_OS_PEAR_RUNTIME_VERSION`**).
|
||||
- `BARE_OS_HOST_DATA` — paths — Base directory for host state (default `~/.bare-os`; Corestore dirs live under `corestore/`)
|
||||
- `BARE_OS_HOST_BOOTER_LOG` — Booter (host, pre-session) — **`stderr**` (default): emit host diagnostics via structured helpers (`**bare-os-host-booter-log**`, `**console.warn**`-compatible). `**ndjson**`: append JSON lines (`**type":"booterHostWarn"**` / `**booterHostInfo**`, `**code**`, `**message**`, optional `**detail**`, `**ts**`) to `**BARE_OS_HOST_BOOTER_LOG_PATH**` or default `**~/.bare-os/var/log/booter-host.ndjson**`. `**0**` / `**false**` / `**off**` / `**silent**`: suppress host booter warnings entirely. **Guest session UX** lines belong on `**ctx.console`** (kernel / REPL), not the host NDJSON sink — see handbook ch.4.
|
||||
- `BARE_OS_HOST_BOOTER_LOG` — Booter (host, pre-session) — **`stderr`** (default): emit host diagnostics via structured helpers (**`bare-os-host-booter-log`**, **`console.warn`**-compatible). **`ndjson`**: append JSON lines (`**type":"booterHostWarn"**` / **`booterHostInfo`**, **`code`**, **`message`**, optional **`detail`**, **`ts`**) to **`BARE_OS_HOST_BOOTER_LOG_PATH`** or default **`~/.bare-os/var/log/booter-host.ndjson`**. **`0`** / **`false`** / **`off`** / **`silent`**: suppress host booter warnings entirely. **Guest session UX** lines belong on **`ctx.console`** (kernel / REPL), not the host NDJSON sink — see handbook ch.4.
|
||||
- `BARE_OS_HOST_BOOTER_LOG_PATH` — Booter — Absolute path override when **`BARE_OS_HOST_BOOTER_LOG=ndjson`** (parent dirs created best-effort).
|
||||
- `BARE_OS_HOST_BOOTER_LOG_STDERR` — Booter — When **`1**` with `**ndjson`**, also mirror warnings to stderr after the file append.
|
||||
- `BARE_OS_HOST_BOOTER_LOG_STDERR` — Booter — When **`1`** with **`ndjson`**, also mirror warnings to stderr after the file append.
|
||||
- `BARE_OS_SEED_STORE` — Seeder — Corestore directory (default: `~/.bare-os/corestore/seeder`)
|
||||
- `BARE_OS_SEED_LOG_LEVEL` — Seeder — Host logger level: **`debug**`, `**info**`, `**warn**`, `**error**` (default `**info`**).
|
||||
- `BARE_OS_SEED_LOG_FORMAT` — Seeder — Set **`ndjson**` or `**json**` for one JSON object per stdout line (`**ts**`, `**level**`, `**msg`**, …); default human-readable lines.
|
||||
- `BARE_OS_SEED_LOG_LEVEL` — Seeder — Host logger level: **`debug`**, **`info`**, **`warn`**, **`error`** (default **`info`**).
|
||||
- `BARE_OS_SEED_LOG_FORMAT` — Seeder — Set **`ndjson`** or **`json`** for one JSON object per stdout line (**`ts`**, **`level`**, **`msg`**, …); default human-readable lines.
|
||||
- `BARE_OS_BOOT_STORE` — Booter — Corestore for boot side (default: `~/.bare-os/corestore/booter`)
|
||||
- `BARE_OS_BOOT_TIMEOUT_MS` — Booter — Wall-clock budget for peer wait + network boot (default `60000`)
|
||||
- `BARE_OS_MBR_READ_TIMEOUT_MS` — Booter (host) — Max wait in milliseconds for replicated **block 0** / MBR before boot fails (**≥ 3000**, hard cap **600000**); when unset, defaults to **60000** unless adaptive mode adjusts it.
|
||||
- `BARE_OS_MBR_READ_TIMEOUT_ADAPTIVE` — Booter — When **`1**` / `**true**` and `**BARE_OS_MBR_READ_TIMEOUT_MS`** is unset, adjusts the MBR wait from live **peer count** (sparse swarms get a longer budget; multi-peer sessions may use a shorter one).
|
||||
- `BARE_OS_DISK_OS_SEARCH_THROTTLE_MS` — Booter / **`disk.os**` — Optional **0–500** ms delay between scanning the system Hyperdrive and each `**auxiliaryDrives**` entry during peer `**searchLocal`** fan-out (default **0**); softens load on large offline mirrors.
|
||||
- `BARE_OS_DISK_OS_PATH_MANIFEST` — Booter / **`disk.os**` — Absolute path on the **system** Hyperdrive to a JSON manifest (**default** `**/etc/bare-os/path-manifest.json**`). The file may be `**{ "schema": 1, "paths": ["/bin/sh", …] }`** or a bare JSON array of path strings. Substring matches from the manifest are merged **before** the primary drive’s recursive listing. Set to **empty** to disable manifest acceleration (full listing only on the primary drive).
|
||||
- `BARE_OS_DISK_OS_SEARCH_MANIFEST_ONLY` — Booter — When **`1**` / `**true**`, `**searchLocal` skips the primary drive’s recursive `list()` scan** and uses only manifest hits on that drive (auxiliary drives are still listed). For tests and operator-tuned images with a complete manifest.
|
||||
- `BARE_OS_MBR_READ_TIMEOUT_ADAPTIVE` — Booter — When **`1`** / **`true`** and **`BARE_OS_MBR_READ_TIMEOUT_MS`** is unset, adjusts the MBR wait from live **peer count** (sparse swarms get a longer budget; multi-peer sessions may use a shorter one).
|
||||
- `BARE_OS_DISK_OS_SEARCH_THROTTLE_MS` — Booter / **`disk.os`** — Optional **0–500** ms delay between scanning the system Hyperdrive and each **`auxiliaryDrives`** entry during peer **`searchLocal`** fan-out (default **0**); softens load on large offline mirrors.
|
||||
- `BARE_OS_DISK_OS_PATH_MANIFEST` — Booter / **`disk.os`** — Absolute path on the **system** Hyperdrive to a JSON manifest (**default** **`/etc/bare-os/path-manifest.json`**). The file may be `**{ "schema": 1, "paths": ["/bin/sh", …] }`** or a bare JSON array of path strings. Substring matches from the manifest are merged **before** the primary drive’s recursive listing. Set to **empty** to disable manifest acceleration (full listing only on the primary drive).
|
||||
- `BARE_OS_DISK_OS_SEARCH_MANIFEST_ONLY` — Booter — When **`1`** / **`true`**, `**searchLocal` skips the primary drive’s recursive `list()` scan** and uses only manifest hits on that drive (auxiliary drives are still listed). For tests and operator-tuned images with a complete manifest.
|
||||
- `BARE_OS_DISK_OS_MANIFEST_CACHE_MS` — Booter — Cache parsed manifest paths per system drive (**default** **30000**, max **3600000**). Reduces **`drive.get`** churn when peers issue many searches.
|
||||
- `BARE_OS_PATH_CAPABILITY_ENFORCE_READ` — Booter / VFS — When **`1**` / `**true**`, reads on the **personal** drive under `**BARE_OS_PATH_CAPABILITY_PREFIX**` require a valid `**user.bareos.cap_v1**` entry in `**PATH.bare_xattr.json**` (see `**path-capability.envelope.example.json**` and `**ctx.bareOsVerifyPathCapabilityEnvelope`**). Sidecar and ACL files are exempt from the check.
|
||||
- `BARE_OS_PATH_CAPABILITY_PREFIX` — Booter — Logical path prefix for the capability gate (**default** **`/home/**`). Only applies with `**BARE_OS_PATH_CAPABILITY_ENFORCE_READ`**.
|
||||
- `BARE_OS_PATH_CAPABILITY_TRUSTED_PUBKEYS_HEX` — Booter — Comma- or whitespace-separated **ed25519** public keys (**hex**) allowed as **`ctx.bareOsVerifyPathCapabilityEnvelopeTrusted**` issuers for signed envelopes (see `**/bin/pathcap-verify --trusted`**).
|
||||
- `BARE_OS_SAVEVAULT_PRESNAPSHOT_HINT` — Booter — When **`1**` / `**true**`, `**saveVaultToDrive**` emits `**process.emit('bare-os:vault-pre-save-snapshot-hint', …)`** so the host may snapshot the personal Corestore namespace before sealing vault blobs.
|
||||
- `BARE_OS_POSIX_SOCKET_CONNECT_TIMEOUT_MS` — Booter — Optional **SOCK_STREAM** bridge **`connect**` wall timeout in milliseconds (**default** **0** = unlimited). On expiry the socket is destroyed and `**connect**` returns `**ETIMEDOUT`**.
|
||||
- `BARE_OS_WASM_KERNEL_CTX_API_PEEK` — Booter / guest env — With **`BARE_OS_WASM_KERNEL_SYSCALL**`, adds Wasm import `**env.bare_os_ctx_api_version_peek**` writing `**ctx.bareOsCtxApiVersion`** NUL-terminated (**bounded**).
|
||||
- `BARE_OS_PATH_CAPABILITY_ENFORCE_READ` — Booter / VFS — When **`1`** / **`true`**, reads on the **personal** drive under **`BARE_OS_PATH_CAPABILITY_PREFIX`** require a valid **`user.bareos.cap_v1`** entry in **`PATH.bare_xattr.json`** (see **`path-capability.envelope.example.json`** and **`ctx.bareOsVerifyPathCapabilityEnvelope`**). Sidecar and ACL files are exempt from the check.
|
||||
- `BARE_OS_PATH_CAPABILITY_PREFIX` — Booter — Logical path prefix for the capability gate (**default** **`/home/`**). Only applies with **`BARE_OS_PATH_CAPABILITY_ENFORCE_READ`**.
|
||||
- `BARE_OS_PATH_CAPABILITY_TRUSTED_PUBKEYS_HEX` — Booter — Comma- or whitespace-separated **ed25519** public keys (**hex**) allowed as **`ctx.bareOsVerifyPathCapabilityEnvelopeTrusted`** issuers for signed envelopes (see `**/bin/pathcap-verify --trusted`**).
|
||||
- `BARE_OS_SAVEVAULT_PRESNAPSHOT_HINT` — Booter — When **`1`** / **`true`**, **`saveVaultToDrive`** emits `**process.emit('bare-os:vault-pre-save-snapshot-hint', …)`** so the host may snapshot the personal Corestore namespace before sealing vault blobs.
|
||||
- `BARE_OS_POSIX_SOCKET_CONNECT_TIMEOUT_MS` — Booter — Optional **SOCK_STREAM** bridge **`connect`** wall timeout in milliseconds (**default** **0** = unlimited). On expiry the socket is destroyed and **`connect`** returns **`ETIMEDOUT`**.
|
||||
- `BARE_OS_WASM_KERNEL_CTX_API_PEEK` — Booter / guest env — With **`BARE_OS_WASM_KERNEL_SYSCALL`**, adds Wasm import **`env.bare_os_ctx_api_version_peek`** writing **`ctx.bareOsCtxApiVersion`** NUL-terminated (**bounded**).
|
||||
- `BARE_OS_PKG_SWARM_TOPIC_HEX` — Guest — Optional **64-hex** topic class hint for **`pkg-swarm-index`** operator documentation (not wired to Hyperswarm by the stock utility).
|
||||
- `BARE_OS_PKG_INDEX_PATH` — Booter / **`disk.os**` — Absolute path on the **system** Hyperdrive for `**bare_os.pkg_index_get**` (default `**/etc/bare-os/pkg-index.json**`); see `**kernel/etc/bare-os/pkg-index.example.json`**.
|
||||
- `BARE_OS_RC_PROPOSAL_MULTISIG_STRICT` — Stock kernel — When **`1**` / `**true**`, before `**rc.d**` validate `**/etc/bare-os/rc.proposals/enabled/*.json**` against `**/etc/bare-os/pear.multisig.json**` (`**signaturesFrom**` ⊆ `**signers**`, distinct count ≥ `**quorum**`). Emits audit rows `**rc.proposal.multisig_***` via `**ctx.bareOsAuditLogAppend`** when present.
|
||||
- `BARE_OS_PKG_INDEX_PATH` — Booter / **`disk.os`** — Absolute path on the **system** Hyperdrive for **`bare_os.pkg_index_get`** (default **`/etc/bare-os/pkg-index.json`**); see **`kernel/etc/bare-os/pkg-index.example.json`**.
|
||||
- `BARE_OS_RC_PROPOSAL_MULTISIG_STRICT` — Stock kernel — When **`1`** / **`true`**, before **`rc.d`** validate **`/etc/bare-os/rc.proposals/enabled/*.json`** against **`/etc/bare-os/pear.multisig.json`** (**`signaturesFrom`** ⊆ **`signers`**, distinct count ≥ **`quorum`**). Emits audit rows **`rc.proposal.multisig_*`** via **`ctx.bareOsAuditLogAppend`** when present.
|
||||
- `BARE_OS_NO_SPLASH` — Booter — If `1`, skip TTY splash (plain logs / non-TTY behavior unchanged)
|
||||
- `BARE_OS_LOCAL_SEED` — paths — Overrides local seed path helper (`defaultLocalSeedCorestorePath`); booter does not local-boot
|
||||
- `BARE_OS_SKIP_REPL` — Booter — If `1`, readline returns null — non-interactive exit
|
||||
- `BARE_OS_SSH_LISTEN_PORT` — Booter / **`bare-openssh**` — When set on the **host**, copied into `**vfs.env**`; overrides `**Port**` from `**/etc/ssh/sshd_config**` after parse. Use `**0`** for an OS-chosen ephemeral port (tests). Parsed as a non-negative integer; invalid values are ignored.
|
||||
- `BARE_OS_SSH_BIND_ALL` — Booter / **`bare-openssh**` — When `**1**` or `**true**` on the **host**, copied into `**vfs.env**`; if `**ListenAddress**` in config is `**127.0.0.1**`, the server binds `**0.0.0.0`** instead (operator override; default stock config stays on loopback).
|
||||
- `BARE_OS_SSH_LISTEN_PORT` — Booter / **`bare-openssh`** — When set on the **host**, copied into **`vfs.env`**; overrides **`Port`** from **`/etc/ssh/sshd_config`** after parse. Use **`0`** for an OS-chosen ephemeral port (tests). Parsed as a non-negative integer; invalid values are ignored.
|
||||
- `BARE_OS_SSH_BIND_ALL` — Booter / **`bare-openssh`** — When **`1`** or **`true`** on the **host**, copied into **`vfs.env`**; if **`ListenAddress`** in config is **`127.0.0.1`**, the server binds **`0.0.0.0`** instead (operator override; default stock config stays on loopback).
|
||||
- `BARE_OS_FISH` — Booter — Set **`0`** to disable the **Fish-style** raw TTY line editor (`createFishReadLine`); a simpler stream reader is used instead. Any other value (including unset) leaves Fish mode enabled when stdin is a TTY. See [Shell completion and REPL editor](shell-completion-and-repl-editor.md).
|
||||
- `BARE_OS_COMPACT_MENU` — Booter — When **`1**` / `**true**`, tab completion **cycles inline** (no multi-line candidate menu) even on wide terminals. Narrow TTYs (`**stdout.columns` < 44**) use the same compact behavior without this flag.
|
||||
- `BARE_OS_BOOT_TRACE` — Stock kernel (bundled **`/boot/init.js`** from [`kernel/lib/init/init-main.js`](../../kernel/lib/init/init-main.js) via [`scripts/bundle-kernel-init.mjs`](../../scripts/bundle-kernel-init.mjs)) — If `1` or `true`, log each boot phase duration on stderr as `[boot] phase: Nms`; if `json` / **`ndjson**`, log structured phase lines (`**bootTraceSchemaVersion` 2**, **`step**` / `**stage**` / `**phase**`) per completed stage; `**ndjson**` adds `**sessionId**` / `**ts`**. When `json` or **`ndjson**`, guest `**os-release**`, `**motd**`, and `**banner**` text also emit extra stderr lines with `**type":"bootOutput"**` and a capped `**textPreview**` (the live session output still uses `**ctx.console.log`** only).
|
||||
- `BARE_OS_BOOT_SAFE_MODE` — Stock kernel — **`1**` / `**true**` skips `**rc.d**`, `**kernel.ext.d**`, `**onboot`** after boot policy merge.
|
||||
- `BARE_OS_BOOT_TRANSACTION_JOURNAL` — Stock kernel — **`1**`, `**true**`, or `**ndjson**` appends phase records to `**/run/bare-os/boot-transaction.ndjson**` when `**ctx.vfs`** supports it.
|
||||
- `BARE_OS_BOOT_CHECKPOINT` — Stock kernel — **`1**` / `**true**` writes `**/run/bare-os/boot-checkpoint.json`** after each completed boot phase.
|
||||
- `BARE_OS_BOOT_DRY_RUN` — Stock kernel — **`1**` / `**true**` parses boot snippets but skips trusted `**execLine**` and `**kernel.ext.d`** scripts.
|
||||
- `BARE_OS_BOOT_POLICY_PATH` — Stock kernel — Optional **`/etc/bare-os/…**` path for the primary `**boot.policy.json**` (default `**/etc/bare-os/boot.policy.json`**).
|
||||
- `BARE_OS_BOOT_ROLLBACK_APPLY` — Stock kernel — **`1**` merges skip phases from `**/run/bare-os/boot-rollback.marker**` when `**ctx.vfs`** can read it.
|
||||
- `BARE_OS_COMPACT_MENU` — Booter — When **`1`** / **`true`**, tab completion **cycles inline** (no multi-line candidate menu) even on wide terminals. Narrow TTYs (`**stdout.columns` < 44**) use the same compact behavior without this flag.
|
||||
- `BARE_OS_BOOT_TRACE` — Stock kernel (bundled **`/boot/init.js`** from [`kernel/lib/init/init-main.js`](../../kernel/lib/init/init-main.js) via [`scripts/bundle-kernel-init.mjs`](../../scripts/bundle-kernel-init.mjs)) — If `1` or `true`, log each boot phase duration on stderr as `[boot] phase: Nms`; if `json` / **`ndjson`**, log structured phase lines (`**bootTraceSchemaVersion` 2**, **`step`** / **`stage`** / **`phase`**) per completed stage; **`ndjson`** adds **`sessionId`** / **`ts`**. When `json` or **`ndjson`**, guest **`os-release`**, **`motd`**, and **`banner`** text also emit extra stderr lines with `**type":"bootOutput"**` and a capped **`textPreview`** (the live session output still uses **`ctx.console.log`** only).
|
||||
- `BARE_OS_BOOT_SAFE_MODE` — Stock kernel — **`1`** / **`true`** skips **`rc.d`**, **`kernel.ext.d`**, **`onboot`** after boot policy merge.
|
||||
- `BARE_OS_BOOT_TRANSACTION_JOURNAL` — Stock kernel — **`1`**, **`true`**, or **`ndjson`** appends phase records to **`/run/bare-os/boot-transaction.ndjson`** when **`ctx.vfs`** supports it.
|
||||
- `BARE_OS_BOOT_CHECKPOINT` — Stock kernel — **`1`** / **`true`** writes **`/run/bare-os/boot-checkpoint.json`** after each completed boot phase.
|
||||
- `BARE_OS_BOOT_DRY_RUN` — Stock kernel — **`1`** / **`true`** parses boot snippets but skips trusted **`execLine`** and **`kernel.ext.d`** scripts.
|
||||
- `BARE_OS_BOOT_POLICY_PATH` — Stock kernel — Optional **`/etc/bare-os/…**` path for the primary **`boot.policy.json`** (default **`/etc/bare-os/boot.policy.json`**).
|
||||
- `BARE_OS_BOOT_ROLLBACK_APPLY` — Stock kernel — **`1`** merges skip phases from **`/run/bare-os/boot-rollback.marker`** when **`ctx.vfs`** can read it.
|
||||
- `BARE_OS_BOOT_BUNDLE_DIGEST_HEX` — Operator — Lowercase hex compared to policy **`requireBootBundleSha256Hex`** when set.
|
||||
- `BARE_OS_REQUIRE_CTX_API_MIN` — Stock kernel — Minimum **`ctx.bareOsCtxApiVersion**` semver; enforced when `**BARE_OS_BOOT_ABI_STRICT`** or strict boot policy applies.
|
||||
- `BARE_OS_REQUIRE_CTX_API_MIN` — Stock kernel — Minimum **`ctx.bareOsCtxApiVersion`** semver; enforced when **`BARE_OS_BOOT_ABI_STRICT`** or strict boot policy applies.
|
||||
- `BARE_OS_BOOT_ABI_STRICT` — Stock kernel — **`1`** exits boot when ABI minimum is not met.
|
||||
- `BARE_OS_LOADER_AUDIT` — Booter — **`1**` appends kernel extension loads to `**/run/bare-os/loader-audit.ndjson`**.
|
||||
- `BARE_OS_DELEGATE_TRACE` — Session hint — Logged in **`/proc/bare_os/kernel_program.json**` `**hooks.delegateTrace**` when `**1`**.
|
||||
- `BARE_OS_DNS_PROFILE` — Operator — Coarse DNS stance (**`system**`, `**offline-cache**`, …) surfaced under `**operatorSketches.dnsProfile**` in `**/proc/bare_os/kernel_program.json`**.
|
||||
- `BARE_OS_LOADER_AUDIT` — Booter — **`1`** appends kernel extension loads to **`/run/bare-os/loader-audit.ndjson`**.
|
||||
- `BARE_OS_DELEGATE_TRACE` — Session hint — Logged in **`/proc/bare_os/kernel_program.json`** **`hooks.delegateTrace`** when **`1`**.
|
||||
- `BARE_OS_DNS_PROFILE` — Operator — Coarse DNS stance (**`system`**, **`offline-cache`**, …) surfaced under **`operatorSketches.dnsProfile`** in **`/proc/bare_os/kernel_program.json`**.
|
||||
- `BARE_OS_KERNEL_PROGRAM_PROC_JSON` — Booter / **`/proc/bare_os/kernel_program.json`** — Optional JSON merged into the kernel program proc snapshot (non-secret).
|
||||
- `BARE_OS_GIANT_PHASE_PROGRAM_JSON` — Legacy alias for **`BARE_OS_KERNEL_PROGRAM_PROC_JSON`** (same merge semantics).
|
||||
- `MANWIDTH` — `/bin/man` — If set, wrap width for manual text (clamped `40`–`200`); overrides TTY auto width. When unset, uses TTY columns when `stdout` is a terminal, else `COLUMNS` if set, else default `72`.
|
||||
- `NO_COLOR` — `/bin/man` — If set, disable ANSI bold for section headings on a TTY
|
||||
|
||||
**Host → session passthrough** (booter copies into **`shellEnv`** when the host sets a non-empty value; canonical list in [`packages/bare-os-booter/index.js`](../../packages/bare-os-booter/index.js)): `BARE_OS_PIPELINE_MAX_STAGES`, `BARE_OS_PIPELINE_MAX_BYTES`, `BARE_OS_PIPELINE_MAX_LINES`, `BARE_OS_PIPELINE_ABS_MAX_BYTES`, `BARE_OS_PIPELINE_ABS_MAX_LINES`, `BARE_OS_SHELL_STREAMING`, `BARE_OS_SHELL_STREAMING_MULT`, `BARE_OS_STREAMING_MULTIPLIER`, `BARE_OS_SHELL_PIPEFAIL`, `BARE_OS_SHELL_PIPESTATUS`, `BARE_OS_SHELL_READ_BUILTIN`, `BARE_OS_SHELL_READ_MAX_BYTES`, `BARE_OS_SHELL_ERREXIT`, `BARE_OS_SHELL_NOUNSET`, `BARE_OS_SHELL_POSIX_MODE`, `BARE_OS_SHELL_CMDSUBST`, `BARE_OS_SHELL_CMDSUBST_MAX_BYTES`, `BARE_OS_SHELL_PARAM_EXPANSION`, `BARE_OS_SHELL_PARAM_EXPANSION_V2`, `BARE_OS_SHELL_PARAM_EXPANSION_V3`, `BARE_OS_ENV_DASH_S`, `BARE_OS_VFS_WATCH_PSEUDO`, `BARE_OS_VFS_WATCH_SWARM`, `BARE_OS_SHELL_LOCAL_DECLARE`, `BARE_OS_DIAGNOSTICS_SUBSCRIBE`, `BARE_OS_AUTOPASS_INVITE_URL`, `BARE_OS_BIN_WORKER_OFFLOAD`, `BARE_OS_BIN_WORKER_ALLOW`, `BARE_OS_BIN_WORKER_CPU_MS_MAX`, `BARE_OS_BIN_WORKER_WASM_MS_MAX`, `BARE_OS_BOOT_PROFILE`, `BARE_OS_ONBOOT`, `BARE_OS_BOOT_STRICT`, `BARE_OS_RC_D_SKIP`, `BARE_OS_BOOT_MINIMAL`, `BARE_OS_BOOT_SKIP`, `BARE_OS_BOOT_SAFE_MODE`, `BARE_OS_BOOT_TRANSACTION_JOURNAL`, `BARE_OS_BOOT_CHECKPOINT`, `BARE_OS_BOOT_DRY_RUN`, `BARE_OS_BOOT_POLICY_PATH`, `BARE_OS_BOOT_ROLLBACK_APPLY`, `BARE_OS_BOOT_BUNDLE_DIGEST_HEX`, `BARE_OS_REQUIRE_CTX_API_MIN`, `BARE_OS_BOOT_ABI_STRICT`, `BARE_OS_LOADER_AUDIT`, `BARE_OS_DELEGATE_TRACE`, `BARE_OS_DNS_PROFILE`, `BARE_OS_BOOT_TRACE`, `BARE_OS_KERNEL_PROGRAM_PROC_JSON`, `BARE_OS_GIANT_PHASE_PROGRAM_JSON`, `BARE_OS_KERNEL_SELFTEST`, `BARE_OS_SELFTEST_FORMAT`, `BARE_OS_AUDIT`, `BARE_OS_AUDIT_JSON`, `BARE_OS_AUDIT_REDACT`, `BARE_OS_IMAGE_DIGEST`, `BARE_OS_EXEC_MAX_DEPTH`, `BARE_OS_EXEC_LINE_BUDGET_MS`, `BARE_OS_TIMER_BUDGET_MS`, `BARE_OS_IPC_MAX_BYTES`, `BARE_OS_IPC_CHANNEL_MAX_BYTES`, `BARE_OS_IPC_RPC_TOKEN`, `BARE_OS_IPC_FANOUT`, `BARE_OS_IPC_JSON_MAX_BYTES`, `BARE_OS_IPC_MAX_CHANNELS`, `BARE_OS_POSIX_MQ_MAX_MSGS`, `BARE_OS_POSIX_MQ_MSG_BYTES`, `BARE_OS_IPC_NAMESPACE`, `BARE_OS_VFS_WATCH`, `BARE_OS_VFS_MAX_OPEN`, `BARE_OS_VFS_UNION_PREFIXES`, `BARE_OS_VFS_UNION_WRITE_DENY`, `BARE_OS_VFS_HYPERBLOBS_DEDUP`, `BARE_OS_VFS_BIN_CACHE`, `BARE_OS_VFS_BIN_CACHE_BLAKE2B`, `BARE_OS_VFS_WARM_CACHE_INVALIDATE_ON_APPEND`, `BARE_OS_VFS_ENFORCE_ACL`, `BARE_OS_VFS_BIN_INDEX_BUILD`, `BARE_OS_VFS_SYSTEM_IMAGE_WRITE`, `BARE_OS_BOOT_ALLOWLIST`, `BARE_OS_BOOT_MANIFEST`, `BARE_OS_BOOT_MANIFEST_SIGN`, `BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`, `BARE_OS_BOOT_POLICY`, `BARE_OS_BOOT_POLICY_STRICT`, `BARE_OS_LAZY_PERSONAL_DRIVE`, `BARE_OS_SYSTEM_REVISION_ID`, `BARE_OS_SYSTEM_REVISION_PENDING`, `BARE_OS_SYSTEM_SLOT`, `BARE_OS_DELEGATE_ALLOW`, `BARE_OS_DELEGATE_MAX_PER_MIN`, `BARE_OS_DELEGATE_MAX_CONCURRENT`, `BARE_OS_DELEGATE_GIT_MAX_PER_MIN`, `BARE_OS_DELEGATE_CURL_MAX_PER_MIN`, `BARE_OS_DELEGATE_WGET_MAX_PER_MIN`, `BARE_OS_DELEGATE_SYSTEMCTL_MAX_PER_MIN`, `BARE_OS_DELEGATE_GIT_MAX_CONCURRENT`, `BARE_OS_DELEGATE_CURL_MAX_CONCURRENT`, `BARE_OS_DELEGATE_WGET_MAX_CONCURRENT`, `BARE_OS_DELEGATE_SYSTEMCTL_MAX_CONCURRENT`, `BARE_OS_DELEGATE_AUDIT_ONLY`, `BARE_OS_DNS_ALLOWLIST`, `BARE_OS_KERNEL_HOT_RELOAD`, `BARE_OS_KERNEL_EXT_D_HOT_RELOAD`, `BARE_OS_KERNEL_EXT_GRAPH`, `BARE_OS_KERNEL_EXT_RESOLUTION_JSON_ALWAYS`, `BARE_OS_SANDBOX_SCRIPT`, `BARE_OS_SANDBOX_WORKER`, `BARE_OS_INITD_MAX_PARALLEL`, `BARE_OS_INITD_JOURNAL_MAX_LINES`, `BARE_OS_URANDOM_CRYPTO`, `BARE_OS_TELEMETRY_NDJSON`, `BARE_OS_TELEMETRY_OTEL_JSONL`, `BARE_OS_TELEMETRY_OTEL`, `BARE_OS_PROC_POLL_MS`, `BARE_OS_TIMER_EVERY_MS_MONOTONIC`, `BARE_OS_TRACE_ID`, `BARE_OS_SEED_RPC_HANDSHAKE`, `BARE_OS_SEED_CAP_STRICT`, `BARE_OS_SEED_CAP_FAIL`, `BARE_OS_OFFLINE_LKG_BOOT`, `BARE_OS_LKG_SYSTEM_KEY_HEX`, `BARE_OS_HOST_STORAGE_JSON`, `BARE_OS_BOOT_POLICY_DENY_EXEC_LINE_BUILTINS`, `BARE_OS_BOOT_POLICY_ALLOWED_CTX_METHODS`, `BARE_OS_SUBPROCESS_BRIDGE_JOBS_JSON`, `BARE_OS_IPC_AUDIT`, `BARE_OS_HTTP_ALLOWLIST`, `BARE_OS_HTTP_DENYLIST`, `BARE_OS_TLS_PIN_SHA256`, `BARE_OS_BARE_MODULES`, `BARE_OS_BARE_DRIVE_BUNDLES`, `BARE_OS_PEAR_CHANNEL`, `BARE_OS_PEAR_RELEASE`, `PEAR_CHANNEL`, `BARE_OS_FIND_EXEC_MAX`, `BARE_OS_XARGS_MAX_PROCS`, `BARE_OS_YES_MAX_LINES`, `BARE_OS_SHUF_MAX_LINES`, `BARE_OS_SPLIT_MAX_FILES`, `BARE_OS_SSH_BIND_ALL`, `BARE_OS_SSH_LISTEN_PORT`, `BARE_OS_NPROC`, `BARE_OS_BLIND_BOOTSTRAP_URL`, `BARE_OS_BLIND_BOOTSTRAP_JSON`, `BARE_OS_MIRROR_READ_KEY`, `BARE_OS_PEER_FIREWALL_E2E_JSON`, `BARE_OS_PEAR_SECURE_ENCLAVE_JSON`, `BARE_OS_ACCOUNT_KEY_ROTATION_STATE_JSON`, `BARE_OS_PEAR_TRUST_JSON`, `BARE_OS_HOST_BUNDLE_EVALUATE`, `BARE_OS_WASM_KERNEL`, `BARE_OS_WASM_KERNEL_SYSCALL`, `BARE_OS_WASM_KERNEL_MONOTONIC_MS`, `BARE_OS_WASM_KERNEL_HOSTNAME_IMPORT`, **`TERM**`, `**COLORTERM`**. *(Many additional operator JSON pointers and version pins are also copied from the same loop; see source.)*
|
||||
**Host → session passthrough** (booter copies into **`shellEnv`** when the host sets a non-empty value; canonical list in [`packages/bare-os-booter/index.js`](../../packages/bare-os-booter/index.js)): `BARE_OS_PIPELINE_MAX_STAGES`, `BARE_OS_PIPELINE_MAX_BYTES`, `BARE_OS_PIPELINE_MAX_LINES`, `BARE_OS_PIPELINE_ABS_MAX_BYTES`, `BARE_OS_PIPELINE_ABS_MAX_LINES`, `BARE_OS_SHELL_STREAMING`, `BARE_OS_SHELL_STREAMING_MULT`, `BARE_OS_STREAMING_MULTIPLIER`, `BARE_OS_SHELL_PIPEFAIL`, `BARE_OS_SHELL_PIPESTATUS`, `BARE_OS_SHELL_READ_BUILTIN`, `BARE_OS_SHELL_READ_MAX_BYTES`, `BARE_OS_SHELL_ERREXIT`, `BARE_OS_SHELL_NOUNSET`, `BARE_OS_SHELL_POSIX_MODE`, `BARE_OS_SHELL_CMDSUBST`, `BARE_OS_SHELL_CMDSUBST_MAX_BYTES`, `BARE_OS_SHELL_PARAM_EXPANSION`, `BARE_OS_SHELL_PARAM_EXPANSION_V2`, `BARE_OS_SHELL_PARAM_EXPANSION_V3`, `BARE_OS_ENV_DASH_S`, `BARE_OS_VFS_WATCH_PSEUDO`, `BARE_OS_VFS_WATCH_SWARM`, `BARE_OS_SHELL_LOCAL_DECLARE`, `BARE_OS_DIAGNOSTICS_SUBSCRIBE`, `BARE_OS_AUTOPASS_INVITE_URL`, `BARE_OS_BIN_WORKER_OFFLOAD`, `BARE_OS_BIN_WORKER_ALLOW`, `BARE_OS_BIN_WORKER_CPU_MS_MAX`, `BARE_OS_BIN_WORKER_WASM_MS_MAX`, `BARE_OS_BOOT_PROFILE`, `BARE_OS_ONBOOT`, `BARE_OS_BOOT_STRICT`, `BARE_OS_RC_D_SKIP`, `BARE_OS_BOOT_MINIMAL`, `BARE_OS_BOOT_SKIP`, `BARE_OS_BOOT_SAFE_MODE`, `BARE_OS_BOOT_TRANSACTION_JOURNAL`, `BARE_OS_BOOT_CHECKPOINT`, `BARE_OS_BOOT_DRY_RUN`, `BARE_OS_BOOT_POLICY_PATH`, `BARE_OS_BOOT_ROLLBACK_APPLY`, `BARE_OS_BOOT_BUNDLE_DIGEST_HEX`, `BARE_OS_REQUIRE_CTX_API_MIN`, `BARE_OS_BOOT_ABI_STRICT`, `BARE_OS_LOADER_AUDIT`, `BARE_OS_DELEGATE_TRACE`, `BARE_OS_DNS_PROFILE`, `BARE_OS_BOOT_TRACE`, `BARE_OS_KERNEL_PROGRAM_PROC_JSON`, `BARE_OS_GIANT_PHASE_PROGRAM_JSON`, `BARE_OS_KERNEL_SELFTEST`, `BARE_OS_SELFTEST_FORMAT`, `BARE_OS_AUDIT`, `BARE_OS_AUDIT_JSON`, `BARE_OS_AUDIT_REDACT`, `BARE_OS_IMAGE_DIGEST`, `BARE_OS_EXEC_MAX_DEPTH`, `BARE_OS_EXEC_LINE_BUDGET_MS`, `BARE_OS_TIMER_BUDGET_MS`, `BARE_OS_IPC_MAX_BYTES`, `BARE_OS_IPC_CHANNEL_MAX_BYTES`, `BARE_OS_IPC_RPC_TOKEN`, `BARE_OS_IPC_FANOUT`, `BARE_OS_IPC_JSON_MAX_BYTES`, `BARE_OS_IPC_MAX_CHANNELS`, `BARE_OS_POSIX_MQ_MAX_MSGS`, `BARE_OS_POSIX_MQ_MSG_BYTES`, `BARE_OS_IPC_NAMESPACE`, `BARE_OS_VFS_WATCH`, `BARE_OS_VFS_MAX_OPEN`, `BARE_OS_VFS_UNION_PREFIXES`, `BARE_OS_VFS_UNION_WRITE_DENY`, `BARE_OS_VFS_HYPERBLOBS_DEDUP`, `BARE_OS_VFS_BIN_CACHE`, `BARE_OS_VFS_BIN_CACHE_BLAKE2B`, `BARE_OS_VFS_WARM_CACHE_INVALIDATE_ON_APPEND`, `BARE_OS_VFS_ENFORCE_ACL`, `BARE_OS_VFS_BIN_INDEX_BUILD`, `BARE_OS_VFS_SYSTEM_IMAGE_WRITE`, `BARE_OS_BOOT_ALLOWLIST`, `BARE_OS_BOOT_MANIFEST`, `BARE_OS_BOOT_MANIFEST_SIGN`, `BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`, `BARE_OS_BOOT_POLICY`, `BARE_OS_BOOT_POLICY_STRICT`, `BARE_OS_LAZY_PERSONAL_DRIVE`, `BARE_OS_SYSTEM_REVISION_ID`, `BARE_OS_SYSTEM_REVISION_PENDING`, `BARE_OS_SYSTEM_SLOT`, `BARE_OS_DELEGATE_ALLOW`, `BARE_OS_DELEGATE_MAX_PER_MIN`, `BARE_OS_DELEGATE_MAX_CONCURRENT`, `BARE_OS_DELEGATE_GIT_MAX_PER_MIN`, `BARE_OS_DELEGATE_CURL_MAX_PER_MIN`, `BARE_OS_DELEGATE_WGET_MAX_PER_MIN`, `BARE_OS_DELEGATE_SYSTEMCTL_MAX_PER_MIN`, `BARE_OS_DELEGATE_GIT_MAX_CONCURRENT`, `BARE_OS_DELEGATE_CURL_MAX_CONCURRENT`, `BARE_OS_DELEGATE_WGET_MAX_CONCURRENT`, `BARE_OS_DELEGATE_SYSTEMCTL_MAX_CONCURRENT`, `BARE_OS_DELEGATE_AUDIT_ONLY`, `BARE_OS_DNS_ALLOWLIST`, `BARE_OS_KERNEL_HOT_RELOAD`, `BARE_OS_KERNEL_EXT_D_HOT_RELOAD`, `BARE_OS_KERNEL_EXT_GRAPH`, `BARE_OS_KERNEL_EXT_RESOLUTION_JSON_ALWAYS`, `BARE_OS_SANDBOX_SCRIPT`, `BARE_OS_SANDBOX_WORKER`, `BARE_OS_INITD_MAX_PARALLEL`, `BARE_OS_INITD_JOURNAL_MAX_LINES`, `BARE_OS_URANDOM_CRYPTO`, `BARE_OS_TELEMETRY_NDJSON`, `BARE_OS_TELEMETRY_OTEL_JSONL`, `BARE_OS_TELEMETRY_OTEL`, `BARE_OS_PROC_POLL_MS`, `BARE_OS_TIMER_EVERY_MS_MONOTONIC`, `BARE_OS_TRACE_ID`, `BARE_OS_SEED_RPC_HANDSHAKE`, `BARE_OS_SEED_CAP_STRICT`, `BARE_OS_SEED_CAP_FAIL`, `BARE_OS_OFFLINE_LKG_BOOT`, `BARE_OS_LKG_SYSTEM_KEY_HEX`, `BARE_OS_HOST_STORAGE_JSON`, `BARE_OS_BOOT_POLICY_DENY_EXEC_LINE_BUILTINS`, `BARE_OS_BOOT_POLICY_ALLOWED_CTX_METHODS`, `BARE_OS_SUBPROCESS_BRIDGE_JOBS_JSON`, `BARE_OS_IPC_AUDIT`, `BARE_OS_HTTP_ALLOWLIST`, `BARE_OS_HTTP_DENYLIST`, `BARE_OS_TLS_PIN_SHA256`, `BARE_OS_BARE_MODULES`, `BARE_OS_BARE_DRIVE_BUNDLES`, `BARE_OS_PEAR_CHANNEL`, `BARE_OS_PEAR_RELEASE`, `PEAR_CHANNEL`, `BARE_OS_FIND_EXEC_MAX`, `BARE_OS_XARGS_MAX_PROCS`, `BARE_OS_YES_MAX_LINES`, `BARE_OS_SHUF_MAX_LINES`, `BARE_OS_SPLIT_MAX_FILES`, `BARE_OS_SSH_BIND_ALL`, `BARE_OS_SSH_LISTEN_PORT`, `BARE_OS_NPROC`, `BARE_OS_BLIND_BOOTSTRAP_URL`, `BARE_OS_BLIND_BOOTSTRAP_JSON`, `BARE_OS_MIRROR_READ_KEY`, `BARE_OS_PEER_FIREWALL_E2E_JSON`, `BARE_OS_PEAR_SECURE_ENCLAVE_JSON`, `BARE_OS_ACCOUNT_KEY_ROTATION_STATE_JSON`, `BARE_OS_PEAR_TRUST_JSON`, `BARE_OS_HOST_BUNDLE_EVALUATE`, `BARE_OS_WASM_KERNEL`, `BARE_OS_WASM_KERNEL_SYSCALL`, `BARE_OS_WASM_KERNEL_MONOTONIC_MS`, `BARE_OS_WASM_KERNEL_HOSTNAME_IMPORT`, **`TERM`**, **`COLORTERM`**. *(Many additional operator JSON pointers and version pins are also copied from the same loop; see source.)*
|
||||
|
||||
**Booter default session (host left these empty):** the stock booter assigns **`BARE_OS_SHELL_STREAMING=1**`, `**BARE_OS_SHELL_STREAMING_MULT=2**`, `**BARE_OS_PIPELINE_MAX_BYTES=536870912**`, `**BARE_OS_PIPELINE_MAX_LINES=2000000**`, `**BARE_OS_INITD_MAX_PARALLEL=4**` (parallel starts per DAG level), `**BARE_OS_SHELL_CMDSUBST=1**`, `**BARE_OS_VFS_BIN_CACHE=1**`, and `**BARE_OS_TELEMETRY_NDJSON=/var/log/bare-os/telemetry.ndjson**`. Exec **audit** sinks (`**BARE_OS_AUDIT**`, `**BARE_OS_AUDIT_JSON`**, …) remain off unless the host sets them. Override any key from the host before boot.
|
||||
**Booter default session (host left these empty):** the stock booter assigns **`BARE_OS_SHELL_STREAMING=1`**, **`BARE_OS_SHELL_STREAMING_MULT=2`**, **`BARE_OS_PIPELINE_MAX_BYTES=536870912`**, **`BARE_OS_PIPELINE_MAX_LINES=2000000`**, **`BARE_OS_INITD_MAX_PARALLEL=4`** (parallel starts per DAG level), **`BARE_OS_SHELL_CMDSUBST=1`**, **`BARE_OS_VFS_BIN_CACHE=1`**, and **`BARE_OS_TELEMETRY_NDJSON=/var/log/bare-os/telemetry.ndjson`**. Exec **audit** sinks (**`BARE_OS_AUDIT`**, **`BARE_OS_AUDIT_JSON`**, …) remain off unless the host sets them. Override any key from the host before boot.
|
||||
|
||||
- `BARE_OS_VFS_UNION_PREFIXES` — Booter / VFS — Comma-separated logical path prefixes where **`readFile`** may union system + overlay sources.
|
||||
- `BARE_OS_VFS_UNION_WRITE_DENY` — Booter / VFS — When **`1**` / `**true**`, block `**writeFile**` / `**unlink`** on paths under union read prefixes (read-only union overlay).
|
||||
- `BARE_OS_IPC_CHANNEL_MAX_BYTES` — Booter / IPC — Optional JSON map **`{"fifoName": maxBytes}**` (or legacy comma form) capping buffered bytes per FIFO name under `**/run/bare-os/ipc/`**.
|
||||
- `BARE_OS_IPC_MAX_CHANNELS` — Booter / IPC — Cap distinct FIFO channel keys (default **4096** when unset); host may set a lower or higher bound via passthrough. Exceeding the quota makes **`mkfifo**` fail with `**bare-os ipc: channel quota exceeded**`. Telemetry appears under `**ipcTelemetry.telemetry**` in `**/proc/bare_os/metrics_live.json`**.
|
||||
- `BARE_OS_PIPELINE_ABS_MAX_BYTES` — Shell / booter — Upper bound on simulated pipeline **byte** capture **after** the streaming multiplier is applied (default **536870912** = 512 MiB). Works with **`BARE_OS_PIPELINE_MAX_BYTES**` and `**BARE_OS_SHELL_STREAMING**` / `**BARE_OS_SHELL_STREAMING_MULT`**.
|
||||
- `BARE_OS_VFS_UNION_WRITE_DENY` — Booter / VFS — When **`1`** / **`true`**, block **`writeFile`** / **`unlink`** on paths under union read prefixes (read-only union overlay).
|
||||
- `BARE_OS_IPC_CHANNEL_MAX_BYTES` — Booter / IPC — Optional JSON map **`{"fifoName": maxBytes}**` (or legacy comma form) capping buffered bytes per FIFO name under **`/run/bare-os/ipc/`**.
|
||||
- `BARE_OS_IPC_MAX_CHANNELS` — Booter / IPC — Cap distinct FIFO channel keys (default **4096** when unset); host may set a lower or higher bound via passthrough. Exceeding the quota makes **`mkfifo`** fail with `**bare-os ipc: channel quota exceeded**`. Telemetry appears under **`ipcTelemetry.telemetry`** in **`/proc/bare_os/metrics_live.json`**.
|
||||
- `BARE_OS_PIPELINE_ABS_MAX_BYTES` — Shell / booter — Upper bound on simulated pipeline **byte** capture **after** the streaming multiplier is applied (default **536870912** = 512 MiB). Works with **`BARE_OS_PIPELINE_MAX_BYTES`** and **`BARE_OS_SHELL_STREAMING`** / **`BARE_OS_SHELL_STREAMING_MULT`**.
|
||||
- `BARE_OS_PIPELINE_ABS_MAX_LINES` — Shell / booter — Upper bound on simulated pipeline **line** capture after the multiplier (default **2000000**).
|
||||
- `BARE_OS_POSIX_MQ_MAX_MSGS` — Booter / IPC — Default **`maxmsg**` for POSIX `**mq_open`** when the caller omits attrs (subject to internal ceilings); optional host passthrough.
|
||||
- `BARE_OS_POSIX_MQ_MSG_BYTES` — Booter / IPC — Default per-message **`maxBytes**` for `**mq_open`** when attrs are omitted.
|
||||
- `BARE_OS_VFS_MAX_OPEN` — Booter — When set on the host (positive integer), guest **`/proc/bare_os/rlimits.json**` maps `**RLIMIT_NOFILE**` `**cur**` and `**max**` to that value (advisory mirror for scripts; not a hard kernel `**ulimit`**).
|
||||
- `BARE_OS_VFS_BIN_CACHE` — VFS — When **`1**` / `**true**`, LRU read cache for `**/bin**`; invalidated on `**vfs.watch**` when enabled. Stock booter seeds `**1**` when unset (set `**0**` / `**false`** on the host to disable).
|
||||
- `BARE_OS_VFS_BIN_CACHE_BLAKE2B` — VFS — When **`1**` / `**true**` with `**BARE_OS_VFS_BIN_CACHE**`, `**/bin**` cache entries are keyed by **BLAKE2b** content digests (via `**bare-crypto`**) for deduplication across paths within the LRU budget.
|
||||
- `BARE_OS_VFS_ENFORCE_ACL` — VFS — When **`1**` / `**true**`, `**PATH.bare_acl**` sidecars (same text as `**getfacl` / `setfacl**`) can deny reads/writes on the personal drive. Lines `**user::**`, `**user:UID:**`, `**group::**`, `**group:GID:**`, `**other::**`, and `**mask::**` are interpreted with Linux-style **mask** capping named users, named groups, and `**group::**`; `**user::**` and `**other::**` are not masked. Object owner/group default to `**UID` / `GID**`; override with `**BARE_OS_ACL_OBJECT_UID**` / `**BARE_OS_ACL_OBJECT_GID**` when inode metadata differs. See `**bare-os-vfs-acl-enforce.js`**.
|
||||
- `BARE_OS_SHELL_LOOP_CONTROL` — Shell — When **`1**` / `**true**`, `**break**` and `**continue**` apply inside `**while**` / `**for**` (bounded by `**BARE_OS_SHELL_LOOP_MAX`**).
|
||||
- `BARE_OS_SHELL_UNTIL` — Shell — When **`1**` / `**true**`, enables `**until …; do …; done**` (condition inverted vs `**while**`; same `**BARE_OS_SHELL_LOOP_MAX`** cap).
|
||||
- `BARE_OS_POSIX_MQ_MAX_MSGS` — Booter / IPC — Default **`maxmsg`** for POSIX **`mq_open`** when the caller omits attrs (subject to internal ceilings); optional host passthrough.
|
||||
- `BARE_OS_POSIX_MQ_MSG_BYTES` — Booter / IPC — Default per-message **`maxBytes`** for **`mq_open`** when attrs are omitted.
|
||||
- `BARE_OS_VFS_MAX_OPEN` — Booter — When set on the host (positive integer), guest **`/proc/bare_os/rlimits.json`** maps **`RLIMIT_NOFILE`** **`cur`** and **`max`** to that value (advisory mirror for scripts; not a hard kernel **`ulimit`**).
|
||||
- `BARE_OS_VFS_BIN_CACHE` — VFS — When **`1`** / **`true`**, LRU read cache for **`/bin`**; invalidated on **`vfs.watch`** when enabled. Stock booter seeds **`1`** when unset (set **`0`** / **`false`** on the host to disable).
|
||||
- `BARE_OS_VFS_BIN_CACHE_BLAKE2B` — VFS — When **`1`** / **`true`** with **`BARE_OS_VFS_BIN_CACHE`**, **`/bin`** cache entries are keyed by **BLAKE2b** content digests (via **`bare-crypto`**) for deduplication across paths within the LRU budget.
|
||||
- `BARE_OS_VFS_ENFORCE_ACL` — VFS — When **`1`** / **`true`**, **`PATH.bare_acl`** sidecars (same text as `**getfacl` / `setfacl**`) can deny reads/writes on the personal drive. Lines **`user::`**, **`user:UID:`**, **`group::`**, **`group:GID:`**, **`other::`**, and **`mask::`** are interpreted with Linux-style **mask** capping named users, named groups, and **`group::`**; **`user::`** and **`other::`** are not masked. Object owner/group default to `**UID` / `GID**`; override with **`BARE_OS_ACL_OBJECT_UID`** / **`BARE_OS_ACL_OBJECT_GID`** when inode metadata differs. See **`bare-os-vfs-acl-enforce.js`**.
|
||||
- `BARE_OS_SHELL_LOOP_CONTROL` — Shell — When **`1`** / **`true`**, **`break`** and **`continue`** apply inside **`while`** / **`for`** (bounded by **`BARE_OS_SHELL_LOOP_MAX`**).
|
||||
- `BARE_OS_SHELL_UNTIL` — Shell — When **`1`** / **`true`**, enables `**until …; do …; done**` (condition inverted vs **`while`**; same **`BARE_OS_SHELL_LOOP_MAX`** cap).
|
||||
- `BARE_OS_VFS_SYSTEM_RO_ALIAS` — VFS — Absolute path prefix that maps read-only to the system Hyperdrive (listed in **`/proc/mounts`**).
|
||||
- `BARE_OS_VFS_LIB_BARE_CACHE` — VFS — When **`1**` / `**true**`, extend warm read-through cache to hot `**/lib/bare**` paths (same LRU style as `**/bin**` when bin cache is on). When a batch write updates only `**lib/bare/bare-module-manifest.json**`, the booter evicts `**/lib/bare/bundles/<ctxKey>.js**` entries for `**bundle:true**` manifest rows instead of flushing the whole warm cache; `**ctx.bareOsInvalidateWarmReadCachesFromBareManifestJson`** applies the same parse rules.
|
||||
- `BARE_OS_VFS_WARM_BATCH_SELECTIVE` — Booter — When **`1**` / `**true**`, `**ctx.bareOsVfsBatchWrite**` evicts individual `**/bin/***` and `**/lib/bare/***` warm-cache paths touched in the batch via `**vfs.bareOsEvictWarmReadLogicalPath**` instead of `**bareOsClearWarmReadCaches**`, except `**boot/init.js**` / `**lib/init/*`** puts still force a full clear for safety.
|
||||
- `BARE_OS_BOOT_PERF_DETAIL` — Stock kernel + booter — Per-stage **`boot-perf.json**` (**schema 2**) with optional `**bare-hrtime**` monotonic samples; when `**1**` on the host, the booter also logs `**bare_stdlib_merge_ns**` (wall `**hrtime**` delta for `**maybeMergeBareFromDrive**`) via structured host booter logging. Under `**pear://**`, `**loadBareModuleManifest**` does not perform disk I/O for the host import list (embedded `**bare-module-manifest.data.mjs**`); the `**bare_stdlib_merge_ns`** line still reflects drive bundle merge work only.
|
||||
- `BARE_OS_VFS_LIB_BARE_CACHE` — VFS — When **`1`** / **`true`**, extend warm read-through cache to hot **`/lib/bare`** paths (same LRU style as **`/bin`** when bin cache is on). When a batch write updates only **`lib/bare/bare-module-manifest.json`**, the booter evicts **`/lib/bare/bundles/<ctxKey>.js`** entries for **`bundle:true`** manifest rows instead of flushing the whole warm cache; **`ctx.bareOsInvalidateWarmReadCachesFromBareManifestJson`** applies the same parse rules.
|
||||
- `BARE_OS_VFS_WARM_BATCH_SELECTIVE` — Booter — When **`1`** / **`true`**, **`ctx.bareOsVfsBatchWrite`** evicts individual **`/bin/*`** and **`/lib/bare/*`** warm-cache paths touched in the batch via **`vfs.bareOsEvictWarmReadLogicalPath`** instead of **`bareOsClearWarmReadCaches`**, except **`boot/init.js`** / **`lib/init/*`** puts still force a full clear for safety.
|
||||
- `BARE_OS_BOOT_PERF_DETAIL` — Stock kernel + booter — Per-stage **`boot-perf.json`** (**schema 2**) with optional **`bare-hrtime`** monotonic samples; when **`1`** on the host, the booter also logs **`bare_stdlib_merge_ns`** (wall **`hrtime`** delta for **`maybeMergeBareFromDrive`**) via structured host booter logging. Under **`pear://`**, **`loadBareModuleManifest`** does not perform disk I/O for the host import list (embedded **`bare-module-manifest.data.mjs`**); the **`bare_stdlib_merge_ns`** line still reflects drive bundle merge work only.
|
||||
- `BARE_OS_BOOT_BARE_STDLIB_RESOLUTION_MS` — Booter — Milliseconds for drive **`ctx.bare`** merge + optional host resolve before the guest kernel starts; copied into session env by the stock booter.
|
||||
- `BARE_OS_BOOT_BUDGET_MS_BARE_STDLIB` — Operator — Optional budget (ms) for the value above; when set and exceeded, the stock kernel logs **`bootBudgetBareStdlibExceeded**`, sets `**BARE_OS_BOOT_BUDGET_STDLIB_***`, and records `**bareStdlibBudgetWarning**` in `**/run/bare-os/boot-perf.json`** (**schema 3** when stdlib telemetry fields are present).
|
||||
- `BARE_OS_BOOT_BUDGET_STRICT` — Stock kernel — With **`BARE_OS_BOOT_POLICY_STRICT**`, calls `**bareOsRequestBooterExit(1)**` after a cold or bare-stdlib budget violation (after appending `**bootBudgetViolation**` metadata to `**boot-transaction.ndjson`** when journaling is enabled).
|
||||
- `BARE_OS_KERNEL_EXT_GRAPH` — Stock kernel — Write **`/run/bare-os/kernel-ext-graph.json**` after `**kernel.ext.d`** ordering.
|
||||
- `BARE_OS_KERNEL_EXT_RESOLUTION_JSON_ALWAYS` — Stock kernel — When **`1**` / `**true**`, `**/run/bare-os/kernel-ext-resolution.json**` is written even when resolution succeeds without diagnostics (default omits the file on clean success). Schema **3** adds `**providesInvalidSemver**`, `**providesVersionConflicts**`, `**provideNameToOwner`**, and richer ordering metadata.
|
||||
- `BARE_OS_INIT_DEFER_KERNEL_EXT_GRAPH` — Stock kernel — When **`1**` / `**true**`, skip writing `**/run/bare-os/kernel-ext-graph.json**` during early init (defer to a later boot phase when `**BARE_OS_KERNEL_EXT_GRAPH**` is on); reduces init bundle work on tight `**BARE_OS_BOOT_BUDGET_MS_COLD`** budgets.
|
||||
- `BARE_OS_BIN_HYPERBEE_INDEX` — Booter — When **`1**` / `**true**`, writes `**/.bare-os/index/bin-hyperbee-hint.json**` (**schema 2**, `**namesDigest**`) and `**/.bare-os/indexes/hyperbee_status.json**`; optional `**hyperbee**` import probe; refreshed when `**bareOsVfsBatchWrite**` touches `**bin/*`** (same as manifest).
|
||||
- `BARE_OS_HYPERBEE_GUEST_INDEX` — Booter / extensions — When **`1**` / `**true**`, `**ctx.bareOsHyperbeeGuestHint()`** documents optional **hyperbee2**-style guest indexes for P2P metadata (host/extension must supply the module; see [ADR-hyperbee-guest-index.md](../architecture/ADR-hyperbee-guest-index.md)).
|
||||
- `BARE_OS_PEAR_INSPECT` — Booter — When **`1**` / `**true**`, emit `**bare-os:pear-inspect-snapshot**` on the host process after `**ctx`** is wired (non-secret snapshot only).
|
||||
- `BARE_OS_VFS_BIN_INDEX_BUILD` — Booter — When **`1**` / `**true**`, writes `**/.bare-os/index/bin-manifest.json**` (**schema 2**, `**namesDigest**`) on the personal drive for large images (see `**bare-os-bin-index.js**`); `**bareOsVfsBatchWrite**` on `**bin/*`** rebuilds it when enabled.
|
||||
- `BARE_OS_VFS_SYSTEM_IMAGE_WRITE` — Booter / VFS — When **`1**` / `**true**`, allow `**vfs.writeFile**` on the **system** Hyperdrive for paths that are normally read-only (`**/bin/***`, `**/lib/***`, …) so hosts can mutate the image or run warm-cache tests; default remains guest read-only. ACLs and `**/.bare`** guest rules still apply.
|
||||
- `BARE_OS_BOOT_BUDGET_MS_BARE_STDLIB` — Operator — Optional budget (ms) for the value above; when set and exceeded, the stock kernel logs **`bootBudgetBareStdlibExceeded`**, sets **`BARE_OS_BOOT_BUDGET_STDLIB_*`**, and records **`bareStdlibBudgetWarning`** in **`/run/bare-os/boot-perf.json`** (**schema 3** when stdlib telemetry fields are present).
|
||||
- `BARE_OS_BOOT_BUDGET_STRICT` — Stock kernel — With **`BARE_OS_BOOT_POLICY_STRICT`**, calls `**bareOsRequestBooterExit(1)**` after a cold or bare-stdlib budget violation (after appending **`bootBudgetViolation`** metadata to **`boot-transaction.ndjson`** when journaling is enabled).
|
||||
- `BARE_OS_KERNEL_EXT_GRAPH` — Stock kernel — Write **`/run/bare-os/kernel-ext-graph.json`** after **`kernel.ext.d`** ordering.
|
||||
- `BARE_OS_KERNEL_EXT_RESOLUTION_JSON_ALWAYS` — Stock kernel — When **`1`** / **`true`**, **`/run/bare-os/kernel-ext-resolution.json`** is written even when resolution succeeds without diagnostics (default omits the file on clean success). Schema **3** adds **`providesInvalidSemver`**, **`providesVersionConflicts`**, **`provideNameToOwner`**, and richer ordering metadata.
|
||||
- `BARE_OS_INIT_DEFER_KERNEL_EXT_GRAPH` — Stock kernel — When **`1`** / **`true`**, skip writing **`/run/bare-os/kernel-ext-graph.json`** during early init (defer to a later boot phase when **`BARE_OS_KERNEL_EXT_GRAPH`** is on); reduces init bundle work on tight **`BARE_OS_BOOT_BUDGET_MS_COLD`** budgets.
|
||||
- `BARE_OS_BIN_HYPERBEE_INDEX` — Booter — When **`1`** / **`true`**, writes **`/.bare-os/index/bin-hyperbee-hint.json`** (**schema 2**, **`namesDigest`**) and **`/.bare-os/indexes/hyperbee_status.json`**; optional **`hyperbee`** import probe; refreshed when **`bareOsVfsBatchWrite`** touches **`bin/*`** (same as manifest).
|
||||
- `BARE_OS_HYPERBEE_GUEST_INDEX` — Booter / extensions — When **`1`** / **`true`**, `**ctx.bareOsHyperbeeGuestHint()`** documents optional **hyperbee2**-style guest indexes for P2P metadata (host/extension must supply the module; see [ADR-hyperbee-guest-index.md](../architecture/ADR-hyperbee-guest-index.md)).
|
||||
- `BARE_OS_PEAR_INSPECT` — Booter — When **`1`** / **`true`**, emit **`bare-os:pear-inspect-snapshot`** on the host process after **`ctx`** is wired (non-secret snapshot only).
|
||||
- `BARE_OS_VFS_BIN_INDEX_BUILD` — Booter — When **`1`** / **`true`**, writes **`/.bare-os/index/bin-manifest.json`** (**schema 2**, **`namesDigest`**) on the personal drive for large images (see **`bare-os-bin-index.js`**); **`bareOsVfsBatchWrite`** on **`bin/*`** rebuilds it when enabled.
|
||||
- `BARE_OS_VFS_SYSTEM_IMAGE_WRITE` — Booter / VFS — When **`1`** / **`true`**, allow **`vfs.writeFile`** on the **system** Hyperdrive for paths that are normally read-only (**`/bin/*`**, **`/lib/*`**, …) so hosts can mutate the image or run warm-cache tests; default remains guest read-only. ACLs and **`/.bare`** guest rules still apply.
|
||||
- `BARE_OS_BOOT_MANIFEST` — Stock kernel — Enable digest check of **`/etc/bare-os/boot.manifest.json`**.
|
||||
- `BARE_OS_BOOT_MANIFEST_SIGN` — Stock kernel + booter — When **`1**`, require valid Ed25519 signature file `**/etc/bare-os/boot.manifest.sig**` (see `**BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`**).
|
||||
- `BARE_OS_BOOT_MANIFEST_SIGN` — Stock kernel + booter — When **`1`**, require valid Ed25519 signature file **`/etc/bare-os/boot.manifest.sig`** (see **`BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`**).
|
||||
- `BARE_OS_BOOT_MANIFEST_PUBKEY_HEX` — Booter / kernel — 64 hex chars — public key for signed boot manifest verification.
|
||||
- `BARE_OS_BOOT_POLICY` — Stock kernel — When **`1**` / `**true**`, merge `**skipPhases**` / `**denyBootPhases**` from `**/etc/bare-os/boot.policy.json**`; optional `**minKernelCapabilitiesPrimary**` / `**requireSeedCaps**`; v2 `**maxExecLineDepth**`, `**denyEnvKeys**`, `**requireProcNodes**`; v3 `**requireKernelCapabilitiesExtendedSeedingPlatform**`, `**requireKernelCapabilitiesRlimitsDelegatesShell**`, `**allowedPearIpcChannels**`, `**denyVfsPrefixes**`, `**maxInitdRestartsPerUnit**`; v4 `**requireKernelCapabilitiesOfflineNetExtensions**`, `**denyExecLineBuiltins**`, `**allowedCtxMethods**` (see `**kernel/etc/bare-os/boot.policy.example.json`** and **[`docs/schemas/boot.policy.schema.json`](../schemas/boot.policy.schema.json)**).
|
||||
- `BARE_OS_BOOT_POLICY_STRICT` — Stock kernel — When **`1**`, abort boot if `**minKernelCapabilitiesPrimary**` or `**requireSeedCaps`** checks fail.
|
||||
- `BARE_OS_BOOT_POLICY` — Stock kernel — When **`1`** / **`true`**, merge **`skipPhases`** / **`denyBootPhases`** from **`/etc/bare-os/boot.policy.json`**; optional **`minKernelCapabilitiesPrimary`** / **`requireSeedCaps`**; v2 **`maxExecLineDepth`**, **`denyEnvKeys`**, **`requireProcNodes`**; v3 **`requireKernelCapabilitiesExtendedSeedingPlatform`**, **`requireKernelCapabilitiesRlimitsDelegatesShell`**, **`allowedPearIpcChannels`**, **`denyVfsPrefixes`**, **`maxInitdRestartsPerUnit`**; v4 **`requireKernelCapabilitiesOfflineNetExtensions`**, **`denyExecLineBuiltins`**, **`allowedCtxMethods`** (see **`kernel/etc/bare-os/boot.policy.example.json`** and **[`docs/schemas/boot.policy.schema.json`](../schemas/boot.policy.schema.json)**).
|
||||
- `BARE_OS_BOOT_POLICY_STRICT` — Stock kernel — When **`1`**, abort boot if **`minKernelCapabilitiesPrimary`** or **`requireSeedCaps`** checks fail.
|
||||
- `BARE_OS_BOOT_POLICY_DENY_VFS` — Stock kernel / **`boot.policy` v3** — Comma-separated absolute prefixes; VFS denies read/write/stat/readdir/chdir/unlink under them (set from **`denyVfsPrefixes`**).
|
||||
- `BARE_OS_BOOT_POLICY_PEAR_IPC_CHANNELS` — Stock kernel / **`boot.policy` v3** — Comma-separated Pear IPC channel allowlist for **`ctx.bareOsPearIpcEmit**` (from `**allowedPearIpcChannels`**).
|
||||
- `BARE_OS_BOOT_POLICY_PEAR_IPC_CHANNELS` — Stock kernel / **`boot.policy` v3** — Comma-separated Pear IPC channel allowlist for **`ctx.bareOsPearIpcEmit`** (from **`allowedPearIpcChannels`**).
|
||||
- `BARE_OS_LAZY_PERSONAL_DRIVE` — Booter — When **`1`**, defer mounting the personal Hyperdrive until session setup (after kernel bytes are loaded).
|
||||
- `BARE_OS_SYSTEM_REVISION_ID` / `BARE_OS_SYSTEM_REVISION_PENDING` / `BARE_OS_SYSTEM_SLOT` — Booter — Pear-style hints exposed as **`ctx.bareOsSystemRevision`**.
|
||||
- `BARE_OS_PEAR_UPDATER_MODULE` — Booter — ESM specifier (path, `file:`, `pear:`, `http(s):`) for Pear updater state; **`ctx.bareOsPearUpdaterDelegate()**` (async) dynamic-imports it and invokes `**getPearUpdaterState**`, `**bareOsPearUpdaterSnapshot**`, or `**default**`. Bare/Pear delegates must avoid static `**node:`** imports — follow the same policy as booter sources; see **[`docs/examples/pear-updater-delegate-minimal.mjs`](../../docs/examples/pear-updater-delegate-minimal.mjs)**.
|
||||
- `BARE_OS_PEAR_UPDATER_MODULE` — Booter — ESM specifier (path, `file:`, `pear:`, `http(s):`) for Pear updater state; **`ctx.bareOsPearUpdaterDelegate()**` (async) dynamic-imports it and invokes **`getPearUpdaterState`**, **`bareOsPearUpdaterSnapshot`**, or **`default`**. Bare/Pear delegates must avoid static **`node:`** imports — follow the same policy as booter sources; see **[`docs/examples/pear-updater-delegate-minimal.mjs`](../../docs/examples/pear-updater-delegate-minimal.mjs)**.
|
||||
- `BARE_OS_PEAR_UPDATER_DELEGATE` — Booter — Alias for **`BARE_OS_PEAR_UPDATER_MODULE`**.
|
||||
- `BARE_OS_PEAR_UPDATER_SNAPSHOT_JSON` — Booter — Non-secret JSON string; when set, **`ctx.bareOsPearUpdaterDelegate()**` returns `**{ ok: true, snapshot: … }`** without loading a module (operator / CI).
|
||||
- `BARE_OS_PEAR_UPDATER_AUDIT` — Booter / host — When **`1**`, operators may append Pear updater delegate results to the host audit NDJSON chain (see `**ctx.bareOsPearUpdaterDelegate()**` `**integrationHints`** and handbook ch.7).
|
||||
- `BARE_OS_DELEGATE_ALLOW` — Host delegates — Comma list **`git**`, `**curl**`, `**wget**`, `**systemctl`** — empty = all allowed.
|
||||
- `BARE_OS_PEAR_UPDATER_AUDIT` — Booter / host — When **`1`**, operators may append Pear updater delegate results to the host audit NDJSON chain (see `**ctx.bareOsPearUpdaterDelegate()**` **`integrationHints`** and handbook ch.7).
|
||||
- `BARE_OS_DELEGATE_ALLOW` — Host delegates — Comma list **`git`**, **`curl`**, **`wget`**, **`systemctl`** — empty = all allowed.
|
||||
- `BARE_OS_DNS_ALLOWLIST` — curl / wget — Optional host allowlist for http(s) URLs (`*.example.com` suffix form supported).
|
||||
- `BARE_OS_KERNEL_HOT_RELOAD` — Booter — Dev: allow **`ctx.bareOsRequestKernelReload()**` to re-read `**/boot/init.js`**.
|
||||
- `BARE_OS_KERNEL_EXT_D_HOT_RELOAD` — Stock kernel — When **`1**` / `**true**`, after boot the kernel exposes `**ctx.bareOsReloadKernelExtDropinsSafe()**`, which re-scans `**/etc/bare-os/kernel.ext.d**` and runs only extension scripts not yet recorded (**append-only**; does not unload). When `**ctx.vfs.writeFile**` exists, each reload appends `**kernelExtReloadSchemaVersion**` lines to `**/run/bare-os/kernel-ext-reload.ndjson`**.
|
||||
- `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_HYPERBLOBS_STATS_JSON` — Booter / **`disk.os**` — Optional non-secret JSON parsed into `**replication_operator_sketch.hyperblobsDedupSketch**` (merged into `**disk.os**` `**replication_operator_sketch`** response **schema 8**).
|
||||
- `BARE_OS_CORESTORE_STATS_JSON` — Booter / **`disk.os**` — Optional non-secret JSON parsed into `**replication_operator_sketch.corestoreOperatorSketch**` (`**bare_os.replication_operator_sketch**` response **schema 8**). Use for namespace counts, open-core tallies, or other **non-secret** Corestore operator metrics (no keys or paths to private material). Together with `**BARE_OS_CORESTORE_SNAPSHOT_JSON**`, `**corestoreSnapshotUxHint`** (schema **4**) surfaces non-secret merge counts for rollback UX.
|
||||
- `BARE_OS_HYPERDHT_ADDRESS_JSON` — Booter / **`disk.os**` — Optional non-secret JSON parsed into `**replication_operator_sketch.hyperdhtAddressSketch`** (same RPC; align with **hyperdht-address** operator payloads — keep bounded and non-secret).
|
||||
- `BARE_OS_BLIND_PEER_TOPOLOGY_V3_JSON` — Booter / **`disk.os**` — Optional non-secret JSON parsed into `**replication_operator_sketch.blindTopologySketchV3`** (**schema 3** sketch object).
|
||||
- `BARE_OS_SUBPROCESS_BRIDGE_META_JSON` — Booter / **`process_table.json**` — Optional JSON (**host-injected**); the stock snapshot exposes a non-secret summary under `**subprocessBridgeMeta**` (**schema 7** `**process_table**`) for `**bare-process**` / `**bare-subprocess`** bridge alignment.
|
||||
- `BARE_OS_PROCESS_ACCOUNTING` — Booter / **`process_table.json**` — When `**1**` / `**true**`, per-row accounting fields use `**accountingSource: guest-accounting-env`** (reserved for future Bare-thread–backed counters; defaults remain zero until wired).
|
||||
- `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_KERNEL_HOT_RELOAD` — Booter — Dev: allow **`ctx.bareOsRequestKernelReload()**` to re-read **`/boot/init.js`**.
|
||||
- `BARE_OS_KERNEL_EXT_D_HOT_RELOAD` — Stock kernel — When **`1`** / **`true`**, after boot the kernel exposes `**ctx.bareOsReloadKernelExtDropinsSafe()**`, which re-scans **`/etc/bare-os/kernel.ext.d`** and runs only extension scripts not yet recorded (**append-only**; does not unload). When **`ctx.vfs.writeFile`** exists, each reload appends **`kernelExtReloadSchemaVersion`** lines to **`/run/bare-os/kernel-ext-reload.ndjson`**.
|
||||
- `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_HYPERBLOBS_STATS_JSON` — Booter / **`disk.os`** — Optional non-secret JSON parsed into **`replication_operator_sketch.hyperblobsDedupSketch`** (merged into **`disk.os`** **`replication_operator_sketch`** response **schema 8**).
|
||||
- `BARE_OS_CORESTORE_STATS_JSON` — Booter / **`disk.os`** — Optional non-secret JSON parsed into **`replication_operator_sketch.corestoreOperatorSketch`** (**`bare_os.replication_operator_sketch`** response **schema 8**). Use for namespace counts, open-core tallies, or other **non-secret** Corestore operator metrics (no keys or paths to private material). Together with **`BARE_OS_CORESTORE_SNAPSHOT_JSON`**, **`corestoreSnapshotUxHint`** (schema **4**) surfaces non-secret merge counts for rollback UX.
|
||||
- `BARE_OS_HYPERDHT_ADDRESS_JSON` — Booter / **`disk.os`** — Optional non-secret JSON parsed into **`replication_operator_sketch.hyperdhtAddressSketch`** (same RPC; align with **hyperdht-address** operator payloads — keep bounded and non-secret).
|
||||
- `BARE_OS_BLIND_PEER_TOPOLOGY_V3_JSON` — Booter / **`disk.os`** — Optional non-secret JSON parsed into **`replication_operator_sketch.blindTopologySketchV3`** (**schema 3** sketch object).
|
||||
- `BARE_OS_SUBPROCESS_BRIDGE_META_JSON` — Booter / **`process_table.json`** — Optional JSON (**host-injected**); the stock snapshot exposes a non-secret summary under **`subprocessBridgeMeta`** (**schema 7** **`process_table`**) for **`bare-process`** / **`bare-subprocess`** bridge alignment.
|
||||
- `BARE_OS_PROCESS_ACCOUNTING` — Booter / **`process_table.json`** — When **`1`** / **`true`**, per-row accounting fields use `**accountingSource: guest-accounting-env`** (reserved for future Bare-thread–backed counters; defaults remain zero until wired).
|
||||
- `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_REPLICATION_PLAN_JSON` — Booter — Optional JSON string merged into **`/proc/bare_os/replication**` as `**guestReplicationPlan`** (operator warm-replication / mirror-drive style hints; guest does not execute the plan).
|
||||
- `BARE_OS_REPLICATION_SYNC_PARALLEL_MAX` — Booter — Integer hint surfaced under **`/proc/bare_os/sync_window.json**` as `**parallelismHint`** for overlapping replication window fetches (stock default **4** when unset).
|
||||
- `BARE_OS_REPLICATION_PEER_PRIORITY_JSON` — Booter / **`disk.os**` — Optional non-secret JSON parsed into `**bare_os.replication_operator_sketch**` `**peerPrioritySketch**`. Operator-shaped ordering hints for peer keys (for example `**orderedPeerKeyHex`**) — P2P-local policy only; no central coordinator.
|
||||
- `BARE_OS_REPLICATION_PLAN_JSON` — Booter — Optional JSON string merged into **`/proc/bare_os/replication`** as **`guestReplicationPlan`** (operator warm-replication / mirror-drive style hints; guest does not execute the plan).
|
||||
- `BARE_OS_REPLICATION_SYNC_PARALLEL_MAX` — Booter — Integer hint surfaced under **`/proc/bare_os/sync_window.json`** as **`parallelismHint`** for overlapping replication window fetches (stock default **4** when unset).
|
||||
- `BARE_OS_REPLICATION_PEER_PRIORITY_JSON` — Booter / **`disk.os`** — Optional non-secret JSON parsed into **`bare_os.replication_operator_sketch`** **`peerPrioritySketch`**. Operator-shaped ordering hints for peer keys (for example **`orderedPeerKeyHex`**) — P2P-local policy only; no central coordinator.
|
||||
- `BARE_OS_PEER_ALLOWLIST_HEX` — Booter / Hyperswarm — Optional comma- or space-separated allowlist of peer public keys (hex) for admission; empty list with **`BARE_OS_PEER_ALLOWLIST_STRICT`** denies all peers.
|
||||
- `BARE_OS_PEER_ALLOWLIST_STRICT` — Booter — When **`1**` / `**true**`, `**BARE_OS_PEER_ALLOWLIST_HEX` must be non-empty** or no remote peers are admitted (fail-closed operator posture).
|
||||
- `BARE_OS_PEER_DENYLIST_HEX` — Booter — Comma- or space-separated hex public keys; **`ctx.bareOsEvaluatePeerAdmission**` returns `**deny**` with `**reason: peer_denylist`** before allowlist evaluation (denylist wins).
|
||||
- `BARE_OS_PEER_REQUIRE_CAPS_JSON` — Booter — JSON array of strings; when set, **`meta.caps**` passed to `**ctx.bareOsEvaluatePeerAdmission**` must include every token or the verdict is `**deny**` (`**reason: peer_missing_cap`**).
|
||||
- `BARE_OS_PEER_ADMISSION_AUDIT_NDJSON` — Booter — When **`1**` / `**true**`, each admission evaluation may append a `**peer_admission**` row to the event bus (and session stdout when `**BARE_OS_EVENT_BUS_NDJSON`** is on). Payloads use a **16-hex prefix** of the peer key only.
|
||||
- `BARE_OS_PEER_ADMISSION_AUDIT_RATE_MS` — Booter — Non-negative integer; minimum milliseconds between **`peer_admission**` audit rows **per peer prefix** (or a shared `**unknown**` bucket when the key is empty). `**0`** or unset means no throttling.
|
||||
- `BARE_OS_DHT_ADDRESS_CLASS_ALLOWLIST` — Booter / **`/proc/bare_os/swarm.json**` — Comma-separated tokens (`**ipv4**`, `**ipv6**`, `**relay**`, …) surfaced under `**dhtAddressClassAllowlist**` for operator alignment with **hyperdht-address** discovery classes. `**ctx.bareOsEvaluatePeerAdmission(peerKeyHex, { dhtAddressClass, caps })**` and `**BareOsSwarmConnectionManager.shouldAttemptPeer(peerKey, { dhtAddressClass })**` deny when the hint is present and not listed; the stock Hyperswarm join path does not supply a class — custom hosts wire `**meta.dhtAddressClass`** from their stack.
|
||||
- `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_PEER_ALLOWLIST_STRICT` — Booter — When **`1`** / **`true`**, `**BARE_OS_PEER_ALLOWLIST_HEX` must be non-empty** or no remote peers are admitted (fail-closed operator posture).
|
||||
- `BARE_OS_PEER_DENYLIST_HEX` — Booter — Comma- or space-separated hex public keys; **`ctx.bareOsEvaluatePeerAdmission`** returns **`deny`** with `**reason: peer_denylist`** before allowlist evaluation (denylist wins).
|
||||
- `BARE_OS_PEER_REQUIRE_CAPS_JSON` — Booter — JSON array of strings; when set, **`meta.caps`** passed to **`ctx.bareOsEvaluatePeerAdmission`** must include every token or the verdict is **`deny`** (`**reason: peer_missing_cap`**).
|
||||
- `BARE_OS_PEER_ADMISSION_AUDIT_NDJSON` — Booter — When **`1`** / **`true`**, each admission evaluation may append a **`peer_admission`** row to the event bus (and session stdout when **`BARE_OS_EVENT_BUS_NDJSON`** is on). Payloads use a **16-hex prefix** of the peer key only.
|
||||
- `BARE_OS_PEER_ADMISSION_AUDIT_RATE_MS` — Booter — Non-negative integer; minimum milliseconds between **`peer_admission`** audit rows **per peer prefix** (or a shared **`unknown`** bucket when the key is empty). **`0`** or unset means no throttling.
|
||||
- `BARE_OS_DHT_ADDRESS_CLASS_ALLOWLIST` — Booter / **`/proc/bare_os/swarm.json`** — Comma-separated tokens (**`ipv4`**, **`ipv6`**, **`relay`**, …) surfaced under **`dhtAddressClassAllowlist`** for operator alignment with **hyperdht-address** discovery classes. `**ctx.bareOsEvaluatePeerAdmission(peerKeyHex, { dhtAddressClass, caps })**` and `**BareOsSwarmConnectionManager.shouldAttemptPeer(peerKey, { dhtAddressClass })**` deny when the hint is present and not listed; the stock Hyperswarm join path does not supply a class — custom hosts wire **`meta.dhtAddressClass`** from their stack.
|
||||
- `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_SWARM_MAX_PEERS` — Booter — Integer passed to Hyperswarm **`maxPeers`** when set (non-empty positive integer string).
|
||||
- `BARE_OS_SWARM_MAX_CLIENT_CONNECTIONS` — Booter — Cap inbound client connections (**Hyperswarm** **`maxClientConnections`**).
|
||||
- `BARE_OS_SWARM_MAX_SERVER_CONNECTIONS` — Booter — Cap outbound server connections (**Hyperswarm** **`maxServerConnections`**).
|
||||
- `BARE_OS_SWARM_MAX_PARALLEL` — Booter — Integer passed to Hyperswarm **`maxParallel**` when set. Effective values echo under `**/proc/bare_os/swarm**` `**connectionBudget**` and `**disk.os` `replication_operator_sketch`** (**schema 8**).
|
||||
- `BARE_OS_SWARM_ATTEMPT_BURST_PER_SEC` — Booter — Optional positive integer; caps **connection attempt** accounting in the swarm policy engine (**rolling 1s window**; increments when **`consumeReconnectBudget**` runs). `**shouldAttemptPeer`** returns false when the burst is exhausted.
|
||||
- `BARE_OS_SWARM_MAX_PARALLEL` — Booter — Integer passed to Hyperswarm **`maxParallel`** when set. Effective values echo under **`/proc/bare_os/swarm`** **`connectionBudget`** and `**disk.os` `replication_operator_sketch`** (**schema 8**).
|
||||
- `BARE_OS_SWARM_ATTEMPT_BURST_PER_SEC` — Booter — Optional positive integer; caps **connection attempt** accounting in the swarm policy engine (**rolling 1s window**; increments when **`consumeReconnectBudget`** runs). **`shouldAttemptPeer`** returns false when the burst is exhausted.
|
||||
- `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](../security/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_VAULT_MULTISIG_CONTINUITY_JSON` — Booter / **`/proc/bare_os/hyper_multisig_trust_pointer.json**` — Optional operator JSON merged as `**vaultMultisigContinuity`** when the proc builder uses **schema 2** (pointer-only multisig continuity sketch; no secret keys).
|
||||
- `BARE_OS_VAULT_MULTISIG_CONTINUITY_AUDIT_NDJSON` — Booter — When **`1**` / `**true**`, successful `**applyLoginKeys**` / `**unlockIdentity**` may append a `**vault.multisig_continuity_login_sketch**` row via `**ctx.bareOsAuditLogAppendBatch`** (public-key hex prefix only).
|
||||
- `BARE_OS_BLIND_RELAY_AUDIT_NDJSON` — Booter / **`security_posture.json**` — When `**1**` / `**true**`, `**blindRelayAudit.armed`** is set so operators can route blind-relay admission sketches to host NDJSON sinks; proc JSON still omits peer keys.
|
||||
- `BARE_OS_TIMER_EVERY_MS_MONOTONIC` — bare-cron / timers — When **`1**` / `**true**`, `**EveryMs=`** timer units may use monotonic scheduling where supported.
|
||||
- `BARE_OS_VAULT_MULTISIG_CONTINUITY_JSON` — Booter / **`/proc/bare_os/hyper_multisig_trust_pointer.json`** — Optional operator JSON merged as **`vaultMultisigContinuity`** when the proc builder uses **schema 2** (pointer-only multisig continuity sketch; no secret keys).
|
||||
- `BARE_OS_VAULT_MULTISIG_CONTINUITY_AUDIT_NDJSON` — Booter — When **`1`** / **`true`**, successful **`applyLoginKeys`** / **`unlockIdentity`** may append a **`vault.multisig_continuity_login_sketch`** row via **`ctx.bareOsAuditLogAppendBatch`** (public-key hex prefix only).
|
||||
- `BARE_OS_BLIND_RELAY_AUDIT_NDJSON` — Booter / **`security_posture.json`** — When **`1`** / **`true`**, **`blindRelayAudit.armed`** is set so operators can route blind-relay admission sketches to host NDJSON sinks; proc JSON still omits peer keys.
|
||||
- `BARE_OS_TIMER_EVERY_MS_MONOTONIC` — bare-cron / timers — When **`1`** / **`true`**, **`EveryMs=`** timer units may use monotonic scheduling where supported.
|
||||
- `BARE_OS_TRACE_ID` — Booter / telemetry — Optional correlation id mirrored into telemetry NDJSON lines when set.
|
||||
- `BARE_OS_IPC_NAMESPACE` — VFS / mkfifo / initd — Prefix simulated FIFO keys as **`<ns>__<name>**` while logical paths stay `**/run/bare-os/ipc/<name>`**.
|
||||
- `BARE_OS_SANDBOX_SCRIPT` — `ctx.bareOsSandboxRunScript` — Set **`0**` / `**false`** to disable sandbox script helper.
|
||||
- `BARE_OS_SANDBOX_WORKER` — Booter — When **`1**`, defers `**bareOsSandboxRunScript`** on a **fresh microtask** (async boundary); **not** a separate thread or isolate.
|
||||
- `BARE_OS_IPC_NAMESPACE` — VFS / mkfifo / initd — Prefix simulated FIFO keys as **`<ns>__<name>`** while logical paths stay **`/run/bare-os/ipc/<name>`**.
|
||||
- `BARE_OS_SANDBOX_SCRIPT` — `ctx.bareOsSandboxRunScript` — Set **`0`** / **`false`** to disable sandbox script helper.
|
||||
- `BARE_OS_SANDBOX_WORKER` — Booter — When **`1`**, defers **`bareOsSandboxRunScript`** on a **fresh microtask** (async boundary); **not** a separate thread or isolate.
|
||||
- `BARE_OS_INITD_MAX_PARALLEL` — bare-initd — Max concurrent unit **starts** per DAG level (integer ≥ **1**; stock booter seeds **4** when unset; boot policy **`initdAdmission.maxParallel`** may still clamp).
|
||||
- `BARE_OS_INITD_DISABLED` — bare-initd — **Host-only** (read from **`globalThis.process.env**`, not guest `**vfs.env**`). Comma- or whitespace-separated initd unit names merged into the disabled set alongside `**~/.config/bare-os/initd/disabled.txt**`. Used in `**packages/bare-os-booter/test.js**` to skip `**bare-openssh**` under Node ( `**bare-ssh2**` needs Bare `**require.addon`**).
|
||||
- `BARE_OS_INITD_DISABLED` — bare-initd — **Host-only** (read from **`globalThis.process.env`**, not guest **`vfs.env`**). Comma- or whitespace-separated initd unit names merged into the disabled set alongside **`~/.config/bare-os/initd/disabled.txt`**. Used in **`packages/bare-os-booter/test.js`** to skip **`bare-openssh`** under Node ( **`bare-ssh2`** needs Bare **`require.addon`**).
|
||||
- `BARE_OS_INITD_JOURNAL_MAX_LINES` — bare-initd / unit journals — Cap lines retained per unit NDJSON journal under **`/run/bare-os/unit-journal/`**.
|
||||
- `BARE_OS_TELEMETRY_NDJSON` — Booter — Absolute or **`~/…**` path in the **guest VFS**: append capped NDJSON telemetry records (`**telemetrySchemaVersion` / `lifecycleSchemaVersion**` follow stock `**BARE_OS_LIFECYCLE_SCHEMA_VERSION**`, currently **10** in the tree; `**ts`**, …) mirroring structured boot/kernel events. String fields are passed through a **best-effort redactor** (long hex, `Bearer …`, `sk-…` shapes) before append; do not rely on it for classified payloads. Stock booter seeds **`/var/log/bare-os/telemetry.ndjson**` when unset; set `**0**` / `**false**` on the host to disable the sink (empty path disables `**mirrorBareOsTelemetryNdjson`**).
|
||||
- `BARE_OS_TELEMETRY_NDJSON` — Booter — Absolute or **`~/…**` path in the **guest VFS**: append capped NDJSON telemetry records (`**telemetrySchemaVersion` / `lifecycleSchemaVersion**` follow stock **`BARE_OS_LIFECYCLE_SCHEMA_VERSION`**, currently **10** in the tree; **`ts`**, …) mirroring structured boot/kernel events. String fields are passed through a **best-effort redactor** (long hex, `Bearer …`, `sk-…` shapes) before append; do not rely on it for classified payloads. Stock booter seeds **`/var/log/bare-os/telemetry.ndjson`** when unset; set **`0`** / **`false`** on the host to disable the sink (empty path disables **`mirrorBareOsTelemetryNdjson`**).
|
||||
- `BARE_OS_TELEMETRY_OTEL_JSONL` — Booter / var-log — Guest VFS path for OTLP-inspired JSON lines (var-log mirrors).
|
||||
- `BARE_OS_TELEMETRY_OTEL` — Booter — When **`1**` / `**true**` and `**BARE_OS_TELEMETRY_OTEL_JSONL**` is unset or `**0**`, the booter sets the OTel JSONL path to `**/var/log/bare-os/otel.jsonl`**.
|
||||
- `BARE_OS_TELEMETRY_OTEL` — Booter — When **`1`** / **`true`** and **`BARE_OS_TELEMETRY_OTEL_JSONL`** is unset or **`0`**, the booter sets the OTel JSONL path to **`/var/log/bare-os/otel.jsonl`**.
|
||||
- `BARE_OS_PROC_POLL_MS` — VFS — Coalescing interval for **`/proc/bare_os/metrics_live.json`** and poll cadence for related pseudo metrics reads (250–60000).
|
||||
- `BARE_OS_SHELL_PARAM_EXPANSION` — Shell — When **`1**`, enable `**${VAR:-word}**` and `**${VAR#prefix}**` in `**expandWord`**.
|
||||
- `BARE_OS_SHELL_PARAM_EXPANSION` — Shell — When **`1`**, enable `**${VAR:-word}**` and `**${VAR#prefix}**` in **`expandWord`**.
|
||||
- `BARE_OS_SHELL_PARAM_EXPANSION_V2` — Shell — With param expansion on, enable **`${VAR:=word}**`, `**${VAR##*/}**` / `**${VAR#*/}**`, `**${VAR%%suffix}**` / `**${VAR%suffix}`** (bounded patterns).
|
||||
- `BARE_OS_SHELL_PARAM_EXPANSION_V3` — Shell — With param expansion on, enable **`${VAR:?word}**` and `**${VAR:+word}**` (POSIX-style error/alternate-value forms within documented bounds). Covered by `**expandWord param expansion v3**` in `**packages/bare-os-booter/test.js`**.
|
||||
- `BARE_OS_SHELL_POSIX_UNSET_ONLY_DEFAULT` — Shell — When **`1**` / `**true**` with param expansion on, enables `**${name-default}**` (default only when **unset**, distinct from `**${name:-default}`** when **unset or empty**).
|
||||
- `BARE_OS_ENV_DASH_S` — `/bin/env` — When **`1**`, enable `**-S` / `--split-string**` and `**--env-file`** (bounded).
|
||||
- `BARE_OS_VFS_WATCH_PSEUDO` — VFS — When **`1**`, allow `**vfs.watch**` on coalesced `**/proc/bare_os/metrics_live.json**` and polled `**/proc/bare_os/metrics.prom**` (and flat `**/proc/bare_os_metrics_*`** aliases).
|
||||
- `BARE_OS_VFS_WATCH_SWARM` — VFS — When **`1**`, allow bounded `**vfs.watch**` on `**/proc/bare_os/swarm**`, flat `**/proc/bare_os_swarm**`, `**/proc/bare_os/replication**`, `**/proc/bare_os_replication**` (poll interval `**BARE_OS_PROC_POLL_MS`**).
|
||||
- `BARE_OS_SHELL_LOCAL_DECLARE` — Shell — When **`1**`, `**local**` and read-only `**declare -r**` apply per shell line (shallow `**vfs.env`** copy).
|
||||
- `BARE_OS_DIAGNOSTICS_SUBSCRIBE` — Booter — When **`1**`, `**ctx.bareOsDiagnosticsSubscribe`** receives structured booter events.
|
||||
- `BARE_OS_SHELL_PARAM_EXPANSION_V3` — Shell — With param expansion on, enable **`${VAR:?word}**` and `**${VAR:+word}**` (POSIX-style error/alternate-value forms within documented bounds). Covered by `**expandWord param expansion v3**` in **`packages/bare-os-booter/test.js`**.
|
||||
- `BARE_OS_SHELL_POSIX_UNSET_ONLY_DEFAULT` — Shell — When **`1`** / **`true`** with param expansion on, enables `**${name-default}**` (default only when **unset**, distinct from `**${name:-default}`** when **unset or empty**).
|
||||
- `BARE_OS_ENV_DASH_S` — `/bin/env` — When **`1`**, enable `**-S` / `--split-string**` and **`--env-file`** (bounded).
|
||||
- `BARE_OS_VFS_WATCH_PSEUDO` — VFS — When **`1`**, allow **`vfs.watch`** on coalesced **`/proc/bare_os/metrics_live.json`** and polled **`/proc/bare_os/metrics.prom`** (and flat **`/proc/bare_os_metrics_*`** aliases).
|
||||
- `BARE_OS_VFS_WATCH_SWARM` — VFS — When **`1`**, allow bounded **`vfs.watch`** on **`/proc/bare_os/swarm`**, flat **`/proc/bare_os_swarm`**, **`/proc/bare_os/replication`**, **`/proc/bare_os_replication`** (poll interval **`BARE_OS_PROC_POLL_MS`**).
|
||||
- `BARE_OS_SHELL_LOCAL_DECLARE` — Shell — When **`1`**, **`local`** and read-only `**declare -r**` apply per shell line (shallow **`vfs.env`** copy).
|
||||
- `BARE_OS_DIAGNOSTICS_SUBSCRIBE` — Booter — When **`1`**, **`ctx.bareOsDiagnosticsSubscribe`** receives structured booter events.
|
||||
- `BARE_OS_AUTOPASS_INVITE_URL` — `/proc/bare_os/hdms_hints.json` — Optional operator invite URL hint (guest does not fetch it).
|
||||
- `BARE_OS_BIN_WORKER_OFFLOAD` — **`runBinCommand**` (Bare) — When `**1**` on **Bare** (not Node), may run `**awk**` / `**sed**` / `**jq**` in a `**bare-worker**` thread; falls back in-process on failure. With `**BARE_OS_BIN_WORKER_ALLOW**` (comma list) for future expansion (`**textproc:***`, `**mathproc:***`, `**mediaproc:***`, `**sysproc:***`, `**metaproc:*`**, … — see [kernel-extensions.md](kernel-extensions.md)).
|
||||
- `BARE_OS_BIN_WORKER_CPU_MS_MAX` — Booter — Optional per-invocation CPU-time budget hint (ms) for **`bare-worker**` `**/bin`** offload; surfaced in operator metrics / worker budget snapshots.
|
||||
- `BARE_OS_BIN_WORKER_WASM_MS_MAX` — Booter — When **> 0** (capped at **3_600_000**), stock **`bare-worker**` offload `**terminate()**`s the thread after that many milliseconds and returns `**{ ok: false, reason: 'wasm_time_budget' }**` to `**runBinCommand`** (falls back to in-process behavior).
|
||||
- `BARE_OS_BIN_WORKER_OFFLOAD` — **`runBinCommand`** (Bare) — When **`1`** on **Bare** (not Node), may run **`awk`** / **`sed`** / **`jq`** in a **`bare-worker`** thread; falls back in-process on failure. With **`BARE_OS_BIN_WORKER_ALLOW`** (comma list) for future expansion (**`textproc:*`**, **`mathproc:*`**, **`mediaproc:*`**, **`sysproc:*`**, **`metaproc:*`**, … — see [kernel-extensions.md](kernel-extensions.md)).
|
||||
- `BARE_OS_BIN_WORKER_CPU_MS_MAX` — Booter — Optional per-invocation CPU-time budget hint (ms) for **`bare-worker`** **`/bin`** offload; surfaced in operator metrics / worker budget snapshots.
|
||||
- `BARE_OS_BIN_WORKER_WASM_MS_MAX` — Booter — When **> 0** (capped at **3_600_000**), stock **`bare-worker`** offload `**terminate()**`s the thread after that many milliseconds and returns `**{ ok: false, reason: 'wasm_time_budget' }**` to **`runBinCommand`** (falls back to in-process behavior).
|
||||
- `BARE_OS_EXEC_LINE_BUDGET_MS` — Booter — Reject top-level **`execLine`** when cumulative wall time exceeds budget.
|
||||
- `BARE_OS_TIMER_BUDGET_MS` — Booter — Alias for **`BARE_OS_EXEC_LINE_BUDGET_MS**` applied when `**BARE_OS_EXEC_LINE_BUDGET_MS`** is unset (host convenience).
|
||||
- `BARE_OS_STREAMING_MULTIPLIER` — Shell — Alias for **`BARE_OS_SHELL_STREAMING_MULT**` when unset; pair with `**BARE_OS_SHELL_STREAMING=1`** so pipeline byte/line caps scale.
|
||||
- `BARE_OS_TIMER_BUDGET_MS` — Booter — Alias for **`BARE_OS_EXEC_LINE_BUDGET_MS`** applied when **`BARE_OS_EXEC_LINE_BUDGET_MS`** is unset (host convenience).
|
||||
- `BARE_OS_STREAMING_MULTIPLIER` — Shell — Alias for **`BARE_OS_SHELL_STREAMING_MULT`** when unset; pair with **`BARE_OS_SHELL_STREAMING=1`** so pipeline byte/line caps scale.
|
||||
- `BARE_OS_DELEGATE_MAX_PER_MIN` — Host delegates — Global per-minute cap (sliding window) on delegate invocations.
|
||||
- `BARE_OS_DELEGATE_*_MAX_PER_MIN` — Host delegates — Per-kind override (**`GIT**`, `**CURL**`, `**WGET**`, `**SYSTEMCTL`**).
|
||||
- `BARE_OS_DELEGATE_*_MAX_PER_MIN` — Host delegates — Per-kind override (**`GIT`**, **`CURL`**, **`WGET`**, **`SYSTEMCTL`**).
|
||||
- `BARE_OS_DELEGATE_MAX_CONCURRENT` — Host delegates — Max parallel delegate runs globally (integer **1–64**; **`0`** / unset = unlimited).
|
||||
- `BARE_OS_DELEGATE_*_MAX_CONCURRENT` — Host delegates — Per-kind in-flight cap (**`GIT**`, `**CURL**`, `**WGET**`, `**SYSTEMCTL`**).
|
||||
- `BARE_OS_DELEGATE_AUDIT_ONLY` — Host delegates — With **`BARE_OS_AUDIT**`, log delegate calls and skip execution (**exit 0**). Delegate audit NDJSON rows include `**argvRawCount**`, `**argvTruncated**`, and `**sessionId`** when the stock booter supplies them.
|
||||
- `BARE_OS_SEED_RPC_HANDSHAKE` — Booter — Set **`0**` / `**false**` to skip the pre-MBR `**bare_os.capabilities`** RPC against the first peer.
|
||||
- `BARE_OS_SEED_CAP_STRICT` — Booter — When **`1**` / `**true**`, require `**kernelCapabilityWords**` (wire v2) on the seed `**bare_os.capabilities**` payload and each semantic key’s mask to cover the stock booter `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_***` for that word (as wired in `**bare-os-protocol`**) or throw.
|
||||
- `BARE_OS_SEED_CAP_FAIL` — Booter — When **`1**` / `**true`**, rethrow after a failed handshake instead of recording the error and continuing.
|
||||
- `BARE_OS_SEED_IMAGE_TIP_ID` — Seeder — Optional short string (≤256 chars) echoed on **`bare_os.capabilities**` as `**imageTipId**` so booted peers can prove they match the same release tip when `**BARE_OS_PEER_SEED_IMAGE_TIP_ID`** is set on helpers.
|
||||
- `BARE_OS_PEER_SYSTEM_SEED` — Booter (host) — **Default: enabled** (unset). When enabled, a **fully booted** node may **serve block 0 (MBR)** from its boot-time copy and mirror **publisher `bare_os.*` RPC** payloads captured at boot (**`capabilities**`, `**replication_status**`, wave hints, …) to other cold booters on the same Hyperswarm topic. Set `**0**`, `**false**`, `**no**`, or `**off**` to disable. Same trust model as replication (“who you peer with”). Eligibility requires a successful pre-MBR seed handshake, `**kernelCapabilityWords**`, primary MBR drive key match, and optional gates below. If you set an affirmative value (`**1**` / `**true**` / `**yes`**) and eligibility still fails, the host logs a warning with the reason.
|
||||
- `BARE_OS_PEER_SEED_IMAGE_TIP_ID` — Booter (host) — When non-empty, peer seeding is allowed only if **`bare_os.capabilities.imageTipId**` from the publisher at boot equals this string (set `**BARE_OS_SEED_IMAGE_TIP_ID`** on the seeder to publish the tip).
|
||||
- `BARE_OS_PEER_SEED_ADVERTISE_IMAGE_TIP_ID` — Booter (host) — Optional **`imageTipId**` for **synthetic** peer capabilities (when `**BARE_OS_PEER_SEED_SYNTHETIC_CAPABILITIES**` is on): used if `**BARE_OS_SEED_IMAGE_TIP_ID**` is unset. Align with the seeder tip so helpers pass `**BARE_OS_PEER_SEED_IMAGE_TIP_ID`** gates and cold joiners see a consistent tip.
|
||||
- `BARE_OS_PEER_SEED_SYNTHETIC_CAPABILITIES` — Booter (host) — Default **on** (unset). When **on**, after a successful swarm boot the booter may fill **`seedCapabilityInfo**` with **stock** `**kernelCapabilityWords**` if the publisher `**bare_os.capabilities**` handshake was skipped (`**BARE_OS_SEED_RPC_HANDSHAKE**`, no early peers), failed, or returned no words — maximizing peers that can mirror **MBR block 0**. Set `**0**` / `**false**` / `**no**` / `**off`** to keep the legacy strict requirement for a complete publisher capability snapshot.
|
||||
- `BARE_OS_DELEGATE_*_MAX_CONCURRENT` — Host delegates — Per-kind in-flight cap (**`GIT`**, **`CURL`**, **`WGET`**, **`SYSTEMCTL`**).
|
||||
- `BARE_OS_DELEGATE_AUDIT_ONLY` — Host delegates — With **`BARE_OS_AUDIT`**, log delegate calls and skip execution (**exit 0**). Delegate audit NDJSON rows include **`argvRawCount`**, **`argvTruncated`**, and **`sessionId`** when the stock booter supplies them.
|
||||
- `BARE_OS_SEED_RPC_HANDSHAKE` — Booter — Set **`0`** / **`false`** to skip the pre-MBR **`bare_os.capabilities`** RPC against the first peer.
|
||||
- `BARE_OS_SEED_CAP_STRICT` — Booter — When **`1`** / **`true`**, require **`kernelCapabilityWords`** (wire v2) on the seed **`bare_os.capabilities`** payload and each semantic key’s mask to cover the stock booter **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_*`** for that word (as wired in **`bare-os-protocol`**) or throw.
|
||||
- `BARE_OS_SEED_CAP_FAIL` — Booter — When **`1`** / **`true`**, rethrow after a failed handshake instead of recording the error and continuing.
|
||||
- `BARE_OS_SEED_IMAGE_TIP_ID` — Seeder — Optional short string (≤256 chars) echoed on **`bare_os.capabilities`** as **`imageTipId`** so booted peers can prove they match the same release tip when **`BARE_OS_PEER_SEED_IMAGE_TIP_ID`** is set on helpers.
|
||||
- `BARE_OS_PEER_SYSTEM_SEED` — Booter (host) — **Default: enabled** (unset). When enabled, a **fully booted** node may **serve block 0 (MBR)** from its boot-time copy and mirror **publisher `bare_os.*` RPC** payloads captured at boot (**`capabilities`**, **`replication_status`**, wave hints, …) to other cold booters on the same Hyperswarm topic. Set **`0`**, **`false`**, **`no`**, or **`off`** to disable. Same trust model as replication (“who you peer with”). Eligibility requires a successful pre-MBR seed handshake, **`kernelCapabilityWords`**, primary MBR drive key match, and optional gates below. If you set an affirmative value (**`1`** / **`true`** / **`yes`**) and eligibility still fails, the host logs a warning with the reason.
|
||||
- `BARE_OS_PEER_SEED_IMAGE_TIP_ID` — Booter (host) — When non-empty, peer seeding is allowed only if **`bare_os.capabilities.imageTipId`** from the publisher at boot equals this string (set **`BARE_OS_SEED_IMAGE_TIP_ID`** on the seeder to publish the tip).
|
||||
- `BARE_OS_PEER_SEED_ADVERTISE_IMAGE_TIP_ID` — Booter (host) — Optional **`imageTipId`** for **synthetic** peer capabilities (when **`BARE_OS_PEER_SEED_SYNTHETIC_CAPABILITIES`** is on): used if **`BARE_OS_SEED_IMAGE_TIP_ID`** is unset. Align with the seeder tip so helpers pass **`BARE_OS_PEER_SEED_IMAGE_TIP_ID`** gates and cold joiners see a consistent tip.
|
||||
- `BARE_OS_PEER_SEED_SYNTHETIC_CAPABILITIES` — Booter (host) — Default **on** (unset). When **on**, after a successful swarm boot the booter may fill **`seedCapabilityInfo`** with **stock** **`kernelCapabilityWords`** if the publisher **`bare_os.capabilities`** handshake was skipped (**`BARE_OS_SEED_RPC_HANDSHAKE`**, no early peers), failed, or returned no words — maximizing peers that can mirror **MBR block 0**. Set **`0`** / **`false`** / **`no`** / **`off`** to keep the legacy strict requirement for a complete publisher capability snapshot.
|
||||
- `BARE_OS_PEER_SEED_REQUIRE_REVISION_ID` — Booter (host) — When non-empty, peer seeding requires **`BARE_OS_SYSTEM_REVISION_ID`** (guest env) to equal this value after boot.
|
||||
- `BARE_OS_SWARM_RPC_TRY_PEERS` — Booter — When **`1**` / `**true**` (default), `**bare_os.***` `**SwarmDisk.rpc**` tries each connected peer in order until one succeeds; for `**capabilities**`, responses without `**kernelCapabilityWords**` are skipped. Set `**0**` / `**false`** to use only the first peer (legacy behavior).
|
||||
- `BARE_OS_OFFLINE_LKG_BOOT` — Booter — With **`BARE_OS_LKG_SYSTEM_KEY_HEX**` (64 hex chars), skip swarm peer wait and open the system Hyperdrive from the local Corestore (`**/boot/init.js`** must already be replicated).
|
||||
- `BARE_OS_SWARM_RPC_TRY_PEERS` — Booter — When **`1`** / **`true`** (default), **`bare_os.*`** **`SwarmDisk.rpc`** tries each connected peer in order until one succeeds; for **`capabilities`**, responses without **`kernelCapabilityWords`** are skipped. Set **`0`** / **`false`** to use only the first peer (legacy behavior).
|
||||
- `BARE_OS_OFFLINE_LKG_BOOT` — Booter — With **`BARE_OS_LKG_SYSTEM_KEY_HEX`** (64 hex chars), skip swarm peer wait and open the system Hyperdrive from the local Corestore (**`/boot/init.js`** must already be replicated).
|
||||
- `BARE_OS_LKG_SYSTEM_KEY_HEX` — Booter — 32-byte Hyperdrive public key hex for offline LKG boot.
|
||||
- `BARE_OS_HOST_STORAGE_JSON` — Booter — Optional JSON merged into **`/proc/bare_os/bootstrap**` as `**hostStorage**` (Bare `**bare-storage`**-style hints for hosts).
|
||||
- `BARE_OS_BOOT_POLICY_DENY_EXEC_LINE_BUILTINS` — Shell — Comma-separated shell builtin names denied at **`execLine**` (from `**boot.policy.json**` `**denyExecLineBuiltins`**).
|
||||
- `BARE_OS_HOST_STORAGE_JSON` — Booter — Optional JSON merged into **`/proc/bare_os/bootstrap`** as **`hostStorage`** (Bare **`bare-storage`**-style hints for hosts).
|
||||
- `BARE_OS_BOOT_POLICY_DENY_EXEC_LINE_BUILTINS` — Shell — Comma-separated shell builtin names denied at **`execLine`** (from **`boot.policy.json`** **`denyExecLineBuiltins`**).
|
||||
- `BARE_OS_BOOT_POLICY_ALLOWED_CTX_METHODS` — Kernels — Comma-separated **`ctx` method** names; **`bareOsIsCtxMethodAllowed`** returns false for others when this is set.
|
||||
- `BARE_OS_SUBPROCESS_BRIDGE_JOBS_JSON` — Booter — Optional JSON array of job records surfaced by **`ctx.bareOsReadSubprocessBridgeJobs()**` (host-wired `**bare-subprocess`** bridge only).
|
||||
- `BARE_OS_IPC_AUDIT` — Booter / mkfifo — When **`1**`, append JSON `**ipcAuditSchemaVersion**` lines to `**audit.log**` for events such as `**mkfifo`**.
|
||||
- `BARE_OS_URANDOM_CRYPTO` — VFS **`/dev/urandom**` — Set `**0`** to use non-crypto PRNG for synthetic urandom (default prefers crypto where available).
|
||||
- `BARE_OS_SUBPROCESS_BRIDGE_JOBS_JSON` — Booter — Optional JSON array of job records surfaced by **`ctx.bareOsReadSubprocessBridgeJobs()**` (host-wired **`bare-subprocess`** bridge only).
|
||||
- `BARE_OS_IPC_AUDIT` — Booter / mkfifo — When **`1`**, append JSON **`ipcAuditSchemaVersion`** lines to **`audit.log`** for events such as **`mkfifo`**.
|
||||
- `BARE_OS_URANDOM_CRYPTO` — VFS **`/dev/urandom`** — Set **`0`** to use non-crypto PRNG for synthetic urandom (default prefers crypto where available).
|
||||
- `BARE_OS_BLIND_BOOTSTRAP_URL` — `/proc/bare_os_bootstrap` — Non-empty URL string echoed into the proc JSON for host/operator wiring (guest does not fetch it).
|
||||
- `BARE_OS_BLIND_BOOTSTRAP_JSON` — `/proc/bare_os_bootstrap` — Inline JSON string parsed and exposed under **`blindBootstrap`** (invalid JSON yields an error object in the proc file).
|
||||
- `BARE_OS_MIRROR_READ_KEY` — Replication proc / mirror hint — Optional mirror drive key string included in replication snapshot for operators.
|
||||
- `BARE_OS_PEAR_TRUST_JSON` — `/proc/bare_os/pear_trust.json` — Optional operator JSON merged into trust summary (guest does not verify multisig).
|
||||
- `BARE_OS_HOST_BUNDLE_EVALUATE` — `ctx.bareOsHostCapability` — When **`1**`, advertise host `**bundleEvaluate**` for optional cross-worker / `**bare-bundle-evaluate`** paths (host-only).
|
||||
- `BARE_OS_SHELL_PIPEFAIL` — Shell — When **`1**` / `**true**`, or after `**set -o pipefail`**, a pipeline’s exit status is the first failing stage (bash-like); default is POSIX-like **last stage** status only.
|
||||
- `BARE_OS_SHELL_PIPESTATUS` — Shell — When **`1**` / `**true**`, after each pipeline the space-separated stage exit codes are written to `**BARE_OS_PIPESTATUS**` in `**vfs.env`**.
|
||||
- `BARE_OS_SHELL_ERREXIT` — Shell — When **`1**` / `**true**`, or after `**set -e**`, stop running further top-level `**;**`-separated commands once a foreground command returns non-zero (subset of POSIX **errexit**; `**if` / `while` / `for`** condition lists are not affected the same way as bash — see handbook ch.9).
|
||||
- `BARE_OS_SHELL_NOUNSET` — Shell — When **`1**` / `**true**`, or after `**set -u**` / `**set -o nounset**`, expanding an unset simple parameter is an error (`**shell: unbound variable`**); see handbook ch.9.
|
||||
- `BARE_OS_SHELL_READ_BUILTIN` — Shell — When **`1**` / `**true**`, enables the optional `**read**` builtin (bounded line from `**ctx.shellStdin**`, `**ctx.readLine**`, or interactive input; `**IFS**` split; `**-r**` accepted). Not full POSIX `**sh read`**.
|
||||
- `BARE_OS_HOST_BUNDLE_EVALUATE` — `ctx.bareOsHostCapability` — When **`1`**, advertise host **`bundleEvaluate`** for optional cross-worker / **`bare-bundle-evaluate`** paths (host-only).
|
||||
- `BARE_OS_SHELL_PIPEFAIL` — Shell — When **`1`** / **`true`**, or after `**set -o pipefail`**, a pipeline’s exit status is the first failing stage (bash-like); default is POSIX-like **last stage** status only.
|
||||
- `BARE_OS_SHELL_PIPESTATUS` — Shell — When **`1`** / **`true`**, after each pipeline the space-separated stage exit codes are written to **`BARE_OS_PIPESTATUS`** in **`vfs.env`**.
|
||||
- `BARE_OS_SHELL_ERREXIT` — Shell — When **`1`** / **`true`**, or after `**set -e**`, stop running further top-level `**;**`-separated commands once a foreground command returns non-zero (subset of POSIX **errexit**; `**if` / `while` / `for`** condition lists are not affected the same way as bash — see handbook ch.9).
|
||||
- `BARE_OS_SHELL_NOUNSET` — Shell — When **`1`** / **`true`**, or after `**set -u**` / `**set -o nounset**`, expanding an unset simple parameter is an error (`**shell: unbound variable`**); see handbook ch.9.
|
||||
- `BARE_OS_SHELL_READ_BUILTIN` — Shell — When **`1`** / **`true`**, enables the optional **`read`** builtin (bounded line from **`ctx.shellStdin`**, **`ctx.readLine`**, or interactive input; **`IFS`** split; **`-r`** accepted). Not full POSIX `**sh read`**.
|
||||
- `BARE_OS_SHELL_READ_MAX_BYTES` — Shell — Max raw bytes per **`read`** line when the read builtin is enabled (default **65536**, hard cap **2 MiB**).
|
||||
- `BARE_OS_VFS_WARM_CACHE_INVALIDATE_ON_APPEND` — Booter — When **`1**` / `**true**`, register `**append**` listeners on the system Hyperdrive metadata and blob Hypercores (when present) to clear `**/bin**` / `**lib/bare`** warm read caches on replication (**offline-first** safety; may increase churn on busy drives).
|
||||
- `BARE_OS_VFS_WARM_CACHE_PREFIX_INVALIDATE` — Booter — When **`1**` / `**true**`, evict warm-cache entries for `**/bin**`, `**/etc**`, `**/lib**`, `**/usr**`, and configured personal prefixes when replicated core lengths increase (see `**metrics_live.replicationLive.warmPrefixInvalidate`**).
|
||||
- `BARE_OS_VFS_WARM_CACHE_INVALIDATE_ON_REPLICATION` — Booter — When **`1**` / `**true**`, call `**ctx.bareOsInvalidateWarmReadCaches('replication:core-length')**` on the same growth signal (full flush; `**metrics_live.warmFullInvalidateOnReplication`**).
|
||||
- `BARE_OS_VFS_WARM_REPL_ADAPTIVE_WINDOW_MS` — Booter — When set to a positive integer and full replication-driven invalidation is active, skip issuing another **full** warm-cache flush if the previous one was within this window (milliseconds), reducing churn on busy swarms while **`replication_operator_sketch**` / core-length signals remain visible in `**metrics_live**`. `**0`** or unset disables the grace window.
|
||||
- `BARE_OS_VFS_WARM_CACHE_INVALIDATE_ON_APPEND` — Booter — When **`1`** / **`true`**, register **`append`** listeners on the system Hyperdrive metadata and blob Hypercores (when present) to clear **`/bin`** / **`lib/bare`** warm read caches on replication (**offline-first** safety; may increase churn on busy drives).
|
||||
- `BARE_OS_VFS_WARM_CACHE_PREFIX_INVALIDATE` — Booter — When **`1`** / **`true`**, evict warm-cache entries for **`/bin`**, **`/etc`**, **`/lib`**, **`/usr`**, and configured personal prefixes when replicated core lengths increase (see **`metrics_live.replicationLive.warmPrefixInvalidate`**).
|
||||
- `BARE_OS_VFS_WARM_CACHE_INVALIDATE_ON_REPLICATION` — Booter — When **`1`** / **`true`**, call `**ctx.bareOsInvalidateWarmReadCaches('replication:core-length')**` on the same growth signal (full flush; **`metrics_live.warmFullInvalidateOnReplication`**).
|
||||
- `BARE_OS_VFS_WARM_REPL_ADAPTIVE_WINDOW_MS` — Booter — When set to a positive integer and full replication-driven invalidation is active, skip issuing another **full** warm-cache flush if the previous one was within this window (milliseconds), reducing churn on busy swarms while **`replication_operator_sketch`** / core-length signals remain visible in **`metrics_live`**. **`0`** or unset disables the grace window.
|
||||
- `BARE_OS_VFS_WARM_REPL_ADAPTIVE_JITTER_PCT` — Booter — Optional **0–50** integer percent jitter applied to adaptive warm-cache decisions (reduces synchronized invalidation bursts).
|
||||
- **Warm-cache tuning (replication):** With **`BARE_OS_VFS_WARM_CACHE_INVALIDATE_ON_REPLICATION**`, busy swarms can trigger many full flushes. Pair `**BARE_OS_VFS_WARM_REPL_ADAPTIVE_WINDOW_MS**` (for example **250–2000**) with a modest `**BARE_OS_VFS_WARM_REPL_ADAPTIVE_JITTER_PCT**` (for example **10–15**) so invalidations coalesce without starving correctness; prefer `**BARE_OS_VFS_WARM_CACHE_PREFIX_INVALIDATE**` when you only need `**/bin**` / `**/lib**` freshness. `**metrics_live.replicationLive.warmReplAdaptive.skippedFullFlushCount`** surfaces coalescing behavior.
|
||||
- `BARE_OS_HOSTNAME_SET` — Booter / session — When **`1**` / `**true**`, allows `**ctx.bareOsSetSessionHostname**` and `**hostname --set**` to mutate session `**HOSTNAME**` / `**COMPUTERNAME**` (surfaced in `**/proc/bare_os/security_posture.json**` `**hostnameMutation`**).
|
||||
- `BARE_OS_SHELL_POSIX_MODE` — Shell — When **`1**` / `**true**`, `**( compound-list )`** runs as a grouped list in the same session (**no forked subshell**); must be the full top-level statement.
|
||||
- `BARE_OS_WASM_KERNEL` — Booter — When **`1**` / `**true**`, enables `**ctx.bareOsWasmKernelCompile**` (bounded `**WebAssembly.compile**` probe) and `**ctx.bareOsWasmKernelInstantiate**` (bounded `**WebAssembly.instantiate**` with isolated `**Memory**` and `**env.bare_os_nop`**).
|
||||
- `BARE_OS_WASM_KERNEL_SYSCALL` — Booter — When **`1**` / `**true**` with `**BARE_OS_WASM_KERNEL**`, `**instantiate**` also supplies sync Wasm imports `**env.bare_os_pathconf(pathPtr, pathLen, namePtr, nameLen, outPtr, outCap)**` (delegates to `**ctx.bareOsPathconf**`, NUL-terminated result) and `**env.bare_os_umask_get()**` (from session `**UMASK**`), plus `**env.bare_os_wall_time_ms32()**` (low 32 bits of `**Date.now()**`, signed wrap). Async `**ctx.bareOsSyscall`** ops are not exposed to Wasm.
|
||||
- `BARE_OS_WASM_KERNEL_MONOTONIC_MS` — Booter — When **`1**` / `**true**` with `**BARE_OS_WASM_KERNEL_SYSCALL**`, `**instantiate**` also supplies `**env.bare_os_monotonic_ms()**` (`**Number`**, host monotonic ms helper). Still no async syscall bridge into Wasm.
|
||||
- `BARE_OS_WASM_KERNEL_HOSTNAME_IMPORT` — Booter — When **`1**` / `**true**` with `**BARE_OS_WASM_KERNEL_SYSCALL**`, `**instantiate**` also supplies `**env.bare_os_hostname_peek(outPtr, outCap)**`: writes session `**HOSTNAME**` (or `**bare-os`**) NUL-terminated into Wasm memory (bounded).
|
||||
- `BARE_OS_WASM_KERNEL_POSIX_PROFILE_PEEK` — Booter — When **`1**` / `**true**` with `**BARE_OS_WASM_KERNEL_SYSCALL**`, `**instantiate**` also supplies `**env.bare_os_posix_profile_peek(outPtr, outCap)**`: writes declared `**BARE_OS_POSIX_PROFILE_VERSION`** NUL-terminated into Wasm memory (bounded).
|
||||
- `BARE_OS_POSIX_FD_SIM` — Booter — When **`1**` / `**true**`, enables in-memory POSIX-like pipe simulation: `**ctx.bareOsPosixFdSimPipe**`, `**bareOsPosixFdSimDup**`, `**bareOsPosixFdSimRead**`, `**bareOsPosixFdSimWrite**` (logical FD targets under `**posix-pipe:`**; see handbook ch.9).
|
||||
- **Warm-cache tuning (replication):** With **`BARE_OS_VFS_WARM_CACHE_INVALIDATE_ON_REPLICATION`**, busy swarms can trigger many full flushes. Pair **`BARE_OS_VFS_WARM_REPL_ADAPTIVE_WINDOW_MS`** (for example **250–2000**) with a modest **`BARE_OS_VFS_WARM_REPL_ADAPTIVE_JITTER_PCT`** (for example **10–15**) so invalidations coalesce without starving correctness; prefer **`BARE_OS_VFS_WARM_CACHE_PREFIX_INVALIDATE`** when you only need **`/bin`** / **`/lib`** freshness. **`metrics_live.replicationLive.warmReplAdaptive.skippedFullFlushCount`** surfaces coalescing behavior.
|
||||
- `BARE_OS_HOSTNAME_SET` — Booter / session — When **`1`** / **`true`**, allows **`ctx.bareOsSetSessionHostname`** and `**hostname --set**` to mutate session **`HOSTNAME`** / **`COMPUTERNAME`** (surfaced in **`/proc/bare_os/security_posture.json`** **`hostnameMutation`**).
|
||||
- `BARE_OS_SHELL_POSIX_MODE` — Shell — When **`1`** / **`true`**, `**( compound-list )`** runs as a grouped list in the same session (**no forked subshell**); must be the full top-level statement.
|
||||
- `BARE_OS_WASM_KERNEL` — Booter — When **`1`** / **`true`**, enables **`ctx.bareOsWasmKernelCompile`** (bounded **`WebAssembly.compile`** probe) and **`ctx.bareOsWasmKernelInstantiate`** (bounded **`WebAssembly.instantiate`** with isolated **`Memory`** and **`env.bare_os_nop`**).
|
||||
- `BARE_OS_WASM_KERNEL_SYSCALL` — Booter — When **`1`** / **`true`** with **`BARE_OS_WASM_KERNEL`**, **`instantiate`** also supplies sync Wasm imports `**env.bare_os_pathconf(pathPtr, pathLen, namePtr, nameLen, outPtr, outCap)**` (delegates to **`ctx.bareOsPathconf`**, NUL-terminated result) and `**env.bare_os_umask_get()**` (from session **`UMASK`**), plus `**env.bare_os_wall_time_ms32()**` (low 32 bits of `**Date.now()**`, signed wrap). Async **`ctx.bareOsSyscall`** ops are not exposed to Wasm.
|
||||
- `BARE_OS_WASM_KERNEL_MONOTONIC_MS` — Booter — When **`1`** / **`true`** with **`BARE_OS_WASM_KERNEL_SYSCALL`**, **`instantiate`** also supplies `**env.bare_os_monotonic_ms()**` (**`Number`**, host monotonic ms helper). Still no async syscall bridge into Wasm.
|
||||
- `BARE_OS_WASM_KERNEL_HOSTNAME_IMPORT` — Booter — When **`1`** / **`true`** with **`BARE_OS_WASM_KERNEL_SYSCALL`**, **`instantiate`** also supplies `**env.bare_os_hostname_peek(outPtr, outCap)**`: writes session **`HOSTNAME`** (or **`bare-os`**) NUL-terminated into Wasm memory (bounded).
|
||||
- `BARE_OS_WASM_KERNEL_POSIX_PROFILE_PEEK` — Booter — When **`1`** / **`true`** with **`BARE_OS_WASM_KERNEL_SYSCALL`**, **`instantiate`** also supplies `**env.bare_os_posix_profile_peek(outPtr, outCap)**`: writes declared **`BARE_OS_POSIX_PROFILE_VERSION`** NUL-terminated into Wasm memory (bounded).
|
||||
- `BARE_OS_POSIX_FD_SIM` — Booter — When **`1`** / **`true`**, enables in-memory POSIX-like pipe simulation: **`ctx.bareOsPosixFdSimPipe`**, **`bareOsPosixFdSimDup`**, **`bareOsPosixFdSimRead`**, **`bareOsPosixFdSimWrite`** (logical FD targets under **`posix-pipe:`**; see handbook ch.9).
|
||||
- `BARE_OS_POSIX_FD_SIM_MAX_BYTES` — Booter — Max buffered bytes per simulated pipe pair (default **`1048576`**, hard cap **16 MiB**).
|
||||
- `BARE_OS_POSIX_FCNTL_BLOCKING_WAIT` — Booter — When **`1**` / `**true**` / `**yes**`, `**F_SETLKW**` on cooperative advisory locks **waits** (FIFO queue) until the lock is free or `**BARE_OS_FCNTL_LOCK_WAIT_MS_MAX**` elapses (`**ETIMEDOUT`**).
|
||||
- `BARE_OS_FCNTL_LOCK_WAIT_MS_MAX` — Booter — Upper bound in milliseconds for **`F_SETLKW**` blocking wait (default `**30000**`, hard cap `**300000`**).
|
||||
- `BARE_OS_POSIX_SOCKET_FD_BRIDGE` — Booter — When **`1**` / `**true**`, `**ctx.bareOsSyscall('socket')**` allocates a logical bridge fd; `**SOCK_STREAM**` `**bind`/`listen`/`accept**` or `**connect**` use `**ctx.bare.bareTcp**` when merged; `**SOCK_DGRAM**` uses `**ctx.bare.bareDgram**` with passive `**bind**`, optional `**connect**` after `**bind**`, `**recv`/`recvfrom`/`recvmsg**`, and `**send`/`sendmsg**` (when `**udp_bound**` without default peer, pass `**port**` and `**host`/`address**` in syscall args). Binary ancillary on `**sendmsg**` → `**ENOTSUP**`; with `**BARE_OS_POSIX_SOCKET_SCM_RIGHTS**`, JSON `**cmsgs**` with `**{ fds: number[] }**` duplicates logical fds (`**socketMsgSurface` schema 5**). **`poll`/`select**` readiness includes `**udp_bound`** fds. See [syscall-socket-contract.md](syscall-socket-contract.md).
|
||||
- `BARE_OS_POSIX_SOCKET_SCM_RIGHTS` — Booter — When **`1**` / `**true**`, `**sendmsg**` on the socket FD bridge accepts `**cmsgs**` / `**msgHdr.cmsgs**` entries shaped as `**{ fds: number[] }**` (SCM_RIGHTS-style logical FD list). Each source fd is duplicated into a new integer fd (`**scmRightsLocalDup**` in the syscall result). Caps: `**BARE_OS_POSIX_SOCKET_SCM_RIGHTS_MAX_FDS**` (default **4**, max **16**). Bridge sockets in `**created**`, `**bound**`, or `**listening**` state cannot be duplicated. `**shutdown`** uses reference counts when multiple fds alias the same bridge slot.
|
||||
- `BARE_OS_POSIX_FCNTL_BLOCKING_WAIT` — Booter — When **`1`** / **`true`** / **`yes`**, **`F_SETLKW`** on cooperative advisory locks **waits** (FIFO queue) until the lock is free or **`BARE_OS_FCNTL_LOCK_WAIT_MS_MAX`** elapses (**`ETIMEDOUT`**).
|
||||
- `BARE_OS_FCNTL_LOCK_WAIT_MS_MAX` — Booter — Upper bound in milliseconds for **`F_SETLKW`** blocking wait (default **`30000`**, hard cap **`300000`**).
|
||||
- `BARE_OS_POSIX_SOCKET_FD_BRIDGE` — Booter — When **`1`** / **`true`**, `**ctx.bareOsSyscall('socket')**` allocates a logical bridge fd; **`SOCK_STREAM`** `**bind`/`listen`/`accept**` or **`connect`** use **`ctx.bare.bareTcp`** when merged; **`SOCK_DGRAM`** uses **`ctx.bare.bareDgram`** with passive **`bind`**, optional **`connect`** after **`bind`**, `**recv`/`recvfrom`/`recvmsg**`, and `**send`/`sendmsg**` (when **`udp_bound`** without default peer, pass **`port`** and `**host`/`address**` in syscall args). Binary ancillary on **`sendmsg`** → **`ENOTSUP`**; with **`BARE_OS_POSIX_SOCKET_SCM_RIGHTS`**, JSON **`cmsgs`** with `**{ fds: number[] }**` duplicates logical fds (`**socketMsgSurface` schema 5**). **`poll`/`select**` readiness includes **`udp_bound`** fds. See [syscall-socket-contract.md](syscall-socket-contract.md).
|
||||
- `BARE_OS_POSIX_SOCKET_SCM_RIGHTS` — Booter — When **`1`** / **`true`**, **`sendmsg`** on the socket FD bridge accepts **`cmsgs`** / **`msgHdr.cmsgs`** entries shaped as `**{ fds: number[] }**` (SCM_RIGHTS-style logical FD list). Each source fd is duplicated into a new integer fd (**`scmRightsLocalDup`** in the syscall result). Caps: **`BARE_OS_POSIX_SOCKET_SCM_RIGHTS_MAX_FDS`** (default **4**, max **16**). Bridge sockets in **`created`**, **`bound`**, or **`listening`** state cannot be duplicated. **`shutdown`** uses reference counts when multiple fds alias the same bridge slot.
|
||||
- `BARE_OS_POSIX_SOCKET_SCM_RIGHTS_MAX_FDS` — Booter — Integer **1–16**; max logical fds per **`sendmsg`** SCM list (default **4**).
|
||||
- `BARE_OS_PROTOMUX_OPERATOR_STATS_JSON` — Booter — Optional JSON merged into **`/proc/bare_os/protomux.json**` under `**protomuxLibrary.hostOperatorStats`** (opaque counters from host Protomux instrumentation).
|
||||
- `BARE_OS_DISK_OS_OPERATOR_INTENT_RPC` — Booter — When **`1**` / `**true**`, enables `**disk.os` `bare_os.replication_operator_intent**` (`**execRpc`**) to append audit batches.
|
||||
- `BARE_OS_BARE_STDLIB_RESOLVE_CONCURRENCY` — Booter — **`1`–`32**`: parallel `**vfs.readFile**` for `**/lib/bare**` drive bundles during `**maybeMergeBareFromDrive**` (default `**4`**); deterministic merge order unchanged.
|
||||
- `BARE_OS_SEEDER_MULTISIG_VERIFY_RESULT` — Seeder / host — Set to **`ok**`, `**failed**`, or `**skipped**` by `**logPearMultisigKernelHint**`; mirrored in `**/proc/bare_os/security_posture.json**` as `**pearMultisigSeeder.verifyResult`** (no keys).
|
||||
- `BARE_OS_PERSONAL_VAULT_INDEX_CACHE_MS` — Booter — When **> 0** (capped at **3_600_000** ms), **`vfs.readdir**` on `**/.bare` and `/.bare/**`** on the **personal** Hyperdrive may return a **cached** name list for up to that TTL (best-effort; stale until expiry). Default **unset** / **0** — always read from the drive.
|
||||
- `BARE_OS_POSIX_DGRAM_RECVQ_MAX` — Booter — Max queued datagrams per bridged UDP fd (bounded **`recv**` path); default and caps are enforced in the booter. Also bounds per-chunk queue depth for **accepted** SOCK_STREAM bridge fds (`**tcpRecvQueue`**).
|
||||
- `BARE_OS_POSIX_DGRAM_RECV_BLOCK_MS_MAX` — Booter — Optional blocking **`recv**` / `**accept**` wait cap (ms) for bridged UDP fds and for `**accept**` on listening TCP bridge fds before `**EAGAIN`**-shaped timeout notes.
|
||||
- `BARE_OS_POSIX_ACCEPT_QUEUE_MAX` — Booter — Max pending **`bareTcp.Server**` connections held before `**accept`** (default **64**, cap **1024**).
|
||||
- `BARE_OS_PROTOMUX_APP_CHANNEL` — Booter / seeder — When **`1**` / `**true**`, opens a second Protomux channel `**bare-os-app-v1**` alongside `**bare-os-v1**` for namespaced app RPC (see `**bare-os-protocol**` `**PROTOCOL_APP_CHANNEL_NAME`**).
|
||||
- `BARE_OS_PROTOMUX_CAP_CHANNEL` — Booter — When **`1**` / `**true**`, opens optional Protomux channel `**bare-os-cap-v1**` for capability-scoped guest IPC experiments (gated by kernel feature bit `**BARE_OS_FEATURE8_PROTOMUX_CAP_CHANNEL**`). Inbound cap payloads larger than **65536** bytes are dropped (`**protomux_cap_payload_oversized**` host log); `**protomuxCapChannelRxTotal`** counts only accepted messages.
|
||||
- `BARE_OS_PROTOMUX_CHAT_CHANNEL` — Booter / seeder — **Stock default: swarm chat is on.** Set to **`0**`, `**false**`, `**off**`, or `**no**` (trimmed, case-insensitive) to **disable** pairing Protomux channel `**bare-os-chat-v1**` on Hyperswarm connections (noise-encrypted transport; capability word `**BARE_OS_FEATURE11_SWARM_CHAT**`). When chat is active, the host booter wires `**ctx.bareOsChatSend**` / `**/proc/bare_os/chat.json`**.
|
||||
- `BARE_OS_CHAT_INITD` — Booter — When **`0**` / `**false**`, skips registering the `**bare-os-chat`** initd marker unit (stock default follows chat mux gate). Does not disable the wire protocol when swarm chat remains enabled (default).
|
||||
- `BARE_OS_PROTOMUX_OPERATOR_STATS_JSON` — Booter — Optional JSON merged into **`/proc/bare_os/protomux.json`** under **`protomuxLibrary.hostOperatorStats`** (opaque counters from host Protomux instrumentation).
|
||||
- `BARE_OS_DISK_OS_OPERATOR_INTENT_RPC` — Booter — When **`1`** / **`true`**, enables `**disk.os` `bare_os.replication_operator_intent**` (**`execRpc`**) to append audit batches.
|
||||
- `BARE_OS_BARE_STDLIB_RESOLVE_CONCURRENCY` — Booter — **`1`–`32**`: parallel **`vfs.readFile`** for **`/lib/bare`** drive bundles during **`maybeMergeBareFromDrive`** (default **`4`**); deterministic merge order unchanged.
|
||||
- `BARE_OS_SEEDER_MULTISIG_VERIFY_RESULT` — Seeder / host — Set to **`ok`**, **`failed`**, or **`skipped`** by **`logPearMultisigKernelHint`**; mirrored in **`/proc/bare_os/security_posture.json`** as **`pearMultisigSeeder.verifyResult`** (no keys).
|
||||
- `BARE_OS_PERSONAL_VAULT_INDEX_CACHE_MS` — Booter — When **> 0** (capped at **3_600_000** ms), **`vfs.readdir`** on `**/.bare` and `/.bare/**`** on the **personal** Hyperdrive may return a **cached** name list for up to that TTL (best-effort; stale until expiry). Default **unset** / **0** — always read from the drive.
|
||||
- `BARE_OS_POSIX_DGRAM_RECVQ_MAX` — Booter — Max queued datagrams per bridged UDP fd (bounded **`recv`** path); default and caps are enforced in the booter. Also bounds per-chunk queue depth for **accepted** SOCK_STREAM bridge fds (**`tcpRecvQueue`**).
|
||||
- `BARE_OS_POSIX_DGRAM_RECV_BLOCK_MS_MAX` — Booter — Optional blocking **`recv`** / **`accept`** wait cap (ms) for bridged UDP fds and for **`accept`** on listening TCP bridge fds before **`EAGAIN`**-shaped timeout notes.
|
||||
- `BARE_OS_POSIX_ACCEPT_QUEUE_MAX` — Booter — Max pending **`bareTcp.Server`** connections held before **`accept`** (default **64**, cap **1024**).
|
||||
- `BARE_OS_PROTOMUX_APP_CHANNEL` — Booter / seeder — When **`1`** / **`true`**, opens a second Protomux channel **`bare-os-app-v1`** alongside **`bare-os-v1`** for namespaced app RPC (see **`bare-os-protocol`** **`PROTOCOL_APP_CHANNEL_NAME`**).
|
||||
- `BARE_OS_PROTOMUX_CAP_CHANNEL` — Booter — When **`1`** / **`true`**, opens optional Protomux channel **`bare-os-cap-v1`** for capability-scoped guest IPC experiments (gated by kernel feature bit **`BARE_OS_FEATURE8_PROTOMUX_CAP_CHANNEL`**). Inbound cap payloads larger than **65536** bytes are dropped (**`protomux_cap_payload_oversized`** host log); **`protomuxCapChannelRxTotal`** counts only accepted messages.
|
||||
- `BARE_OS_PROTOMUX_CHAT_CHANNEL` — Booter / seeder — **Stock default: swarm chat is on.** Set to **`0`**, **`false`**, **`off`**, or **`no`** (trimmed, case-insensitive) to **disable** pairing Protomux channel **`bare-os-chat-v1`** on Hyperswarm connections (noise-encrypted transport; capability word **`BARE_OS_FEATURE11_SWARM_CHAT`**). When chat is active, the host booter wires **`ctx.bareOsChatSend`** / **`/proc/bare_os/chat.json`**.
|
||||
- `BARE_OS_CHAT_INITD` — Booter — When **`0`** / **`false`**, skips registering the **`bare-os-chat`** initd marker unit (stock default follows chat mux gate). Does not disable the wire protocol when swarm chat remains enabled (default).
|
||||
- `BARE_OS_CHAT_GOSSIP_TTL` — Booter — Optional **`0`–`32`** relay hop budget for unseen chat events (**default `4`**).
|
||||
- `BARE_OS_CHAT_HISTORY_MAX` — Booter — Ring buffer depth for recent chat records (**default `512**`, range `**16`–`10000`**).
|
||||
- `BARE_OS_CHAT_MAX_BODY_BYTES` — Booter — Max UTF-8 body bytes per **`event`** frame (**default `4096`**).
|
||||
- `BARE_OS_WWW_INITD` — Booter — When **`0**` / `**false**`, skips registering the `**bare-os-www`** initd unit (stock default: unit **on**).
|
||||
- `BARE_OS_WWW_PORT` — Booter — TCP port for the loopback static HTTP server (default **`8088**`; must match the auto-managed Holesail entry when `**BARE_OS_WWW_HOLESAIL`** is on).
|
||||
- `BARE_OS_WWW_HOST` — Booter — Bind address for **`bare-os-www**` (default `**127.0.0.1**`; `**0.0.0.0`** exposes the port on all interfaces — use only with care).
|
||||
- `BARE_OS_HOLESAIL_STATE` — Booter — Logical JSON path for **managed** Holesail tunnels. **Stock default:** **`~/.holesail/state.json**` (resolved under the session `**$HOME**`). **Override** this variable to use a different path (e.g. `**/.bare/holesail/state.json**` on the personal drive). On first read, if the primary file is missing or empty, legacy `**/.bare/holesail/state.json**`, `**/.bare/holesail/guest/state.json**`, and `**/home/guest/.holesail/state.json**` are merged. See handbook [ch.4 — The booter runtime](../../handbook/04-the-booter-runtime.md) (**§ bare-holesail**) for `**seed**` / `**key`** persistence.
|
||||
- `BARE_OS_WWW_HOLESAIL` — Booter — When **`0**` / `**false**`, skips idempotently merging `**bare-www-<port>**` into managed Holesail `**state.json**` after `**bare-os-www`** listens (stock default: **on**).
|
||||
- `BARE_OS_SSH_HOLESAIL` — Booter — When **`0**` / `**false**`, skips idempotently merging `**bare-ssh-<port>**` into the **same** managed `**state.json**` after `**bare-openssh**` listens (stock default: **on**). `**port**` / `**host**` match the actual SSH bind (defaults `**127.0.0.1:2222**` unless `**sshd_config**` / `**BARE_OS_SSH_*`** change them).
|
||||
- `BARE_OS_COLLAB_SESSION_NDJSON` — Booter — When **`1**` / `**true`**, host boot trace may append collaboration session lines (non-secret peer counts) via swarm-disk logging.
|
||||
- `BARE_OS_PHYS_PAGES_HINT` — Booter — Optional integer string for **`getconf _SC_PHYS_PAGES**` via `**ctx.bareOsGetconfSysconf**` (default `**524288`** when unset).
|
||||
- `BARE_OS_SHELL_HEREDOC_MAX_BYTES` — Booter — When **`BARE_OS_SHELL_POSIX_MODE**` is on, caps here-document body size (default `**262144`**, max **2 MiB**).
|
||||
- `BARE_OS_SHELL_LOOP_MAX` — Shell — Max iterations for **`while**` / `**for`** (default **10000**).
|
||||
- `BARE_OS_WWW_INITD` — Booter — When **`0`** / **`false`**, skips registering the **`bare-os-www`** initd unit (stock default: unit **on**).
|
||||
- `BARE_OS_WWW_PORT` — Booter — TCP port for the loopback static HTTP server (default **`8088`**; must match the auto-managed Holesail entry when **`BARE_OS_WWW_HOLESAIL`** is on).
|
||||
- `BARE_OS_WWW_HOST` — Booter — Bind address for **`bare-os-www`** (default **`127.0.0.1`**; **`0.0.0.0`** exposes the port on all interfaces — use only with care).
|
||||
- `BARE_OS_HOLESAIL_STATE` — Booter — Logical JSON path for **managed** Holesail tunnels. **Stock default:** **`~/.holesail/state.json`** (resolved under the session **`$HOME`**). **Override** this variable to use a different path (e.g. **`/.bare/holesail/state.json`** on the personal drive). On first read, if the primary file is missing or empty, legacy **`/.bare/holesail/state.json`**, **`/.bare/holesail/guest/state.json`**, and **`/home/guest/.holesail/state.json`** are merged. See handbook [ch.4 — The booter runtime](../../handbook/04-the-booter-runtime.md) (**§ bare-holesail**) for **`seed`** / **`key`** persistence.
|
||||
- `BARE_OS_WWW_HOLESAIL` — Booter — When **`0`** / **`false`**, skips idempotently merging **`bare-www-<port>`** into managed Holesail **`state.json`** after **`bare-os-www`** listens (stock default: **on**).
|
||||
- `BARE_OS_SSH_HOLESAIL` — Booter — When **`0`** / **`false`**, skips idempotently merging **`bare-ssh-<port>`** into the **same** managed **`state.json`** after **`bare-openssh`** listens (stock default: **on**). **`port`** / **`host`** match the actual SSH bind (defaults **`127.0.0.1:2222`** unless **`sshd_config`** / **`BARE_OS_SSH_*`** change them).
|
||||
- `BARE_OS_COLLAB_SESSION_NDJSON` — Booter — When **`1`** / **`true`**, host boot trace may append collaboration session lines (non-secret peer counts) via swarm-disk logging.
|
||||
- `BARE_OS_PHYS_PAGES_HINT` — Booter — Optional integer string for **`getconf _SC_PHYS_PAGES**` via **`ctx.bareOsGetconfSysconf`** (default **`524288`** when unset).
|
||||
- `BARE_OS_SHELL_HEREDOC_MAX_BYTES` — Booter — When **`BARE_OS_SHELL_POSIX_MODE`** is on, caps here-document body size (default **`262144`**, max **2 MiB**).
|
||||
- `BARE_OS_SHELL_LOOP_MAX` — Shell — Max iterations for **`while`** / **`for`** (default **10000**).
|
||||
- `BARE_OS_SHELL_CASE_MAX_BRANCHES` — Shell — Max **`case`** branches (default **32**).
|
||||
- `BARE_OS_STRICT_POSIX` — Shell / utilities — When **`1`**, pathname globs that match nothing fail the command; tighter diagnostics elsewhere as documented.
|
||||
- `BARE_OS_SHELL_NOGLOB` — Shell — When **`1**`, pathname expansion is disabled (`**set -f**` sets this; `**set +f`** clears).
|
||||
- `BARE_OS_SHELL_NOGLOB` — Shell — When **`1`**, pathname expansion is disabled (`**set -f**` sets this; `**set +f`** clears).
|
||||
- `BARE_OS_GLOB_MAX_MATCHES` — Shell — Max matches per glob word (default **4096**).
|
||||
- `BARE_OS_GLOB_IGNORE` — Shell — Colon-separated fnmatch patterns excluded from glob results.
|
||||
- `BARE_OS_PROC_BLIND_PEER_RELAY_HINTS` — Booter / `/proc` — When **`1**` / `**true**` / `**yes**`, `**blind_relay_router**`, `**blind_pairing_sketch**`, and `**relay_geo_hint**` under `**/proc/bare_os**` use **schema 2** JSON: `**exposed:true**`, env-injected operator sketches (`**BARE_OS_BLIND_RELAY_ROUTER_JSON**`, `**BARE_OS_BLIND_PAIRING_SKETCH_JSON**`, `**BARE_OS_RELAY_GEO_HINT_JSON**`) plus a live `**swarm**` object (**peer count**, `**relayGeoTier`** `isolated` \| `single_peer` \| `multi_peer`, **`pairingSurfaceReady**`, `**lifecycle**`, and optional `**protomuxBackpressure**` when `**BARE_OS_SWARM_PROTOMUX_BACKPRESSURE_COUNT**` is set) from the same non-secret rules as `**bareOsSwarmLifecycleSnapshot**`. Default remains **schema 1** (`**operatorRedacted:true**`, `**exposed:false`**) — no swarm aggregates until the operator opts in.
|
||||
- `BARE_OS_PROC_BLIND_PEER_RELAY_HINTS` — Booter / `/proc` — When **`1`** / **`true`** / **`yes`**, **`blind_relay_router`**, **`blind_pairing_sketch`**, and **`relay_geo_hint`** under **`/proc/bare_os`** use **schema 2** JSON: **`exposed:true`**, env-injected operator sketches (**`BARE_OS_BLIND_RELAY_ROUTER_JSON`**, **`BARE_OS_BLIND_PAIRING_SKETCH_JSON`**, **`BARE_OS_RELAY_GEO_HINT_JSON`**) plus a live **`swarm`** object (**peer count**, **`relayGeoTier`** `isolated` \| `single_peer` \| `multi_peer`, **`pairingSurfaceReady`**, **`lifecycle`**, and optional **`protomuxBackpressure`** when **`BARE_OS_SWARM_PROTOMUX_BACKPRESSURE_COUNT`** is set) from the same non-secret rules as **`bareOsSwarmLifecycleSnapshot`**. Default remains **schema 1** (**`operatorRedacted:true`**, **`exposed:false`**) — no swarm aggregates until the operator opts in.
|
||||
- `BARE_OS_SWARM_PROTOMUX_BACKPRESSURE_COUNT` — Booter — Non-secret integer surfaced in blind-relay **`swarm.protomuxBackpressure`** aggregates when relay hints are exposed.
|
||||
- `BARE_OS_PROC_PROTOMUX_EXTENSIONS_REGISTRY` — Booter / `/proc` — When **`1**` / `**true**`, exposes `**/proc/bare_os/protomux_extensions.json**` and `**ctx.bareOsReadProtomuxExtensionsJson()**` with the operator Protomux alias registry snapshot and logical extension channel hints; default `**exposed:false`**.
|
||||
- `BARE_OS_BARE_SUBPROCESS_BRIDGE` — Booter / kernel-runner — When **`1**` / `**true**`, enables the documented host `**bare-subprocess`** bridge path for long-running children.
|
||||
- `BARE_OS_BARE_SUBPROCESS_TIMEOUT_MS` — Booter / kernel-runner — When set with **`BARE_OS_BARE_SUBPROCESS_BRIDGE**`, supplies a default `**runBin`** timeout when the caller omits one.
|
||||
- `BARE_OS_CTX_BARE_SUBPROCESS_SPAWN` — Booter — When **`1**` / `**true**`, `**ctx.bareOsTrySpawnHostSubprocess**` tries `**ctx.bare.bareSubprocess.spawn**` first (merged drive catalog) before dynamic `**bare-subprocess**` import. Surfaced under `**ctx.bareOsRuntimeCaps.features.ctxBareSubprocessSpawn`**.
|
||||
- `BARE_OS_DOTGLOB` — Shell — When **`1**`, globbing includes names starting with `**.**` (except `**.bareos_empty`**).
|
||||
- `BARE_OS_SHELL_BRACE_EXPANSION` — Shell — When **`1**`, unquoted `**{a,b}`** brace expansion runs before globbing.
|
||||
- `BARE_OS_PROC_PROTOMUX_EXTENSIONS_REGISTRY` — Booter / `/proc` — When **`1`** / **`true`**, exposes **`/proc/bare_os/protomux_extensions.json`** and `**ctx.bareOsReadProtomuxExtensionsJson()**` with the operator Protomux alias registry snapshot and logical extension channel hints; default **`exposed:false`**.
|
||||
- `BARE_OS_BARE_SUBPROCESS_BRIDGE` — Booter / kernel-runner — When **`1`** / **`true`**, enables the documented host **`bare-subprocess`** bridge path for long-running children.
|
||||
- `BARE_OS_BARE_SUBPROCESS_TIMEOUT_MS` — Booter / kernel-runner — When set with **`BARE_OS_BARE_SUBPROCESS_BRIDGE`**, supplies a default **`runBin`** timeout when the caller omits one.
|
||||
- `BARE_OS_CTX_BARE_SUBPROCESS_SPAWN` — Booter — When **`1`** / **`true`**, **`ctx.bareOsTrySpawnHostSubprocess`** tries **`ctx.bare.bareSubprocess.spawn`** first (merged drive catalog) before dynamic **`bare-subprocess`** import. Surfaced under **`ctx.bareOsRuntimeCaps.features.ctxBareSubprocessSpawn`**.
|
||||
- `BARE_OS_DOTGLOB` — Shell — When **`1`**, globbing includes names starting with **`.`** (except **`.bareos_empty`**).
|
||||
- `BARE_OS_SHELL_BRACE_EXPANSION` — Shell — When **`1`**, unquoted `**{a,b}`** brace expansion runs before globbing.
|
||||
- `BARE_OS_GREP_FILTER_MAX` — **`grep -r**` — Max `**--include` / `--exclude` / `--exclude-dir`** glob patterns (default **32**).
|
||||
- `BARE_OS_SED_NULL_MAX_RECORDS` — **`sed -z`** — Max NUL-separated records per run (default **100000**).
|
||||
- `BARE_OS_AWK_FIELDWIDTHS` — **`awk**` — When `**1**` / `**true**`, `**FIELDWIDTHS`** in the awk program selects fixed-width field splitting (space-separated widths; remainder is the last field).
|
||||
- `BARE_OS_HYPER_MULTISIG_VERIFY` — Seeder — When set, runs **`hyper-multisig verify`** via **[`bare-subprocess`](https://github.com/holepunchto/bare-subprocess)** under Pear/Bare (dependency of **`bare-os-seeder**`), or `**child_process**` on Node. Requires `**hyper-multisig**` on `**PATH`**.
|
||||
- `BARE_OS_EXTENSION_MULTISIG_VERIFY` — Stock kernel — When **`1**` / `**true**`, the guest kernel may require a valid `**/etc/bare-os/pear.multisig.json**` before executing `**kernel.ext.d`** extensions (see init-main multisig gate).
|
||||
- `BARE_OS_BOOT_POLICY_REQUIRE_PEAR_MULTISIG` — Stock kernel / boot policy — When **`1**` / `**true**`, strict boot fails if `**pear.multisig.json`** is missing when the multisig gate is active.
|
||||
- `BARE_OS_AWK_FIELDWIDTHS` — **`awk`** — When **`1`** / **`true`**, **`FIELDWIDTHS`** in the awk program selects fixed-width field splitting (space-separated widths; remainder is the last field).
|
||||
- `BARE_OS_HYPER_MULTISIG_VERIFY` — Seeder — When set, runs **`hyper-multisig verify`** via **[`bare-subprocess`](https://github.com/holepunchto/bare-subprocess)** under Pear/Bare (dependency of **`bare-os-seeder`**), or **`child_process`** on Node. Requires **`hyper-multisig`** on **`PATH`**.
|
||||
- `BARE_OS_EXTENSION_MULTISIG_VERIFY` — Stock kernel — When **`1`** / **`true`**, the guest kernel may require a valid **`/etc/bare-os/pear.multisig.json`** before executing **`kernel.ext.d`** extensions (see init-main multisig gate).
|
||||
- `BARE_OS_BOOT_POLICY_REQUIRE_PEAR_MULTISIG` — Stock kernel / boot policy — When **`1`** / **`true`**, strict boot fails if **`pear.multisig.json`** is missing when the multisig gate is active.
|
||||
|
||||
### Capability word 6 (selected)
|
||||
|
||||
- `BARE_OS_DNS_MAP_JSON` — Booter / resolver — Bounded JSON static split-horizon map; summary in **`/proc/bare_os/dns_map_active.json`**.
|
||||
- `BARE_OS_RESUME_STAGGER_MS` — Stock kernel / initd — Optional delay between unit starts on resume.
|
||||
- `BARE_OS_BIN_WORKER_WALL_MS` — Booter — Per-invocation wall-clock cap for **`bare-worker**` `**/bin`** offload.
|
||||
- `BARE_OS_BIN_WORKER_WALL_MS` — Booter — Per-invocation wall-clock cap for **`bare-worker`** **`/bin`** offload.
|
||||
- `BARE_OS_SHM_MAX_BYTES` — VFS — Cap for **`/dev/shm`** backed on the personal drive.
|
||||
- `BARE_OS_PROC_ALIAS_STRICT` — Booter — **`1**` — fail boot if `**/proc/bare_os`** alias manifest is incomplete.
|
||||
- `BARE_OS_PROC_ALIAS_STRICT` — Booter — **`1`** — fail boot if **`/proc/bare_os`** alias manifest is incomplete.
|
||||
- `BARE_OS_KERNEL_PROFILE_WARM_RC_ONLY` — Stock kernel — With warm profile reload: apply **`rc.d`** only (skip full init path).
|
||||
- `BARE_OS_BOOT_POLICY_DENY_KERNEL_EXT_IDS` / `BARE_OS_BOOT_POLICY_EXTENSION_HASH_PINS_JSON` — Stock kernel — Set from **`boot.policy.json**` v6 `**denyKernelExtensionIds**` / `**kernelExtensionHashPins`** when policy merge runs.
|
||||
- `BARE_OS_BOOT_POLICY_DENY_KERNEL_EXT_IDS` / `BARE_OS_BOOT_POLICY_EXTENSION_HASH_PINS_JSON` — Stock kernel — Set from **`boot.policy.json`** v6 **`denyKernelExtensionIds`** / **`kernelExtensionHashPins`** when policy merge runs.
|
||||
|
||||
**Session env (set by booter, not user configuration):** `USER`, `LOGNAME`, `HOME`, `PWD`, `UID`, `GID`, `GROUP`, `BARE_OS_IDENTITY` (`guest` or `unlocked`), `BARE_OS_CTX_API_VERSION`, `BARE_OS_SESSION_ID`, `BARE_OS_BOOT_PROFILE_RESOLVED`, and when unlocked `BARE_OS_PUBLIC_KEY` (hex Ed25519 public key).
|
||||
|
||||
**Personal-drive identity layout (operator-tunable):**
|
||||
|
||||
- **`BARE_OS_PERSONAL_ROOT_MIGRATE`** — Legacy lift of flat `/` entries into `/.bare-os/home/<seg>/`: **`skip**` (never), `**guest**` (allow guest lift even when `**/.bare/account**` exists — unsafe), `**unlocked-only**` (never lift into guest home). Unset: **safe default** — guest lift is **skipped** when an account blob exists so another principal’s files never land under `**/home/guest**`. State file: `**/.bare-os/migration/legacy-root-v1.json`**.
|
||||
- **`BARE_OS_PERSONAL_ACCT_PREFIX**` — When `**1**` / `**true**`, session trees live under `**/.bare-os/acct/<id>/home|tmp|var/log/…`** (see [multi-account design](../design/multi-account-personal-subvolumes.md)).
|
||||
- **`BARE_OS_GUEST_SCRUB**` — When `**1**` / `**true**`, entering **guest** best-effort deletes the guest `**/tmp**` segment and `**~/.cache**` / `**~/tmp`** under the guest home prefix on the personal drive (kiosk-style).
|
||||
- **`BARE_OS_GUEST_BARE_READ_ALL**` — When `**1**` / `**true**`, lifts VFS deny on sealed `**/.bare/account**` and `**/.bare/vault/**`** for **guest** (testing only).
|
||||
- **`BARE_OS_PERSONAL_ROOT_MIGRATE`** — Legacy lift of flat `/` entries into `/.bare-os/home/<seg>/`: **`skip`** (never), **`guest`** (allow guest lift even when **`/.bare/account`** exists — unsafe), **`unlocked-only`** (never lift into guest home). Unset: **safe default** — guest lift is **skipped** when an account blob exists so another principal’s files never land under **`/home/guest`**. State file: **`/.bare-os/migration/legacy-root-v1.json`**.
|
||||
- **`BARE_OS_PERSONAL_ACCT_PREFIX`** — When **`1`** / **`true`**, session trees live under `**/.bare-os/acct/<id>/home|tmp|var/log/…`** (see [multi-account design](../design/multi-account-personal-subvolumes.md)).
|
||||
- **`BARE_OS_GUEST_SCRUB`** — When **`1`** / **`true`**, entering **guest** best-effort deletes the guest **`/tmp`** segment and **`~/.cache`** / **`~/tmp`** under the guest home prefix on the personal drive (kiosk-style).
|
||||
- **`BARE_OS_GUEST_BARE_READ_ALL`** — When **`1`** / **`true`**, lifts VFS deny on sealed **`/.bare/account`** and **`/.bare/vault/`**** for **guest** (testing only).
|
||||
|
||||
**Theme and color (from `~/.barerc`, `/bin/theme`, and `applyBareOsThemeFromEnv`):**
|
||||
|
||||
@@ -320,18 +320,18 @@ 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`).
|
||||
|
||||
- **Pear working directory** — Some Pear/Bare hosts expose **`process.cwd()`** as an empty string. The booter’s **[`packages/bare-os-booter/lib/paths.js`](../../packages/bare-os-booter/lib/paths.js)** falls back to **`bare-os` `os.cwd()**` when resolving `**packageRootDir**` and Corestore path helpers. `**ctx.bare**` manifest selection under `**pear://**` uses embedded `**bare-module-manifest.data.mjs**` (not host FS), so an empty `**process.cwd()`** does not block boot; see [PEAR-RUN.md](../PEAR-RUN.md) and [Developer guide ch.12](../../developer-guide/12-bare-modules-and-pear-ecosystem.md).
|
||||
- **Pear working directory** — Some Pear/Bare hosts expose **`process.cwd()`** as an empty string. The booter’s **[`packages/bare-os-booter/lib/paths.js`](../../packages/bare-os-booter/lib/paths.js)** falls back to **`bare-os` `os.cwd()**` when resolving **`packageRootDir`** and Corestore path helpers. **`ctx.bare`** manifest selection under **`pear://`** uses embedded **`bare-module-manifest.data.mjs`** (not host FS), so an empty `**process.cwd()`** does not block boot; see [PEAR-RUN.md](../PEAR-RUN.md) and [Developer guide ch.12](../../developer-guide/12-bare-modules-and-pear-ecosystem.md).
|
||||
|
||||
- **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).
|
||||
- **Errno vocabulary** — **`/proc/bare_os/syscalls.json**` `**errnoHints**` and `**errnoAlignment`** document Linux-style integers (same family as **libuv** / **Holepunch `bare-fs**` binding `**error.code**` strings). Utilities such as `**mkdir**` print `**errno: message**` on stderr when the caught error exposes a string `**code**` (for example `**EEXIST**`, `**EACCES**`), matching the vocabulary in `**errnoHints**`. Simulated logical FDs (`**BARE_OS_POSIX_FD_SIM**`) use `**EBADF**`, `**EAGAIN**`, `**EINVAL**`, `**ENOSYS**`, `**EOPNOTSUPP**` consistently; `**fcntl**` cooperative `**F_SETLK**` returns `**EAGAIN**` when contended; `**F_SETLKW**` does the same unless `**BARE_OS_POSIX_FCNTL_BLOCKING_WAIT**` is set (then `**ETIMEDOUT**` when `**BARE_OS_FCNTL_LOCK_WAIT_MS_MAX**` elapses). Cooperative waits are **not** kernel futexes: callers may see an `**EINTR`-shaped note** when a blocking wait is interrupted by policy rather than a real signal. **`fcntl**` `**O_APPEND**`/`**O_NONBLOCK**` bit masks align with `**bare-fs`** open-flag shapes when the host resolves native FS errors.
|
||||
- **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**` (**157** commands; authoritative list `**COREUTILS_COMMANDS**` in `**packages/bare-os-coreutils/lib/commands.mjs**`; `**sshd**`/`**bare-sshd**` binaries come from `**bare-os-openssh**`; 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**`, `**sha224sum**` (bundled SHA-224), `**sha256sum**`, `**sha384sum**`, `**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`**.
|
||||
- **Process tooling note** — **`ps**` and `**kill`** operate on Bare OS synthetic process rows (`pid` 1..3 for kernel/booter/shell); they do not target host OS processes.
|
||||
- **Additional utility coverage** — **`dd**` (block-copy subset) and `**logger**` (structured append to `**/var/log/messages`**) are available as Tier-1 commands.
|
||||
- **Mount tooling note** — **`mount**` / `**umount`** are Hyperdrive/HDMS-backed commands for `/mnt/<label>` and are not host-kernel mount syscalls.
|
||||
- **Process introspection note** — **`procstat**` prints `**/proc/bare_os/process_table.json`** (synthetic process table) for automation/debugging.
|
||||
- **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).
|
||||
- **Errno vocabulary** — **`/proc/bare_os/syscalls.json`** **`errnoHints`** and **`errnoAlignment`** document Linux-style integers (same family as **libuv** / **Holepunch `bare-fs**` binding **`error.code`** strings). Utilities such as **`mkdir`** print `**errno: message**` on stderr when the caught error exposes a string **`code`** (for example **`EEXIST`**, **`EACCES`**), matching the vocabulary in **`errnoHints`**. Simulated logical FDs (**`BARE_OS_POSIX_FD_SIM`**) use **`EBADF`**, **`EAGAIN`**, **`EINVAL`**, **`ENOSYS`**, **`EOPNOTSUPP`** consistently; **`fcntl`** cooperative **`F_SETLK`** returns **`EAGAIN`** when contended; **`F_SETLKW`** does the same unless **`BARE_OS_POSIX_FCNTL_BLOCKING_WAIT`** is set (then **`ETIMEDOUT`** when **`BARE_OS_FCNTL_LOCK_WAIT_MS_MAX`** elapses). Cooperative waits are **not** kernel futexes: callers may see an `**EINTR`-shaped note** when a blocking wait is interrupted by policy rather than a real signal. **`fcntl`** **`O_APPEND`**/**`O_NONBLOCK`** bit masks align with **`bare-fs`** open-flag shapes when the host resolves native FS errors.
|
||||
- **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`** (**157** commands; authoritative list **`COREUTILS_COMMANDS`** in **`packages/bare-os-coreutils/lib/commands.mjs`**; **`sshd`**/**`bare-sshd`** binaries come from **`bare-os-openssh`**; 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`**, **`sha224sum`** (bundled SHA-224), **`sha256sum`**, **`sha384sum`**, **`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`**.
|
||||
- **Process tooling note** — **`ps`** and **`kill`** operate on Bare OS synthetic process rows (`pid` 1..3 for kernel/booter/shell); they do not target host OS processes.
|
||||
- **Additional utility coverage** — **`dd`** (block-copy subset) and **`logger`** (structured append to **`/var/log/messages`**) are available as Tier-1 commands.
|
||||
- **Mount tooling note** — **`mount`** / **`umount`** are Hyperdrive/HDMS-backed commands for `/mnt/<label>` and are not host-kernel mount syscalls.
|
||||
- **Process introspection note** — **`procstat`** prints **`/proc/bare_os/process_table.json`** (synthetic process table) for automation/debugging.
|
||||
|
||||
**Handbook:** [handbook/09-posix-utilities-shell-and-vfs.md](../../handbook/09-posix-utilities-shell-and-vfs.md) — narrative catalog, engine notes, and Issue 7 alignment. **Manual pages:** [handbook/10-manpages-and-online-help.md](../../handbook/10-manpages-and-online-help.md).
|
||||
|
||||
|
||||
@@ -35,7 +35,7 @@ This file tracks the twenty-item “kernel super-features” baseline plus expan
|
||||
|
||||
## Capability word 5 checklist (twenty-item super-feature plan)
|
||||
|
||||
Capability word **5** introduces the **fifth capability word** (**`bits5` / host transport delegates**), a **seeder RPC registry** so method lists do not drift, replication queue hints, an **automated compatibility matrix** check in CI, host OS probing under **`/proc**`, subprocess bridge lifecycle v2, transport observability, stricter **boot policy**, scheduled replication windows, union `**readlink**`, kernel profile warm reload, HDMS hints v2, seed-channel error hygiene, `**man**` coverage CI, OTel schema v2, bare-worker allowlist patterns, A/B staging rollback hints, a dev `**/proc/bare_os/debug.json**`, `**ctx.bare`** risk metadata in manifests, and documentation coherence checks.
|
||||
Capability word **5** introduces the **fifth capability word** (**`bits5` / host transport delegates**), a **seeder RPC registry** so method lists do not drift, replication queue hints, an **automated compatibility matrix** check in CI, host OS probing under **`/proc`**, subprocess bridge lifecycle v2, transport observability, stricter **boot policy**, scheduled replication windows, union **`readlink`**, kernel profile warm reload, HDMS hints v2, seed-channel error hygiene, **`man`** coverage CI, OTel schema v2, bare-worker allowlist patterns, A/B staging rollback hints, a dev **`/proc/bare_os/debug.json`**, **`ctx.bare`** risk metadata in manifests, and documentation coherence checks.
|
||||
|
||||
| # | Item | Status |
|
||||
|---|------|--------|
|
||||
@@ -62,7 +62,7 @@ Capability word **5** introduces the **fifth capability word** (**`bits5` / host
|
||||
|
||||
## Mega-kernel capability words (6–11)
|
||||
|
||||
Capability words **6** through **11** use **hundred-item** checklists that track the mega-kernel program: capability words, **`ctx**` API semver, boot policy revisions, seed RPC additions, `**/proc/bare_os/`** schema bumps, telemetry and audit schema versions, and Pear or Bare runtime gates. Rows stay **terse** by design; follow links in each row, [`kernel-extensions.md`](./kernel-extensions.md), and [`developer-guide/adr/001-kernel-feature-bits-governance.md`](../../developer-guide/adr/001-kernel-feature-bits-governance.md) for prose explanations.
|
||||
Capability words **6** through **11** use **hundred-item** checklists that track the mega-kernel program: capability words, **`ctx`** API semver, boot policy revisions, seed RPC additions, **`/proc/bare_os/`** schema bumps, telemetry and audit schema versions, and Pear or Bare runtime gates. Rows stay **terse** by design; follow links in each row, [`kernel-extensions.md`](./kernel-extensions.md), and [`developer-guide/adr/001-kernel-feature-bits-governance.md`](../../developer-guide/adr/001-kernel-feature-bits-governance.md) for prose explanations.
|
||||
|
||||
## Capability word 6 checklist (100-item mega kernel)
|
||||
|
||||
@@ -108,7 +108,7 @@ Capability words **6** through **11** use **hundred-item** checklists that track
|
||||
| 38 | /proc/bare_os/dns_map_active.json | done — split-horizon summary |
|
||||
| 39 | /proc/bare_os/git_delegate_stats.json | done — fetch depth summary |
|
||||
| 40 | /proc/bare_os/index.json manifest | done — bare_os_proc_index schema 2 |
|
||||
| 41 | ctx.bareOsPearUpdaterDelegate | done — async bridge: **`BARE_OS_PEAR_UPDATER_MODULE**` / `**BARE_OS_PEAR_UPDATER_SNAPSHOT_JSON`** via [`bare-os-pear-updater-bridge.js`](../../packages/bare-os-booter/lib/bare-os-pear-updater-bridge.js) |
|
||||
| 41 | ctx.bareOsPearUpdaterDelegate | done — async bridge: **`BARE_OS_PEAR_UPDATER_MODULE`** / **`BARE_OS_PEAR_UPDATER_SNAPSHOT_JSON`** via [`bare-os-pear-updater-bridge.js`](../../packages/bare-os-booter/lib/bare-os-pear-updater-bridge.js) |
|
||||
| 42 | ctx.bareOsEmitHyperdhtBootstrapRefresh | done — callback |
|
||||
| 43 | Pear IPC namespaced registry doc | done — developer-guide / handbook |
|
||||
| 44 | pear-runtime release channel in version adjunct | done — /proc version JSON |
|
||||
@@ -701,7 +701,7 @@ See also [kernel-extensions.md](kernel-extensions.md) and [package-bare-os-proto
|
||||
|
||||
## Kernel program backlog — batch A (100 items)
|
||||
|
||||
Governed kernel expansion: [developer-guide/kernel-program.md](../../developer-guide/kernel-program.md), stock kernel boot hooks (**`BARE_OS_BOOT_SAFE_MODE**`, `**BARE_OS_BOOT_TRANSACTION_JOURNAL**`, `**BARE_OS_BOOT_CHECKPOINT**`), `**kernel.ext.d**` ordering fields `**requires**` / `**after**` / `**before**`, `**/proc/bare_os/kernel_program.json**` (legacy `**giant_phase_program.json**`), `**/bin/kernel-doctor**`, `**/bin/kernel-explain**`, scripts `**verify-kernel-program-doc.mjs**` + `**kernel-program-benchmark-harness.mjs**`. `**bareOsCtxApiVersion` `1.25.0**`: optional `**subsystems.kernel.programProc**` on `**bareOsPublishBootReady`** payloads.
|
||||
Governed kernel expansion: [developer-guide/kernel-program.md](../../developer-guide/kernel-program.md), stock kernel boot hooks (**`BARE_OS_BOOT_SAFE_MODE`**, **`BARE_OS_BOOT_TRANSACTION_JOURNAL`**, **`BARE_OS_BOOT_CHECKPOINT`**), **`kernel.ext.d`** ordering fields **`requires`** / **`after`** / **`before`**, **`/proc/bare_os/kernel_program.json`** (legacy **`giant_phase_program.json`**), **`/bin/kernel-doctor`**, **`/bin/kernel-explain`**, scripts **`verify-kernel-program-doc.mjs`** + **`kernel-program-benchmark-harness.mjs`**. `**bareOsCtxApiVersion` `1.25.0**`: optional **`subsystems.kernel.programProc`** on **`bareOsPublishBootReady`** payloads.
|
||||
|
||||
|
||||
## Kernel program backlog — batch B (100 items)
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
[Reference index →](README.md)
|
||||
|
||||
Bare OS exposes **`curl**` and `**wget`** as familiar command names, but they are **not** Daniel Stenberg’s libcurl or full GNU **wget**. Both are **JavaScript CLIs** in the booter that use the **Fetch API** (or a compatible implementation), support a **documented subset** of common flags, and honor the same **HTTP / DNS policy** environment variables as the rest of the session.
|
||||
Bare OS exposes **`curl`** and **`wget`** as familiar command names, but they are **not** Daniel Stenberg’s libcurl or full GNU **wget**. Both are **JavaScript CLIs** in the booter that use the **Fetch API** (or a compatible implementation), support a **documented subset** of common flags, and honor the same **HTTP / DNS policy** environment variables as the rest of the session.
|
||||
|
||||
---
|
||||
|
||||
@@ -12,53 +12,53 @@ Bare OS exposes **`curl**` and `**wget`** as familiar command names, but they ar
|
||||
- Online **`man curl**` / `**man wget`** — Merged manual DB: [`packages/bare-os-coreutils/man/pages/curl.json`](../../packages/bare-os-coreutils/man/pages/curl.json), [`wget.json`](../../packages/bare-os-coreutils/man/pages/wget.json); narrative in [Handbook ch. 10](../../handbook/10-manpages-and-online-help.md)
|
||||
- Security, allowlists, audit — [Developer guide — Security and trust](../../developer-guide/09-security-and-trust.md)
|
||||
- Environment variables (tables) — [Environment variables and POSIX appendix](environment-and-posix-appendix.md#14-environment-variables-complete-list)
|
||||
- Capability / proc map — [kernel-capabilities-index.md](./kernel-capabilities-index.md); kernel program net sketches — [kernel-extensions.md](./kernel-extensions.md) ( **`BARE_OS_NET_DELEGATE_SKETCH_JSON**` (legacy `**BARE_OS_GP2_NET_DELEGATE_SKETCH_JSON**`), `**BARE_OS_DNS_PROFILE**`, `**BARE_OS_DELEGATE_TRACE`** )
|
||||
- Capability / proc map — [kernel-capabilities-index.md](./kernel-capabilities-index.md); kernel program net sketches — [kernel-extensions.md](./kernel-extensions.md) ( **`BARE_OS_NET_DELEGATE_SKETCH_JSON`** (legacy **`BARE_OS_GP2_NET_DELEGATE_SKETCH_JSON`**), **`BARE_OS_DNS_PROFILE`**, **`BARE_OS_DELEGATE_TRACE`** )
|
||||
|
||||
---
|
||||
|
||||
## Invocation: delegates run before `/bin`
|
||||
|
||||
When the shell or **`ctx.runBinCommand`** resolves an external command, [`runBinCommand` in `kernel-runner.js`](../../packages/bare-os-booter/lib/kernel-runner.js) consults the **host delegate registry** **first** (see [`host-delegate-registry.js`](../../packages/bare-os-booter/lib/host-delegate-registry.js)). Delegates are registered with **static imports** of **`curl-cli.js**`, `**wget-cli.js**`, `**git-cli.js**`, and `**systemctl-cli.js**` so Pear staging and module resolution stay predictable (avoid dynamic `**import('./…')`** of sibling CLI modules from deep paths).
|
||||
When the shell or **`ctx.runBinCommand`** resolves an external command, [`runBinCommand` in `kernel-runner.js`](../../packages/bare-os-booter/lib/kernel-runner.js) consults the **host delegate registry** **first** (see [`host-delegate-registry.js`](../../packages/bare-os-booter/lib/host-delegate-registry.js)). Delegates are registered with **static imports** of **`curl-cli.js`**, **`wget-cli.js`**, **`git-cli.js`**, and **`systemctl-cli.js`** so Pear staging and module resolution stay predictable (avoid dynamic `**import('./…')`** of sibling CLI modules from deep paths).
|
||||
|
||||
Order for a simple command name:
|
||||
|
||||
1. **Host delegates** — basename match for **`git**`, `**curl**`, `**wget**`, and `**systemctl**` / `**bare-initctl**` / `**journalctl`**.
|
||||
2. **Explicit paths** — **`/**` in `**argv[0]`** → VFS script load.
|
||||
3. **`*.js` in `$PWD**` — before `**PATH`**.
|
||||
4. **`PATH**` on the **system** drive only — normal `**/bin`** utilities.
|
||||
1. **Host delegates** — basename match for **`git`**, **`curl`**, **`wget`**, and **`systemctl`** / **`bare-initctl`** / **`journalctl`**.
|
||||
2. **Explicit paths** — **`/`** in `**argv[0]`** → VFS script load.
|
||||
3. **`*.js` in `$PWD**` — before **`PATH`**.
|
||||
4. **`PATH`** on the **system** drive only — normal **`/bin`** utilities.
|
||||
|
||||
**`BARE_OS_DELEGATE_ALLOW**` (host → session passthrough) may restrict which delegate **kinds** run. When set to a comma- or whitespace-separated list (`**git**`, `**curl**`, `**wget**`, `**systemctl**`), only those kinds are allowed; a denied delegate logs a message and exits with **126**. When unset or empty, all registered delegates are allowed. Optional **per-minute** rate limits use `**BARE_OS_DELEGATE_MAX_PER_MIN**` and per-kind `**BARE_OS_DELEGATE_*_MAX_PER_MIN**`. Optional **in-flight** caps use `**BARE_OS_DELEGATE_MAX_CONCURRENT**` (global) and `**BARE_OS_DELEGATE_<KIND>_MAX_CONCURRENT**` (e.g. `**CURL**`, `**GIT**`, `**WGET**`, `**SYSTEMCTL**`) to queue or reject parallel delegate runs. With `**BARE_OS_AUDIT=1**`, `**BARE_OS_DELEGATE_AUDIT_ONLY=1`** logs invocations and skips the host run (**exit 0**). Optional audit logging for delegate invocations is described in the security guide.
|
||||
**`BARE_OS_DELEGATE_ALLOW`** (host → session passthrough) may restrict which delegate **kinds** run. When set to a comma- or whitespace-separated list (**`git`**, **`curl`**, **`wget`**, **`systemctl`**), only those kinds are allowed; a denied delegate logs a message and exits with **126**. When unset or empty, all registered delegates are allowed. Optional **per-minute** rate limits use **`BARE_OS_DELEGATE_MAX_PER_MIN`** and per-kind **`BARE_OS_DELEGATE_*_MAX_PER_MIN`**. Optional **in-flight** caps use **`BARE_OS_DELEGATE_MAX_CONCURRENT`** (global) and **`BARE_OS_DELEGATE_<KIND>_MAX_CONCURRENT`** (e.g. **`CURL`**, **`GIT`**, **`WGET`**, **`SYSTEMCTL`**) to queue or reject parallel delegate runs. With **`BARE_OS_AUDIT=1`**, **`BARE_OS_DELEGATE_AUDIT_ONLY=1`** logs invocations and skips the host run (**exit 0**). Optional audit logging for delegate invocations is described in the security guide.
|
||||
|
||||
---
|
||||
|
||||
## `/bin/curl` and `/bin/wget` on the system image
|
||||
|
||||
The coreutils build still emits **`kernel/bin/curl**` and `**kernel/bin/wget**` so `**ls /bin**`, `**which curl**`, and the sorted `**/bin`** manifest stay complete. Those files are **placeholders**: if the runner ever executed them, they would print an error, because the booter is expected to **delegate** first. In normal operation you never run the stub bodies in [`packages/bare-os-coreutils/src/curl.js`](../../packages/bare-os-coreutils/src/curl.js) and [`wget.js`](../../packages/bare-os-coreutils/src/wget.js).
|
||||
The coreutils build still emits **`kernel/bin/curl`** and **`kernel/bin/wget`** so `**ls /bin**`, `**which curl**`, and the sorted **`/bin`** manifest stay complete. Those files are **placeholders**: if the runner ever executed them, they would print an error, because the booter is expected to **delegate** first. In normal operation you never run the stub bodies in [`packages/bare-os-coreutils/src/curl.js`](../../packages/bare-os-coreutils/src/curl.js) and [`wget.js`](../../packages/bare-os-coreutils/src/wget.js).
|
||||
|
||||
---
|
||||
|
||||
## How HTTP requests choose a `fetch` implementation
|
||||
|
||||
Delegated **`curl**` and `**wget`** share the resolution helpers in [`bare-os-ensure-bare-fetch.js`](../../packages/bare-os-booter/lib/bare-os-ensure-bare-fetch.js).
|
||||
Delegated **`curl`** and **`wget`** share the resolution helpers in [`bare-os-ensure-bare-fetch.js`](../../packages/bare-os-booter/lib/bare-os-ensure-bare-fetch.js).
|
||||
|
||||
**Per-request function** — **`resolveBareOsFetchFn(ctx)`** returns, in order:
|
||||
|
||||
1. **`ctx.httpFetch`** when it is a function — typically the booter’s **policy-wrapped** fetch (HTTP allow/deny lists, optional audit).
|
||||
2. Else **`ctx.bare.fetch**` when present — drive bundles may expose `**fetch**`; legacy bundles sometimes attach a CJS-shaped object, so the booter **unwraps** `**.default**` when needed (`**coerceBareFetchExport`**).
|
||||
2. Else **`ctx.bare.fetch`** when present — drive bundles may expose **`fetch`**; legacy bundles sometimes attach a CJS-shaped object, so the booter **unwraps** **`.default`** when needed (**`coerceBareFetchExport`**).
|
||||
3. Else **`globalThis.fetch`** when defined.
|
||||
|
||||
**Priming globals on hosts without native fetch** — **`ensureBareFetchGlobals(ctx)`** (async) runs when the CLI needs globals installed:
|
||||
|
||||
1. If **`globalThis.fetch`** already exists, return.
|
||||
2. Try **`ctx.bare.fetch**` (same `**.default**` unwrap) and copy `**fetch**` / `**Request**` / `**Response**` / `**Headers**` onto `**globalThis**` (and `**global`** on Node).
|
||||
3. Otherwise try **`import**` of `**bare-fetch**` (via `**import.meta.resolve**` when available, then `**import(href)`**, for Pear-friendly resolution).
|
||||
4. If still missing, try **`bare-https**` and use its exported `**fetch`**.
|
||||
2. Try **`ctx.bare.fetch`** (same **`.default`** unwrap) and copy **`fetch`** / **`Request`** / **`Response`** / **`Headers`** onto **`globalThis`** (and **`global`** on Node).
|
||||
3. Otherwise try **`import`** of **`bare-fetch`** (via **`import.meta.resolve`** when available, then `**import(href)`**, for Pear-friendly resolution).
|
||||
4. If still missing, try **`bare-https`** and use its exported **`fetch`**.
|
||||
|
||||
The booter may also call **`primeGlobalFetchFromBareLibrary(bareLibrary)**` during `**ctx**` assembly so `**globalThis.fetch**` exists before guest code runs when the system image supplies `**/lib/bare/bundles/fetch.js`**.
|
||||
The booter may also call **`primeGlobalFetchFromBareLibrary(bareLibrary)**` during **`ctx`** assembly so **`globalThis.fetch`** exists before guest code runs when the system image supplies **`/lib/bare/bundles/fetch.js`**.
|
||||
|
||||
**TLS and CA behavior** for delegated **`curl**` can use optional `**init.bareOsCurlTls**` ( `**insecure**`, `**caPem**`, `**pinnedSha256**`) alongside `**BARE_OS_TLS_PIN_SHA256**`; see the security guide and kernel `**init`** documentation.
|
||||
**TLS and CA behavior** for delegated **`curl`** can use optional **`init.bareOsCurlTls`** ( **`insecure`**, **`caPem`**, **`pinnedSha256`**) alongside **`BARE_OS_TLS_PIN_SHA256`**; see the security guide and kernel **`init`** documentation.
|
||||
|
||||
**Capability word 6 (rotation and HTTP hints)** — For operators running **bare-fetch** (or host **`fetch**`) behind the delegate, document **multi-pin** rotation as a comma- or JSON-list of hex digests (same semantics as single-pin, evaluated by the host). **HSTS preload** lists and **alt-svc** hints are **host-layer** concerns: reserved env names `**BARE_OS_TLS_PINS_JSON**`, `**BARE_OS_HSTS_PRELOAD_PINS_JSON**`, `**BARE_OS_CURL_ALT_SVC_JSON`** are listed in [kernel-extensions.md](./kernel-extensions.md) for Pear-side wiring; the stock in-guest booter does not parse them.
|
||||
**Capability word 6 (rotation and HTTP hints)** — For operators running **bare-fetch** (or host **`fetch`**) behind the delegate, document **multi-pin** rotation as a comma- or JSON-list of hex digests (same semantics as single-pin, evaluated by the host). **HSTS preload** lists and **alt-svc** hints are **host-layer** concerns: reserved env names **`BARE_OS_TLS_PINS_JSON`**, **`BARE_OS_HSTS_PRELOAD_PINS_JSON`**, **`BARE_OS_CURL_ALT_SVC_JSON`** are listed in [kernel-extensions.md](./kernel-extensions.md) for Pear-side wiring; the stock in-guest booter does not parse them.
|
||||
|
||||
---
|
||||
|
||||
@@ -66,16 +66,16 @@ The booter may also call **`primeGlobalFetchFromBareLibrary(bareLibrary)**` duri
|
||||
|
||||
These are summarized in the [environment appendix](environment-and-posix-appendix.md); the security guide explains threat model and audit interaction.
|
||||
|
||||
- **`BARE_OS_HTTP_ALLOWLIST**` / `**BARE_OS_HTTP_DENYLIST**` — Restrict outbound **http(s)** URLs for policy-wrapped fetch (delegated clients and `**ctx.httpFetch`**).
|
||||
- **`BARE_OS_HTTP_ALLOWLIST`** / **`BARE_OS_HTTP_DENYLIST`** — Restrict outbound **http(s)** URLs for policy-wrapped fetch (delegated clients and **`ctx.httpFetch`**).
|
||||
- **`BARE_OS_TLS_PIN_SHA256`** — Optional TLS certificate pinning hint forwarded for pinning-aware hosts.
|
||||
- **`BARE_OS_DNS_ALLOWLIST**` — Optional host allowlist for **http(s)** URLs in delegated `**curl**` / `**wget**` (suffix forms such as `***.example.com`** supported).
|
||||
- **`BARE_OS_DELEGATE_ALLOW**` — Limits which delegate kinds (`**curl**`, `**wget`**, …) may run.
|
||||
- **`BARE_OS_DNS_ALLOWLIST`** — Optional host allowlist for **http(s)** URLs in delegated **`curl`** / **`wget`** (suffix forms such as **`*.example.com`** supported).
|
||||
- **`BARE_OS_DELEGATE_ALLOW`** — Limits which delegate kinds (**`curl`**, **`wget`**, …) may run.
|
||||
|
||||
---
|
||||
|
||||
## `agent` and the `web_fetch` tool
|
||||
|
||||
In-guest **`/bin/agent**` uses the same `**ctx.httpFetch**` implementation as delegated `**curl**` / `**wget**`: policy-wrapped `**fetch**` when the booter sets `**ctx.httpFetch**`, with `**BARE_OS_HTTP_ALLOWLIST**` / `**BARE_OS_HTTP_DENYLIST**` applying to **both** the OpenAI-compatible provider `**/chat/completions**` URL and URLs fetched by the assistant’s `**web_fetch**` tool. Operators must allowlist **every** host the session will call (API origin plus any `**http(s)**` sites you expect `**web_fetch`** to retrieve).
|
||||
In-guest **`/bin/agent`** uses the same **`ctx.httpFetch`** implementation as delegated **`curl`** / **`wget`**: policy-wrapped **`fetch`** when the booter sets **`ctx.httpFetch`**, with **`BARE_OS_HTTP_ALLOWLIST`** / **`BARE_OS_HTTP_DENYLIST`** applying to **both** the OpenAI-compatible provider **`/chat/completions`** URL and URLs fetched by the assistant’s **`web_fetch`** tool. Operators must allowlist **every** host the session will call (API origin plus any `**http(s)**` sites you expect **`web_fetch`** to retrieve).
|
||||
|
||||
Configuration and tool semantics are **not** duplicated here — see guest **`man agent`** ([`packages/bare-os-coreutils/man/pages/agent.json`](../../packages/bare-os-coreutils/man/pages/agent.json) in the repo) and [User manual — ch.4](../../users-manual/04-shell-path-and-scripts.md).
|
||||
|
||||
@@ -83,6 +83,6 @@ Configuration and tool semantics are **not** duplicated here — see guest **`ma
|
||||
|
||||
## Related handbook sections
|
||||
|
||||
- [Handbook ch. 4 — Booter runtime](../../handbook/04-the-booter-runtime.md) ( **`ctx**`, HTTP policy overview, `**agent`**)
|
||||
- [Handbook ch. 4 — Booter runtime](../../handbook/04-the-booter-runtime.md) ( **`ctx`**, HTTP policy overview, **`agent`**)
|
||||
- [Handbook ch. 6 — Kernel and `/bin`](../../handbook/06-kernel-and-binaries.md) (delegated vs coreutils)
|
||||
- [Handbook ch. 9 — POSIX utilities](../../handbook/09-posix-utilities-shell-and-vfs.md) (catalog classification; **`agent**` / `**chat`** as non-POSIX Tier-1)
|
||||
- [Handbook ch. 9 — POSIX utilities](../../handbook/09-posix-utilities-shell-and-vfs.md) (catalog classification; **`agent`** / **`chat`** as non-POSIX Tier-1)
|
||||
|
||||
@@ -2,11 +2,11 @@
|
||||
|
||||
[Reference index →](README.md)
|
||||
|
||||
The stock booter ([`packages/bare-os-booter/index.js`](../../packages/bare-os-booter/index.js)) constructs a **`Hyperswarm**` instance with optional caps from host env (`**BARE_OS_SWARM_MAX_PEERS**`, `**BARE_OS_SWARM_MAX_CLIENT_CONNECTIONS**`, `**BARE_OS_SWARM_MAX_SERVER_CONNECTIONS**`, `**BARE_OS_SWARM_MAX_PARALLEL**` — see `**bareOsHyperswarmOptsFromEnv**`). Each inbound connection is wrapped in `**Protomux**` and registered on `**SwarmDisk**` (`**disk.addPeer(mux, socket)`**).
|
||||
The stock booter ([`packages/bare-os-booter/index.js`](../../packages/bare-os-booter/index.js)) constructs a **`Hyperswarm`** instance with optional caps from host env (**`BARE_OS_SWARM_MAX_PEERS`**, **`BARE_OS_SWARM_MAX_CLIENT_CONNECTIONS`**, **`BARE_OS_SWARM_MAX_SERVER_CONNECTIONS`**, **`BARE_OS_SWARM_MAX_PARALLEL`** — see **`bareOsHyperswarmOptsFromEnv`**). Each inbound connection is wrapped in **`Protomux`** and registered on **`SwarmDisk`** (`**disk.addPeer(mux, socket)`**).
|
||||
|
||||
## Shutdown ordering
|
||||
|
||||
[`teardownBareOsBootResources`](../../packages/bare-os-booter/lib/bare-os-lifecycle-manager.js) runs in a **`finally**` block after `**executeKernel`** completes or throws:
|
||||
[`teardownBareOsBootResources`](../../packages/bare-os-booter/lib/bare-os-lifecycle-manager.js) runs in a **`finally`** block after **`executeKernel`** completes or throws:
|
||||
|
||||
1. **`disk.hdmsController.deactivate()`** when present — stops HDMS-driven replication surfaces before closing drives.
|
||||
2. **`swarm.destroy()`** — tears down Hyperswarm; closes live streams so Protomux sessions end before Hyperdrive teardown (avoids native heap issues under Pear when drives close mid-stream).
|
||||
@@ -17,7 +17,7 @@ Replication and mux teardown **before** drive close is intentional: closing a Hy
|
||||
|
||||
## Retry and peer wait
|
||||
|
||||
Until **`BARE_OS_OFFLINE_LKG_BOOT**` is used with a valid `**BARE_OS_LKG_SYSTEM_KEY_HEX**`, the booter waits (polling **~400 ms**) until at least one swarm peer connects or `**BARE_OS_BOOT_TIMEOUT_MS`** elapses. There is no automatic exponential backoff beyond that loop; operators raise the timeout or enable offline LKG for air-gapped boots.
|
||||
Until **`BARE_OS_OFFLINE_LKG_BOOT`** is used with a valid **`BARE_OS_LKG_SYSTEM_KEY_HEX`**, the booter waits (polling **~400 ms**) until at least one swarm peer connects or **`BARE_OS_BOOT_TIMEOUT_MS`** elapses. There is no automatic exponential backoff beyond that loop; operators raise the timeout or enable offline LKG for air-gapped boots.
|
||||
|
||||
## P2P-first note
|
||||
|
||||
@@ -25,7 +25,7 @@ There is **no central broker**: topic membership and peer discovery follow Hyper
|
||||
|
||||
## `disk.os` after initd
|
||||
|
||||
After **`bare-initd**` starts, the booter attaches `**disk.os**` (`**createBareOsDiskOsBridge**`) for **local** Hyperdrive search and whitelisted `**bare_os.*` `execRpc**` ( `**disk_os_hints**`, `**replication_operator_sketch**`, cap-gated `**replication_operator_intent**`, etc.). The same payloads are reachable via stock `**ctx.bareOsHrpcRequest**` routes `**bare_os.disk_os_hints**`, `**bare_os.replication_operator_sketch**`, and `**bare_os.replication_snapshot**` when `**disk.os**` is wired. Teardown still follows the ordering above: **swarm down before drives**, so in-flight `**execRpc**` / replication should finish or time out before `**teardownBareOsBootResources`**.
|
||||
After **`bare-initd`** starts, the booter attaches **`disk.os`** (**`createBareOsDiskOsBridge`**) for **local** Hyperdrive search and whitelisted `**bare_os.*` `execRpc**` ( **`disk_os_hints`**, **`replication_operator_sketch`**, cap-gated **`replication_operator_intent`**, etc.). The same payloads are reachable via stock **`ctx.bareOsHrpcRequest`** routes **`bare_os.disk_os_hints`**, **`bare_os.replication_operator_sketch`**, and **`bare_os.replication_snapshot`** when **`disk.os`** is wired. Teardown still follows the ordering above: **swarm down before drives**, so in-flight **`execRpc`** / replication should finish or time out before **`teardownBareOsBootResources`**.
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Kernel capabilities index (capability words, env, `/proc`, `ctx`)
|
||||
|
||||
Single map from optional **feature bits** ([`packages/bare-os-protocol/lib/kernel-feature-bits.js`](../../packages/bare-os-protocol/lib/kernel-feature-bits.js)) to operator env vars, guest **`/proc**` paths, and `**ctx**` fields. Stock booter advertises the eleven `**kernelCapabilityWords**` keys (`**primary**` … `**hypercorePackHrpcLifecycle**`) on seed RPC, `**/proc/bare_os_features**`, and `**ctx.bareOsAdvertisedKernelCapabilityWords`**. Governance: [`developer-guide/adr/001-kernel-feature-bits-governance.md`](../../developer-guide/adr/001-kernel-feature-bits-governance.md).
|
||||
Single map from optional **feature bits** ([`packages/bare-os-protocol/lib/kernel-feature-bits.js`](../../packages/bare-os-protocol/lib/kernel-feature-bits.js)) to operator env vars, guest **`/proc`** paths, and **`ctx`** fields. Stock booter advertises the eleven **`kernelCapabilityWords`** keys (**`primary`** … **`hypercorePackHrpcLifecycle`**) on seed RPC, **`/proc/bare_os_features`**, and **`ctx.bareOsAdvertisedKernelCapabilityWords`**. Governance: [`developer-guide/adr/001-kernel-feature-bits-governance.md`](../../developer-guide/adr/001-kernel-feature-bits-governance.md).
|
||||
|
||||
**`/proc/bare_os/metrics_live.json**` — Built in `**procBareOsMetricsLiveText**` with an in-memory cache keyed by `**BARE_OS_PROC_POLL_MS**` (`**coalesceMs**` in JSON): repeated reads within the window reuse one `**JSON.stringify`** result so dashboard polling does not rebuild the full object every tick.
|
||||
**`/proc/bare_os/metrics_live.json`** — Built in **`procBareOsMetricsLiveText`** with an in-memory cache keyed by **`BARE_OS_PROC_POLL_MS`** (**`coalesceMs`** in JSON): repeated reads within the window reuse one **`JSON.stringify`** result so dashboard polling does not rebuild the full object every tick.
|
||||
|
||||
---
|
||||
|
||||
@@ -70,7 +70,7 @@ Each row is one **bit index** in the first capability word. Columns list **env o
|
||||
| 3 `FEATURE2_PEAR_IPC_REQUEST` | — | — | `bareOsPearIpcRequest` |
|
||||
| 4 `FEATURE2_MIRROR_DRIVE_CTX` | — | — | `bareOsEmitMirrorDriveHint` |
|
||||
| 5 `FEATURE2_AUTOPASS_HDMS_HINTS` | `BARE_OS_AUTOPASS_INVITE_URL` | `/proc/bare_os/hdms_hints.json` | operational pairing hint only |
|
||||
| 6 `FEATURE2_BIN_WORKER_OFFLOAD` | `BARE_OS_BIN_WORKER_OFFLOAD`, `BARE_OS_BIN_WORKER_ALLOW` | — | on **Bare** (non-Node), **`awk**` / `**sed**` / `**jq**` may run via `**bare-worker`** (falls back in-process) |
|
||||
| 6 `FEATURE2_BIN_WORKER_OFFLOAD` | `BARE_OS_BIN_WORKER_OFFLOAD`, `BARE_OS_BIN_WORKER_ALLOW` | — | on **Bare** (non-Node), **`awk`** / **`sed`** / **`jq`** may run via **`bare-worker`** (falls back in-process) |
|
||||
| 7 `FEATURE2_DIAGNOSTICS_CHANNEL` | `BARE_OS_DIAGNOSTICS_SUBSCRIBE=1` | — | `bareOsDiagnosticsSubscribe` / `Emit` |
|
||||
| 8 `FEATURE2_INITD_IDLE_STOP` | initd `IdleSec=` | — | socket-activated idle stop |
|
||||
| 9 `FEATURE2_INITD_UNITS_D` | — | — | `~/.config/bare-os/units.d/<unit>/*.conf` |
|
||||
@@ -167,7 +167,7 @@ Each row is one **bit index** in the first capability word. Columns list **env o
|
||||
| 14 `FEATURE6_HANDSHAKE_TOKEN_BUCKET` | `BARE_OS_SEED_TOKEN_BUCKET_JSON` | seed handshake | client backoff metadata |
|
||||
| 15 `FEATURE6_COMPACT_SEED_PING` | — | `compact_ping` / `compact_pong` | optional bandwidth probe |
|
||||
|
||||
**Related `ctx` (1.22.0+):** eleven words are only in frozen **`bareOsAdvertisedKernelCapabilityWords**` / `**bareOsSeedKernelCapabilityWords**` (semantic keys per [capability-words.md](./capability-words.md)). Hooks and helpers from words 6–11 still apply — e.g. `**bareOsReadProcMetricsLive()**`, `**bareOsReadDelegateFairnessSnapshot**`, `**bareOsReadSubprocessBridgeJobs**`, `**bareOsReadSubprocessBridgeSnapshot**`, `**bareOsRequestKernelProfileReload**`, `**bareOsIsCtxMethodAllowed**`, `**bareOsEmitIpcAudit**`, `**bareOsEmitBlindPeerHint**`, `**bareOsHostCapability**`, `**bareOsPearUpdaterDelegate**`, `**bareOsEmitHyperdhtBootstrapRefresh**`, `**bareOsBooterPackageVersion`**; Pear IPC channel names in [`bare-os-pear-ipc-registry.js`](../../packages/bare-os-booter/lib/bare-os-pear-ipc-registry.js).
|
||||
**Related `ctx` (1.22.0+):** eleven words are only in frozen **`bareOsAdvertisedKernelCapabilityWords`** / **`bareOsSeedKernelCapabilityWords`** (semantic keys per [capability-words.md](./capability-words.md)). Hooks and helpers from words 6–11 still apply — e.g. `**bareOsReadProcMetricsLive()**`, **`bareOsReadDelegateFairnessSnapshot`**, **`bareOsReadSubprocessBridgeJobs`**, **`bareOsReadSubprocessBridgeSnapshot`**, **`bareOsRequestKernelProfileReload`**, **`bareOsIsCtxMethodAllowed`**, **`bareOsEmitIpcAudit`**, **`bareOsEmitBlindPeerHint`**, **`bareOsHostCapability`**, **`bareOsPearUpdaterDelegate`**, **`bareOsEmitHyperdhtBootstrapRefresh`**, **`bareOsBooterPackageVersion`**; Pear IPC channel names in [`bare-os-pear-ipc-registry.js`](../../packages/bare-os-booter/lib/bare-os-pear-ipc-registry.js).
|
||||
|
||||
### Word 7 (seventh capability word, `pearCorestoreHrpc`)
|
||||
|
||||
@@ -175,14 +175,14 @@ Each row is one **bit index** in the first capability word. Columns list **env o
|
||||
| --- | --- | --- | --- |
|
||||
| 0 `FEATURE7_CAP_WORD` | — | seed **`kernelCapabilityWords.pearCorestoreHrpc`** + `/proc/bare_os_features` | seventh word marker |
|
||||
| 1 `FEATURE7_SEED_RPC_EXTENDED` | `BARE_OS_SEED_*` for payloads | `corestore_stats`, `snapshot_manifest_slice`, `mirror_drive_hint_v2`, `hrpc_registry_summary`, `protomux_capability_ad`, `dht_address_book`, `replication_throttle_hint`, `bundlebee_stage`, `http_dht_proxy_hint` | registry in [`seed-rpc-methods.js`](../../packages/bare-os-protocol/lib/seed-rpc-methods.js) |
|
||||
| 2 `FEATURE7_REPLICATION_JSON_ADJUNCT` | seeder opts | `replication_status` adjuncts, `staging_slot` schema **4→5** quarantine (v5 adds **`drainDeadlineMs`**), `peer_firewall_stats` transport breakdown | ready-guard **`notReadyReason**`, `**udxRttMsEstimate**`, `**relayCircuitId**`, `**hyperbee2ReadOnlyHint`** |
|
||||
| 2 `FEATURE7_REPLICATION_JSON_ADJUNCT` | seeder opts | `replication_status` adjuncts, `staging_slot` schema **4→5** quarantine (v5 adds **`drainDeadlineMs`**), `peer_firewall_stats` transport breakdown | ready-guard **`notReadyReason`**, **`udxRttMsEstimate`**, **`relayCircuitId`**, **`hyperbee2ReadOnlyHint`** |
|
||||
| 3 `FEATURE7_PROC_OPERATOR_METRICS` | `BARE_OS_*` JSON envs | Word-7 `bare_os_*.json` under `/proc` + `bare_os_proc_index` (superseded by schema **4** on word 8) | [`bare-os-proc-pear-corestore-hrpc.js`](../../packages/bare-os-booter/lib/bare-os-proc-pear-corestore-hrpc.js) |
|
||||
| 4 `FEATURE7_BOOT_POLICY_SURFACE` | `boot.policy.json` | — | **`requireKernelCapabilitiesPearCorestoreHrpc**`, `**requirePearRuntimeMin**`, `**requireProtocolPackageMin**`, `**denyCtxMethodPrefixes**`, `**maxKernelExtensionDepth**`, `**gitPartialClonePolicy`** |
|
||||
| 5 `FEATURE7_KERNEL_EXT_REGISTRY_V4` | `kernel.ext.d` | `/proc/bare_os/extensions.json` schema **4** | optional **`signaturePointer**` on records; topological `**dependsOn`** load order |
|
||||
| 6 `FEATURE7_PEAR_BARE_BRIDGE_EXTENDED` | `BARE_OS_BARE_DIAGNOSTICS_CHANNEL_TAP` | `/proc/version` may append **`pear_tty_flags_json**` | `**bareOsEmitBundlebeeHint**`, `**bareOsRegisterBareDiagnosticsTap**`, `**bareOsHrpcRequest`** stub |
|
||||
| 4 `FEATURE7_BOOT_POLICY_SURFACE` | `boot.policy.json` | — | **`requireKernelCapabilitiesPearCorestoreHrpc`**, **`requirePearRuntimeMin`**, **`requireProtocolPackageMin`**, **`denyCtxMethodPrefixes`**, **`maxKernelExtensionDepth`**, **`gitPartialClonePolicy`** |
|
||||
| 5 `FEATURE7_KERNEL_EXT_REGISTRY_V4` | `kernel.ext.d` | `/proc/bare_os/extensions.json` schema **4** | optional **`signaturePointer`** on records; topological **`dependsOn`** load order |
|
||||
| 6 `FEATURE7_PEAR_BARE_BRIDGE_EXTENDED` | `BARE_OS_BARE_DIAGNOSTICS_CHANNEL_TAP` | `/proc/version` may append **`pear_tty_flags_json`** | **`bareOsEmitBundlebeeHint`**, **`bareOsRegisterBareDiagnosticsTap`**, **`bareOsHrpcRequest`** stub |
|
||||
| 7 `FEATURE7_VFS_POSIX_EXTENSIONS` | `BARE_OS_CURL_RESOLVE_MAP_JSON`, proxy map docs | env tables in reference | **`/bin/env -C`**, git partial-clone policy env |
|
||||
| 8 `FEATURE7_INITD_SUBPROCESS` | initd graph extensions | docs | Slice/timeout/timer/socket fields |
|
||||
| 9 `FEATURE7_WORKER_NET` | worker/sandbox/delegate docs | — | **`netproc:***`, audit `**retryAfterMs`** |
|
||||
| 9 `FEATURE7_WORKER_NET` | worker/sandbox/delegate docs | — | **`netproc:*`**, audit **`retryAfterMs`** |
|
||||
| 10 `FEATURE7_TELEMETRY_AUDIT` | telemetry sinks | NDJSON v6 / OTel v4 / audit v4 | **`bootAttemptId`**, exemplars, redirect depth |
|
||||
| 11 `FEATURE7_DOC_CI_CONTRACTS` | — | — | **`verify-kernel-capabilities-word-7.mjs`** |
|
||||
| 12 `FEATURE7_COMPACT_MUX_ADVERT` | `BARE_OS_SEED_PROTOMUX_CAPABILITY_AD_HEX` | `protomux_capability_ad` RPC | hex-capped optional ad |
|
||||
@@ -193,18 +193,18 @@ Each row is one **bit index** in the first capability word. Columns list **env o
|
||||
| --- | --- | --- | --- |
|
||||
| 0 `FEATURE8_CAP_WORD` | — | seed **`kernelCapabilityWords.bareRuntimeProtoMux`** + `/proc/bare_os_features` | eighth word marker |
|
||||
| 1 `FEATURE8_SEED_RPC_EXTENDED` | `BARE_OS_SEED_*` JSON | `protomux_rpc_pool_hint`, `hyperblob_store_hint`, `signing_request_queue_hint`, `core_storage_layout_hint`, `mirror_drive_compaction_v3`, `bundlebee_cli_stage`, `ready_guard_v2`, `blind_relay_circuit_hint`, `http_dht_proxy_routes` | registry in [`seed-rpc-methods.js`](../../packages/bare-os-protocol/lib/seed-rpc-methods.js) |
|
||||
| 2 `FEATURE8_REPLICATION_JSON_ADJUNCT` | seeder opts | `replication_status` **`udxLossEstimateBps**`, `**tcpFallbackReason**`, `**hyperdbIndexLagHint`**; `peer_firewall_stats` **`saturationClass`**; `staging_slot` **`drainDeadlineMs`** | advisory only |
|
||||
| 2 `FEATURE8_REPLICATION_JSON_ADJUNCT` | seeder opts | `replication_status` **`udxLossEstimateBps`**, **`tcpFallbackReason`**, **`hyperdbIndexLagHint`**; `peer_firewall_stats` **`saturationClass`**; `staging_slot` **`drainDeadlineMs`** | advisory only |
|
||||
| 3 `FEATURE8_PROC_OPERATOR_METRICS` | Word-8 `BARE_OS_*_JSON` envs | 17× `bare_os_*.json` + `bare_os_proc_index` schema **4** | [`bare-os-proc-bare-runtime-proto-mux.js`](../../packages/bare-os-booter/lib/bare-os-proc-bare-runtime-proto-mux.js) |
|
||||
| 4 `FEATURE8_BOOT_POLICY_SURFACE` | `boot.policy.json` v8 | — | **`requireKernelCapabilitiesBareRuntimeProtoMux**`, `**requireBareRuntimeMin**`, `**denySeedRpcMethods**`, `**maxProtomuxChannelNameLength`** |
|
||||
| 4 `FEATURE8_BOOT_POLICY_SURFACE` | `boot.policy.json` v8 | — | **`requireKernelCapabilitiesBareRuntimeProtoMux`**, **`requireBareRuntimeMin`**, **`denySeedRpcMethods`**, **`maxProtomuxChannelNameLength`** |
|
||||
| 5 `FEATURE8_KERNEL_EXT_REGISTRY_V5` | extension records | `/proc/bare_os/extensions.json` schema **5** | optional **`compatPearBundleId`** |
|
||||
| 6 `FEATURE8_PEAR_BARE_BRIDGE_EXTENDED` | — | — | **`bareOsEmitStructuredCloneCap**`, `**bareOsProtomuxChannelAlias`** |
|
||||
| 6 `FEATURE8_PEAR_BARE_BRIDGE_EXTENDED` | — | — | **`bareOsEmitStructuredCloneCap`**, **`bareOsProtomuxChannelAlias`** |
|
||||
| 7 `FEATURE8_VFS_POSIX_EXTENSIONS` | `BARE_OS_CURL_RESOLVE_MAP_JSON`, docs | curl/wget resolve map; git partial clone deny; POSIX handbook rows | FIFO metrics v2 doc |
|
||||
| 8 `FEATURE8_INITD_SUBPROCESS` | initd/timer/socket / resume env | `/proc/self/limits`, subprocess snapshot schema **4** | **`BARE_OS_RESUME_STAGGER_LEVEL_MS_JSON**`, `**BARE_OS_INITD_START_LIMIT_*`** |
|
||||
| 9 `FEATURE8_WORKER_NET` | **`ioproc:*`**, proxy/DNS docs | `sandbox_worker_queue.json`, `rocksdb_pointer.json` | delegate **`bundlebee**`, `**warc**`, `**archive`** audit stubs |
|
||||
| 10 `FEATURE8_TELEMETRY_AUDIT` | telemetry sinks | NDJSON v7 / OTel v5 / audit v5 | **`sessionForkGeneration**`, `**scopeMetrics**`, `**requestSmugglingClass**`, HDMS `**vaultRotateCount`** |
|
||||
| 8 `FEATURE8_INITD_SUBPROCESS` | initd/timer/socket / resume env | `/proc/self/limits`, subprocess snapshot schema **4** | **`BARE_OS_RESUME_STAGGER_LEVEL_MS_JSON`**, **`BARE_OS_INITD_START_LIMIT_*`** |
|
||||
| 9 `FEATURE8_WORKER_NET` | **`ioproc:*`**, proxy/DNS docs | `sandbox_worker_queue.json`, `rocksdb_pointer.json` | delegate **`bundlebee`**, **`warc`**, **`archive`** audit stubs |
|
||||
| 10 `FEATURE8_TELEMETRY_AUDIT` | telemetry sinks | NDJSON v7 / OTel v5 / audit v5 | **`sessionForkGeneration`**, **`scopeMetrics`**, **`requestSmugglingClass`**, HDMS **`vaultRotateCount`** |
|
||||
| 11 `FEATURE8_DOC_CI_CONTRACTS` | — | — | **`verify-kernel-capabilities-word-8.mjs`** |
|
||||
| 12 `FEATURE8_HTTP_DHT_PROXY_ROUTES` | — | `http_dht_proxy_routes` RPC | route revision JSON |
|
||||
| 13 `FEATURE8_PROTOMUX_CAP_CHANNEL` | `BARE_OS_PROTOMUX_CAP_CHANNEL` | Protomux pair on **`bare-os-cap-v1**` | Inbound messages **≤ 65536** bytes; oversized payloads logged, counter unchanged (`**swarm-disk.js`**) |
|
||||
| 13 `FEATURE8_PROTOMUX_CAP_CHANNEL` | `BARE_OS_PROTOMUX_CAP_CHANNEL` | Protomux pair on **`bare-os-cap-v1`** | Inbound messages **≤ 65536** bytes; oversized payloads logged, counter unchanged (**`swarm-disk.js`**) |
|
||||
|
||||
### Word 9 (ninth capability word, `bareModuleCryptoStaging`)
|
||||
|
||||
@@ -212,14 +212,14 @@ Each row is one **bit index** in the first capability word. Columns list **env o
|
||||
| --- | --- | --- | --- |
|
||||
| 0 `FEATURE9_CAP_WORD` | — | seed **`kernelCapabilityWords.bareModuleCryptoStaging`** + `/proc/bare_os_features` | ninth word marker |
|
||||
| 1 `FEATURE9_SEED_RPC_EXTENDED` | `BARE_OS_SEED_*` JSON | `pear_stage_hint`, `updater_channel_matrix`, `drive_resolve_policy`, …, `http_dht_proxy_routes_v2` | [`seed-rpc-methods.js`](../../packages/bare-os-protocol/lib/seed-rpc-methods.js) |
|
||||
| 2 `FEATURE9_REPLICATION_JSON_ADJUNCT` | seeder opts | `replication_status` **`pearRuntimeChannel**`, `**handshakeTokenBucketV3`**; `staging_slot` **schema 6**; `compact_ping` **schema 3** | advisory |
|
||||
| 2 `FEATURE9_REPLICATION_JSON_ADJUNCT` | seeder opts | `replication_status` **`pearRuntimeChannel`**, **`handshakeTokenBucketV3`**; `staging_slot` **schema 6**; `compact_ping` **schema 3** | advisory |
|
||||
| 3 `FEATURE9_PROC_OPERATOR_METRICS` | Word-9 `BARE_OS_*_JSON` envs | 19× `bare_os_*.json` + `bare_os_proc_index` schema **5** | [`bare-os-proc-bare-module-crypto-staging.js`](../../packages/bare-os-booter/lib/bare-os-proc-bare-module-crypto-staging.js) |
|
||||
| 4 `FEATURE9_BOOT_POLICY_SURFACE` | `boot.policy.json` v9 | — | **`requireKernelCapabilitiesBareModuleCryptoStaging**`, `**requirePearRuntimeRange**`, `**requireBareCryptoMin`**, … |
|
||||
| 4 `FEATURE9_BOOT_POLICY_SURFACE` | `boot.policy.json` v9 | — | **`requireKernelCapabilitiesBareModuleCryptoStaging`**, **`requirePearRuntimeRange`**, **`requireBareCryptoMin`**, … |
|
||||
| 5 `FEATURE9_KERNEL_EXT_REGISTRY_V6` | extension records | `/proc/bare_os/extensions.json` schema **6** | **`extensionSignerPinsV2`** env |
|
||||
| 6 `FEATURE9_PEAR_BARE_BRIDGE_EXTENDED` | — | — | **`bareOsEmitPearStageHint`**, probes, storage hint |
|
||||
| 7 `FEATURE9_VFS_POSIX_EXTENSIONS` | `/bin/openssl` stub | documents **`bare-crypto**` | Node `**node:crypto`** not used |
|
||||
| 7 `FEATURE9_VFS_POSIX_EXTENSIONS` | `/bin/openssl` stub | documents **`bare-crypto`** | Node **`node:crypto`** not used |
|
||||
| 8 `FEATURE9_INITD_SUBPROCESS` | — | — | shared with earlier capability words |
|
||||
| 9 `FEATURE9_WORKER_NET` | **`mediaproc:***`, `**BARE_OS_SOCKS_PROXY_MAP_JSON`** | SOCKS map helper | [`http-fetch-url.js`](../../packages/bare-os-booter/lib/http-fetch-url.js) |
|
||||
| 9 `FEATURE9_WORKER_NET` | **`mediaproc:*`**, **`BARE_OS_SOCKS_PROXY_MAP_JSON`** | SOCKS map helper | [`http-fetch-url.js`](../../packages/bare-os-booter/lib/http-fetch-url.js) |
|
||||
| 10 `FEATURE9_TELEMETRY_AUDIT` | telemetry sinks | NDJSON **8** / OTel **6** / audit **6** | **`bareModuleCryptoStagingProbeId`** |
|
||||
| 11 `FEATURE9_DOC_CI_CONTRACTS` | — | — | **`verify-kernel-capabilities-word-9.mjs`** |
|
||||
| 12 `FEATURE9_HTTP_DHT_PROXY_ROUTES_V2` | — | `http_dht_proxy_routes_v2` RPC | revision v2 |
|
||||
@@ -232,13 +232,13 @@ Each row is one **bit index** in the first capability word. Columns list **env o
|
||||
| 1 `FEATURE10_SEED_RPC_EXTENDED` | `BARE_OS_SEED_*` JSON | `pear_doctor_hint` … `pear_terminal_caps`, `ready_guard_v4`, `compact_ping_v4`, … | [`seed-rpc-methods.js`](../../packages/bare-os-protocol/lib/seed-rpc-methods.js) |
|
||||
| 2 `FEATURE10_REPLICATION_JSON_ADJUNCT` | seeder opts | `pearBundleTier`, `autobaseDiscoveryHint`, `handshakeTokenBucketV4`, `staging_slot` **schema 7**, `peer_firewall_stats` **v5** | advisory |
|
||||
| 3 `FEATURE10_PROC_OPERATOR_METRICS` | Word-10 `BARE_OS_*_JSON` envs | 19× `bare_os_*.json` + `bare_os_proc_index` schema **6** | [`bare-os-proc-pear-inspect-logger-tls.js`](../../packages/bare-os-booter/lib/bare-os-proc-pear-inspect-logger-tls.js) |
|
||||
| 4 `FEATURE10_BOOT_POLICY_SURFACE` | `boot.policy.json` v10 | — | **`requireKernelCapabilitiesPearInspectLoggerTls**`, `**requireBareBootMin**`, `**bootPhasesRequireLifecycleMinSchema`**, … |
|
||||
| 4 `FEATURE10_BOOT_POLICY_SURFACE` | `boot.policy.json` v10 | — | **`requireKernelCapabilitiesPearInspectLoggerTls`**, **`requireBareBootMin`**, **`bootPhasesRequireLifecycleMinSchema`**, … |
|
||||
| 5 `FEATURE10_KERNEL_EXT_REGISTRY_V7` | extension records | `/proc/bare_os/extensions.json` schema **7** | **`extensionSignerPinsV3`** env |
|
||||
| 6 `FEATURE10_PEAR_BARE_BRIDGE_EXTENDED` | — | — | **`bareOsEmitPearDoctorHint`**, terminal probe, logger tap, … |
|
||||
| 7 `FEATURE10_VFS_POSIX_EXTENSIONS` | coreutils / handbook ch.9 | `ssh-keygen` stub, `xargs -P` cap, `tar` xattr sketch | no guest **`node:crypto`** |
|
||||
| 8 `FEATURE10_INITD_SUBPROCESS` | — | — | shared with earlier capability words |
|
||||
| 9 `FEATURE10_WORKER_NET` | **`sysproc:***`, `**BARE_OS_MTLS_PROXY_MAP_JSON**`, `**BARE_OS_HAPPY_EYEBALLS_V4_MODE`** | thread telemetry env | transport docs |
|
||||
| 10 `FEATURE10_TELEMETRY_AUDIT` | telemetry sinks | NDJSON **9** / OTel **7** / audit **7** | **`pearInspectLoggerTlsProbeId**`, `**bareRpcProbeClass`** |
|
||||
| 9 `FEATURE10_WORKER_NET` | **`sysproc:*`**, **`BARE_OS_MTLS_PROXY_MAP_JSON`**, **`BARE_OS_HAPPY_EYEBALLS_V4_MODE`** | thread telemetry env | transport docs |
|
||||
| 10 `FEATURE10_TELEMETRY_AUDIT` | telemetry sinks | NDJSON **9** / OTel **7** / audit **7** | **`pearInspectLoggerTlsProbeId`**, **`bareRpcProbeClass`** |
|
||||
| 11 `FEATURE10_DOC_CI_CONTRACTS` | — | — | **`verify-kernel-capabilities-word-10.mjs`** |
|
||||
| 12 `FEATURE10_COMPACT_READY_RPC_V4` | — | `compact_ping_v4`, `ready_guard_v4` RPC | dedicated v4 payloads |
|
||||
|
||||
@@ -250,12 +250,12 @@ Each row is one **bit index** in the first capability word. Columns list **env o
|
||||
| 1 `FEATURE11_SEED_RPC_EXTENDED` | `BARE_OS_SEED_*` JSON | `hypercore_replicate_budget_v2` … `mirror_drive_compaction_v6` | [`seed-rpc-methods.js`](../../packages/bare-os-protocol/lib/seed-rpc-methods.js) |
|
||||
| 2 `FEATURE11_REPLICATION_JSON_ADJUNCT` | seeder / replication adjuncts | advisory JSON for word-11 seed RPC payloads | pairs with seed channel |
|
||||
| 3 `FEATURE11_PROC_OPERATOR_METRICS` | Word-11 `BARE_OS_*_JSON` envs | 20× `bare_os_*.json` + **`bare_os_proc_index`** schema **7** | [`bare-os-proc-hypercore-pack-hrpc-lifecycle.js`](../../packages/bare-os-booter/lib/bare-os-proc-hypercore-pack-hrpc-lifecycle.js) |
|
||||
| 4 `FEATURE11_BOOT_POLICY_SURFACE` | `boot.policy.json` v11 | — | **`requireKernelCapabilitiesHypercorePackHrpcLifecycle**`, `**extensionSignerPinsV4`**, pack/addon semver, HRPC depth, offline eleventh-word strict |
|
||||
| 4 `FEATURE11_BOOT_POLICY_SURFACE` | `boot.policy.json` v11 | — | **`requireKernelCapabilitiesHypercorePackHrpcLifecycle`**, **`extensionSignerPinsV4`**, pack/addon semver, HRPC depth, offline eleventh-word strict |
|
||||
| 5 `FEATURE11_KERNEL_EXT_REGISTRY_V8` | extension records | `/proc/bare_os/extensions.json` schema **8** | schema branch in **`kernel-extensions.registry.schema.json`** |
|
||||
| 6 `FEATURE11_PEAR_BARE_BRIDGE_EXTENDED` | — | — | Pear matrix + Bare pack/addon/signals **`ctx`** probes |
|
||||
| 7 `FEATURE11_VFS_POSIX_EXTENSIONS` | VFS / handbook | hide word-11 proc JSON via env | **`BARE_OS_HIDE_PROC_HYPERCORE_PACK_HRPC_LIFECYCLE`** (`0` / `false` / `off` → flat + `/proc/bare_os/*` + index rows) |
|
||||
| 8 `FEATURE11_INITD_SUBPROCESS` | — | — | shared with earlier capability words |
|
||||
| 9 `FEATURE11_WORKER_NET` | **`cryptoproc:***`, `**indexerproc:*`** | worker allowlist | [`kernel-runner.js`](../../packages/bare-os-booter/lib/kernel-runner.js) |
|
||||
| 9 `FEATURE11_WORKER_NET` | **`cryptoproc:*`**, **`indexerproc:*`** | worker allowlist | [`kernel-runner.js`](../../packages/bare-os-booter/lib/kernel-runner.js) |
|
||||
| 10 `FEATURE11_TELEMETRY_AUDIT` | telemetry sinks | NDJSON **10** / OTel **8** / audit **8** | **`hypercorePackHrpcLifecycleProbeId`** |
|
||||
| 11 `FEATURE11_DOC_CI_CONTRACTS` | — | — | **`verify-kernel-capabilities-word-11.mjs`** |
|
||||
| 12 `FEATURE11_HTTP_DHT_PROXY_ROUTES_V3` | — | `http_dht_proxy_routes_v3` RPC | route table v3 |
|
||||
|
||||
@@ -8,26 +8,26 @@ Bare OS splits **hand-authored kernel code** from **vendored Holepunch runtime b
|
||||
|
||||
| Layer | Paths | Policy |
|
||||
|--------|--------|--------|
|
||||
| **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). **`kernel/init.js` is generated** from sorted `kernel/lib/boot/*.js` + sorted `kernel/lib/init/fragments/*.js` + `kernel/lib/init/init-main.js` ([`scripts/bundle-kernel-init.mjs`](../../scripts/bundle-kernel-init.mjs)); **`invokeCtxBootHooks**` and `**BARE_OS_BOOT_TXN_STATE`** are defined in [`kernel/lib/boot/01-invoke-ctx-hooks.js`](../../kernel/lib/boot/01-invoke-ctx-hooks.js); shared **`pear.multisig.json`** shape checks live in [`kernel/lib/boot/00-pear-multisig-shape.js`](../../kernel/lib/boot/00-pear-multisig-shape.js) (mirrors **`bare-os-protocol**`); `**kernel.ext.d`** loading is in [`kernel/lib/init/fragments/30-init-kernel-extensions.js`](../../kernel/lib/init/fragments/30-init-kernel-extensions.js). |
|
||||
| **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). **`kernel/init.js` is generated** from sorted `kernel/lib/boot/*.js` + sorted `kernel/lib/init/fragments/*.js` + `kernel/lib/init/init-main.js` ([`scripts/bundle-kernel-init.mjs`](../../scripts/bundle-kernel-init.mjs)); **`invokeCtxBootHooks`** and **`BARE_OS_BOOT_TXN_STATE`** are defined in [`kernel/lib/boot/01-invoke-ctx-hooks.js`](../../kernel/lib/boot/01-invoke-ctx-hooks.js); shared **`pear.multisig.json`** shape checks live in [`kernel/lib/boot/00-pear-multisig-shape.js`](../../kernel/lib/boot/00-pear-multisig-shape.js) (mirrors **`bare-os-protocol`**); **`kernel.ext.d`** loading is in [`kernel/lib/init/fragments/30-init-kernel-extensions.js`](../../kernel/lib/init/fragments/30-init-kernel-extensions.js). |
|
||||
| **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); 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.
|
||||
|
||||
**`kernel.ext.d` ordering:** The Kahn topological sort in [`kernel/lib/init/fragments/30-init-kernel-extensions.js`](../../kernel/lib/init/fragments/30-init-kernel-extensions.js) must stay aligned with [`packages/bare-os-booter/lib/kernel-extension-resolver.js`](../../packages/bare-os-booter/lib/kernel-extension-resolver.js) (**`topologicalOrderKernelExtensions**`); CI covers this via the Brittle test `**kernel extension topological order matches guest Kahn tie-break**` in `**packages/bare-os-booter/test.js**`. Optional manifest field `**provides`**: `{ name, version }[]` — two different extension ids must not claim the same **`name**` with different `**version**` strings when strict policy applies (`**detectKernelExtensionProvidesConflicts**` / guest `**kernelExt.providesConflict**`). Additional harness tests cover `**minCtxApiVersion**` skip paths, `**conflictsWith`** / dependency **cycles** under strict boot policy (no extension scripts run on hard failures).
|
||||
**`kernel.ext.d` ordering:** The Kahn topological sort in [`kernel/lib/init/fragments/30-init-kernel-extensions.js`](../../kernel/lib/init/fragments/30-init-kernel-extensions.js) must stay aligned with [`packages/bare-os-booter/lib/kernel-extension-resolver.js`](../../packages/bare-os-booter/lib/kernel-extension-resolver.js) (**`topologicalOrderKernelExtensions`**); CI covers this via the Brittle test `**kernel extension topological order matches guest Kahn tie-break**` in **`packages/bare-os-booter/test.js`**. Optional manifest field **`provides`**: `{ name, version }[]` — two different extension ids must not claim the same **`name`** with different **`version`** strings when strict policy applies (**`detectKernelExtensionProvidesConflicts`** / guest **`kernelExt.providesConflict`**). Additional harness tests cover **`minCtxApiVersion`** skip paths, **`conflictsWith`** / dependency **cycles** under strict boot policy (no extension scripts run on hard failures).
|
||||
|
||||
## Post-initd `disk.os` peer bridge
|
||||
|
||||
**`pkg-swarm-index` / path capabilities:** Drive manifest **`/etc/bare-os/pkg-index.json**` (or HRPC `**bare_os.pkg_index_get**`) may attach `**pathCapabilityEnvelope**` on entries; `**pkg-swarm-index get**` calls `**ctx.bareOsVerifyPathCapabilityEnvelope**` when present and prints `**pathCapabilityEnvelopeVerify`** (see [`kernel/etc/bare-os/pkg-index.example.json`](../../kernel/etc/bare-os/pkg-index.example.json)). VFS read enforcement remains under **`BARE_OS_PATH_CAPABILITY_*`** as documented in the POSIX profile.
|
||||
**`pkg-swarm-index` / path capabilities:** Drive manifest **`/etc/bare-os/pkg-index.json`** (or HRPC **`bare_os.pkg_index_get`**) may attach **`pathCapabilityEnvelope`** on entries; `**pkg-swarm-index get**` calls **`ctx.bareOsVerifyPathCapabilityEnvelope`** when present and prints **`pathCapabilityEnvelopeVerify`** (see [`kernel/etc/bare-os/pkg-index.example.json`](../../kernel/etc/bare-os/pkg-index.example.json)). VFS read enforcement remains under **`BARE_OS_PATH_CAPABILITY_*`** as documented in the POSIX profile.
|
||||
|
||||
After **initd**, **`SwarmDisk**` wires `**disk.os`** via [`createBareOsDiskOsBridge`](../../packages/bare-os-booter/lib/bare-os-disk-os-bridge.js): peer **`searchLocal**`, whitelisted `**bare_os.***` `**execRpc**` methods including `**bare_os.replication_operator_sketch**` (**schema 8** JSON: replication status, `**swarmPeerCount**`, Hyperswarm `**connectionBudget**`, protomux operator sketch fields, `**hyperdhtAddressSketch**` from `**BARE_OS_HYPERDHT_ADDRESS_JSON**`, `**pkgIndexSurface**`, env mirrors for pause/backpressure, `**corestoreSnapshotUxHint**`, optional `**corestoreOperatorSketch**` from `**BARE_OS_CORESTORE_STATS_JSON**`), and optional cap-gated `**bare_os.replication_operator_intent**` when `**BARE_OS_DISK_OS_OPERATOR_INTENT_RPC=1**` (append-only audit via `**ctx.bareOsAuditLogAppendBatch**` when the booter supplies `**auditBatch`**). Narrative: [Handbook ch.3](../../handbook/03-protocol-and-disk.md).
|
||||
After **initd**, **`SwarmDisk`** wires **`disk.os`** via [`createBareOsDiskOsBridge`](../../packages/bare-os-booter/lib/bare-os-disk-os-bridge.js): peer **`searchLocal`**, whitelisted **`bare_os.*`** **`execRpc`** methods including **`bare_os.replication_operator_sketch`** (**schema 8** JSON: replication status, **`swarmPeerCount`**, Hyperswarm **`connectionBudget`**, protomux operator sketch fields, **`hyperdhtAddressSketch`** from **`BARE_OS_HYPERDHT_ADDRESS_JSON`**, **`pkgIndexSurface`**, env mirrors for pause/backpressure, **`corestoreSnapshotUxHint`**, optional **`corestoreOperatorSketch`** from **`BARE_OS_CORESTORE_STATS_JSON`**), and optional cap-gated **`bare_os.replication_operator_intent`** when **`BARE_OS_DISK_OS_OPERATOR_INTENT_RPC=1`** (append-only audit via **`ctx.bareOsAuditLogAppendBatch`** when the booter supplies **`auditBatch`**). Narrative: [Handbook ch.3](../../handbook/03-protocol-and-disk.md).
|
||||
|
||||
**bare-module alignment:** Compare local Holepunch clones **`bare-module**`, `**bare-module-traverse**`, and `**bare-pack**` against boot policy keys `**denyBareModuleSpecifierPatterns**`, `**requireBareCryptoMin**`, and extension `**signaturePointer**` / `**extensionSignerPins**` when evolving the guest `**ctx.bare**` merge — resolver parity is enforced in `**packages/bare-os-booter/lib/kernel-extension-resolver.js**` and `**kernel/lib/init/fragments/30-init-kernel-extensions.js`**.
|
||||
**bare-module alignment:** Compare local Holepunch clones **`bare-module`**, **`bare-module-traverse`**, and **`bare-pack`** against boot policy keys **`denyBareModuleSpecifierPatterns`**, **`requireBareCryptoMin`**, and extension **`signaturePointer`** / **`extensionSignerPins`** when evolving the guest **`ctx.bare`** merge — resolver parity is enforced in **`packages/bare-os-booter/lib/kernel-extension-resolver.js`** and **`kernel/lib/init/fragments/30-init-kernel-extensions.js`**.
|
||||
|
||||
### Blind relay / Protomux proc hints (schema 2)
|
||||
|
||||
With **`BARE_OS_PROC_BLIND_PEER_RELAY_HINTS**`, `**blind_relay_router**`, `**blind_pairing_sketch**`, and `**relay_geo_hint**` JSON under `**/proc/bare_os**` switch from operator-redacted **schema 1** to **schema 2** and merge live `**swarm**` aggregates (`**peerCount**`, `**relayGeoTier**`, `**lifecycle**`, `**pairingSurfaceReady**`). Set `**BARE_OS_SWARM_PROTOMUX_BACKPRESSURE_COUNT**` to surface a non-secret `**protomuxBackpressure.emitCountEstimate`** (operator-injected aggregate for drain/cork dashboards). Implementation: [`bare-os-proc-blind-peer-relay-gate.js`](../../packages/bare-os-booter/lib/bare-os-proc-blind-peer-relay-gate.js), [`bare-os-proc-pear-corestore-hrpc.js`](../../packages/bare-os-booter/lib/bare-os-proc-pear-corestore-hrpc.js). CI covers schema **2** + backpressure in **`packages/bare-os-booter/test.js`**.
|
||||
With **`BARE_OS_PROC_BLIND_PEER_RELAY_HINTS`**, **`blind_relay_router`**, **`blind_pairing_sketch`**, and **`relay_geo_hint`** JSON under **`/proc/bare_os`** switch from operator-redacted **schema 1** to **schema 2** and merge live **`swarm`** aggregates (**`peerCount`**, **`relayGeoTier`**, **`lifecycle`**, **`pairingSurfaceReady`**). Set **`BARE_OS_SWARM_PROTOMUX_BACKPRESSURE_COUNT`** to surface a non-secret **`protomuxBackpressure.emitCountEstimate`** (operator-injected aggregate for drain/cork dashboards). Implementation: [`bare-os-proc-blind-peer-relay-gate.js`](../../packages/bare-os-booter/lib/bare-os-proc-blind-peer-relay-gate.js), [`bare-os-proc-pear-corestore-hrpc.js`](../../packages/bare-os-booter/lib/bare-os-proc-pear-corestore-hrpc.js). CI covers schema **2** + backpressure in **`packages/bare-os-booter/test.js`**.
|
||||
|
||||
### Strict boot / `kernel.ext.d` failure catalog (operator)
|
||||
|
||||
@@ -35,15 +35,15 @@ When **`BARE_OS_BOOT_POLICY_STRICT=1`** (or equivalent strict policy paths), the
|
||||
|
||||
| Kind | Guest signal | Notes |
|
||||
|------|----------------|-------|
|
||||
| Dependency cycle | **`kernelExt.cycle**`, `**/run/bare-os/kernel-ext-resolution.json**` `**failure.kind: dependency_cycle`** | Topological sort fails; extension IDs listed in proc/trace JSON. |
|
||||
| **`conflictsWith**` | `**kernelExt.conflict`** | Two loaded ids mutually exclude each other. |
|
||||
| **`provides` version clash** | **`kernelExt.providesConflict**`, audit `**provides_version_conflict**` | Same logical `**provides[].name**` with differing `**version`** across drop-ins. |
|
||||
| **`minCtxApiVersion**` | `**kernelExt.minCtxApiVersion**` | Drop-in skipped or strict boot fails when `**ctx.bareOsCtxApiVersion`** is below the declared floor. |
|
||||
| **`denyKernelExtensionIds` / deny id** | **`kernelExt.denyId**` | Policy denies an extension `**id`** before script execution. |
|
||||
| **Pear multisig gate** | **`kernelExt.multisigMissing**`, `**kernelExt.multisigInvalid**`, `**kernelExt.multisigRead**` | When multisig verification is required, `**/etc/bare-os/pear.multisig.json**` must be well-formed (`**signers**`, `**quorum`**). |
|
||||
| **Extension signer pins (v2–v5)** | Env **`BARE_OS_BOOT_POLICY_EXTENSION_SIGNER_PINS_V*_JSON**` | Merged from `**boot.policy.json**` when present — capability alignment for downstream verifiers; CI `**scripts/verify-boot-policy-extension-signer-pins.mjs**` guards the env mapping. The stock kernel calls `**verifyKernelExtSignerPinsForScript**` immediately before **every** `**kernel.ext.d**` script execution (initial boot and later reload paths) using `**ctx.bareOsVerifyBootManifestSignature**` and each script’s `**signaturePointer**` when pins list that extension id — strict boot fails closed on missing `**ctx`**, missing files, or bad signatures. |
|
||||
| Dependency cycle | **`kernelExt.cycle`**, **`/run/bare-os/kernel-ext-resolution.json`** `**failure.kind: dependency_cycle`** | Topological sort fails; extension IDs listed in proc/trace JSON. |
|
||||
| **`conflictsWith`** | **`kernelExt.conflict`** | Two loaded ids mutually exclude each other. |
|
||||
| **`provides` version clash** | **`kernelExt.providesConflict`**, audit **`provides_version_conflict`** | Same logical `**provides[].name**` with differing **`version`** across drop-ins. |
|
||||
| **`minCtxApiVersion`** | **`kernelExt.minCtxApiVersion`** | Drop-in skipped or strict boot fails when **`ctx.bareOsCtxApiVersion`** is below the declared floor. |
|
||||
| **`denyKernelExtensionIds` / deny id** | **`kernelExt.denyId`** | Policy denies an extension **`id`** before script execution. |
|
||||
| **Pear multisig gate** | **`kernelExt.multisigMissing`**, **`kernelExt.multisigInvalid`**, **`kernelExt.multisigRead`** | When multisig verification is required, **`/etc/bare-os/pear.multisig.json`** must be well-formed (**`signers`**, **`quorum`**). |
|
||||
| **Extension signer pins (v2–v5)** | Env **`BARE_OS_BOOT_POLICY_EXTENSION_SIGNER_PINS_V*_JSON`** | Merged from **`boot.policy.json`** when present — capability alignment for downstream verifiers; CI **`scripts/verify-boot-policy-extension-signer-pins.mjs`** guards the env mapping. The stock kernel calls **`verifyKernelExtSignerPinsForScript`** immediately before **every** **`kernel.ext.d`** script execution (initial boot and later reload paths) using **`ctx.bareOsVerifyBootManifestSignature`** and each script’s **`signaturePointer`** when pins list that extension id — strict boot fails closed on missing **`ctx`**, missing files, or bad signatures. |
|
||||
|
||||
**`/run/bare-os/kernel-ext-resolution.json` (schema 3):** Written when extension ordering fails or when **`BARE_OS_KERNEL_EXT_RESOLUTION_JSON_ALWAYS=1**`. Includes `**providesInvalidSemver**`, `**providesVersionConflicts**`, `**provideNameToOwner**`, and ordered ids for operators. Manifest `**provides[].version**` strings must be valid **semver** when declared; invalid or conflicting claims fail strict boot with structured `**kernelExt.***` signals (see guest `**30-init-kernel-extensions.js`**).
|
||||
**`/run/bare-os/kernel-ext-resolution.json` (schema 3):** Written when extension ordering fails or when **`BARE_OS_KERNEL_EXT_RESOLUTION_JSON_ALWAYS=1`**. Includes **`providesInvalidSemver`**, **`providesVersionConflicts`**, **`provideNameToOwner`**, and ordered ids for operators. Manifest `**provides[].version**` strings must be valid **semver** when declared; invalid or conflicting claims fail strict boot with structured **`kernelExt.*`** signals (see guest **`30-init-kernel-extensions.js`**).
|
||||
|
||||
## Governance (feature bits doc v14)
|
||||
|
||||
@@ -53,19 +53,19 @@ New capability bits are governed by [ADR 001 — Kernel feature bit governance](
|
||||
|
||||
## Capability bitmask
|
||||
|
||||
Runtime bits are defined in `bare-os-protocol` (`kernel-feature-bits.js`) and surfaced under `/proc/bare_os_features` and the **`/proc/bare_os/**` tree. The stock booter advertises `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_PRIMARY**` through `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_HYPERCORE_PACK_HRPC_LIFECYCLE`** (eleven words on the wire when non-zero; see [capability-words.md](./capability-words.md)).
|
||||
Runtime bits are defined in `bare-os-protocol` (`kernel-feature-bits.js`) and surfaced under `/proc/bare_os_features` and the **`/proc/bare_os/`** tree. The stock booter advertises **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_PRIMARY`** through **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_HYPERCORE_PACK_HRPC_LIFECYCLE`** (eleven words on the wire when non-zero; see [capability-words.md](./capability-words.md)).
|
||||
|
||||
Seed RPC **`bare_os.capabilities**` includes `**protocolPackageVersion**`, optional `**booterPackageVersion**`, `**featureBitsDoc**`, `**doc**`, `**bits**`, `**bits2**`, `**bits3**`, `**bits4**`, `**bits5**`, `**bits6**`, `**bits7**`, `**bits8**`, `**bits9**`, `**bits10**`, `**role**`, `**protocol`**. RPC method names are listed from a single registry ([`seed-rpc-methods.js`](../../packages/bare-os-protocol/lib/seed-rpc-methods.js)); unknown methods return **`bare_os.rpc_unknown_method**`. `**bare_os.replication_status**` returns seeder-side replication hints (manifest path count, local RAM block count). `**bare_os.replication_queue**` includes bounded `**queueDepthEstimate**` and snapshot workflow notes; `**bare_os.capability_attestation**`, and `**bare_os.mbr_layout**` remain optional word-2 RPCs. Capability word 6 adds `**replication_plan**`, `**dht_bootstrap_hint**`, `**snapshot_chain**`, `**mirror_compaction_hint**`, `**updater_state**`, `**blind_peer_topology_v2**`, `**compact_ping**`. Capability word 7 adds `**corestore_stats**`, `**snapshot_manifest_slice**`, `**mirror_drive_hint_v2**`, `**hrpc_registry_summary**`, `**protomux_capability_ad**`, `**dht_address_book**`, `**replication_throttle_hint**`, `**bundlebee_stage**`, `**http_dht_proxy_hint**`. Capability word 8 adds `**protomux_rpc_pool_hint**`, `**hyperblob_store_hint**`, `**signing_request_queue_hint**`, `**core_storage_layout_hint**`, `**mirror_drive_compaction_v3**`, `**bundlebee_cli_stage**`, `**ready_guard_v2**`, `**blind_relay_circuit_hint**`, `**http_dht_proxy_routes**`. **Capability word 9** adds Holepunch-aligned short names such as `**pear_stage_hint**`, `**updater_channel_matrix**`, `**appling_bundle_pointer**`, `**drive_resolve_policy**`, `**bundle_id_fingerprint**`, `**hyperdb_migration_hint**`, `**sidecar_bundle_index_v2**`, `**pear_message_queue_sketch**`, `**runtime_bootstrap_etag**`, `**force_update_guard**`, `**gracedown_window**`, `**tryboot_slot**`, `**hotmods_allowlist**`, `**prefetcher_budget**`, `**opstream_backpressure**`, `**multisig_link_pointer**`, `**md_render_caps**`, `**bundlebee_cli_stage_v2**`, `**seed_manifest_diff_v2**`, `**peer_handshake_latency_budget**`, plus replication adjuncts (`**ready_guard_v3**`, `**mirror_drive_compaction_v4**`, `**blind_relay_circuit_v2**`, `**http_dht_proxy_routes_v2**`, token-bucket metadata, `**compact_ping` v3**, **`peer_firewall_stats` v4**, **`staging_slot` schema 6**, **`kernel_info.pearApplingId**`). `**bare_os.manifest_hints**` returns a sample of manifest paths; `**bare_os.peer_health**` returns seeder health counters; `**bare_os.staging_slot`** returns optional A/B slot hints (seeder env `BARE_OS_SEED_STAGING_SLOT`, `BARE_OS_SEED_STAGING_PENDING`). Booter mirrors hints under **`/proc/bare_os/manifest_hints**`, `**peer_health**`, `**staging_slot**`, `**net_summary.json**`, `**extensions.json**` (schema **7** in Capability word 10), `**hdms_hints.json**` (schema **3**: optional `**vaultRotateCount**`) and embeds them in `**/proc/bare_os_replication**` JSON. `**/proc/bare_os/index.json**` lists stable aliases (`**bare_os_proc_index` schema 6**). **Capability word 10** adds Pear/Bare sketch RPCs (**`pear_doctor_hint**` … `**pear_terminal_caps**`, `**ready_guard_v4**`, `**compact_ping_v4**`, compaction/blind-relay v5/v3), replication adjuncts (`**pearBundleTier**`, `**autobaseDiscoveryHint**`, `**handshakeTokenBucketV4**`, `**staging_slot` schema 7**, **`peer_firewall_stats` v5**), and 19× Capability word 10 **`/proc/bare_os/*.json**` files via `**bare-os-proc-pear-inspect-logger-tls.js`**.
|
||||
Seed RPC **`bare_os.capabilities`** includes **`protocolPackageVersion`**, optional **`booterPackageVersion`**, **`featureBitsDoc`**, **`doc`**, **`bits`**, **`bits2`**, **`bits3`**, **`bits4`**, **`bits5`**, **`bits6`**, **`bits7`**, **`bits8`**, **`bits9`**, **`bits10`**, **`role`**, **`protocol`**. RPC method names are listed from a single registry ([`seed-rpc-methods.js`](../../packages/bare-os-protocol/lib/seed-rpc-methods.js)); unknown methods return **`bare_os.rpc_unknown_method`**. **`bare_os.replication_status`** returns seeder-side replication hints (manifest path count, local RAM block count). **`bare_os.replication_queue`** includes bounded **`queueDepthEstimate`** and snapshot workflow notes; **`bare_os.capability_attestation`**, and **`bare_os.mbr_layout`** remain optional word-2 RPCs. Capability word 6 adds **`replication_plan`**, **`dht_bootstrap_hint`**, **`snapshot_chain`**, **`mirror_compaction_hint`**, **`updater_state`**, **`blind_peer_topology_v2`**, **`compact_ping`**. Capability word 7 adds **`corestore_stats`**, **`snapshot_manifest_slice`**, **`mirror_drive_hint_v2`**, **`hrpc_registry_summary`**, **`protomux_capability_ad`**, **`dht_address_book`**, **`replication_throttle_hint`**, **`bundlebee_stage`**, **`http_dht_proxy_hint`**. Capability word 8 adds **`protomux_rpc_pool_hint`**, **`hyperblob_store_hint`**, **`signing_request_queue_hint`**, **`core_storage_layout_hint`**, **`mirror_drive_compaction_v3`**, **`bundlebee_cli_stage`**, **`ready_guard_v2`**, **`blind_relay_circuit_hint`**, **`http_dht_proxy_routes`**. **Capability word 9** adds Holepunch-aligned short names such as **`pear_stage_hint`**, **`updater_channel_matrix`**, **`appling_bundle_pointer`**, **`drive_resolve_policy`**, **`bundle_id_fingerprint`**, **`hyperdb_migration_hint`**, **`sidecar_bundle_index_v2`**, **`pear_message_queue_sketch`**, **`runtime_bootstrap_etag`**, **`force_update_guard`**, **`gracedown_window`**, **`tryboot_slot`**, **`hotmods_allowlist`**, **`prefetcher_budget`**, **`opstream_backpressure`**, **`multisig_link_pointer`**, **`md_render_caps`**, **`bundlebee_cli_stage_v2`**, **`seed_manifest_diff_v2`**, **`peer_handshake_latency_budget`**, plus replication adjuncts (**`ready_guard_v3`**, **`mirror_drive_compaction_v4`**, **`blind_relay_circuit_v2`**, **`http_dht_proxy_routes_v2`**, token-bucket metadata, `**compact_ping` v3**, **`peer_firewall_stats` v4**, **`staging_slot` schema 6**, **`kernel_info.pearApplingId`**). **`bare_os.manifest_hints`** returns a sample of manifest paths; **`bare_os.peer_health`** returns seeder health counters; **`bare_os.staging_slot`** returns optional A/B slot hints (seeder env `BARE_OS_SEED_STAGING_SLOT`, `BARE_OS_SEED_STAGING_PENDING`). Booter mirrors hints under **`/proc/bare_os/manifest_hints`**, **`peer_health`**, **`staging_slot`**, **`net_summary.json`**, **`extensions.json`** (schema **7** in Capability word 10), **`hdms_hints.json`** (schema **3**: optional **`vaultRotateCount`**) and embeds them in **`/proc/bare_os_replication`** JSON. **`/proc/bare_os/index.json`** lists stable aliases (`**bare_os_proc_index` schema 6**). **Capability word 10** adds Pear/Bare sketch RPCs (**`pear_doctor_hint`** … **`pear_terminal_caps`**, **`ready_guard_v4`**, **`compact_ping_v4`**, compaction/blind-relay v5/v3), replication adjuncts (**`pearBundleTier`**, **`autobaseDiscoveryHint`**, **`handshakeTokenBucketV4`**, `**staging_slot` schema 7**, **`peer_firewall_stats` v5**), and 19× Capability word 10 **`/proc/bare_os/*.json`** files via **`bare-os-proc-pear-inspect-logger-tls.js`**.
|
||||
|
||||
**Capability word 8 Pear/Bare bridge (doc-first):** **`ctx.bareOsEmitStructuredCloneCap**` / `**ctx.bareOsProtomuxChannelAlias**`; `**BARE_OS_CURL_RESOLVE_MAP_JSON**` (curl/wget); `**BARE_OS_HTTP_PROXY_MAP_JSON**` (operator proxy map, host-interpreted); `**BARE_OS_BARE_HTTP1_KEEPALIVE_POOL**`, `**BARE_OS_HAPPY_EYEBALLS_IPV6_FIRST**`, `**BARE_OS_RESUME_STAGGER_LEVEL_MS_JSON**`, `**BARE_OS_INITD_COLLECT_MODE_HINT**`, `**BARE_OS_INITD_START_LIMIT_INTERVAL_MS**`, `**BARE_OS_INITD_START_LIMIT_BURST**`, `**BARE_OS_WORKER_RSS_HIGH_WATER_JSON**`, `**BARE_OS_SANDBOX_FS_CLASS**`, `**BARE_OS_SUBPROCESS_SCHED_POLICY_HINT**`, `**BARE_OS_DIAGNOSTICS_SUBSCRIBE_ALLOWLIST_JSON**`; `**BARE_OS_BOOT_POLICY_DENY_SEED_RPC_METHODS**` (comma-separated short names, also merged from `**denySeedRpcMethods**` in `**boot.policy.json`** v8).
|
||||
**Capability word 8 Pear/Bare bridge (doc-first):** **`ctx.bareOsEmitStructuredCloneCap`** / **`ctx.bareOsProtomuxChannelAlias`**; **`BARE_OS_CURL_RESOLVE_MAP_JSON`** (curl/wget); **`BARE_OS_HTTP_PROXY_MAP_JSON`** (operator proxy map, host-interpreted); **`BARE_OS_BARE_HTTP1_KEEPALIVE_POOL`**, **`BARE_OS_HAPPY_EYEBALLS_IPV6_FIRST`**, **`BARE_OS_RESUME_STAGGER_LEVEL_MS_JSON`**, **`BARE_OS_INITD_COLLECT_MODE_HINT`**, **`BARE_OS_INITD_START_LIMIT_INTERVAL_MS`**, **`BARE_OS_INITD_START_LIMIT_BURST`**, **`BARE_OS_WORKER_RSS_HIGH_WATER_JSON`**, **`BARE_OS_SANDBOX_FS_CLASS`**, **`BARE_OS_SUBPROCESS_SCHED_POLICY_HINT`**, **`BARE_OS_DIAGNOSTICS_SUBSCRIBE_ALLOWLIST_JSON`**; **`BARE_OS_BOOT_POLICY_DENY_SEED_RPC_METHODS`** (comma-separated short names, also merged from **`denySeedRpcMethods`** in **`boot.policy.json`** v8).
|
||||
|
||||
**Capability word 9 Pear/Bare bridge:** **`ctx.bareOsEmitPearStageHint**`, `**ctx.bareOsBareModuleResolveProbe**`, `**ctx.bareOsBareCryptoCapProbe**`, `**ctx.bareOsPearUpdaterChannel**`, `**ctx.bareOsEmitDriveResolveHint**`, `**ctx.bareOsRegisterBareDiagnosticsTapV2**`, `**ctx.bareOsEmitPearMessageSketch**`, `**ctx.bareOsEmitTrybootSlot**`, `**ctx.bareOsEmitMultisigPointer**`, `**ctx.bareOsBareStorageHint**`; host env `**BARE_OS_SOCKS_PROXY_MAP_JSON**` (delegated fetch); `**BARE_OS_BARE_CRYPTO_VERSION**`, `**BARE_OS_PEAR_IPC_PACKAGE_VERSION**`, `**BARE_OS_PEAR_UPDATER_CHANNEL**`, `**BARE_OS_HAPPY_EYEBALLS_V3_MODE**`, `**BARE_OS_BIN_WORKER_WASM_MS_MAX**`, `**BARE_OS_PROBE_ID_BARE_MODULE_CRYPTO_STAGING**`, `**BARE_OS_BARE_MODULE_PROBE_CLASS**`; optional `**BARE_OS_*_JSON**` blobs for Capability word 9 `**/proc/bare_os/*.json**` files (see `**bare-os-proc-bare-module-crypto-staging.js**`); boot policy **v9** adds `**requireKernelCapabilitiesBareModuleCryptoStaging**`, `**requirePearRuntimeRange**`, `**denyBareModuleSpecifierPatterns**`, `**requireBareCryptoMin**`, `**denyKernelSyscalls**`, `**requirePearIpcMin**`, `**extensionSignerPinsV2**`, `**offlineLkgManifestMaxAgeSec**`, `**bootStagesRequireProcIndexMinSchema**` (legacy `**bootPhasesRequireProcIndexMinSchema**`), `**maxKernelExtensionDepth` v2 semantics**, … — see [`boot.policy.schema.json`](../schemas/boot.policy.schema.json).
|
||||
**Capability word 9 Pear/Bare bridge:** **`ctx.bareOsEmitPearStageHint`**, **`ctx.bareOsBareModuleResolveProbe`**, **`ctx.bareOsBareCryptoCapProbe`**, **`ctx.bareOsPearUpdaterChannel`**, **`ctx.bareOsEmitDriveResolveHint`**, **`ctx.bareOsRegisterBareDiagnosticsTapV2`**, **`ctx.bareOsEmitPearMessageSketch`**, **`ctx.bareOsEmitTrybootSlot`**, **`ctx.bareOsEmitMultisigPointer`**, **`ctx.bareOsBareStorageHint`**; host env **`BARE_OS_SOCKS_PROXY_MAP_JSON`** (delegated fetch); **`BARE_OS_BARE_CRYPTO_VERSION`**, **`BARE_OS_PEAR_IPC_PACKAGE_VERSION`**, **`BARE_OS_PEAR_UPDATER_CHANNEL`**, **`BARE_OS_HAPPY_EYEBALLS_V3_MODE`**, **`BARE_OS_BIN_WORKER_WASM_MS_MAX`**, **`BARE_OS_PROBE_ID_BARE_MODULE_CRYPTO_STAGING`**, **`BARE_OS_BARE_MODULE_PROBE_CLASS`**; optional **`BARE_OS_*_JSON`** blobs for Capability word 9 **`/proc/bare_os/*.json`** files (see **`bare-os-proc-bare-module-crypto-staging.js`**); boot policy **v9** adds **`requireKernelCapabilitiesBareModuleCryptoStaging`**, **`requirePearRuntimeRange`**, **`denyBareModuleSpecifierPatterns`**, **`requireBareCryptoMin`**, **`denyKernelSyscalls`**, **`requirePearIpcMin`**, **`extensionSignerPinsV2`**, **`offlineLkgManifestMaxAgeSec`**, **`bootStagesRequireProcIndexMinSchema`** (legacy **`bootPhasesRequireProcIndexMinSchema`**), `**maxKernelExtensionDepth` v2 semantics**, … — see [`boot.policy.schema.json`](../schemas/boot.policy.schema.json).
|
||||
|
||||
**Capability word 10 Pear/Bare bridge:** **`ctx.bareOsEmitPearDoctorHint**`, `**ctx.bareOsPearInspectProbe**`, `**ctx.bareOsEmitBareBootStepHint**` (legacy `**ctx.bareOsEmitBareBootPhaseHint**`), `**ctx.bareOsBareRpcCapProbe**`, `**ctx.bareOsEmitPearStampPointer**`, `**ctx.bareOsRegisterBareLoggerTap**`, `**ctx.bareOsEmitAutobaseDiscoveryHint**`, `**ctx.bareOsEmitBlindPairingSketch**`, `**ctx.bareOsBareStreamBackpressureHint**`, `**ctx.bareOsPearTerminalCapsProbe**`; host env `**BARE_OS_PROBE_ID_PEAR_INSPECT_LOGGER_TLS**`, `**BARE_OS_BARE_RPC_PROBE_CLASS**`, `**BARE_OS_MTLS_PROXY_MAP_JSON**`, `**BARE_OS_THREAD_POOL_TELEMETRY_JSON**`, `**BARE_OS_HAPPY_EYEBALLS_V4_MODE**`, `**BARE_OS_BARE_BOOT_VERSION**`, `**BARE_OS_BARE_LOGGER_VERSION**`, `**BARE_OS_BARE_TLS_VERSION**`, `**BARE_OS_LIFECYCLE_SCHEMA_VERSION**` (injected); boot policy **v10** adds `**requireKernelCapabilitiesPearInspectLoggerTls**`, `**requireBareBootMin**`, `**denyBareRpcMethodPatterns**`, `**maxPearInspectDepth**`, `**requireBareLoggerMin**`, `**denyAutobaseDiscoveryChannels**`, `**requireBareTlsMin**`, `**extensionSignerPinsV3**`, `**offlineLkgRequirePearStamp**`, `**bootStagesRequireLifecycleMinSchema**` (legacy `**bootPhasesRequireLifecycleMinSchema`**), …
|
||||
**Capability word 10 Pear/Bare bridge:** **`ctx.bareOsEmitPearDoctorHint`**, **`ctx.bareOsPearInspectProbe`**, **`ctx.bareOsEmitBareBootStepHint`** (legacy **`ctx.bareOsEmitBareBootPhaseHint`**), **`ctx.bareOsBareRpcCapProbe`**, **`ctx.bareOsEmitPearStampPointer`**, **`ctx.bareOsRegisterBareLoggerTap`**, **`ctx.bareOsEmitAutobaseDiscoveryHint`**, **`ctx.bareOsEmitBlindPairingSketch`**, **`ctx.bareOsBareStreamBackpressureHint`**, **`ctx.bareOsPearTerminalCapsProbe`**; host env **`BARE_OS_PROBE_ID_PEAR_INSPECT_LOGGER_TLS`**, **`BARE_OS_BARE_RPC_PROBE_CLASS`**, **`BARE_OS_MTLS_PROXY_MAP_JSON`**, **`BARE_OS_THREAD_POOL_TELEMETRY_JSON`**, **`BARE_OS_HAPPY_EYEBALLS_V4_MODE`**, **`BARE_OS_BARE_BOOT_VERSION`**, **`BARE_OS_BARE_LOGGER_VERSION`**, **`BARE_OS_BARE_TLS_VERSION`**, **`BARE_OS_LIFECYCLE_SCHEMA_VERSION`** (injected); boot policy **v10** adds **`requireKernelCapabilitiesPearInspectLoggerTls`**, **`requireBareBootMin`**, **`denyBareRpcMethodPatterns`**, **`maxPearInspectDepth`**, **`requireBareLoggerMin`**, **`denyAutobaseDiscoveryChannels`**, **`requireBareTlsMin`**, **`extensionSignerPinsV3`**, **`offlineLkgRequirePearStamp`**, **`bootStagesRequireLifecycleMinSchema`** (legacy **`bootPhasesRequireLifecycleMinSchema`**), …
|
||||
|
||||
**Kernel program proc:** governance [developer-guide/kernel-program.md](../../developer-guide/kernel-program.md); program tables [feature-roadmap.md](./feature-roadmap.md) (batches A and B). **`BARE_OS_BOOT_SAFE_MODE**` (skip `**rc.d**`, `**kernel.ext.d**`, `**onboot**`); `**BARE_OS_BOOT_TRANSACTION_JOURNAL**` → `**/run/bare-os/boot-transaction.ndjson**` (lines include `**bootStage**`); `**BARE_OS_BOOT_CHECKPOINT**` → `**/run/bare-os/boot-checkpoint.json**` (schema **2**, `**bootStage**`); `**BARE_OS_BOOT_DRY_RUN**`, `**BARE_OS_BOOT_POLICY_PATH**`, `**policyFallbackPaths**`, rollback marker, bundle digest, ABI min; `**kernel.d**` `**# ConditionEnvironment=**` guards; `**kernel.ext.d**` `**requires**` / `**after**` / `**before**`; `**/proc/bare_os/kernel_program.json**` **schema 2** + `**operatorSketches**` (`**BARE_OS_KERNEL_PROGRAM_PROC_JSON**` override, legacy `**BARE_OS_GIANT_PHASE_PROGRAM_JSON**`); `**bareOsEmitKernelEvent**` / `**Subscribe**`, `**bareOsAcquireKeyHandle**`; `**/run/bare-os/services.json**`, `**loader-audit.ndjson**`; `**/bin/kernel-doctor**`, `**kernel-explain**`, `**kernel-boot-diff**`, `**kernel-preflight**`, `**kernel-triage**`, `**kernel-manifest-validate**`, `**kernel-fsck`**.
|
||||
**Kernel program proc:** governance [developer-guide/kernel-program.md](../../developer-guide/kernel-program.md); program tables [feature-roadmap.md](./feature-roadmap.md) (batches A and B). **`BARE_OS_BOOT_SAFE_MODE`** (skip **`rc.d`**, **`kernel.ext.d`**, **`onboot`**); **`BARE_OS_BOOT_TRANSACTION_JOURNAL`** → **`/run/bare-os/boot-transaction.ndjson`** (lines include **`bootStage`**); **`BARE_OS_BOOT_CHECKPOINT`** → **`/run/bare-os/boot-checkpoint.json`** (schema **2**, **`bootStage`**); **`BARE_OS_BOOT_DRY_RUN`**, **`BARE_OS_BOOT_POLICY_PATH`**, **`policyFallbackPaths`**, rollback marker, bundle digest, ABI min; **`kernel.d`** `**# ConditionEnvironment=**` guards; **`kernel.ext.d`** **`requires`** / **`after`** / **`before`**; **`/proc/bare_os/kernel_program.json`** **schema 2** + **`operatorSketches`** (**`BARE_OS_KERNEL_PROGRAM_PROC_JSON`** override, legacy **`BARE_OS_GIANT_PHASE_PROGRAM_JSON`**); **`bareOsEmitKernelEvent`** / **`Subscribe`**, **`bareOsAcquireKeyHandle`**; **`/run/bare-os/services.json`**, **`loader-audit.ndjson`**; **`/bin/kernel-doctor`**, **`kernel-explain`**, **`kernel-boot-diff`**, **`kernel-preflight`**, **`kernel-triage`**, **`kernel-manifest-validate`**, **`kernel-fsck`**.
|
||||
|
||||
**Word 11** (`bare-os-protocol` **0.8.x**, **`bits11**`): twenty new seed RPC short names (through `**mirror_drive_compaction_v6**`, `**compact_ping_v5**`, `**http_dht_proxy_routes_v3**`, …), boot policy **v11** (`**requireKernelCapabilitiesHypercorePackHrpcLifecycle**`, `**extensionSignerPinsV4**`, pack/addon semver floors, `**maxHrpcAllowlistDepth**`, `**offlineLkgRequireHypercorePackHrpcLifecycle**`, merged `**denySeedRpcMethods**`), `**/proc/bare_os/index.json**` schema **7** with 20 word-11 JSON aliases, NDJSON lifecycle **10** / OTel **8** / audit **8**, `**kernel-extensions.registry.schema.json**` branch **8**. Host env `**BARE_OS_PROBE_ID_HYPERCORE_PACK_HRPC_LIFECYCLE**`; optional `**BARE_OS_HIDE_PROC_HYPERCORE_PACK_HRPC_LIFECYCLE=0**` (or `**false**` / `**off**`) hides those word-11 proc nodes from `**readdir**`, path resolution, and the proc index (see `**vfs.js`**).
|
||||
**Word 11** (`bare-os-protocol` **0.8.x**, **`bits11`**): twenty new seed RPC short names (through **`mirror_drive_compaction_v6`**, **`compact_ping_v5`**, **`http_dht_proxy_routes_v3`**, …), boot policy **v11** (**`requireKernelCapabilitiesHypercorePackHrpcLifecycle`**, **`extensionSignerPinsV4`**, pack/addon semver floors, **`maxHrpcAllowlistDepth`**, **`offlineLkgRequireHypercorePackHrpcLifecycle`**, merged **`denySeedRpcMethods`**), **`/proc/bare_os/index.json`** schema **7** with 20 word-11 JSON aliases, NDJSON lifecycle **10** / OTel **8** / audit **8**, **`kernel-extensions.registry.schema.json`** branch **8**. Host env **`BARE_OS_PROBE_ID_HYPERCORE_PACK_HRPC_LIFECYCLE`**; optional **`BARE_OS_HIDE_PROC_HYPERCORE_PACK_HRPC_LIFECYCLE=0`** (or **`false`** / **`off`**) hides those word-11 proc nodes from **`readdir`**, path resolution, and the proc index (see **`vfs.js`**).
|
||||
|
||||
**JSON Schemas** (policy, telemetry, boot trace): [`docs/schemas/`](../schemas/) (see also [reference README](./README.md)).
|
||||
|
||||
@@ -79,28 +79,28 @@ Seed RPC **`bare_os.capabilities**` includes `**protocolPackageVersion**`, optio
|
||||
- Union writes — `BARE_OS_VFS_UNION_WRITE_DENY` — Comma/colon list of path prefixes blocked for writes under union prefixes
|
||||
- IPC — `BARE_OS_IPC_CHANNEL_MAX_BYTES` — JSON map `{"fifoName": 65536}` per-channel backlog cap
|
||||
- IPC — `BARE_OS_IPC_MAX_CHANNELS` — Upper bound on distinct FIFO names (default 4096 when unset; host passthrough can change it); telemetry in **`metrics_live.ipcTelemetry`**
|
||||
- IPC / POSIX MQ — `BARE_OS_POSIX_MQ_MAX_MSGS`, `BARE_OS_POSIX_MQ_MSG_BYTES` — Session defaults for simulated **`mq_open**` when attrs are omitted (bounded ceilings in `**bare-os-ipc.js`**)
|
||||
- IPC / POSIX MQ — `BARE_OS_POSIX_MQ_MAX_MSGS`, `BARE_OS_POSIX_MQ_MSG_BYTES` — Session defaults for simulated **`mq_open`** when attrs are omitted (bounded ceilings in **`bare-os-ipc.js`**)
|
||||
- Initd journal — `BARE_OS_INITD_JOURNAL_MAX_LINES` — Cap NDJSON lines per unit (default 400, max 20000)
|
||||
- Telemetry — `BARE_OS_TELEMETRY_NDJSON` — Logical path; append NDJSON mirror (`telemetrySchemaVersion` / `lifecycleSchemaVersion` **10**); optional **`sessionForkGeneration**`, `**bareModuleCryptoStagingProbeId**`, `**pearInspectLoggerTlsProbeId**`, `**hypercorePackHrpcLifecycleProbeId**`, `**bareModuleProbeClass**`, `**bareRpcProbeClass**`; optional correlation via `**BARE_OS_BOOT_ATTEMPT_ID**` → `**bootAttemptId`**
|
||||
- Telemetry — `BARE_OS_TELEMETRY_NDJSON` — Logical path; append NDJSON mirror (`telemetrySchemaVersion` / `lifecycleSchemaVersion` **10**); optional **`sessionForkGeneration`**, **`bareModuleCryptoStagingProbeId`**, **`pearInspectLoggerTlsProbeId`**, **`hypercorePackHrpcLifecycleProbeId`**, **`bareModuleProbeClass`**, **`bareRpcProbeClass`**; optional correlation via **`BARE_OS_BOOT_ATTEMPT_ID`** → **`bootAttemptId`**
|
||||
- Telemetry OTel — `BARE_OS_TELEMETRY_OTEL_JSONL` — Logical path; append OTLP-inspired JSON lines (`otlSchemaVersion` **8**, optional **`scopeMetrics`** sketch; see [`otel-bare-os-jsonl.schema.json`](../schemas/otel-bare-os-jsonl.schema.json)). Shorthand: `BARE_OS_TELEMETRY_OTEL=1` with no path defaults to **`/var/log/bare-os/otel.jsonl`**
|
||||
- Proc poll — `BARE_OS_PROC_POLL_MS` — Min interval 250ms, max 60s, for coalesced **`/proc/bare_os/metrics_live.json`**
|
||||
- Protomux registry proc — `BARE_OS_PROC_PROTOMUX_EXTENSIONS_REGISTRY=1` — Exposes **`/proc/bare_os/protomux_extensions.json**` (alias registry + logical channel hints) and `**ctx.bareOsReadProtomuxExtensionsJson()`** when the booter attaches the helper
|
||||
- Protomux registry proc — `BARE_OS_PROC_PROTOMUX_EXTENSIONS_REGISTRY=1` — Exposes **`/proc/bare_os/protomux_extensions.json`** (alias registry + logical channel hints) and `**ctx.bareOsReadProtomuxExtensionsJson()`** when the booter attaches the helper
|
||||
- Shell `${…}` — `BARE_OS_SHELL_PARAM_EXPANSION=1` — Enable `${VAR:-default}` and `${VAR#prefix}` (bounded prefix length)
|
||||
- Shell `${…}` v2 — `BARE_OS_SHELL_PARAM_EXPANSION_V2=1` — With param expansion on: `${VAR:=x}`, `${VAR##*/}` / `${VAR#*/}`, `${VAR%%pat}` / `${VAR%pat}` (bounded; see handbook ch.9)
|
||||
- Env GNU-like — `BARE_OS_ENV_DASH_S=1` — `/bin/env` supports `-S` / `--split-string` and `--env-file` (bounded)
|
||||
- VFS pseudo watch — `BARE_OS_VFS_WATCH_PSEUDO=1` — `vfs.watch` on coalesced **`/proc/bare_os/metrics_live.json`**
|
||||
- Diagnostics — `BARE_OS_DIAGNOSTICS_SUBSCRIBE=1` — `ctx.bareOsDiagnosticsSubscribe` for structured dev events
|
||||
- HDMS / autopass hint — `BARE_OS_AUTOPASS_INVITE_URL` — Surfaced in **`/proc/bare_os/hdms_hints.json`** (guest does not open URLs)
|
||||
- Bin worker — `BARE_OS_BIN_WORKER_OFFLOAD=1`, `BARE_OS_BIN_WORKER_ALLOW` — Offload eligible `/bin` on Bare via `bare-worker`; allow list defaults to awk/sed/jq, or patterns like `textproc:*` (cut, tr, sort, uniq, …); **`mathproc:*`** (`bc`, `dc`); **`mediaproc:*`** (`ffmpeg`, `ffprobe`); **`sysproc:*`** (bounded process-adjacent builtins: `echo`, `pwd`, `printenv`, …); optional per-invocation wall cap **`BARE_OS_BIN_WORKER_WALL_MS**`; optional WASM time budget `**BARE_OS_BIN_WORKER_WASM_MS_MAX`**
|
||||
- Bin worker — `BARE_OS_BIN_WORKER_OFFLOAD=1`, `BARE_OS_BIN_WORKER_ALLOW` — Offload eligible `/bin` on Bare via `bare-worker`; allow list defaults to awk/sed/jq, or patterns like `textproc:*` (cut, tr, sort, uniq, …); **`mathproc:*`** (`bc`, `dc`); **`mediaproc:*`** (`ffmpeg`, `ffprobe`); **`sysproc:*`** (bounded process-adjacent builtins: `echo`, `pwd`, `printenv`, …); optional per-invocation wall cap **`BARE_OS_BIN_WORKER_WALL_MS`**; optional WASM time budget **`BARE_OS_BIN_WORKER_WASM_MS_MAX`**
|
||||
- Word-6 proc inject — `BARE_OS_PROC_*` (see [kernel-capabilities-index](./kernel-capabilities-index.md) Word 6) — Bounded JSON for **`/proc/bare_os/*.json`** operator metrics (udx, DHT, backpressure, locale, …)
|
||||
- DNS map — `BARE_OS_DNS_MAP_JSON` — Split-horizon static map; summary in **`/proc/bare_os/dns_map_active.json`**
|
||||
- Resume stagger — `BARE_OS_RESUME_STAGGER_MS` — Delay between initd unit starts on resume (advisory)
|
||||
- Profile warm rc.d — `BARE_OS_KERNEL_PROFILE_WARM_RC_ONLY=1` — With **`BARE_OS_KERNEL_PROFILE_WARM**`: reload `**rc.d`** snippets only
|
||||
- Proc alias strict — `BARE_OS_PROC_ALIAS_STRICT=1` — Fail boot if **`/proc/bare_os**` alias index incomplete (`**FEATURE6_STRICT_PROC_ALIAS`**)
|
||||
- Profile warm rc.d — `BARE_OS_KERNEL_PROFILE_WARM_RC_ONLY=1` — With **`BARE_OS_KERNEL_PROFILE_WARM`**: reload **`rc.d`** snippets only
|
||||
- Proc alias strict — `BARE_OS_PROC_ALIAS_STRICT=1` — Fail boot if **`/proc/bare_os`** alias index incomplete (**`FEATURE6_STRICT_PROC_ALIAS`**)
|
||||
- SHM cap — `BARE_OS_SHM_MAX_BYTES` — Cap for **`/dev/shm`** on personal-backed tmp
|
||||
- TLS / HTTP hints — *(reserved names in docs)* `BARE_OS_HSTS_PRELOAD_PINS_JSON`, `BARE_OS_TLS_PINS_JSON`, `BARE_OS_CURL_ALT_SVC_JSON` — Multi-pin rotation, HSTS preload list, **alt-svc** — **host-delegate / Pear layer**; stock booter does not parse these env vars yet (see [http-curl-and-wget.md](./http-curl-and-wget.md))
|
||||
- Exec budget — `BARE_OS_EXEC_LINE_BUDGET_MS` — Reject top-level `execLine` when session wall time exceeds budget; alias `BARE_OS_TIMER_BUDGET_MS` when unset
|
||||
- Rlimit hint / NOFILE — `BARE_OS_VFS_MAX_OPEN` — When set, guest **`/proc/bare_os/rlimits.json**` maps `**RLIMIT_NOFILE**` to that value (advisory; not a real process `**ulimit`**)
|
||||
- Rlimit hint / NOFILE — `BARE_OS_VFS_MAX_OPEN` — When set, guest **`/proc/bare_os/rlimits.json`** maps **`RLIMIT_NOFILE`** to that value (advisory; not a real process **`ulimit`**)
|
||||
- Delegates — `BARE_OS_DELEGATE_MAX_PER_MIN`, `BARE_OS_DELEGATE_CURL_MAX_PER_MIN`, … — Per-minute caps on host delegates (sliding minute window)
|
||||
- Delegates — `BARE_OS_DELEGATE_AUDIT_ONLY=1` — With `BARE_OS_AUDIT=1`, log delegate invocations and skip host run (exit 0)
|
||||
- Boot policy — `BARE_OS_BOOT_POLICY=1` — Merge `skipBootStages` / `denyBootStages` (legacy `skipPhases` / `denyBootPhases`) from `/etc/bare-os/boot.policy.json`; optional `minKernelCapabilitiesPrimary` / `requireSeedCaps`; v2 `maxExecLineDepth`, `denyEnvKeys`, `requireProcNodes`; **v3** `requireKernelCapabilitiesExtendedSeedingPlatform`, `requireKernelCapabilitiesRlimitsDelegatesShell`, `allowedPearIpcChannels` → session env, `denyVfsPrefixes` (VFS deny), `maxInitdRestartsPerUnit` → `BARE_OS_INITD_RESTART_MAX_DEFAULT`; **v4** `requireKernelCapabilitiesOfflineNetExtensions`, `denyExecLineBuiltins` → `BARE_OS_BOOT_POLICY_DENY_EXEC_LINE_BUILTINS`, `allowedCtxMethods` → `BARE_OS_BOOT_POLICY_ALLOWED_CTX_METHODS`; **v5** `requireKernelCapabilitiesHostTransportDelegates`, `requireInitJsSha256`; **v6** `requireKernelCapabilitiesReplicationOperatorSurface`, `requireBooterSemver`, `requireCtxApiMin`, `denyKernelExtensionIds`, `kernelExtensionHashPins`, `offlineLkgIntegrityStrict`; **v7–v8** (see schema); **v9** `requireKernelCapabilitiesBareModuleCryptoStaging`, `requirePearRuntimeRange`, `denyBareModuleSpecifierPatterns`, `requireBareCryptoMin`, `denyKernelSyscalls`, `requirePearIpcMin`, `extensionSignerPinsV2`, `offlineLkgManifestMaxAgeSec`, `bootStagesRequireProcIndexMinSchema` (legacy `bootPhasesRequireProcIndexMinSchema`), stricter extension depth / cycle diagnostics; **v10** `requireKernelCapabilitiesPearInspectLoggerTls`, `requireBareBootMin`, `denyBareRpcMethodPatterns`, `maxPearInspectDepth`, `requireBareLoggerMin`, `denyAutobaseDiscoveryChannels`, `requireBareTlsMin`, `extensionSignerPinsV3`, `offlineLkgRequirePearStamp`, `bootStagesRequireLifecycleMinSchema` (legacy `bootPhasesRequireLifecycleMinSchema`)
|
||||
@@ -123,23 +123,23 @@ Seed RPC **`bare_os.capabilities**` includes `**protocolPackageVersion**`, optio
|
||||
- Seeder staging — `BARE_OS_SEED_STAGING_PREVIOUS_SLOT`, `BARE_OS_SEED_REPLICATION_QUEUE_DEPTH_HINT`, `BARE_OS_SEED_REPLICATION_SNAPSHOT_NOTE_JSON` — Seeder-only env for richer RPC payloads
|
||||
- Sandbox — `BARE_OS_SANDBOX_WORKER=1` — Try `bare-worker` when available; else microtask defer
|
||||
- Bundle tier — `BARE_OS_BUNDLE_TIER=core` — `bare-os-bare-libs` build: only manifest rows with matching `tier` (`all` = default); optional per-row `risk` in manifest
|
||||
- Word-11 proc — `BARE_OS_HIDE_PROC_HYPERCORE_PACK_HRPC_LIFECYCLE=0` (or `false` / `off`) — Hides the 20 word-11 **`/proc/bare_os_*.json**` entries, matching `**/proc/bare_os/*.json**` aliases, and their rows in `**/proc/bare_os/index.json**`; reads resolve as absent (`**null`** / ENOENT semantics)
|
||||
- Word-11 proc — `BARE_OS_HIDE_PROC_HYPERCORE_PACK_HRPC_LIFECYCLE=0` (or `false` / `off`) — Hides the 20 word-11 **`/proc/bare_os_*.json`** entries, matching **`/proc/bare_os/*.json`** aliases, and their rows in **`/proc/bare_os/index.json`**; reads resolve as absent (**`null`** / ENOENT semantics)
|
||||
|
||||
## Capability word 6 summary
|
||||
|
||||
Shipped as **`bits6**` + `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_REPLICATION_OPERATOR_SURFACE**`. Full bit map: [kernel-capabilities-index.md](./kernel-capabilities-index.md) (Word 6). One-row checklist: [feature-roadmap.md](./feature-roadmap.md) (Capability word 6 table). CI: `**verify-kernel-capabilities-word-6.mjs**`, `**verify-pear-no-static-node-import.mjs`**.
|
||||
Shipped as **`bits6`** + **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_REPLICATION_OPERATOR_SURFACE`**. Full bit map: [kernel-capabilities-index.md](./kernel-capabilities-index.md) (Word 6). One-row checklist: [feature-roadmap.md](./feature-roadmap.md) (Capability word 6 table). CI: **`verify-kernel-capabilities-word-6.mjs`**, **`verify-pear-no-static-node-import.mjs`**.
|
||||
|
||||
## Capability word 9 summary
|
||||
|
||||
Shipped as **`bits9**` + `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_BARE_MODULE_CRYPTO_STAGING**`. Word 9 map: [kernel-capabilities-index.md](./kernel-capabilities-index.md). Checklist: [feature-roadmap.md](./feature-roadmap.md) (Capability word 9 table). Node→Bare map: [node-to-bare-modules.md](../../developer-guide/node-to-bare-modules.md). CI: `**verify-kernel-capabilities-word-9.mjs**`, `**verify-kernel-capabilities-contract.mjs**`, `**verify-ctx-api-feature-bits.mjs**`, `**verify-ctx-dts.mjs**`, `**verify-compat-matrix.mjs`**.
|
||||
Shipped as **`bits9`** + **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_BARE_MODULE_CRYPTO_STAGING`**. Word 9 map: [kernel-capabilities-index.md](./kernel-capabilities-index.md). Checklist: [feature-roadmap.md](./feature-roadmap.md) (Capability word 9 table). Node→Bare map: [node-to-bare-modules.md](../../developer-guide/node-to-bare-modules.md). CI: **`verify-kernel-capabilities-word-9.mjs`**, **`verify-kernel-capabilities-contract.mjs`**, **`verify-ctx-api-feature-bits.mjs`**, **`verify-ctx-dts.mjs`**, **`verify-compat-matrix.mjs`**.
|
||||
|
||||
## Capability word 10 summary
|
||||
|
||||
Shipped as **`bits10**` + `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_PEAR_INSPECT_LOGGER_TLS**`. Word 10 map: [kernel-capabilities-index.md](./kernel-capabilities-index.md). Checklist: [feature-roadmap.md](./feature-roadmap.md) (Capability word 10 table). CI: `**verify-kernel-capabilities-word-10.mjs`** plus the capabilities-contract / ctx / compat scripts above.
|
||||
Shipped as **`bits10`** + **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_PEAR_INSPECT_LOGGER_TLS`**. Word 10 map: [kernel-capabilities-index.md](./kernel-capabilities-index.md). Checklist: [feature-roadmap.md](./feature-roadmap.md) (Capability word 10 table). CI: **`verify-kernel-capabilities-word-10.mjs`** plus the capabilities-contract / ctx / compat scripts above.
|
||||
|
||||
## Capability word 11 summary
|
||||
|
||||
Shipped as **`bits11**` + `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_HYPERCORE_PACK_HRPC_LIFECYCLE**`. Word 11 map: [kernel-capabilities-index.md](./kernel-capabilities-index.md). Checklist: [feature-roadmap.md](./feature-roadmap.md) (Capability word 11 table). Node→Bare map: [node-to-bare-modules.md](../../developer-guide/node-to-bare-modules.md). CI: `**verify-kernel-capabilities-word-11.mjs**` plus `**verify-kernel-capabilities-contract.mjs**`, `**verify-ctx-api-feature-bits.mjs**`, `**verify-ctx-dts.mjs**`, `**verify-compat-matrix.mjs`**.
|
||||
Shipped as **`bits11`** + **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_HYPERCORE_PACK_HRPC_LIFECYCLE`**. Word 11 map: [kernel-capabilities-index.md](./kernel-capabilities-index.md). Checklist: [feature-roadmap.md](./feature-roadmap.md) (Capability word 11 table). Node→Bare map: [node-to-bare-modules.md](../../developer-guide/node-to-bare-modules.md). CI: **`verify-kernel-capabilities-word-11.mjs`** plus **`verify-kernel-capabilities-contract.mjs`**, **`verify-ctx-api-feature-bits.mjs`**, **`verify-ctx-dts.mjs`**, **`verify-compat-matrix.mjs`**.
|
||||
|
||||
## POSIX utility notes
|
||||
|
||||
@@ -151,9 +151,9 @@ Shipped as **`bits11**` + `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_HYPERCORE_PACK_H
|
||||
1. **Boot phases** — Use `ctx.bareOsRegisterBootPhaseHook` (see stock `kernel/init.js` header).
|
||||
2. **Virtual files** — `ctx.bareOsRegisterVirtualFile(name, reader, { etag, mime, ttlMs })`; list via `/proc/bare_os_virtual_registry`.
|
||||
3. **IPC** — Named FIFOs under `/run/bare-os/ipc/`; optional `BARE_OS_IPC_NAMESPACE`; JSON-RPC and fan-out documented in the booter package README.
|
||||
4. **Initd drop-ins** — `After=` / `Before=` / `Wants=` / `Requires=`; `RestartMaxAttempts=` in `~/.config/bare-os/units/<name>.unit` (1–32). **Fragments** — `~/.config/bare-os/units.d/<name>/*.conf` merged before `bare-init` overrides. **`IdleSec=**` with `**SocketActivationIpc=**` stops the unit after idle IPC (requires `**stop**`). `**ReadinessPath=**` may be `**exec:<line>**` for an `**execLine`** gate. **Timers** — `~/.config/bare-os/timers/*.timer`: `[Timer]` with `OnCalendar=` + `ExecLine=`, optional **`JitterSec=`**, or `EveryMs=` (1000–86400000) + `ExecLine=` for fixed-interval jobs (max 8 files).
|
||||
4. **Initd drop-ins** — `After=` / `Before=` / `Wants=` / `Requires=`; `RestartMaxAttempts=` in `~/.config/bare-os/units/<name>.unit` (1–32). **Fragments** — `~/.config/bare-os/units.d/<name>/*.conf` merged before `bare-init` overrides. **`IdleSec=`** with **`SocketActivationIpc=`** stops the unit after idle IPC (requires **`stop`**). **`ReadinessPath=`** may be **`exec:<line>`** for an **`execLine`** gate. **Timers** — `~/.config/bare-os/timers/*.timer`: `[Timer]` with `OnCalendar=` + `ExecLine=`, optional **`JitterSec=`**, or `EveryMs=` (1000–86400000) + `ExecLine=` for fixed-interval jobs (max 8 files).
|
||||
5. **`/proc/bare_os/`** — Stable aliases (`features`, `replication`, `provenance`, `metrics_live.json`, `initd_dag.json`, `pear_ipc.json`, `manifest_hints`, …) mirroring flat `/proc/bare_os_*` files.
|
||||
6. **`ctx.bareOsReadProcMetricsLive()**` — Same JSON as `**/proc/bare_os/metrics_live.json`** without a VFS read.
|
||||
6. **`ctx.bareOsReadProcMetricsLive()**` — Same JSON as **`/proc/bare_os/metrics_live.json`** without a VFS read.
|
||||
7. **Initd** — `bareOsRegisterSuspendHook` / `ResumeHook` stop and restart units with `stop` handlers around Bare mobile suspend (see **`bare-initd`**).
|
||||
|
||||
## Profiles
|
||||
|
||||
@@ -26,11 +26,11 @@ These files are **read from disk by the seeder** and written into the system dri
|
||||
|
||||
- **Staged as**: `/bin/help`
|
||||
- **Contract**: `async function run(ctx, _argv)`.
|
||||
- **Behavior**: Logs a compact list of **`/bin**` names, builtins, and pointers to `**man**` / identity commands (not an exhaustive tutorial; see `**man edit**` / `**man nano`** for the TTY editor).
|
||||
- **Behavior**: Logs a compact list of **`/bin`** names, builtins, and pointers to **`man`** / identity commands (not an exhaustive tutorial; see `**man edit**` / `**man nano`** for the TTY editor).
|
||||
|
||||
### 9.4 Optional `/bin` index artifacts (booter, personal drive)
|
||||
|
||||
When **`BARE_OS_VFS_BIN_INDEX_BUILD**` or `**BARE_OS_BIN_HYPERBEE_INDEX**` is enabled, the host booter may write `**/.bare-os/index/bin-manifest.json**` and `**/.bare-os/index/bin-hyperbee-hint.json**` (**schema 2**, includes `**namesDigest**` for deterministic invalidation). `**ctx.bareOsVfsBatchWrite**` rebuilds these when any batch `**put**` touches `**bin/*`**.
|
||||
When **`BARE_OS_VFS_BIN_INDEX_BUILD`** or **`BARE_OS_BIN_HYPERBEE_INDEX`** is enabled, the host booter may write **`/.bare-os/index/bin-manifest.json`** and **`/.bare-os/index/bin-hyperbee-hint.json`** (**schema 2**, includes **`namesDigest`** for deterministic invalidation). **`ctx.bareOsVfsBatchWrite`** rebuilds these when any batch **`put`** touches **`bin/*`**.
|
||||
|
||||
### 9.5 [kernel/etc/os-release](../../kernel/etc/os-release)
|
||||
|
||||
|
||||
@@ -4,17 +4,17 @@ Stock booter modules under `packages/bare-os-booter/lib/`:
|
||||
|
||||
| Module | Role |
|
||||
| --- | --- |
|
||||
| `identity-account.js` | On-disk account v2 (Ed25519, PBKDF2, ChaCha20-Poly1305); **`BARE_OS_ACCOUNT_CRYPTO_PROFILE_V2**` and `**readAccountCryptoProfile(buf)`** expose algorithm metadata without decryption. |
|
||||
| `identity-account.js` | On-disk account v2 (Ed25519, PBKDF2, ChaCha20-Poly1305); **`BARE_OS_ACCOUNT_CRYPTO_PROFILE_V2`** and `**readAccountCryptoProfile(buf)`** expose algorithm metadata without decryption. |
|
||||
| `identity-session.js` | Login, vault unlock, session key application. |
|
||||
| `bare-os-secret-handle-registry.js` | Opaque handles with TTL, optional max uses, revocation; surfaced via **`ctx.bareOsAcquireKeyHandle**` / `**bareOsReleaseKeyHandle**` / `**bareOsTouchKeyHandle`**. |
|
||||
| `bare-os-secret-handle-registry.js` | Opaque handles with TTL, optional max uses, revocation; surfaced via **`ctx.bareOsAcquireKeyHandle`** / **`bareOsReleaseKeyHandle`** / **`bareOsTouchKeyHandle`**. |
|
||||
| `bare-os-audit-chain.js` | In-memory hash-linked audit rows; **`ctx.bareOsAuditLogAppend`**. |
|
||||
| `bare-os-acl-eval.js` | Advisory **`evaluateBareOsAcl**`; `**ctx.bareOsAclEvaluate`**. |
|
||||
| `bare-os-acl-eval.js` | Advisory **`evaluateBareOsAcl`**; **`ctx.bareOsAclEvaluate`**. |
|
||||
|
||||
## Protomux and optional RPC client pool
|
||||
|
||||
Stock **`/proc/bare_os/protomux.json**` and `**metrics_live.json**` may include **operator-only** sketches for Hyperswarm / Protomux backpressure and (when `**BARE_OS_PROTOMUX_RPC_CLIENT_POOL_COMPOSITION=1**`) a **composition gate** for `**protomux-rpc-client-pool**`-style reuse. The guest never opens pool handles itself: the booter only surfaces **env-gated, non-spoofable counters** so fleet dashboards can correlate replication pressure with mux RPC depth. Treat pool metrics like any other **P2P hint** — no central authority and no silent network from `**/proc`**.
|
||||
Stock **`/proc/bare_os/protomux.json`** and **`metrics_live.json`** may include **operator-only** sketches for Hyperswarm / Protomux backpressure and (when **`BARE_OS_PROTOMUX_RPC_CLIENT_POOL_COMPOSITION=1`**) a **composition gate** for **`protomux-rpc-client-pool`**-style reuse. The guest never opens pool handles itself: the booter only surfaces **env-gated, non-spoofable counters** so fleet dashboards can correlate replication pressure with mux RPC depth. Treat pool metrics like any other **P2P hint** — no central authority and no silent network from **`/proc`**.
|
||||
|
||||
`/proc/bare_os/security_posture.json` (**schema 4**) aggregates non-secret snapshots: account profile, active handle counts, audit chain head/length, vault rotation checkpoint path, peer admission env pointers, optional blind-relay audit gate, and policy flags. Host env may supply **`BARE_OS_PEAR_SECURE_ENCLAVE_JSON**` (opaque Pear enclave pointer) and `**BARE_OS_ACCOUNT_KEY_ROTATION_STATE_JSON`** (rotation continuity metadata — not secret keys); both are merged only when non-empty.
|
||||
`/proc/bare_os/security_posture.json` (**schema 4**) aggregates non-secret snapshots: account profile, active handle counts, audit chain head/length, vault rotation checkpoint path, peer admission env pointers, optional blind-relay audit gate, and policy flags. Host env may supply **`BARE_OS_PEAR_SECURE_ENCLAVE_JSON`** (opaque Pear enclave pointer) and **`BARE_OS_ACCOUNT_KEY_ROTATION_STATE_JSON`** (rotation continuity metadata — not secret keys); both are merged only when non-empty.
|
||||
|
||||
**Threat model and encryption posture:** [vault-threat-model.md](vault-threat-model.md) (encryption at rest, AEAD, operator assumptions).
|
||||
|
||||
|
||||
@@ -19,7 +19,7 @@ Machine-checked by `scripts/verify-naming-alias-matrix.mjs` (see root `pretest`)
|
||||
|
||||
## `/proc` stable names
|
||||
|
||||
- **`/proc/bare_os/kernel_program.json**` is canonical; `**giant_phase_program.json`** remains a documented legacy alias filename on some images.
|
||||
- **`/proc/bare_os/kernel_program.json`** is canonical; **`giant_phase_program.json`** remains a documented legacy alias filename on some images.
|
||||
|
||||
## Terminology policy
|
||||
|
||||
|
||||
@@ -5,12 +5,12 @@ This repository mixes **Node** (CI and some package scripts) and **Bare** / **Pe
|
||||
| Surface | Typical host | Notes |
|
||||
|--------|----------------|-------|
|
||||
| `packages/bare-os-booter/test.js` | **Node** + `bare-node-test-shim.cjs` | Exercises the booter with Brittle; the harness may use Node APIs; **booter `index.js` + `lib/*.js**` use `**#host-fs**` / `**#host-path`** (`bare-fs` / `bare-path` on Bare). |
|
||||
| `packages/bare-os-seeder` sources | **Bare** / **Pear** entry | **`index.js**` and `**lib/*.js**` use `**#host-***` aliases like the booter; seeder adds `**#host-fs-promises`**. |
|
||||
| `packages/bare-os-seeder` sources | **Bare** / **Pear** entry | **`index.js`** and **`lib/*.js`** use `**#host-***` aliases like the booter; seeder adds `**#host-fs-promises`**. |
|
||||
| `packages/bare-os-booter/test.identity.js` | **Bare** (`brittle-bare`) | Identity paths prefer Bare APIs. |
|
||||
| `packages/bare-os-protocol/test.js` | **Bare** (`brittle-bare`); optional `test:node` | Protocol encodings are runtime-agnostic. |
|
||||
| `packages/bare-os-coreutils/test/*.mjs` | **Node** | Utilities are loaded via `AsyncFunction`; stdin/fs helpers use Node in tests. |
|
||||
| `packages/bare-os-booter` `start` / `dev` | **Bare** (`bare index.js`) | Production-shaped guest path; Pear uses the same tree with staged `node_modules`. |
|
||||
| Guest **`ctx**` / `**/bin**` / kernel `**init.js`** | **Bare** (or Pear) | Must not rely on `node:*` built-ins; use **`bare-*`** shims per project rules. |
|
||||
| Guest **`ctx`** / **`/bin`** / kernel **`init.js`** | **Bare** (or Pear) | Must not rely on `node:*` built-ins; use **`bare-*`** shims per project rules. |
|
||||
| Repo `pretest` verify scripts | **Node** | Static analysis, schema checks, bundle policy. |
|
||||
|
||||
Root **`npm run test:bare`** runs a small Bare-first slice (protocol + coreutils Node tests are still Node; see script in root `package.json`).
|
||||
|
||||
@@ -2,12 +2,12 @@
|
||||
|
||||
Bare OS mirrors structured **boot** and **kernel** events to optional sinks:
|
||||
|
||||
- **Boot trace** — `BARE_OS_BOOT_TRACE` (`json` / `ndjson`) from the stock bundled kernel ([`kernel/lib/init/init-main.js`](../../kernel/lib/init/init-main.js) → `/boot/init.js`), including canonical **`stage**` plus legacy `**phase`** fields on each line.
|
||||
- **Kernel extension reload audit** — When `BARE_OS_KERNEL_EXT_D_HOT_RELOAD` is enabled and `ctx.bareOsReloadKernelExtDropinsSafe()` runs, append-only lines (**`kernelExtReloadSchemaVersion**`) may be written to `**/run/bare-os/kernel-ext-reload.ndjson**` (guest VFS), alongside existing `**loader-audit.ndjson`** when `BARE_OS_LOADER_AUDIT` is on.
|
||||
- **Boot trace** — `BARE_OS_BOOT_TRACE` (`json` / `ndjson`) from the stock bundled kernel ([`kernel/lib/init/init-main.js`](../../kernel/lib/init/init-main.js) → `/boot/init.js`), including canonical **`stage`** plus legacy **`phase`** fields on each line.
|
||||
- **Kernel extension reload audit** — When `BARE_OS_KERNEL_EXT_D_HOT_RELOAD` is enabled and `ctx.bareOsReloadKernelExtDropinsSafe()` runs, append-only lines (**`kernelExtReloadSchemaVersion`**) may be written to **`/run/bare-os/kernel-ext-reload.ndjson`** (guest VFS), alongside existing **`loader-audit.ndjson`** when `BARE_OS_LOADER_AUDIT` is on.
|
||||
- **Telemetry NDJSON** — `BARE_OS_TELEMETRY_NDJSON` (guest path); schema **`telemetry-ndjson-record.schema.json`** (`telemetrySchemaVersion` / `lifecycleSchemaVersion`).
|
||||
- **OTel-style JSONL** — `BARE_OS_TELEMETRY_OTEL_JSONL`; schema **`otel-bare-os-jsonl.schema.json**`. When `**BARE_OS_TELEMETRY_OTEL=1**` (or `**true**`) and no JSONL path is set, the booter defaults to `**/var/log/bare-os/otel.jsonl`**.
|
||||
- **Audit stream** — host/session policy; see kernel extensions reference for env keys. **`ctx.bareOsAuditLogAppendBatch**` mirrors may include `**identity.personal_root_migration`** (schema **1**: legacy `/` → `/.bare-os/home/<seg>/` decisions) and **`identity.guest_scrub**` (schema **1**: paths wiped when `**BARE_OS_GUEST_SCRUB`** runs on guest login).
|
||||
- **OTel-style JSONL** — `BARE_OS_TELEMETRY_OTEL_JSONL`; schema **`otel-bare-os-jsonl.schema.json`**. When **`BARE_OS_TELEMETRY_OTEL=1`** (or **`true`**) and no JSONL path is set, the booter defaults to **`/var/log/bare-os/otel.jsonl`**.
|
||||
- **Audit stream** — host/session policy; see kernel extensions reference for env keys. **`ctx.bareOsAuditLogAppendBatch`** mirrors may include **`identity.personal_root_migration`** (schema **1**: legacy `/` → `/.bare-os/home/<seg>/` decisions) and **`identity.guest_scrub`** (schema **1**: paths wiped when **`BARE_OS_GUEST_SCRUB`** runs on guest login).
|
||||
- **Event bus** — `ctx.bareOsEmitEventBus` / `ctx.bareOsSubscribeEventBus`; optional **`BARE_OS_EVENT_BUS_NDJSON=1`** mirrors one JSON line per event on session stdout (`eventBusSchema: 1`).
|
||||
- **Boot budget / bare-stdlib** — Guest **`/run/bare-os/boot-perf.json**` (**schema 5**) records cold wall vs `**BARE_OS_BOOT_BUDGET_MS_COLD**` and bare-stdlib resolution vs `**BARE_OS_BOOT_BUDGET_MS_BARE_STDLIB**` (booter seeds `**BARE_OS_BOOT_BARE_STDLIB_RESOLUTION_MS**`). `**/proc/bare_os/metrics_live.json**` exposes `**bootBudgetCold**`, `**bootBudgetBareStdlib**`, and coalesced `**bootBudgetTelemetry`** (**schema 2**) for the same knobs.
|
||||
- **Boot budget / bare-stdlib** — Guest **`/run/bare-os/boot-perf.json`** (**schema 5**) records cold wall vs **`BARE_OS_BOOT_BUDGET_MS_COLD`** and bare-stdlib resolution vs **`BARE_OS_BOOT_BUDGET_MS_BARE_STDLIB`** (booter seeds **`BARE_OS_BOOT_BARE_STDLIB_RESOLUTION_MS`**). **`/proc/bare_os/metrics_live.json`** exposes **`bootBudgetCold`**, **`bootBudgetBareStdlib`**, and coalesced **`bootBudgetTelemetry`** (**schema 2**) for the same knobs.
|
||||
|
||||
**Contract tests** in root `pretest`: `validate-example-schemas.mjs`, `verify-kernel-capabilities-contract.mjs`, `verify-compat-matrix.mjs`, **`verify-banned-terminology.mjs`** (governance wording; skips vendored `kernel/lib/bare/`), and **`verify-naming-alias-matrix.mjs`**. When adding fields, bump schema versions and extend the example JSON under `kernel/etc/bare-os/`.
|
||||
|
||||
@@ -6,37 +6,37 @@ Former **DOCUMENTATION.md** §§12.1–12.9 plus **§12.7a** (REPL completion).
|
||||
|
||||
### 12.1 [packages/bare-os-booter/package.json](../../packages/bare-os-booter/package.json)
|
||||
|
||||
**Resolved hyperstack (hoisted root lockfile, illustrative):** after **`npm install**` at the repo root, `**node_modules/protomux**` and `**node_modules/hyperswarm**` versions are pinned in `**package-lock.json**` and guarded by `**packages/bare-os-booter/test.js**` (`**fixtures/protomux-hyperswarm-lock.json**`, `**schema` 2** metadata row). Intentional upgrades require bumping that fixture alongside the lockfile.
|
||||
**Resolved hyperstack (hoisted root lockfile, illustrative):** after **`npm install**` at the repo root, **`node_modules/protomux`** and **`node_modules/hyperswarm`** versions are pinned in **`package-lock.json`** and guarded by **`packages/bare-os-booter/test.js`** (**`fixtures/protomux-hyperswarm-lock.json`**, `**schema` 2** metadata row). Intentional upgrades require bumping that fixture alongside the lockfile.
|
||||
|
||||
**Hyperbee guest hints:** **`ctx.bareOsHyperbeeGuestHint()**` (when `**BARE_OS_HYPERBEE_GUEST_INDEX`** is set) returns read-only JSON aligned with optional **[hyperbee2](https://github.com/holepunchto/hyperbee2)**-style guest indexes — see [ADR-hyperbee-guest-index.md](../architecture/ADR-hyperbee-guest-index.md); the stock kernel does not import Hyperbee by default.
|
||||
**Hyperbee guest hints:** **`ctx.bareOsHyperbeeGuestHint()**` (when **`BARE_OS_HYPERBEE_GUEST_INDEX`** is set) returns read-only JSON aligned with optional **[hyperbee2](https://github.com/holepunchto/hyperbee2)**-style guest indexes — see [ADR-hyperbee-guest-index.md](../architecture/ADR-hyperbee-guest-index.md); the stock kernel does not import Hyperbee by default.
|
||||
|
||||
- `main` — `./index.js`
|
||||
- `scripts.start` / `dev` — `bare index.js`
|
||||
- `scripts.test` — `brittle-bare test.identity.js` then `node --require ./scripts/bare-node-test-shim.cjs … brittle-node test.js` (shim supplies Bare-style `bare-type` binding + Node `util.inspect` stand-in for `bare-inspect`; `openssl` / `ssh-keygen` delegates lazy-load `bare-crypto` so the main suite does not import native addons at startup)
|
||||
- `dependencies` — Same hyperstack as seeder + `bare-os-protocol` + `bare-crypto` (identity account + vault AEAD)
|
||||
- `devDependencies` — `brittle`
|
||||
- `imports` — **`#host-fs**` / `**#host-path**` resolve to `**bare-fs**` / `**bare-path**` under Bare and Node’s built-in `**fs**` / `**path**` under the default condition (package `**imports**` cannot target `**node:**` URLs). First-party sources import `**#host-***` only (CI forbids bare `**from 'fs'**` / `**from 'path'**`). `**url**` maps to `**bare-url**` / `**node:url**`. `**#bare-os-boot-manifest-sig`** selects Bare vs Node Ed25519 verify helper.
|
||||
- `imports` — **`#host-fs**` / `**#host-path**` resolve to **`bare-fs`** / **`bare-path`** under Bare and Node’s built-in **`fs`** / **`path`** under the default condition (package **`imports`** cannot target **`node:`** URLs). First-party sources import `**#host-***` only (CI forbids bare `**from 'fs'**` / `**from 'path'**`). **`url`** maps to **`bare-url`** / **`node:url`**. `**#bare-os-boot-manifest-sig`** selects Bare vs Node Ed25519 verify helper.
|
||||
- `pear.stage.ignore` — Includes `test.js`, `test.identity.js`, `.test-data` so tests are not staged
|
||||
|
||||
**Pear + npm workspaces:** dependencies are hoisted to the repo root; Pear’s dev bundle often does not follow a single symlinked `node_modules` tree. **[scripts/ensure-pear-node-modules.mjs](../../scripts/ensure-pear-node-modules.mjs)** (run from the repo root) rebuilds `packages/bare-os-booter/node_modules` by symlinking **each top-level** package from the root `node_modules` (matching npm’s flat hoist). **`pear.stage.include**` lists `**node_modules**` so the staged Hyperdrive uses `**node_modules/<pkg>**` paths (Bare `**require('bare-node-net')**` and similar resolve correctly; `**../../node_modules**` alone did not). For `**bare-ssh2**`, `**bare-net**` (Bare TCP) and the `**bare-node-***` shims it loads are direct `**dependencies**` of the booter so versions match the vendored `**bare-ssh2**` tree and Pear staging always sees them. `**npm run os:booter`** runs the script before `pear run`. After `npm install` at the root, re-run the script if hoisted packages change.
|
||||
**Pear + npm workspaces:** dependencies are hoisted to the repo root; Pear’s dev bundle often does not follow a single symlinked `node_modules` tree. **[scripts/ensure-pear-node-modules.mjs](../../scripts/ensure-pear-node-modules.mjs)** (run from the repo root) rebuilds `packages/bare-os-booter/node_modules` by symlinking **each top-level** package from the root `node_modules` (matching npm’s flat hoist). **`pear.stage.include`** lists **`node_modules`** so the staged Hyperdrive uses **`node_modules/<pkg>`** paths (Bare `**require('bare-node-net')**` and similar resolve correctly; **`../../node_modules`** alone did not). For **`bare-ssh2`**, **`bare-net`** (Bare TCP) and the **`bare-node-*`** shims it loads are direct **`dependencies`** of the booter so versions match the vendored **`bare-ssh2`** tree and Pear staging always sees them. `**npm run os:booter`** runs the script before `pear run`. After `npm install` at the root, re-run the script if hoisted packages change.
|
||||
|
||||
### 12.2 [packages/bare-os-booter/lib/paths.js](../../packages/bare-os-booter/lib/paths.js)
|
||||
|
||||
- **`packageRootDir(metaUrl)`** — Same as seeder (Pear RTI / `swapDir` / `cwd`).
|
||||
- **`defaultBootCorestorePath**` / `**defaultLocalSeedCorestorePath`** — `BARE_OS_BOOT_STORE` / `BARE_OS_LOCAL_SEED`, or under **`hostDataRoot()`** (`BARE_OS_HOST_DATA` or `~/.bare-os`): `corestore/booter` and `corestore/seeder` respectively. Same signature stability as the seeder helper.
|
||||
- **`defaultBootCorestorePath`** / **`defaultLocalSeedCorestorePath`** — `BARE_OS_BOOT_STORE` / `BARE_OS_LOCAL_SEED`, or under **`hostDataRoot()`** (`BARE_OS_HOST_DATA` or `~/.bare-os`): `corestore/booter` and `corestore/seeder` respectively. Same signature stability as the seeder helper.
|
||||
|
||||
### 12.2a Boot modularity (loader, capabilities, lifecycle)
|
||||
|
||||
- **[`lib/bare-os-kernel-loader.js`](../../packages/bare-os-booter/lib/bare-os-kernel-loader.js)** — **`loadOsFromPeers**`, `**loadOsFromOfflineLkg`**: seed capability handshake + optional RPC wave, MBR read, system Hyperdrive open/replicate, `/boot/init.js` fetch, personal drive mount (when not lazy). Invoked from `index.js` inside the boot timeout race.
|
||||
- **[`lib/bare-os-capability-registry.js`](../../packages/bare-os-booter/lib/bare-os-capability-registry.js)** — **`KERNEL_CAPABILITY_SEED_STRICT_ROWS**`, `**buildStockKernelCapabilityWords**`, `**freezeKernelCapabilityWordsFromCapabilities`**: single place for stock capability word math used by the booter and loader.
|
||||
- **[`lib/bare-os-lifecycle-manager.js`](../../packages/bare-os-booter/lib/bare-os-lifecycle-manager.js)** — **`exitHostProcess**`, `**teardownBareOsBootResources`**: `Bare.exit` deferral and ordered HDMS → swarm → drives → Corestore teardown (Pear heap safety).
|
||||
- **[`lib/bare-os-kernel-loader.js`](../../packages/bare-os-booter/lib/bare-os-kernel-loader.js)** — **`loadOsFromPeers`**, **`loadOsFromOfflineLkg`**: seed capability handshake + optional RPC wave, MBR read, system Hyperdrive open/replicate, `/boot/init.js` fetch, personal drive mount (when not lazy). Invoked from `index.js` inside the boot timeout race.
|
||||
- **[`lib/bare-os-capability-registry.js`](../../packages/bare-os-booter/lib/bare-os-capability-registry.js)** — **`KERNEL_CAPABILITY_SEED_STRICT_ROWS`**, **`buildStockKernelCapabilityWords`**, **`freezeKernelCapabilityWordsFromCapabilities`**: single place for stock capability word math used by the booter and loader.
|
||||
- **[`lib/bare-os-lifecycle-manager.js`](../../packages/bare-os-booter/lib/bare-os-lifecycle-manager.js)** — **`exitHostProcess`**, **`teardownBareOsBootResources`**: `Bare.exit` deferral and ordered HDMS → swarm → drives → Corestore teardown (Pear heap safety).
|
||||
- **[`lib/bare-os-kernel-errno.js`](../../packages/bare-os-booter/lib/bare-os-kernel-errno.js)** — POSIX-inspired **`BARE_OS_ERRNO`** constants and name helpers for future unified error reporting across VFS/utilities.
|
||||
|
||||
See also [Kernel subsystem map](../architecture/kernel-subsystems.md) and [ADR 0001](../adr/0001-kernel-subsystem-boundaries.md).
|
||||
|
||||
### 12.2b Corestore / swarm suspend–resume bridge
|
||||
|
||||
- **[`lib/corestore-host-lifecycle.js`](../../packages/bare-os-booter/lib/corestore-host-lifecycle.js)** — Registers one-shot hooks so guest **`ctx.bareOsRegisterSuspendHook**` / `**bareOsRegisterResumeHook**` call host `**corestore**` / `**hyperswarm**` `**suspend()**` / `**resume()**` when those methods exist (mobile sleep, Pear lifecycle). **Non-goal (stock booter):** automatic `**corestore-snapshot**` / frozen peer images from the guest — operators replicate Hyperdrives via swarm + personal-drive export of keys when needed; `**bareOsCorestoreSnapshotOperatorHint**` in `**/proc**` is an advisory field only (no guest RPC that invokes `**corestore-snapshot`**).
|
||||
- **[`lib/corestore-host-lifecycle.js`](../../packages/bare-os-booter/lib/corestore-host-lifecycle.js)** — Registers one-shot hooks so guest **`ctx.bareOsRegisterSuspendHook`** / **`bareOsRegisterResumeHook`** call host **`corestore`** / **`hyperswarm`** `**suspend()**` / `**resume()**` when those methods exist (mobile sleep, Pear lifecycle). **Non-goal (stock booter):** automatic **`corestore-snapshot`** / frozen peer images from the guest — operators replicate Hyperdrives via swarm + personal-drive export of keys when needed; **`bareOsCorestoreSnapshotOperatorHint`** in **`/proc`** is an advisory field only (no guest RPC that invokes **`corestore-snapshot`**).
|
||||
|
||||
### 12.3 [packages/bare-os-booter/index.js](../../packages/bare-os-booter/index.js)
|
||||
|
||||
@@ -47,39 +47,39 @@ See also [Kernel subsystem map](../architecture/kernel-subsystems.md) and [ADR 0
|
||||
**`createReadLine()`**
|
||||
|
||||
- If `BARE_OS_SKIP_REPL === '1'`: returns `async () => null`.
|
||||
- Else prefers **fish-style** / **`bare-readline**` raw TTY editing when stdin is a TTY; falls back to a stream line reader (no `**node:readline`** in the stock boot path).
|
||||
- Else prefers **fish-style** / **`bare-readline`** raw TTY editing when stdin is a TTY; falls back to a stream line reader (no **`node:readline`** in the stock boot path).
|
||||
- On failure: warns and returns `async () => null`.
|
||||
|
||||
**`executeKernel(disk, store, swarm, initSource)`** (`store`/`swarm` unused but kept for signature symmetry / future use)
|
||||
|
||||
- Builds `shellEnv` with **guest** defaults: `USER`/`LOGNAME`=`guest`, `HOME`/`PWD`=`/home/guest`, `UID`/`GID`=`65534`, `BARE_OS_IDENTITY=guest`, `BARE_OS_EXIT_STATUS`=`0`, `BARE_OS_CTX_API_VERSION`, `PATH=/bin`, `SHELL`, `HOSTNAME`, `0`. When the host sets any of the keys listed under “host → session passthrough” in [Environment variables and POSIX appendix](environment-and-posix-appendix.md#14-environment-variables-complete-list), those values are copied into `shellEnv`. Sets **`BARE_OS_BOOT_PROFILE_RESOLVED**` from `**BARE_OS_BOOT_PROFILE**` or the first line of `**/etc/bare-os/profile**`, and `**BARE_OS_SESSION_ID**` (random UUID). Seeds `**/run/bare-os/boot.json**` fields `**imageDigest**`, `**pearChannel**`, `**pearRelease**` from `**BARE_OS_IMAGE_DIGEST**`, `**BARE_OS_PEAR_CHANNEL**` / `**PEAR_CHANNEL**`, `**BARE_OS_PEAR_RELEASE`** when present.
|
||||
- **`createBareOsIpc({ maxFifoBytes, maxChannels?, perChannelMaxBytes?, ipcRpcToken?, enableFanout?, maxJsonRpcLineBytes?, posixMqDefaultMaxmsg?, posixMqDefaultMaxBytes?, posixMqMaxmsgCeiling? })`** ([`bare-os-ipc.js`](../../packages/bare-os-booter/lib/bare-os-ipc.js)) — FIFOs under **`/run/bare-os/ipc/<name>**`; optional per-name byte caps from `**BARE_OS_IPC_CHANNEL_MAX_BYTES**`; optional global channel cap `**BARE_OS_IPC_MAX_CHANNELS**` (host passthrough); POSIX MQ defaults from `**BARE_OS_POSIX_MQ_MAX_MSGS**` / `**BARE_OS_POSIX_MQ_MSG_BYTES**`; JSON-RPC with optional token and line cap; fan-out `**fanoutPublish`/`fanoutSubscribe**`; `**stats**` includes fan-out counts, quota telemetry, and operator backpressure snapshots when caps expose `**features.ipcFanout`**.
|
||||
- **`createVfs(drive, personalDrive, shellEnv, vfsMountRef, vfsOptions)`** → `ctx.vfs` (same `env` object as `ctx.env`). **`vfsOptions**` supply `**procSnapshot**`, dynamic `**/proc/***` and `**/sys/***` text (quotas JSON, `**bare_os_features**` with `**bits**`–`**bits5**` when advertised, `**bare_os_net_summary**`, `**bare_os_host_os**`, `**bare_os_sync_window**`, `**bare_os_debug**`, net/disk stubs, session stats), `**bootProfileText**`, `**sessionText**`, `**initdRunText**`, `**bootReadyJsonText**`, mount map for `**/proc/mounts**`, `**bootStartedMs**` for `**/proc/uptime**`, etc. Exposes `**vfs.watch(logicalPath)**` for Hyperdrive-backed paths when `**BARE_OS_VFS_WATCH**` is not `**0**`. Operator blind-relay sketches (`**blind_relay_router**`, `**blind_pairing_sketch**`, `**relay_geo_hint**`) return **schema 1** JSON with `**operatorRedacted: true**` until the host sets `**BARE_OS_PROC_BLIND_PEER_RELAY_HINTS**`. `**kernel-runner**`: when `**BARE_OS_BARE_SUBPROCESS_BRIDGE**` is set, `**BARE_OS_BARE_SUBPROCESS_TIMEOUT_MS**` can default `**runBin`** timeouts.
|
||||
- Builds `shellEnv` with **guest** defaults: `USER`/`LOGNAME`=`guest`, `HOME`/`PWD`=`/home/guest`, `UID`/`GID`=`65534`, `BARE_OS_IDENTITY=guest`, `BARE_OS_EXIT_STATUS`=`0`, `BARE_OS_CTX_API_VERSION`, `PATH=/bin`, `SHELL`, `HOSTNAME`, `0`. When the host sets any of the keys listed under “host → session passthrough” in [Environment variables and POSIX appendix](environment-and-posix-appendix.md#14-environment-variables-complete-list), those values are copied into `shellEnv`. Sets **`BARE_OS_BOOT_PROFILE_RESOLVED`** from **`BARE_OS_BOOT_PROFILE`** or the first line of **`/etc/bare-os/profile`**, and **`BARE_OS_SESSION_ID`** (random UUID). Seeds **`/run/bare-os/boot.json`** fields **`imageDigest`**, **`pearChannel`**, **`pearRelease`** from **`BARE_OS_IMAGE_DIGEST`**, **`BARE_OS_PEAR_CHANNEL`** / **`PEAR_CHANNEL`**, **`BARE_OS_PEAR_RELEASE`** when present.
|
||||
- **`createBareOsIpc({ maxFifoBytes, maxChannels?, perChannelMaxBytes?, ipcRpcToken?, enableFanout?, maxJsonRpcLineBytes?, posixMqDefaultMaxmsg?, posixMqDefaultMaxBytes?, posixMqMaxmsgCeiling? })`** ([`bare-os-ipc.js`](../../packages/bare-os-booter/lib/bare-os-ipc.js)) — FIFOs under **`/run/bare-os/ipc/<name>`**; optional per-name byte caps from **`BARE_OS_IPC_CHANNEL_MAX_BYTES`**; optional global channel cap **`BARE_OS_IPC_MAX_CHANNELS`** (host passthrough); POSIX MQ defaults from **`BARE_OS_POSIX_MQ_MAX_MSGS`** / **`BARE_OS_POSIX_MQ_MSG_BYTES`**; JSON-RPC with optional token and line cap; fan-out `**fanoutPublish`/`fanoutSubscribe**`; **`stats`** includes fan-out counts, quota telemetry, and operator backpressure snapshots when caps expose **`features.ipcFanout`**.
|
||||
- **`createVfs(drive, personalDrive, shellEnv, vfsMountRef, vfsOptions)`** → `ctx.vfs` (same `env` object as `ctx.env`). **`vfsOptions`** supply **`procSnapshot`**, dynamic **`/proc/*`** and **`/sys/*`** text (quotas JSON, **`bare_os_features`** with **`bits`**–**`bits5`** when advertised, **`bare_os_net_summary`**, **`bare_os_host_os`**, **`bare_os_sync_window`**, **`bare_os_debug`**, net/disk stubs, session stats), **`bootProfileText`**, **`sessionText`**, **`initdRunText`**, **`bootReadyJsonText`**, mount map for **`/proc/mounts`**, **`bootStartedMs`** for **`/proc/uptime`**, etc. Exposes `**vfs.watch(logicalPath)**` for Hyperdrive-backed paths when **`BARE_OS_VFS_WATCH`** is not **`0`**. Operator blind-relay sketches (**`blind_relay_router`**, **`blind_pairing_sketch`**, **`relay_geo_hint`**) return **schema 1** JSON with `**operatorRedacted: true**` until the host sets **`BARE_OS_PROC_BLIND_PEER_RELAY_HINTS`**. **`kernel-runner`**: when **`BARE_OS_BARE_SUBPROCESS_BRIDGE`** is set, **`BARE_OS_BARE_SUBPROCESS_TIMEOUT_MS`** can default **`runBin`** timeouts.
|
||||
- **`applyGuestEnv(ctx)**` then `**ensureGuestHome(ctx)`** — normalizes `ctx.identity` and seeds `/.bare/` (and a guest marker) on the personal drive.
|
||||
- **`createReadLine()`** always resolves stdio first and returns `stdout` (may be `null`) alongside `readLine` so the kernel can write to the **same** stream as the REPL (including `bare-stdio` under Pear).
|
||||
- Builds `ctx`: **`bareOsCtxApiVersion`** (from [`bare-os-ctx-api.js`](../../packages/bare-os-booter/lib/bare-os-ctx-api.js)), **`bareOsRuntimeCaps`** (frozen snapshot from [`bare-os-runtime-caps.js`](../../packages/bare-os-booter/lib/bare-os-runtime-caps.js): pipeline limits, **`quotas**`, pseudo path list, feature flags such as `**vfsWatch**`, `**ipcRpcJson**`, `**initdSocketActivation**`), `**bareOsIpc`**, `disk`, `drive`, `personalDrive`, `vfs`, `env`, `console`, `b4a`, `topic: topicKey()`, `readLine`, **`writeScreen(str)**`, `**bareOsSubscribeBootEvent**` / `**bareOsEmitBootEvent**`, `**bareOsSubscribeHdmsLifecycle**`, `**bareOsAwaitInitdUnits**`, `**bareOsPublishBootReady`**, `execLine` → wraps **`execShellLine**` with optional **audit** (`**BARE_OS_AUDIT**`, `**BARE_OS_AUDIT_JSON**`, redaction), `**execLine` depth cap** (**`BARE_OS_EXEC_MAX_DEPTH`**), then the shell (returns `'ok'` or `'exit'`; updates **`BARE_OS_EXIT_STATUS**` in `**vfs.env**`; bare `**exit**` line sets status then `**requestBooterExit**`), `**runBinCommand(argv)**` → delegates to `**runBinCommand(this, argv)`** from `kernel-runner.js` (for `/bin/time` and similar), plus identity hooks for `/bin` and builtins:
|
||||
- Builds `ctx`: **`bareOsCtxApiVersion`** (from [`bare-os-ctx-api.js`](../../packages/bare-os-booter/lib/bare-os-ctx-api.js)), **`bareOsRuntimeCaps`** (frozen snapshot from [`bare-os-runtime-caps.js`](../../packages/bare-os-booter/lib/bare-os-runtime-caps.js): pipeline limits, **`quotas`**, pseudo path list, feature flags such as **`vfsWatch`**, **`ipcRpcJson`**, **`initdSocketActivation`**), **`bareOsIpc`**, `disk`, `drive`, `personalDrive`, `vfs`, `env`, `console`, `b4a`, `topic: topicKey()`, `readLine`, **`writeScreen(str)**`, **`bareOsSubscribeBootEvent`** / **`bareOsEmitBootEvent`**, **`bareOsSubscribeHdmsLifecycle`**, **`bareOsAwaitInitdUnits`**, **`bareOsPublishBootReady`**, `execLine` → wraps **`execShellLine`** with optional **audit** (**`BARE_OS_AUDIT`**, **`BARE_OS_AUDIT_JSON`**, redaction), `**execLine` depth cap** (**`BARE_OS_EXEC_MAX_DEPTH`**), then the shell (returns `'ok'` or `'exit'`; updates **`BARE_OS_EXIT_STATUS`** in **`vfs.env`**; bare **`exit`** line sets status then **`requestBooterExit`**), `**runBinCommand(argv)**` → delegates to `**runBinCommand(this, argv)`** from `kernel-runner.js` (for `/bin/time` and similar), plus identity hooks for `/bin` and builtins:
|
||||
- **`applyUnlock(passphrase)`** — load `/.bare/account`, decrypt, unlock session.
|
||||
- **`applyRegister(passphrase)`** — create account file, unlock.
|
||||
- **`applyLogin({ publicKey, secretKey })`** — set session from an already-decoded keypair.
|
||||
- **`applyLogout({ save? })**` — optional `**save`** runs encrypted vault snapshot first (see `identity-session.js`).
|
||||
- **`applyLogout({ save? })**` — optional **`save`** runs encrypted vault snapshot first (see `identity-session.js`).
|
||||
- **`saveVault()`** — encrypt personal-drive files into `/.bare/vault/` (skips `/.bare`, `bin`, `boot`, history paths).
|
||||
- **`registerKernelShutdownHook(fn)**` — register async/sync teardown before `**stopBareInitd`** when the REPL session cleans up.
|
||||
- After **`createKernelReplSession**`: wires `**readLine**`, `**console**`, `**execLine**`, `**suspendReplForSubprocess**` / `**resumeReplAfterSubprocess**`, then `**await startBareInitd(ctx)**` (stock units include `**kernel-logger**`, `**bare-os-www**` — loopback static HTTP for `**~/.www**` — `**bare-holesail**` (managed `**~/.holesail/state.json**`: `**seed**`, `**key**`, stock `**bare-www-***` / `**bare-ssh-***` rows), `**bare-cron**`, `**bare-openssh**`, `**bare-os-chat`** when enabled, …).
|
||||
- Sets **`disk.os**` **after initd** with `**createBareOsDiskOsBridge**` (`**searchLocal**` with optional path manifest, whitelisted `**execRpc**` / `**bare_os.***`, `**disk_os_hints**` schema **3**, `**replication_operator_sketch**` schema **7**, cap-gated `**replication_operator_intent**` when `**BARE_OS_DISK_OS_OPERATOR_INTENT_RPC=1**`) — peers use `**SwarmDisk`** messages **3–6**; see [`bare-os-disk-os-bridge.js`](../../packages/bare-os-booter/lib/bare-os-disk-os-bridge.js) and §12.4.
|
||||
- **`ctx.bareOsHrpcRequest**` (stock) — validates `**service**`, `**method**`, object `**payload**`; optional `**BARE_OS_HRPC_ALLOWLIST_JSON**`; built-in routes `**kernel.ping**`, `**kernel.capabilities**`, `**vfs.readText**`, `**bare_os.echo**`, `**bare_os.disk_os_hints**`, `**bare_os.search_local**`, `**bare_os.replication_operator_sketch**`, `**bare_os.replication_snapshot**`, `**bare_os.pkg_index_get**` (`**BARE_OS_HRPC_ROUTE_TABLE_SCHEMA_VERSION` 3**). **`BARE_OS_HRPC_EMIT_UNLISTED**` forwards unknown routes to `**process.emit('bare-os:hrpc-request', …)`** on Node when enabled.
|
||||
- `try { await runKernelFromSource(...) } finally { await session.cleanup() }` — cleanup runs **`bareInitdShutdownActiveUnitsReverse**`, `**runKernelShutdownHooks**`, `**stopBareInitd`**, fish TTY teardown.
|
||||
- **`registerKernelShutdownHook(fn)**` — register async/sync teardown before **`stopBareInitd`** when the REPL session cleans up.
|
||||
- After **`createKernelReplSession`**: wires **`readLine`**, **`console`**, **`execLine`**, **`suspendReplForSubprocess`** / **`resumeReplAfterSubprocess`**, then `**await startBareInitd(ctx)**` (stock units include **`kernel-logger`**, **`bare-os-www`** — loopback static HTTP for **`~/.www`** — **`bare-holesail`** (managed **`~/.holesail/state.json`**: **`seed`**, **`key`**, stock **`bare-www-*`** / **`bare-ssh-*`** rows), **`bare-cron`**, **`bare-openssh`**, **`bare-os-chat`** when enabled, …).
|
||||
- Sets **`disk.os`** **after initd** with **`createBareOsDiskOsBridge`** (**`searchLocal`** with optional path manifest, whitelisted **`execRpc`** / **`bare_os.*`**, **`disk_os_hints`** schema **3**, **`replication_operator_sketch`** schema **7**, cap-gated **`replication_operator_intent`** when **`BARE_OS_DISK_OS_OPERATOR_INTENT_RPC=1`**) — peers use **`SwarmDisk`** messages **3–6**; see [`bare-os-disk-os-bridge.js`](../../packages/bare-os-booter/lib/bare-os-disk-os-bridge.js) and §12.4.
|
||||
- **`ctx.bareOsHrpcRequest`** (stock) — validates **`service`**, **`method`**, object **`payload`**; optional **`BARE_OS_HRPC_ALLOWLIST_JSON`**; built-in routes **`kernel.ping`**, **`kernel.capabilities`**, **`vfs.readText`**, **`bare_os.echo`**, **`bare_os.disk_os_hints`**, **`bare_os.search_local`**, **`bare_os.replication_operator_sketch`**, **`bare_os.replication_snapshot`**, **`bare_os.pkg_index_get`** (`**BARE_OS_HRPC_ROUTE_TABLE_SCHEMA_VERSION` 3**). **`BARE_OS_HRPC_EMIT_UNLISTED`** forwards unknown routes to `**process.emit('bare-os:hrpc-request', …)`** on Node when enabled.
|
||||
- `try { await runKernelFromSource(...) } finally { await session.cleanup() }` — cleanup runs **`bareInitdShutdownActiveUnitsReverse`**, **`runKernelShutdownHooks`**, **`stopBareInitd`**, fish TTY teardown.
|
||||
|
||||
**`boot-splash.js`** — TTY splash (disabled when `stdout` is not a TTY or `BARE_OS_NO_SPLASH=1`): initial full-screen clear and hidden cursor, then centered redraws from the top-left without erasing the whole screen each tick (reduces flicker); one full clear again if the terminal is resized. Vertically and horizontally centered “card” (Unicode box frame when wide enough; compact rules on very narrow widths). On very wide terminals the framed card (and progress bar) width is capped so the bar does not span the entire display. Layout scales with `stdout.columns` / `stdout.rows` (sensible fallbacks): more log lines on tall terminals (capped), word-wrapped phase text, ANSI-safe centering. **`createBootSplash(stdout, { bootLimitMs?, tagline?, footerLines? })**` — optional `**tagline**` and dim `**footerLines**`; `**main()`** passes booter and protocol package versions. Braille spinner, elapsed boot timer, bar vs `BARE_OS_BOOT_TIMEOUT_MS` (default 60s), shimmer title. `prepareForKernel()` stops the splash ticker, clears again, and shows the cursor before the fish shell; `fail()` centers a wrapped error message.
|
||||
**`boot-splash.js`** — TTY splash (disabled when `stdout` is not a TTY or `BARE_OS_NO_SPLASH=1`): initial full-screen clear and hidden cursor, then centered redraws from the top-left without erasing the whole screen each tick (reduces flicker); one full clear again if the terminal is resized. Vertically and horizontally centered “card” (Unicode box frame when wide enough; compact rules on very narrow widths). On very wide terminals the framed card (and progress bar) width is capped so the bar does not span the entire display. Layout scales with `stdout.columns` / `stdout.rows` (sensible fallbacks): more log lines on tall terminals (capped), word-wrapped phase text, ANSI-safe centering. **`createBootSplash(stdout, { bootLimitMs?, tagline?, footerLines? })**` — optional **`tagline`** and dim **`footerLines`**; `**main()`** passes booter and protocol package versions. Braille spinner, elapsed boot timer, bar vs `BARE_OS_BOOT_TIMEOUT_MS` (default 60s), shimmer title. `prepareForKernel()` stops the splash ticker, clears again, and shows the cursor before the fish shell; `fail()` centers a wrapped error message.
|
||||
|
||||
**`loadOsFromPeers(disk, store, swarm, splash)**` (network boot path used by `**main()`**)
|
||||
|
||||
- Optional pre-MBR **`disk.rpc('bare_os', 'capabilities', …)**` when peers exist and `**BARE_OS_SEED_RPC_HANDSHAKE**` is not `**0**`/`**false**`; result stored on `**disk.seedCapabilityInfo**`; `**BARE_OS_SEED_CAP_STRICT**` / `**BARE_OS_SEED_CAP_FAIL`** tighten failure behavior.
|
||||
- **`disk.read(0)**` → `**parseMbr`**.
|
||||
- Stores boot provenance as **`disk.mbrKeysHex**` and `**disk.bootMbr512`** (exact 512-byte copy) for later peer-assist eligibility.
|
||||
- Optional pre-MBR **`disk.rpc('bare_os', 'capabilities', …)**` when peers exist and **`BARE_OS_SEED_RPC_HANDSHAKE`** is not **`0`**/**`false`**; result stored on **`disk.seedCapabilityInfo`**; **`BARE_OS_SEED_CAP_STRICT`** / **`BARE_OS_SEED_CAP_FAIL`** tighten failure behavior.
|
||||
- **`disk.read(0)**` → **`parseMbr`**.
|
||||
- Stores boot provenance as **`disk.mbrKeysHex`** and **`disk.bootMbr512`** (exact 512-byte copy) for later peer-assist eligibility.
|
||||
- For each MBR key: `Hyperdrive(store, driveKey)`, `ready()`, replicate on all `disk.peers`’ mux streams, join drive discovery, `findingPeers` + `swarm.flush`, poll up to 30×200ms for `/boot/init.js`.
|
||||
- On success: `initPersonalDrive`, `splash.prepareForKernel()`, `executeKernel`.
|
||||
|
||||
Peer-assist helper path: [`lib/bare-os-peer-system-seed.js`](../../packages/bare-os-booter/lib/bare-os-peer-system-seed.js) computes **`peerSystemSeedMirror**` eligibility and builds snapshot mirrors with `**buildPeerSeedSnapshots**` (including `**mbr_layout**` from `**seedMbrLayout`**). When eligible, `index.js` writes **`bootMbr512**` into `**localRAM**` and serves mirrored `**bare_os.***` RPC responses through `**disk.os`** for cold joiners.
|
||||
Peer-assist helper path: [`lib/bare-os-peer-system-seed.js`](../../packages/bare-os-booter/lib/bare-os-peer-system-seed.js) computes **`peerSystemSeedMirror`** eligibility and builds snapshot mirrors with **`buildPeerSeedSnapshots`** (including **`mbr_layout`** from **`seedMbrLayout`**). When eligible, `index.js` writes **`bootMbr512`** into **`localRAM`** and serves mirrored **`bare_os.*`** RPC responses through **`disk.os`** for cold joiners.
|
||||
|
||||
**`main()`**
|
||||
|
||||
@@ -96,11 +96,11 @@ Peer-assist helper path: [`lib/bare-os-peer-system-seed.js`](../../packages/bare
|
||||
|
||||
**`SwarmDisk` class**
|
||||
|
||||
**State:** `localRAM`, `peers` (Set of `{ chan, mux, socket, id }`), `pendingReads`, `pendingSearches`, `pendingRpc`, counters, `drive`, `personalDrive`, `os`, **`seedCapabilityInfo**` (last `**bare_os.capabilities**` handshake or error object), `**mbrKeysHex**` (MBR-derived key list), `**bootMbr512**` (boot-time 512-byte copy), `**seedMbrLayout`** (optional `bare_os.mbr_layout` snapshot), and **`peerSystemSeedActive`** (helper mirroring active).
|
||||
**State:** `localRAM`, `peers` (Set of `{ chan, mux, socket, id }`), `pendingReads`, `pendingSearches`, `pendingRpc`, counters, `drive`, `personalDrive`, `os`, **`seedCapabilityInfo`** (last **`bare_os.capabilities`** handshake or error object), **`mbrKeysHex`** (MBR-derived key list), **`bootMbr512`** (boot-time 512-byte copy), **`seedMbrLayout`** (optional `bare_os.mbr_layout` snapshot), and **`peerSystemSeedActive`** (helper mirroring active).
|
||||
|
||||
**`initPersonalDrive(store, swarm, Hyperdrive)`**
|
||||
|
||||
- `store.namespace('bare-os-personal-v1')`, new `Hyperdrive(localStore)`, ensure writable, structured host log (see **`emitSwarmDiskHostLog**` — stderr JSON when `**BARE_OS_BOOT_TRACE=json|ndjson`**, else stderr / `console.warn`), `swarm.join(personalDrive.discoveryKey)`.
|
||||
- `store.namespace('bare-os-personal-v1')`, new `Hyperdrive(localStore)`, ensure writable, structured host log (see **`emitSwarmDiskHostLog`** — stderr JSON when **`BARE_OS_BOOT_TRACE=json|ndjson`**, else stderr / `console.warn`), `swarm.join(personalDrive.discoveryKey)`.
|
||||
|
||||
**`addPeer(mux, socket)`**
|
||||
|
||||
@@ -119,7 +119,7 @@ Peer-assist helper path: [`lib/bare-os-peer-system-seed.js`](../../packages/bare
|
||||
|
||||
**`rpc(module, method, args?, timeoutMs?)`**
|
||||
|
||||
- Sends message **5** to the **first** peer in **`peers**`; awaits message **6**; parses `**result**` as JSON when possible. Used for the pre-boot `**bare_os.capabilities`** handshake and operator tooling.
|
||||
- Sends message **5** to the **first** peer in **`peers`**; awaits message **6**; parses **`result`** as JSON when possible. Used for the pre-boot **`bare_os.capabilities`** handshake and operator tooling.
|
||||
|
||||
### 12.5 [packages/bare-os-booter/lib/kernel-runner.js](../../packages/bare-os-booter/lib/kernel-runner.js)
|
||||
|
||||
@@ -131,49 +131,49 @@ Peer-assist helper path: [`lib/bare-os-peer-system-seed.js`](../../packages/bare
|
||||
|
||||
**`runBinCommand(ctx, argv)`**
|
||||
|
||||
- **Host delegates first** — [`host-delegate-registry.js`](../../packages/bare-os-booter/lib/host-delegate-registry.js) registers **`git**`, `**curl**`, `**wget**`, `**openssl**`, `**ssh-keygen**`, `**tar**`, `**systemctl**` / `**bare-initctl**` / `**journalctl**`, `**warc**`, `**archive**` (ustar front-end), `**hrpc**`, `**bundlebee**`, `**sidecar**`, and `**pear-runtime-matrix`** via [`host-bridge-cli.js`](../../packages/bare-os-booter/lib/host-bridge-cli.js), with **static** imports (Pear-safe). Each delegate checks **`BARE_OS_DELEGATE_ALLOW**`; denied kinds exit **126**. `**curl**` and `**wget**` are Fetch-based subsets (not libcurl / full GNU wget); `**/bin/curl**` and `**/bin/wget**` on the image call `**ctx.bareOsRunCurlCli**` / `**ctx.bareOsRunWgetCli**` when present—see [HTTP: curl and wget](http-curl-and-wget.md). `**/bin/systemctl**` and `**/bin/journalctl**` call `**ctx.bareOsRunSystemctlCli**` when present (same backend as the host delegate). **Host bridge CLIs:** `**hrpc probe**` prints `**bareOsHrpcAllowlistProbe()**` (optional `**BARE_OS_HRPC_ALLOWLIST_JSON**`); `**hrpc request**` always calls `**ctx.bareOsHrpcRequest`** (stock handler supports validated built-in routes such as `kernel.ping`, `kernel.capabilities`, `vfs.readText`; host overrides remain supported and `BARE_OS_HRPC_BRIDGE_WIRED=1` still advertises host bridge capability). **`bundlebee hint**` emits `**bare-os:bundlebee-cli**`; `**bundlebee status**` prints `**BARE_OS_BUNDLEBEE_STAGE_JSON**`. `**sidecar cap <class>**` calls `**bareOsSidecarResourceCap**`. `**pear-runtime-matrix**` prints `**bareOsPearRuntimeMatrixProbe()**` (optional `**BARE_OS_PEAR_RUNTIME_MATRIX_JSON**`). `**BARE_OS_SIDECAR_BRIDGE_WIRED**` / `**BARE_OS_BUNDLEBEE_CLI_WIRED**` are advertised via `**bareOsHostCapability`** for operator probes.
|
||||
- If **`argv[0]**` is `**git`** (or a POSIX path whose basename is `git`, but not `./git` or `../git`), **delegates** to **`runGitCli`** in [`git-cli.js`](../../packages/bare-os-booter/lib/git-cli.js).
|
||||
- If **`argv[0]**` is `**curl**` under the same basename rules, **delegates** to `**runCurlCli`** in [`curl-cli.js`](../../packages/bare-os-booter/lib/curl-cli.js).
|
||||
- If **`argv[0]**` is `**wget**` under the same basename rules, **delegates** to `**runWgetCli`** in [`wget-cli.js`](../../packages/bare-os-booter/lib/wget-cli.js).
|
||||
- **Host delegates first** — [`host-delegate-registry.js`](../../packages/bare-os-booter/lib/host-delegate-registry.js) registers **`git`**, **`curl`**, **`wget`**, **`openssl`**, **`ssh-keygen`**, **`tar`**, **`systemctl`** / **`bare-initctl`** / **`journalctl`**, **`warc`**, **`archive`** (ustar front-end), **`hrpc`**, **`bundlebee`**, **`sidecar`**, and **`pear-runtime-matrix`** via [`host-bridge-cli.js`](../../packages/bare-os-booter/lib/host-bridge-cli.js), with **static** imports (Pear-safe). Each delegate checks **`BARE_OS_DELEGATE_ALLOW`**; denied kinds exit **126**. **`curl`** and **`wget`** are Fetch-based subsets (not libcurl / full GNU wget); **`/bin/curl`** and **`/bin/wget`** on the image call **`ctx.bareOsRunCurlCli`** / **`ctx.bareOsRunWgetCli`** when present—see [HTTP: curl and wget](http-curl-and-wget.md). **`/bin/systemctl`** and **`/bin/journalctl`** call **`ctx.bareOsRunSystemctlCli`** when present (same backend as the host delegate). **Host bridge CLIs:** `**hrpc probe**` prints `**bareOsHrpcAllowlistProbe()**` (optional **`BARE_OS_HRPC_ALLOWLIST_JSON`**); `**hrpc request**` always calls **`ctx.bareOsHrpcRequest`** (stock handler supports validated built-in routes such as `kernel.ping`, `kernel.capabilities`, `vfs.readText`; host overrides remain supported and `BARE_OS_HRPC_BRIDGE_WIRED=1` still advertises host bridge capability). **`bundlebee hint**` emits **`bare-os:bundlebee-cli`**; `**bundlebee status**` prints **`BARE_OS_BUNDLEBEE_STAGE_JSON`**. `**sidecar cap <class>**` calls **`bareOsSidecarResourceCap`**. **`pear-runtime-matrix`** prints `**bareOsPearRuntimeMatrixProbe()**` (optional **`BARE_OS_PEAR_RUNTIME_MATRIX_JSON`**). **`BARE_OS_SIDECAR_BRIDGE_WIRED`** / **`BARE_OS_BUNDLEBEE_CLI_WIRED`** are advertised via **`bareOsHostCapability`** for operator probes.
|
||||
- If **`argv[0]**` is **`git`** (or a POSIX path whose basename is `git`, but not `./git` or `../git`), **delegates** to **`runGitCli`** in [`git-cli.js`](../../packages/bare-os-booter/lib/git-cli.js).
|
||||
- If **`argv[0]**` is **`curl`** under the same basename rules, **delegates** to **`runCurlCli`** in [`curl-cli.js`](../../packages/bare-os-booter/lib/curl-cli.js).
|
||||
- If **`argv[0]**` is **`wget`** under the same basename rules, **delegates** to **`runWgetCli`** in [`wget-cli.js`](../../packages/bare-os-booter/lib/wget-cli.js).
|
||||
- If `argv[0]` contains `/`, resolves with `ctx.vfs.resolveLogical`, `route`, loads script bytes from the routed Hyperdrive (`get` with `follow`).
|
||||
- Else walks `$PATH` (`ctx.vfs.env.PATH`, default `/bin`), joining each directory with `unix-path-resolve(dir, cmd)` (not three-argument resolve), loads from **system** `ctx.drive` only.
|
||||
- Builds `AsyncFunction('ctx','argv', ...)` with the script source plus `if (typeof run === 'function') await run(ctx, argv)` (top-level statements run first; optional `run` matches `/bin` utilities).
|
||||
- Unknown command: `ctx.console.log('unknown command: ...')`.
|
||||
|
||||
**`resolveBinInPath(ctx, name)**` — returns the first `**PATH`** hit on the system drive (absolute `/bin/...` path string) or **`null**`; used by shell `**command -v**` / `**type`**.
|
||||
**`resolveBinInPath(ctx, name)**` — returns the first **`PATH`** hit on the system drive (absolute `/bin/...` path string) or **`null`**; used by shell `**command -v**` / **`type`**.
|
||||
|
||||
### 12.6 [packages/bare-os-booter/lib/vfs.js](../../packages/bare-os-booter/lib/vfs.js)
|
||||
|
||||
**`createVfs(systemDrive, personalDrive, env, mntRef?, vfsOptions?)`**
|
||||
|
||||
- **Logical paths** under `$HOME` (booter default `/home/guest`; after `login`, `/home/<pubkey-prefix>`) map to the **personal** Hyperdrive under `/.bare-os/home/<basename>/…`; **`/var/log**` and `**/tmp**` map to `**/.bare-os/var/log/…**` and `**/.bare-os/tmp/…**` with the same basename. Read-only synthetic `**/proc**` and `**/sys**` (optional `**vfsOptions**` for version/cmdline, quotas JSON, net/disk stubs, `**/run/bare-os/***` text providers, mount map, union policy, seed handshake, virtual registry, etc.). Optional union read overlays via env `**BARE_OS_VFS_UNION_PREFIXES**`; optional `**BARE_OS_VFS_UNION_WRITE_DENY`** blocks writes under those prefixes. All other absolute paths use the **system** drive (read-mostly OS image).
|
||||
- **Logical paths** under `$HOME` (booter default `/home/guest`; after `login`, `/home/<pubkey-prefix>`) map to the **personal** Hyperdrive under `/.bare-os/home/<basename>/…`; **`/var/log`** and **`/tmp`** map to `**/.bare-os/var/log/…**` and `**/.bare-os/tmp/…**` with the same basename. Read-only synthetic **`/proc`** and **`/sys`** (optional **`vfsOptions`** for version/cmdline, quotas JSON, net/disk stubs, **`/run/bare-os/*`** text providers, mount map, union policy, seed handshake, virtual registry, etc.). Optional union read overlays via env **`BARE_OS_VFS_UNION_PREFIXES`**; optional **`BARE_OS_VFS_UNION_WRITE_DENY`** blocks writes under those prefixes. All other absolute paths use the **system** drive (read-mostly OS image).
|
||||
- **`resolveLogical(p)`** — `unix-path-resolve(cwd, p)` so cwd + relative segments work (the `unix-path-resolve` package only accepts two path arguments).
|
||||
- **API**: `getcwd`, `chdir` (rejects regular files), `readFile`, `writeFile` / `unlink` (personal only), `exists`, `readdir`, `stat` / `lstat`, `readlink`, `symlink`, `chmod`, `mkdir` (recursive via `.bareos_empty` marker), `rmdir` (empty dirs; marker-aware), `rm` (recursive tree walk), `route`, `resolveLogical`, `env`, **`watch(logicalPath)**` (Hyperdrive-backed paths only; throws on pseudo `**/proc**`/`**/sys**`/`**/run**`/`**/dev**` and on virtual `**$HOME**`, `**/var**`, `**/mnt`** roots).
|
||||
- **API**: `getcwd`, `chdir` (rejects regular files), `readFile`, `writeFile` / `unlink` (personal only), `exists`, `readdir`, `stat` / `lstat`, `readlink`, `symlink`, `chmod`, `mkdir` (recursive via `.bareos_empty` marker), `rmdir` (empty dirs; marker-aware), `rm` (recursive tree walk), `route`, `resolveLogical`, `env`, **`watch(logicalPath)**` (Hyperdrive-backed paths only; throws on pseudo **`/proc`**/**`/sys`**/**`/run`**/**`/dev`** and on virtual **`$HOME`**, **`/var`**, **`/mnt`** roots).
|
||||
- **Hyperdrive quirk**: `entry` / `get` / `exists` use `std(path, false)` and **throw** on path `'/'` (`Invalid filename: /`). The VFS special-cases drive path `'/'` (logical `/` and personal `$HOME` root) for `chdir`, `stat`, `exists`, `isRegularFile`, and blocks `readFile`/`put`/`del` on that key.
|
||||
- **Bare / Pear**: do not rely on global `TextEncoder` / `TextDecoder` in booter `lib/*.js`; this tree uses **`b4a`** for UTF-8 where needed (pseudo `/proc` content, symlink size in `vfs-posix-meta.js`, `systemctl` log tailing, etc.).
|
||||
|
||||
### 12.7 [packages/bare-os-booter/lib/shell.js](../../packages/bare-os-booter/lib/shell.js)
|
||||
|
||||
- **`defaultShellAliases`** — includes `ll`, `la`, `l`, `..`, `...` as the baseline merged from **`~/.barerc`**.
|
||||
- **`tokenize` / `expandWord` / `parsePipeline`** — POSIX-ish words, `'...'`, `"..."`, `\`, `|`, `||`, `&&`, `;`, `>`, `>>`, `<`; `$VAR` and `${VAR}`; pipelines split on `|`; **`;**` splits lists; `**&&**` / `**||**` short-circuit using `**ctx.exitCode`** (left-associative).
|
||||
- **`execShellLine(ctx, line)`** — semicolon-separated lists, then per segment AND-OR chains of pipelines; leading `NAME=value` assignments (blocked for `ctx.shellReadonlyVars`), redirections, builtins `alias`, **`barerc`** (`barerc reload` re-parses `~/.barerc` and reapplies theme), `unalias`, `cd`, `export`, `unset`, `readonly`, `umask`, `:`, `command`, `type`, `login`, `logout`, `exit`, **`jobs**`, `**fg**`, `**wait`**, else `runBinCommand`. Optional **`BARE_OS_SHELL_CMDSUBST**` enables bounded `**$(…)**`; optional `**BARE_OS_SHELL_STREAMING**` / `**BARE_OS_SHELL_STREAMING_MULT**` relax pipeline capture caps. Trailing `**&`** at list depth runs prior segments in the **background** (async jobs table). `command -v`/`-V` and `type` use **`resolveBinInPath`**. `login`/`logout` call the same `ctx.applyRegister` / `ctx.applyUnlock` / `ctx.applyLogout` hooks as `/bin/login` and `/bin/logout`. Captures `console.log` for pipes and file redirection; `>` / `>>` target paths via `ctx.vfs.writeFile` (personal tree). Returns `'exit'` when the `exit` builtin runs. After each completed line (except empty input), **`syncBareOsExitStatusEnv**` writes `**ctx.exitCode**` to `**vfs.env.BARE_OS_EXIT_STATUS**`; `**expandWord**` maps `**$?**` / `**${?}`** to that value.
|
||||
- **`listBareOsShellBuiltins(env)**` — stable list of builtin names for highlighting and completion parity (includes optional `**read**` when `**BARE_OS_SHELL_READ_BUILTIN`** is set).
|
||||
- **`tokenize` / `expandWord` / `parsePipeline`** — POSIX-ish words, `'...'`, `"..."`, `\`, `|`, `||`, `&&`, `;`, `>`, `>>`, `<`; `$VAR` and `${VAR}`; pipelines split on `|`; **`;**` splits lists; `**&&**` / **`||`** short-circuit using **`ctx.exitCode`** (left-associative).
|
||||
- **`execShellLine(ctx, line)`** — semicolon-separated lists, then per segment AND-OR chains of pipelines; leading `NAME=value` assignments (blocked for `ctx.shellReadonlyVars`), redirections, builtins `alias`, **`barerc`** (`barerc reload` re-parses `~/.barerc` and reapplies theme), `unalias`, `cd`, `export`, `unset`, `readonly`, `umask`, `:`, `command`, `type`, `login`, `logout`, `exit`, **`jobs`**, **`fg`**, **`wait`**, else `runBinCommand`. Optional **`BARE_OS_SHELL_CMDSUBST`** enables bounded `**$(…)**`; optional **`BARE_OS_SHELL_STREAMING`** / **`BARE_OS_SHELL_STREAMING_MULT`** relax pipeline capture caps. Trailing `**&`** at list depth runs prior segments in the **background** (async jobs table). `command -v`/`-V` and `type` use **`resolveBinInPath`**. `login`/`logout` call the same `ctx.applyRegister` / `ctx.applyUnlock` / `ctx.applyLogout` hooks as `/bin/login` and `/bin/logout`. Captures `console.log` for pipes and file redirection; `>` / `>>` target paths via `ctx.vfs.writeFile` (personal tree). Returns `'exit'` when the `exit` builtin runs. After each completed line (except empty input), **`syncBareOsExitStatusEnv`** writes **`ctx.exitCode`** to **`vfs.env.BARE_OS_EXIT_STATUS`**; **`expandWord`** maps **`$?`** / `**${?}`** to that value.
|
||||
- **`listBareOsShellBuiltins(env)**` — stable list of builtin names for highlighting and completion parity (includes optional **`read`** when **`BARE_OS_SHELL_READ_BUILTIN`** is set).
|
||||
|
||||
### 12.7a REPL line editor and completion
|
||||
|
||||
Narrative reference: **[Shell completion and REPL editor](shell-completion-and-repl-editor.md)**.
|
||||
|
||||
- **[`lib/repl-session.js`](../../packages/bare-os-booter/lib/repl-session.js)** — **`createKernelReplSession**`: chooses Fish-style `**createFishReadLine**` when `**BARE_OS_FISH` ≠ `0**`, TTY raw mode works, and `**BARE_OS_SKIP_REPL**` is off; wires `**ctx.console**` / `**ctx.readLine**` / `**writeScreen`** to the same stdout as the prompt.
|
||||
- **[`lib/repl-session.js`](../../packages/bare-os-booter/lib/repl-session.js)** — **`createKernelReplSession`**: chooses Fish-style **`createFishReadLine`** when `**BARE_OS_FISH` ≠ `0**`, TTY raw mode works, and **`BARE_OS_SKIP_REPL`** is off; wires **`ctx.console`** / **`ctx.readLine`** / **`writeScreen`** to the same stdout as the prompt.
|
||||
- **[`lib/fish-readline.js`](../../packages/bare-os-booter/lib/fish-readline.js)** — History file on the personal drive, ghost suggestions, reverse search, **Tab** menu or inline cycling (**`BARE_OS_COMPACT_MENU`** / narrow columns), **Ctrl+Space** man preview, **save/restore cursor** + erase-to-EOS so menu redraws do not stack stale lines.
|
||||
- **[`lib/completion-engine.js`](../../packages/bare-os-booter/lib/completion-engine.js)** — **`parseCompletionContext**`, `**gatherCompletionItems**`, `**completeLine**`, `**rankCompletionItems**`, `**suggestGhostFromHistory**`, VFS timeouts, `**/share/man/man.json**` cache, `**ctx.bareOsRegisterCompleter`** registry.
|
||||
- **[`lib/completion-engine.js`](../../packages/bare-os-booter/lib/completion-engine.js)** — **`parseCompletionContext`**, **`gatherCompletionItems`**, **`completeLine`**, **`rankCompletionItems`**, **`suggestGhostFromHistory`**, VFS timeouts, **`/share/man/man.json`** cache, **`ctx.bareOsRegisterCompleter`** registry.
|
||||
|
||||
### 12.8 [packages/bare-os-booter/lib/identity-account.js](../../packages/bare-os-booter/lib/identity-account.js)
|
||||
|
||||
- On-disk **`/.bare/account` (v2)**: magic `BAREOS01`, version `2`, 32-byte Ed25519 public key (bare-crypto), 16-byte PBKDF2 salt, 4-byte iteration count (big-endian), ChaCha20-Poly1305 seal of the 64-byte Ed25519 private key material (nonce + ciphertext + tag). Passphrase stretching: **PBKDF2-SHA256** (`210000` iterations by default). **v1** (libsodium) files are rejected with a message to run `login --new`.
|
||||
- **`encodeAccount` / `decodeAccount` / `encodeNewAccount**`, `**sealBytes` / `openBytes**`, `**vaultKeyFromSecret**`, `**hashUtf8Path`** — shared by `identity-session.js` (vault snapshots use the same AEAD).
|
||||
- **`encodeAccount` / `decodeAccount` / `encodeNewAccount**`, `**sealBytes` / `openBytes**`, **`vaultKeyFromSecret`**, **`hashUtf8Path`** — shared by `identity-session.js` (vault snapshots use the same AEAD).
|
||||
|
||||
### 12.9 [packages/bare-os-booter/lib/identity-session.js](../../packages/bare-os-booter/lib/identity-session.js)
|
||||
|
||||
- **`applyGuestEnv` / `applyUnlockedEnv`** — set `ctx.vfs.env` (`BARE_OS_PUBLIC_KEY`, `BARE_OS_IDENTITY`, `USER`, `HOME`, derived `UID`/`GID` from pubkey hash for logged-in users) and `vfs.chdir` to the new home. **`applyUnlockedEnv**` calls `**loadBarerc**` after unlock (`**createSkeletonIfMissing: true**` on first login) so `**~/.barerc**` applies without restarting the session. Both paths call `**bareOsResetShellIdentityState**` (clear simulated `**shellBackgroundJobs**`), `**syncVfsIdentitySession**` (`**vfs.bareOsIdentitySession**`, warm-cache invalidation, `**ctx.bareOsInvalidateWarmReadCaches('identity-switch')**` when present), optional `**ctx.bareOsReloadFishHistoryForIdentity**` (fish readline), optional `**scrubGuestWorkspaces**` when `**BARE_OS_GUEST_SCRUB=1`**.
|
||||
- **`migrateLegacyPersonalHomeIfNeeded**` — lifts legacy flat `**/**` personal-drive entries into the active `**/.bare-os/home/<segment>/…**` once per segment; records `**/.bare-os/migration/legacy-root-v1.json**`. **Guest** skips when `**/.bare/account**` exists unless `**BARE_OS_PERSONAL_ROOT_MIGRATE=guest**`. `**BARE_OS_PERSONAL_ROOT_MIGRATE=skip**` disables all lifts; `**unlocked-only`** skips guest lifts.
|
||||
- **`registerIdentity` / `unlockIdentity` / `logoutIdentity` / `saveVaultToDrive`** — personal Hyperdrive persistence and encrypted vault index under `/.bare/vault/`. **`saveVaultToDrive**` skips other `**bare-os/acct/…**` subtrees when `**BARE_OS_PERSONAL_ACCT_PREFIX`** is on so vault export does not bundle sibling accounts.
|
||||
- **`applyGuestEnv` / `applyUnlockedEnv`** — set `ctx.vfs.env` (`BARE_OS_PUBLIC_KEY`, `BARE_OS_IDENTITY`, `USER`, `HOME`, derived `UID`/`GID` from pubkey hash for logged-in users) and `vfs.chdir` to the new home. **`applyUnlockedEnv`** calls **`loadBarerc`** after unlock (`**createSkeletonIfMissing: true**` on first login) so **`~/.barerc`** applies without restarting the session. Both paths call **`bareOsResetShellIdentityState`** (clear simulated **`shellBackgroundJobs`**), **`syncVfsIdentitySession`** (**`vfs.bareOsIdentitySession`**, warm-cache invalidation, `**ctx.bareOsInvalidateWarmReadCaches('identity-switch')**` when present), optional **`ctx.bareOsReloadFishHistoryForIdentity`** (fish readline), optional **`scrubGuestWorkspaces`** when **`BARE_OS_GUEST_SCRUB=1`**.
|
||||
- **`migrateLegacyPersonalHomeIfNeeded`** — lifts legacy flat **`/`** personal-drive entries into the active `**/.bare-os/home/<segment>/…**` once per segment; records **`/.bare-os/migration/legacy-root-v1.json`**. **Guest** skips when **`/.bare/account`** exists unless **`BARE_OS_PERSONAL_ROOT_MIGRATE=guest`**. **`BARE_OS_PERSONAL_ROOT_MIGRATE=skip`** disables all lifts; **`unlocked-only`** skips guest lifts.
|
||||
- **`registerIdentity` / `unlockIdentity` / `logoutIdentity` / `saveVaultToDrive`** — personal Hyperdrive persistence and encrypted vault index under `/.bare/vault/`. **`saveVaultToDrive`** skips other `**bare-os/acct/…**` subtrees when **`BARE_OS_PERSONAL_ACCT_PREFIX`** is on so vault export does not bundle sibling accounts.
|
||||
|
||||
@@ -4,11 +4,11 @@ Former **DOCUMENTATION.md** §§12.10–12.12. [Reference index →](README.md)
|
||||
|
||||
### 12.10 Package `bare-os-coreutils`
|
||||
|
||||
- **[packages/bare-os-coreutils/lib/commands.mjs](../../packages/bare-os-coreutils/lib/commands.mjs)** — **`COREUTILS_COMMANDS`**: authoritative sorted `/bin` names for **`build.mjs**` and the manual database builder (keeps the image and `**man`** coverage in sync).
|
||||
- **[packages/bare-os-coreutils/build.mjs](../../packages/bare-os-coreutils/build.mjs)** — `export async function build()`: runs **`scripts/build-man-db.mjs**` (validates `**man/pages/*.json**`, writes `**kernel/share/man/man.json**` and the same path under `**packages/bare-os-seeder/kernel/share/man/`**); then for each command concatenates `lib/runtime.js`, optional **`preamble**` libs (`**md5sum**` → `**lib/md5.js**`, `**sed**` → `**lib/sed-engine.js**`, `**awk**` → `**lib/awk-engine.js**`, `**jq**` → `**lib/jq-engine.js**`, `**man**` → `**lib/man-render.js**`, `**ls**` / `**dircolors**` → lscolors helpers, `**edit**` / `**nano**` → `**lib/edit-*.js**` + shared TUI), then `**src/<name>.js**` (`**nano**` reuses `**src/edit.js**`); writes to `**kernel/bin/<name>**` and `**packages/bare-os-seeder/kernel/bin/<name>**`. CLI: `**node build.mjs`** when executed as main.
|
||||
- **Manual pages** — Authoring: **`packages/bare-os-coreutils/man/pages/<name>.json**`; schema: `**man/schema.json**`. Optional `**examples**` (cheat.sh-style) and `**descriptionMode**`: `**preserve**` for preformatted text. `**scripts/ingest-handbook-for-man.mjs**` merges every `**handbook/*.md**` as `**man(7)**` at build time (`**man handbook**`, `**man handbook-01-introduction**`, …). Regenerate JSON stubs with `**node packages/bare-os-coreutils/scripts/seed-man-pages.mjs**`. Runtime: `**/bin/man**` reads `**/share/man/man.json`**. **Handbook:** [handbook/10-manpages-and-online-help.md](../../handbook/10-manpages-and-online-help.md).
|
||||
- **POSIX utility index (optional image file)** — **`kernel/etc/bare-os/posix_utilities.json**` carries machine-readable per-command notes when staged; the booter echoes `**utilitiesIndexPath**` in `**/proc/bare_os_features**` and coalesced `**metrics_live`** (see handbook ch.9).
|
||||
- **Commands** — The authoritative sorted list is **`COREUTILS_COMMANDS`** in [`commands.mjs`](../../packages/bare-os-coreutils/lib/commands.mjs) (count and names change with releases; **do not** paste the full inventory into prose here). Each Tier-1 name has **`src/<name>.js**` (or a mapped source such as `**nano**` → `**src/edit.js**`) and a matching `**man/pages/<name>.json**`. Notable **large preambles** (see `**preamble**` in `**build.mjs**`): `**edit**` / `**nano**` (shared TUI stack), `**baretop**` / `**btop**`, `**agent**` (OpenAI-compatible assistant + `**web_fetch**` and related `**lib/agent-*.js**`), `**chat**` (swarm chat TUI + `**lib/chat-tui.js**`), `**md5sum**`, `**sed**`, `**awk**`, `**jq**`, `**man**`, `**ls**` / `**dircolors**`. `**agent**` uses `**ctx.httpFetch**` like delegated `**curl**` / `**wget**` ([HTTP: curl and wget](http-curl-and-wget.md)). The interactive TTY editor is `**edit**`; `**nano**` is the same built script under `**/bin/nano**`, and the default shell maps `**nano` → `edit**` (see `**defaultShellAliases`** in [`shell.js`](../../packages/bare-os-booter/lib/shell.js)). Each built script begins with **`BARE_OS_BIN_API**` in the concatenated prelude; root `**pretest`** runs **[`scripts/verify-kernel-seeder-parity.mjs`](../../scripts/verify-kernel-seeder-parity.mjs)** to keep **`kernel/bin/***` and `**packages/bare-os-seeder/kernel/bin/***` in sync and to require that pragma on every staged binary. Scripts are plain `**async function run(ctx, argv)**` using `**ctx.vfs**`, `**ctx.drive**`, `**ctx.b4a**`, `**ctx.console**`, optional `**bareStdin(ctx)**`, optional `**ctx.runBinCommand**` — no ESM `**import**` in `**src/**` (Bare-safe `**AsyncFunction**` load). `**dir**` / `**vdir**` delegate to `**ls -C**` / `**ls -l**`. **Booter-delegated** (stubs under `**kernel/bin/**`, logic in `**packages/bare-os-booter/lib/**`): `**systemctl**`, `**journalctl**` (bare-initd control; `**bare-initctl`** alias; see [handbook/04-the-booter-runtime.md](../../handbook/04-the-booter-runtime.md)). **Narrative reference:** [handbook/09-posix-utilities-shell-and-vfs.md](../../handbook/09-posix-utilities-shell-and-vfs.md). Package overview: [bare-os-coreutils README](../../packages/bare-os-coreutils/README.md).
|
||||
- **[packages/bare-os-coreutils/lib/commands.mjs](../../packages/bare-os-coreutils/lib/commands.mjs)** — **`COREUTILS_COMMANDS`**: authoritative sorted `/bin` names for **`build.mjs`** and the manual database builder (keeps the image and **`man`** coverage in sync).
|
||||
- **[packages/bare-os-coreutils/build.mjs](../../packages/bare-os-coreutils/build.mjs)** — `export async function build()`: runs **`scripts/build-man-db.mjs`** (validates **`man/pages/*.json`**, writes **`kernel/share/man/man.json`** and the same path under **`packages/bare-os-seeder/kernel/share/man/`**); then for each command concatenates `lib/runtime.js`, optional **`preamble`** libs (**`md5sum`** → **`lib/md5.js`**, **`sed`** → **`lib/sed-engine.js`**, **`awk`** → **`lib/awk-engine.js`**, **`jq`** → **`lib/jq-engine.js`**, **`man`** → **`lib/man-render.js`**, **`ls`** / **`dircolors`** → lscolors helpers, **`edit`** / **`nano`** → **`lib/edit-*.js`** + shared TUI), then **`src/<name>.js`** (**`nano`** reuses **`src/edit.js`**); writes to **`kernel/bin/<name>`** and **`packages/bare-os-seeder/kernel/bin/<name>`**. CLI: `**node build.mjs`** when executed as main.
|
||||
- **Manual pages** — Authoring: **`packages/bare-os-coreutils/man/pages/<name>.json`**; schema: **`man/schema.json`**. Optional **`examples`** (cheat.sh-style) and **`descriptionMode`**: **`preserve`** for preformatted text. **`scripts/ingest-handbook-for-man.mjs`** merges every **`handbook/*.md`** as `**man(7)**` at build time (`**man handbook**`, `**man handbook-01-introduction**`, …). Regenerate JSON stubs with `**node packages/bare-os-coreutils/scripts/seed-man-pages.mjs**`. Runtime: **`/bin/man`** reads **`/share/man/man.json`**. **Handbook:** [handbook/10-manpages-and-online-help.md](../../handbook/10-manpages-and-online-help.md).
|
||||
- **POSIX utility index (optional image file)** — **`kernel/etc/bare-os/posix_utilities.json`** carries machine-readable per-command notes when staged; the booter echoes **`utilitiesIndexPath`** in **`/proc/bare_os_features`** and coalesced **`metrics_live`** (see handbook ch.9).
|
||||
- **Commands** — The authoritative sorted list is **`COREUTILS_COMMANDS`** in [`commands.mjs`](../../packages/bare-os-coreutils/lib/commands.mjs) (count and names change with releases; **do not** paste the full inventory into prose here). Each Tier-1 name has **`src/<name>.js`** (or a mapped source such as **`nano`** → **`src/edit.js`**) and a matching **`man/pages/<name>.json`**. Notable **large preambles** (see **`preamble`** in **`build.mjs`**): **`edit`** / **`nano`** (shared TUI stack), **`baretop`** / **`btop`**, **`agent`** (OpenAI-compatible assistant + **`web_fetch`** and related **`lib/agent-*.js`**), **`chat`** (swarm chat TUI + **`lib/chat-tui.js`**), **`md5sum`**, **`sed`**, **`awk`**, **`jq`**, **`man`**, **`ls`** / **`dircolors`**. **`agent`** uses **`ctx.httpFetch`** like delegated **`curl`** / **`wget`** ([HTTP: curl and wget](http-curl-and-wget.md)). The interactive TTY editor is **`edit`**; **`nano`** is the same built script under **`/bin/nano`**, and the default shell maps `**nano` → `edit**` (see **`defaultShellAliases`** in [`shell.js`](../../packages/bare-os-booter/lib/shell.js)). Each built script begins with **`BARE_OS_BIN_API`** in the concatenated prelude; root **`pretest`** runs **[`scripts/verify-kernel-seeder-parity.mjs`](../../scripts/verify-kernel-seeder-parity.mjs)** to keep **`kernel/bin/*`** and **`packages/bare-os-seeder/kernel/bin/*`** in sync and to require that pragma on every staged binary. Scripts are plain `**async function run(ctx, argv)**` using **`ctx.vfs`**, **`ctx.drive`**, **`ctx.b4a`**, **`ctx.console`**, optional `**bareStdin(ctx)**`, optional **`ctx.runBinCommand`** — no ESM **`import`** in **`src/`** (Bare-safe **`AsyncFunction`** load). **`dir`** / **`vdir`** delegate to `**ls -C**` / `**ls -l**`. **Booter-delegated** (stubs under **`kernel/bin/`**, logic in **`packages/bare-os-booter/lib/`**): **`systemctl`**, **`journalctl`** (bare-initd control; **`bare-initctl`** alias; see [handbook/04-the-booter-runtime.md](../../handbook/04-the-booter-runtime.md)). **Narrative reference:** [handbook/09-posix-utilities-shell-and-vfs.md](../../handbook/09-posix-utilities-shell-and-vfs.md). Package overview: [bare-os-coreutils README](../../packages/bare-os-coreutils/README.md).
|
||||
|
||||
### 12.11 [packages/bare-os-booter/test.js](../../packages/bare-os-booter/test.js) and [test.identity.js](../../packages/bare-os-booter/test.identity.js)
|
||||
|
||||
|
||||
@@ -4,14 +4,14 @@ 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.15**`), `**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.15`**), **`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`
|
||||
|
||||
### 10.1 [packages/bare-os-protocol/package.json](../../packages/bare-os-protocol/package.json)
|
||||
|
||||
- `name` — `bare-os-protocol`
|
||||
- `version` — `0.9.0` (wire v2: **`kernelCapabilityWords**`; couple boot policy `**requireProtocolPackageMin`** to this semver)
|
||||
- `version` — `0.9.0` (wire v2: **`kernelCapabilityWords`**; couple boot policy **`requireProtocolPackageMin`** to this semver)
|
||||
- `main` / `exports["."]` — `./index.js`
|
||||
- `exports["./constants.js"]` — `./constants.js` (for `bare-os-protocol/constants.js` imports)
|
||||
- `exports["./messages"]` — `./lib/messages.js`
|
||||
@@ -30,9 +30,9 @@ Re-exports from `./lib/channel.js`: `setupSeedChannel`, and from `./lib/chat-cha
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
When Capability word **6** (replication operator surface) is advertised, the stock booter also exposes **`ctx.bareOsReadReplicationOperatorJson()**` as a typed convenience reader over the same JSON as `**/proc/bare_os/replication`** (feature-bit alignment is documented in the capability index).
|
||||
When Capability word **6** (replication operator surface) is advertised, the stock booter also exposes **`ctx.bareOsReadReplicationOperatorJson()**` as a typed convenience reader over the same JSON as **`/proc/bare_os/replication`** (feature-bit alignment is documented in the capability index).
|
||||
|
||||
### 10.3 [packages/bare-os-protocol/constants.js](../../packages/bare-os-protocol/constants.js)
|
||||
|
||||
@@ -63,19 +63,19 @@ When Capability word **6** (replication operator surface) is advertised, the sto
|
||||
- **Message 0**: `uint32` read index → if `localRAM.get(index)`, send on message 1.
|
||||
- **Message 1**: `msgDataEncoding` (inbound only on client).
|
||||
- **Message 2**: `c.buffer` — after `chan.open()`, sends 250-byte bitfield with bit 0 set (capability gossip stub; see **`kernel-feature-bits.js`**).
|
||||
- **Message 3**: search request (`msgSearchReqEncoding`) → **message 4** returns paths from the staged manifest whose lowercase path contains the query (trimmed); empty query returns a capped prefix of all manifest paths. **`setupSeedChannel(..., { manifestPaths, searchMaxMatches })**` supplies the list (seeder collects paths during `**stageKernelTree`**).
|
||||
- **Message 3**: search request (`msgSearchReqEncoding`) → **message 4** returns paths from the staged manifest whose lowercase path contains the query (trimmed); empty query returns a capped prefix of all manifest paths. **`setupSeedChannel(..., { manifestPaths, searchMaxMatches })**` supplies the list (seeder collects paths during **`stageKernelTree`**).
|
||||
- **Message 4**: search response encoding.
|
||||
- **Message 5**: RPC request → **message 6** implements registered **`bare_os.***` methods (see `**lib/seed-rpc-methods.js**`); `**bare_os.capabilities**` returns `**bits**`–`**bits5**` plus `**protocolPackageVersion**`. Wrong module / missing module → `**bare_os.rpc_wrong_module**` / `**bare_os.rpc_missing_module**`; unknown method → `**bare_os.rpc_unknown_method**`. Internal fallthrough → `**bare_os.rpc_internal_unreachable`**.
|
||||
- **Message 5**: RPC request → **message 6** implements registered **`bare_os.*`** methods (see **`lib/seed-rpc-methods.js`**); **`bare_os.capabilities`** returns **`bits`**–**`bits5`** plus **`protocolPackageVersion`**. Wrong module / missing module → **`bare_os.rpc_wrong_module`** / **`bare_os.rpc_missing_module`**; unknown method → **`bare_os.rpc_unknown_method`**. Internal fallthrough → **`bare_os.rpc_internal_unreachable`**.
|
||||
- **Message 6**: RPC response encoding.
|
||||
- Calls `replicateDrive(mux.stream)` (typically `drive.replicate(stream)`).
|
||||
|
||||
Unless **`opts.enableBareOsChatChannel**` is `**false**` or `**BARE_OS_PROTOMUX_CHAT_CHANNEL**` opts out (`**0**` / `**false**` / `**off**` / `**no**`), `**setupSeedChannel**` pairs `**bare-os-chat-v1**` by default via `**setupBareOsChatChannel**` (see `**lib/chat-channel.js**` / `**lib/chat-messages.js**` / `**lib/chat-env.js**`) and adds optional `**chatChannel**` metadata to `**bare_os.capabilities`** JSON.
|
||||
Unless **`opts.enableBareOsChatChannel`** is **`false`** or **`BARE_OS_PROTOMUX_CHAT_CHANNEL`** opts out (**`0`** / **`false`** / **`off`** / **`no`**), **`setupSeedChannel`** pairs **`bare-os-chat-v1`** by default via **`setupBareOsChatChannel`** (see **`lib/chat-channel.js`** / **`lib/chat-messages.js`** / **`lib/chat-env.js`**) and adds optional **`chatChannel`** metadata to **`bare_os.capabilities`** JSON.
|
||||
|
||||
### 10.6 Chat channel [packages/bare-os-protocol/lib/chat-channel.js](../../packages/bare-os-protocol/lib/chat-channel.js)
|
||||
|
||||
**`setupBareOsChatChannel(mux, handlers)`**
|
||||
|
||||
- Creates the session with **`mux.createChannel({ protocol, unique: true })**`, adds six compact-encoded message types, and `**chan.open()`** (same pattern as the main seed channel; not a raw `pair` callback, which only receives the session id and would not open a session if misused). Wire: **hello**, **helloAck**, **join**, **leave**, **`event**`, `**control`**; no Hyperdrive replication on this channel.
|
||||
- Creates the session with **`mux.createChannel({ protocol, unique: true })**`, adds six compact-encoded message types, and `**chan.open()`** (same pattern as the main seed channel; not a raw `pair` callback, which only receives the session id and would not open a session if misused). Wire: **hello**, **helloAck**, **join**, **leave**, **`event`**, **`control`**; no Hyperdrive replication on this channel.
|
||||
|
||||
### 10.7 [packages/bare-os-protocol/test.js](../../packages/bare-os-protocol/test.js)
|
||||
|
||||
@@ -87,6 +87,6 @@ Brittle tests:
|
||||
4. `msgDataEncoding` encode/decode.
|
||||
5. `msgSearchReqEncoding` encode/decode.
|
||||
6. `TOPIC_STRING === 'bare-os-v1'`.
|
||||
7. Seed RPC method list length matches **`BARE_OS_SEED_RPC_METHODS**` / `**kernel_info`** surface.
|
||||
7. Seed RPC method list length matches **`BARE_OS_SEED_RPC_METHODS`** / **`kernel_info`** surface.
|
||||
8. **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_HOST_TRANSPORT_DELEGATES`** is non-zero.
|
||||
|
||||
|
||||
@@ -8,18 +8,18 @@ Former **DOCUMENTATION.md** §11. [Reference index →](README.md)
|
||||
|
||||
- `main` — `./index.js`
|
||||
- `scripts.start` / `dev` — `bare index.js` (Pear/Bare entry)
|
||||
- `dependencies` — `bare-os-protocol` (workspace `*`), **`bare-fs**`, `**bare-path`**, `b4a`, `compact-encoding`, `corestore`, `hyperdrive`, `hyperswarm`, `protomux`, `safety-catch`
|
||||
- `dependencies` — `bare-os-protocol` (workspace `*`), **`bare-fs`**, **`bare-path`**, `b4a`, `compact-encoding`, `corestore`, `hyperdrive`, `hyperswarm`, `protomux`, `safety-catch`
|
||||
- `engines.bare` — `>=2.0.0`
|
||||
- `pear.name` — `bare-os-seeder`
|
||||
- `pear.stage.include` — `../../node_modules` (hoisted workspace deps) and **`kernel**` (vendored tree under the package). The seeder reads `**kernel/**` only at runtime via `**readdir`/`readFile**` (no static imports), so Pear’s static analyzer would otherwise omit it from released bundles — `**kernel directory missing**` at runtime means `**pear stage**` did not ship `**kernel/**`; fix by keeping `**kernel**` in `**include**` and re-staging after `**rsync**` / `**verify-kernel-seeder-parity**`. With `**pear stage --compact**`, `**include**` is required for non-traced assets ([Pear configuration](https://docs.pears.com/reference/configuration.html) uses the heading “includes”; the manifest field is `**include`**).
|
||||
- `pear.stage.include` — `../../node_modules` (hoisted workspace deps) and **`kernel`** (vendored tree under the package). The seeder reads **`kernel/`** only at runtime via `**readdir`/`readFile**` (no static imports), so Pear’s static analyzer would otherwise omit it from released bundles — `**kernel directory missing**` at runtime means `**pear stage**` did not ship **`kernel/`**; fix by keeping **`kernel`** in **`include`** and re-staging after **`rsync`** / **`verify-kernel-seeder-parity`**. With `**pear stage --compact**`, **`include`** is required for non-traced assets ([Pear configuration](https://docs.pears.com/reference/configuration.html) uses the heading “includes”; the manifest field is **`include`**).
|
||||
- `pear.stage.ignore` — `.git`, `test`, `coverage`, `.DS_Store`, `node_modules/.bin`, `node_modules/.package-lock.json`
|
||||
- `imports` — **`#host-fs**`, `**#host-path**`, `**#host-fs-promises**` (preferred in first-party sources); legacy keys `**fs**`, `**fs/promises**`, `**path**`, `**url**`, `**node:url`** — Bare vs Node shims
|
||||
- `imports` — **`#host-fs**`, `**#host-path**`, `**#host-fs-promises**` (preferred in first-party sources); legacy keys **`fs`**, **`fs/promises`**, **`path`**, **`url`**, **`node:url`** — Bare vs Node shims
|
||||
|
||||
### 11.2 [packages/bare-os-seeder/lib/paths.js](../../packages/bare-os-seeder/lib/paths.js)
|
||||
|
||||
Pear-safe path resolution (same idea as Holepunch [pear-rti](https://github.com/holepunchto/pear-rti) `MOUNT` / `swapDir`):
|
||||
|
||||
- **`packageRootDir(metaUrl)`** — If `import.meta.url` is `file:`, `path.dirname(fileURLToPath(...))` via **`node:url`**. If `pear:` / other, tries **`RTI.mount**`, `**Pear.config.swapDir**`, `**Pear.app.dir` / `Pear.config.dir**`, `**RTI.dir**`, then `**process.cwd()**` (with `**bare-os` `os.cwd()**` fallback when `**process.cwd()**` is empty) — first directory that contains a `**kernel/`** subfolder wins; otherwise the first candidate (see [`paths.js`](../../packages/bare-os-seeder/lib/paths.js)).
|
||||
- **`packageRootDir(metaUrl)`** — If `import.meta.url` is `file:`, `path.dirname(fileURLToPath(...))` via **`node:url`**. If `pear:` / other, tries **`RTI.mount`**, **`Pear.config.swapDir`**, `**Pear.app.dir` / `Pear.config.dir**`, **`RTI.dir`**, then `**process.cwd()**` (with `**bare-os` `os.cwd()**` fallback when `**process.cwd()**` is empty) — first directory that contains a **`kernel/`** subfolder wins; otherwise the first candidate (see [`paths.js`](../../packages/bare-os-seeder/lib/paths.js)).
|
||||
- **`defaultKernelRoot(pkgRoot, metaUrl)`** — `BARE_OS_KERNEL_ROOT` or `path.join(pkgRoot, 'kernel')` (vendored copy under the seeder package for Pear bundles).
|
||||
- **`defaultSeedCorestorePath(pkgRoot, metaUrl)`** — `BARE_OS_SEED_STORE` or `path.join(hostDataRoot(), 'corestore', 'seeder')` where **`hostDataRoot()`** is `BARE_OS_HOST_DATA` (resolved) or `~/.bare-os`. Signature keeps `pkgRoot` / `metaUrl` for callers; defaults do not use them.
|
||||
|
||||
|
||||
@@ -4,13 +4,13 @@ This index links **IEEE Std 1003.1-2017 (Issue 7)** areas to **Bare OS** surface
|
||||
|
||||
| Issue 7 volume | Topic | Bare OS stand-in | Primary docs |
|
||||
| --- | --- | --- | --- |
|
||||
| XBD | Definitions / environment | Session **`vfs.env**`, `**/proc/self/environ**`, `**/proc/bare_os/security_posture.json`** | [environment-and-posix-appendix.md](environment-and-posix-appendix.md), handbook [ch.9](../../handbook/09-posix-utilities-shell-and-vfs.md) |
|
||||
| XSH | File I/O, metadata | **`ctx.bareOsSyscall**` ops + `**/proc/bare_os/syscalls.json**` (`**opsDetail**`, `**posixXsh**`, `**schemaVersion`**) | [POSIX_DECLARED_PROFILE.md](../architecture/POSIX_DECLARED_PROFILE.md), [posix-syscall-facade-map.md](posix-syscall-facade-map.md) |
|
||||
| XSH | Sockets (logical) | Socket bridge env (**`BARE_OS_POSIX_SOCKET_FD_BRIDGE**`, `**BARE_OS_POSIX_SOCKET_SCM_RIGHTS**`), `**socketMsgSurface`** in syscalls proc JSON | [syscall-socket-contract.md](syscall-socket-contract.md), handbook [ch.9](../../handbook/09-posix-utilities-shell-and-vfs.md) |
|
||||
| XCU | Shell | **`packages/bare-os-booter/lib/shell.js**`, env gates `**BARE_OS_SHELL_*`** | Handbook [ch.9 §3](../../handbook/09-posix-utilities-shell-and-vfs.md#3-shell-lists-pipelines-and-builtins-packagesbare-os-booterlibshelljs) |
|
||||
| XCU | Utilities | **`/bin**` (from `**bare-os-coreutils**`), `**/etc/bare-os/posix_utilities.json**`, `**man**`, `**/share/man/man.json`** | Handbook [ch.9 §5](../../handbook/09-posix-utilities-shell-and-vfs.md#5-bin-utilities-catalog) |
|
||||
| XCU | **`awk**`, `**expr**`, `**test`/`[**` | Bounded engines in `**packages/bare-os-coreutils**`; profile `**BARE_OS_POSIX_PROFILE_VERSION**` + [posix-compliance-matrix.json](posix-compliance-matrix.json) `**susv4Refs`** rows | Handbook [ch.9 §7](../../handbook/09-posix-utilities-shell-and-vfs.md#7-awk-sed-grep-and-text-utils-packagesbare-os-coreutils) |
|
||||
| (informative) | P2P / replication | **`/proc/bare_os/replication**`, `**/proc/bare_os/swarm**`, `**/proc/bare_os/swarm_health.json**`, `**disk.os**` RPC, `**ctx.bareOsHrpcRequest`** (versioned route table) | [KERNEL_CONTRACT.md](../architecture/KERNEL_CONTRACT.md), handbook [ch.3](../../handbook/03-protocol-and-disk.md) |
|
||||
| (informative) | Package index / path caps | **`pkg-swarm-index**`, `**bare_os.pkg_index_get**`, `**pathCapabilityEnvelope**` + `**ctx.bareOsVerifyPathCapabilityEnvelope`** | Handbook [ch.3](../../handbook/03-protocol-and-disk.md), [kernel-extensions.md](kernel-extensions.md) |
|
||||
| XBD | Definitions / environment | Session **`vfs.env`**, **`/proc/self/environ`**, **`/proc/bare_os/security_posture.json`** | [environment-and-posix-appendix.md](environment-and-posix-appendix.md), handbook [ch.9](../../handbook/09-posix-utilities-shell-and-vfs.md) |
|
||||
| XSH | File I/O, metadata | **`ctx.bareOsSyscall`** ops + **`/proc/bare_os/syscalls.json`** (**`opsDetail`**, **`posixXsh`**, **`schemaVersion`**) | [POSIX_DECLARED_PROFILE.md](../architecture/POSIX_DECLARED_PROFILE.md), [posix-syscall-facade-map.md](posix-syscall-facade-map.md) |
|
||||
| XSH | Sockets (logical) | Socket bridge env (**`BARE_OS_POSIX_SOCKET_FD_BRIDGE`**, **`BARE_OS_POSIX_SOCKET_SCM_RIGHTS`**), **`socketMsgSurface`** in syscalls proc JSON | [syscall-socket-contract.md](syscall-socket-contract.md), handbook [ch.9](../../handbook/09-posix-utilities-shell-and-vfs.md) |
|
||||
| XCU | Shell | **`packages/bare-os-booter/lib/shell.js`**, env gates **`BARE_OS_SHELL_*`** | Handbook [ch.9 §3](../../handbook/09-posix-utilities-shell-and-vfs.md#3-shell-lists-pipelines-and-builtins-packagesbare-os-booterlibshelljs) |
|
||||
| XCU | Utilities | **`/bin`** (from **`bare-os-coreutils`**), **`/etc/bare-os/posix_utilities.json`**, **`man`**, **`/share/man/man.json`** | Handbook [ch.9 §5](../../handbook/09-posix-utilities-shell-and-vfs.md#5-bin-utilities-catalog) |
|
||||
| XCU | **`awk`**, **`expr`**, `**test`/`[**` | Bounded engines in **`packages/bare-os-coreutils`**; profile **`BARE_OS_POSIX_PROFILE_VERSION`** + [posix-compliance-matrix.json](posix-compliance-matrix.json) **`susv4Refs`** rows | Handbook [ch.9 §7](../../handbook/09-posix-utilities-shell-and-vfs.md#7-awk-sed-grep-and-text-utils-packagesbare-os-coreutils) |
|
||||
| (informative) | P2P / replication | **`/proc/bare_os/replication`**, **`/proc/bare_os/swarm`**, **`/proc/bare_os/swarm_health.json`**, **`disk.os`** RPC, **`ctx.bareOsHrpcRequest`** (versioned route table) | [KERNEL_CONTRACT.md](../architecture/KERNEL_CONTRACT.md), handbook [ch.3](../../handbook/03-protocol-and-disk.md) |
|
||||
| (informative) | Package index / path caps | **`pkg-swarm-index`**, **`bare_os.pkg_index_get`**, **`pathCapabilityEnvelope`** + **`ctx.bareOsVerifyPathCapabilityEnvelope`** | Handbook [ch.3](../../handbook/03-protocol-and-disk.md), [kernel-extensions.md](kernel-extensions.md) |
|
||||
|
||||
**Maintainers:** when changing **`/proc/bare_os/syscalls.json**` `**schemaVersion**`, update `**kernel/etc/bare-os/syscalls.example.json**`, `**docs/schemas/bare-os-syscalls.schema.json**`, `**docs/reference/posix-compliance-matrix.json**`, and run `**node scripts/gen-posix-dashboard.mjs`**.
|
||||
**Maintainers:** when changing **`/proc/bare_os/syscalls.json`** **`schemaVersion`**, update **`kernel/etc/bare-os/syscalls.example.json`**, **`docs/schemas/bare-os-syscalls.schema.json`**, **`docs/reference/posix-compliance-matrix.json`**, and run `**node scripts/gen-posix-dashboard.mjs`**.
|
||||
|
||||
@@ -8,47 +8,47 @@ This document maps the **guest-visible** syscall-shaped surface to POSIX.1-2017
|
||||
|
||||
| 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-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`**).
|
||||
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`, experimental **`readv**`, `**writev**` (posix-pipe facades), `**clock_gettime**` (wall / monotonic sketch via `**bare-hrtime**` or `**performance.now**`), and `**nanosleep`** (capped wall sleep).
|
||||
**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`, experimental **`readv`**, **`writev`** (posix-pipe facades), **`clock_gettime`** (wall / monotonic sketch via **`bare-hrtime`** or **`performance.now`**), and **`nanosleep`** (capped wall sleep).
|
||||
|
||||
**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).
|
||||
**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**`, `**clock_gettime**`, `**umask**`, socket family aliases, etc.) with `**posixAlignment**`: `**simulated**`, `**partial**`, or `**ENOTSUP**`. They are **not** all separate `**ctx.bareOsSyscall**` op strings; they document how guest utilities and Wasm shims should reason about behavior. **Wasm:** only the small **sync** import set under `**BARE_OS_WASM_KERNEL_SYSCALL**` is wired into linear memory; use JS `**ctx.bareOsSyscall**` for `**clock_gettime**` and other async-shaped ops. The CSV of names is exposed as `**posixXsh.namesCsv`** in proc JSON.
|
||||
**`BARE_OS_POSIX_XSH_OPS_DETAIL`** lists Issue 7–style names (**`open`**, **`close`**, **`read`**, **`write`**, **`pipe`**, **`dup`**, **`dup2`**, **`fcntl`**, **`poll`**, **`select`**, **`lseek`**, **`nanosleep`**, **`clock_gettime`**, **`umask`**, socket family aliases, etc.) with **`posixAlignment`**: **`simulated`**, **`partial`**, or **`ENOTSUP`**. They are **not** all separate **`ctx.bareOsSyscall`** op strings; they document how guest utilities and Wasm shims should reason about behavior. **Wasm:** only the small **sync** import set under **`BARE_OS_WASM_KERNEL_SYSCALL`** is wired into linear memory; use JS **`ctx.bareOsSyscall`** for **`clock_gettime`** and other async-shaped ops. The CSV of names is exposed as **`posixXsh.namesCsv`** in proc JSON.
|
||||
|
||||
## Structured errno payloads (`partial` / `ENOTSUP`)
|
||||
|
||||
When the socket FD bridge or **`sendmsg**` / `**recvmsg**` paths reject input, stock `**ctx.bareOsSyscall**` throws or returns `**Error`** objects carrying stable machine fields (see [`packages/bare-os-booter/index.js`](../../packages/bare-os-booter/index.js)):
|
||||
When the socket FD bridge or **`sendmsg`** / **`recvmsg`** paths reject input, stock **`ctx.bareOsSyscall`** throws or returns **`Error`** objects carrying stable machine fields (see [`packages/bare-os-booter/index.js`](../../packages/bare-os-booter/index.js)):
|
||||
|
||||
| Field | Role |
|
||||
| --- | --- |
|
||||
| **`code**` | Short token (`**ENOTSUP**`, `**EINVAL**`, `**EBADF**`, `**EAGAIN**`, `**ETIMEDOUT`**, …) aligned with POSIX errno names where applicable |
|
||||
| **`errnoHint**` | Same as `**code`** for proc JSON symmetry |
|
||||
| **`posixAlignment**` | `**ENOTSUP**`, `**partial**`, or `**simulated**` — mirrors `**opsDetail.posixAlignment`** |
|
||||
| **`code`** | Short token (**`ENOTSUP`**, **`EINVAL`**, **`EBADF`**, **`EAGAIN`**, **`ETIMEDOUT`**, …) aligned with POSIX errno names where applicable |
|
||||
| **`errnoHint`** | Same as **`code`** for proc JSON symmetry |
|
||||
| **`posixAlignment`** | **`ENOTSUP`**, **`partial`**, or **`simulated`** — mirrors **`opsDetail.posixAlignment`** |
|
||||
| **`note`** | Human-readable reason (iov cap, ancillary unsupported, SCM_RIGHTS dup failure, unknown FD, …) |
|
||||
| **`op**` | Syscall-shaped op name (`**sendmsg**`, `**recvmsg**`, `**connect`**, …) for log correlation |
|
||||
| **`op`** | Syscall-shaped op name (**`sendmsg`**, **`recvmsg`**, **`connect`**, …) for log correlation |
|
||||
|
||||
**`recvmsg**` on the bridge reports `**controllen: 0**` when ancillary data is not surfaced; non-empty host-style cmsg requests without `**BARE_OS_POSIX_SOCKET_SCM_RIGHTS**` yield `**ENOTSUP**` with `**note**` explaining the gate. `**socketMsgSurface**` in proc JSON (schema **5**) documents `**sendmsg**` / `**recvmsg`** caps and rejection shapes.
|
||||
**`recvmsg`** on the bridge reports `**controllen: 0**` when ancillary data is not surfaced; non-empty host-style cmsg requests without **`BARE_OS_POSIX_SOCKET_SCM_RIGHTS`** yield **`ENOTSUP`** with **`note`** explaining the gate. **`socketMsgSurface`** in proc JSON (schema **5**) documents **`sendmsg`** / **`recvmsg`** caps and rejection shapes.
|
||||
|
||||
## 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`**.
|
||||
- **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.
|
||||
- **`lseek` on arbitrary guest FDs** — Marked **`ENOTSUP`** / **`ESPIPE`**-hinted: no universal byte cursor across VFS logical FDs.
|
||||
|
||||
## Related documentation
|
||||
|
||||
|
||||
@@ -16,13 +16,13 @@ Same Hyperswarm connection as `bare-os-v1`; gated by env / capability bits.
|
||||
|--------------|---------|----------|
|
||||
| `bare-os-app-v1` | Namespaced app RPC buffers | `BARE_OS_PROTOMUX_APP_CHANNEL` |
|
||||
| `bare-os-cap-v1` | Capability/datagram experiments | `BARE_OS_PROTOMUX_CAP_CHANNEL` |
|
||||
| `bare-os-chat-v1` | Global swarm chat messaging | Default on; disable with **`BARE_OS_PROTOMUX_CHAT_CHANNEL=0**` / `**false**` / `**off**` / `**no`** |
|
||||
| `bare-os-chat-v1` | Global swarm chat messaging | Default on; disable with **`BARE_OS_PROTOMUX_CHAT_CHANNEL=0`** / **`false`** / **`off`** / **`no`** |
|
||||
|
||||
See `PROTOCOL_CHAT_CHANNEL_NAME`, `setupBareOsChatChannel`, and `lib/chat-messages.js` in **`bare-os-protocol`**.
|
||||
|
||||
## Alias registry
|
||||
|
||||
Runtime merges env-driven aliases with the in-process registry (`createBareOsProtomuxAliasRegistry` in [`packages/bare-os-booter/lib/bare-os-protomux-alias-registry.js`](../../packages/bare-os-booter/lib/bare-os-protomux-alias-registry.js)). Snapshot JSON is exposed as **`/proc/bare_os/protomux.json**` and `**/proc/bare_os_protomux_wire`**.
|
||||
Runtime merges env-driven aliases with the in-process registry (`createBareOsProtomuxAliasRegistry` in [`packages/bare-os-booter/lib/bare-os-protomux-alias-registry.js`](../../packages/bare-os-booter/lib/bare-os-protomux-alias-registry.js)). Snapshot JSON is exposed as **`/proc/bare_os/protomux.json`** and **`/proc/bare_os_protomux_wire`**.
|
||||
|
||||
## Related Holepunch packages
|
||||
|
||||
|
||||
@@ -160,4 +160,4 @@ JSON: `semi: false`, `singleQuote: true`, `trailingComma: "none"`.
|
||||
|
||||
## 9. Root: `patches/` ([patch-package](https://github.com/ds300/patch-package))
|
||||
|
||||
The repo may ship **`patches/*.patch`** files in **patch-package** format (for example [`patches/autopass+3.4.0.patch`](../../patches/autopass+3.4.0.patch)) so maintainers can apply small **upstream dependency fixes** during development. They are **not** staged into the guest Hyperdrive. **`patch-package**` is a root devDependency; wire a `**postinstall**` script if you want patches applied automatically after `**npm ci`**. Document **why** each patch exists in the commit message and keep diffs minimal.
|
||||
The repo may ship **`patches/*.patch`** files in **patch-package** format (for example [`patches/autopass+3.4.0.patch`](../../patches/autopass+3.4.0.patch)) so maintainers can apply small **upstream dependency fixes** during development. They are **not** staged into the guest Hyperdrive. **`patch-package`** is a root devDependency; wire a **`postinstall`** script if you want patches applied automatically after `**npm ci`**. Document **why** each patch exists in the commit message and keep diffs minimal.
|
||||
|
||||
@@ -81,23 +81,23 @@ The engine consults (with **timeouts** on VFS calls so slow Hyperdrive I/O does
|
||||
|
||||
| Source | Use |
|
||||
| --- | --- |
|
||||
| **`/bin**` + `**PATH`** | First-token commands; PATH directories are read once per completion pass (deduped basenames). |
|
||||
| **Shell builtins** | From **`listBareOsShellBuiltins(env)**` (includes optional `**read`** when `BARE_OS_SHELL_READ_BUILTIN` is set). |
|
||||
| **`/bin`** + **`PATH`** | First-token commands; PATH directories are read once per completion pass (deduped basenames). |
|
||||
| **Shell builtins** | From **`listBareOsShellBuiltins(env)**` (includes optional **`read`** when `BARE_OS_SHELL_READ_BUILTIN` is set). |
|
||||
| **`ctx.shellAliases`** | Alias names and expansion preview in descriptions; alias expansion for man/flag lookup. |
|
||||
| **`/share/man/man.json**` | Session-cached merged manual: `**options[]**` flags, `**keywords**` for ranking, `**synopsis`/`description**` for `**--long**` regex extraction and subcommand heuristics; `**man `** second argument → index keys. |
|
||||
| **`/share/man/man.json`** | Session-cached merged manual: `**options[]**` flags, **`keywords`** for ranking, `**synopsis`/`description**` for **`--long`** regex extraction and subcommand heuristics; `**man `** second argument → index keys. |
|
||||
| **Static fallbacks** | `COMPLETION_FLAG_MAP` in `completion-engine.js` when man options are empty. |
|
||||
| **VFS `readdir` + `stat`** | Paths, `~/`, globs (`*?[` via `bareOsFnmatch`); **directories only** for `cd` / `rmdir`; colored labels from **`LS_COLORS`**. |
|
||||
| **Environment** | `$VAR` completion. |
|
||||
| **`/proc/bare_os/process_table.json**` | `**kill**` / `**wait`** arguments (cached ~400ms). |
|
||||
| **`/proc/bare_os/process_table.json`** | **`kill`** / **`wait`** arguments (cached ~400ms). |
|
||||
| **`/proc/bare_os`** | Extra names when the command is a file-reading heuristic (`cat`, `grep`, …) and the partial path looks under proc. |
|
||||
| **`/run/bare-os/units`** | Initd-style unit name column (tab-separated). |
|
||||
| **`metrics_live.json`** | Hint entry when the typed path suggests it. |
|
||||
| **`/sys**`, `**/run`** | Ordinary path completion when the user types those prefixes (VFS virtual nodes). |
|
||||
| **`/sys`**, **`/run`** | Ordinary path completion when the user types those prefixes (VFS virtual nodes). |
|
||||
| **Registry** | **`ctx.bareOsRegisterCompleter`** (see below). |
|
||||
|
||||
### Context parsing
|
||||
|
||||
`parseCompletionContext(line, cursor)` tokenizes **`line.slice(0, cursor)**` with the same `**tokenize`** as the shell:
|
||||
`parseCompletionContext(line, cursor)` tokenizes **`line.slice(0, cursor)**` with the same **`tokenize`** as the shell:
|
||||
|
||||
- **Pipeline segment** — only tokens after the last **`|`** in the prefix are completed (so `cmd1 | cmd2 ` completes `cmd2` as a command).
|
||||
- **Redirection** — after `>`, `>>`, `<`, `2>`, … the next word is treated as a path when relevant.
|
||||
@@ -105,7 +105,7 @@ The engine consults (with **timeouts** on VFS calls so slow Hyperdrive I/O does
|
||||
|
||||
### Ranking
|
||||
|
||||
Candidates are scored with (among others): exact match, prefix match, subsequence fuzzy match, capped **Levenshtein**, frequency from history, **bigram** boost from the last executed command’s first token, **man keyword** overlap, and a **kind boost** so **VFS path** rows (`kind: path`) sort above builtins, aliases, **`/bin**`, and **PATH** executables. For the **first token**, `**readdir('.')**` matches are gathered **before** command names with a raised `**scoreBase**` so files in the working directory compete strongly with binaries. Results are capped for display (`**menuVisibleCap()`**, currently 200) with a footer hint if more exist.
|
||||
Candidates are scored with (among others): exact match, prefix match, subsequence fuzzy match, capped **Levenshtein**, frequency from history, **bigram** boost from the last executed command’s first token, **man keyword** overlap, and a **kind boost** so **VFS path** rows (`kind: path`) sort above builtins, aliases, **`/bin`**, and **PATH** executables. For the **first token**, `**readdir('.')**` matches are gathered **before** command names with a raised **`scoreBase`** so files in the working directory compete strongly with binaries. Results are capped for display (`**menuVisibleCap()`**, currently 200) with a footer hint if more exist.
|
||||
|
||||
---
|
||||
|
||||
@@ -116,7 +116,7 @@ When the Fish editor attaches, the booter sets:
|
||||
- **`ctx.bareOsRegisterCompleter(commandName, async (ctx, meta) => items[])`**
|
||||
- **`ctx.bareOsUnregisterCompleter(commandName)`**
|
||||
|
||||
**`meta**` includes at least: `**env**`, `**cx`** (completion context from `parseCompletionContext`), **`manKey**`, `**resolvedCmd`**.
|
||||
**`meta`** includes at least: **`env`**, **`cx`** (completion context from `parseCompletionContext`), **`manKey`**, **`resolvedCmd`**.
|
||||
|
||||
Each **item** should look like `{ value, description?, kind?, ansiLabel?, manFlag?, scoreBase? }`. Return an array; the engine merges your items with built-in sources and re-ranks.
|
||||
|
||||
@@ -131,10 +131,10 @@ Stub fields also exist on the initial `ctx` object in [`index.js`](../../package
|
||||
| Variable | Effect |
|
||||
| --- | --- |
|
||||
| **`BARE_OS_FISH=0`** | Disable the Fish-style raw TTY editor entirely; use the fallback reader. |
|
||||
| **`BARE_OS_COMPACT_MENU=1**` or `**true`** | Force **inline** tab cycling (no dropdown menu) even on wide terminals. |
|
||||
| **`BARE_OS_COMPACT_MENU=1`** or **`true`** | Force **inline** tab cycling (no dropdown menu) even on wide terminals. |
|
||||
| (implicit) **`stdout.columns` < 44** | Same as compact: no menu, inline only. |
|
||||
| **`LS_COLORS**`, `**BARE_OS_THEME**`, `**BARE_OS_COLOR_*`** | Menu label coloring and prompt/ghost colors (themes apply via `barerc` / `applyBareOsThemeFromEnv`). |
|
||||
| **`LINES**`, `**TERM`** | Menu height clamp uses `stdout.rows` or `LINES`; capability-style behavior follows the rest of the OS. |
|
||||
| **`LS_COLORS`**, **`BARE_OS_THEME`**, **`BARE_OS_COLOR_*`** | Menu label coloring and prompt/ghost colors (themes apply via `barerc` / `applyBareOsThemeFromEnv`). |
|
||||
| **`LINES`**, **`TERM`** | Menu height clamp uses `stdout.rows` or `LINES`; capability-style behavior follows the rest of the OS. |
|
||||
|
||||
Host **passthrough** into guest `ctx.env` follows the same booter loop as other keys; if you need `BARE_OS_COMPACT_MENU` inside the guest, set it on the **host** before boot or export it in **`~/.barerc`** like any other variable.
|
||||
|
||||
@@ -143,7 +143,7 @@ Host **passthrough** into guest `ctx.env` follows the same booter loop as other
|
||||
## Performance and resilience
|
||||
|
||||
- VFS reads inside the engine use **`withVfsTimeout`** (~220ms): slow P2P replication returns empty/partial candidates instead of hanging the REPL.
|
||||
- **`readdir**` results are soft-capped before `**stat`** storms.
|
||||
- **`readdir`** results are soft-capped before **`stat`** storms.
|
||||
- **`process_table.json`** is parsed from a short-lived cache per `ctx`.
|
||||
- **`man.json`** is parsed once per session (`ctx.__bareOsManDbParsed`).
|
||||
- The stdin pump **awaits** `completeLine` only on **Tab** (and similar), not on every keystroke.
|
||||
@@ -152,7 +152,7 @@ Host **passthrough** into guest `ctx.env` follows the same booter loop as other
|
||||
|
||||
## Tests
|
||||
|
||||
[`packages/bare-os-booter/test.js`](../../packages/bare-os-booter/test.js) includes unit coverage for **`parseCompletionContext**`, `**rankCompletionItems**`, `**suggestGhostFromHistory**`, `**completeLine**` with a mock VFS (e.g. `**kill**` + process table), and a large-list ranking budget check. Older `**fish-readline`** history/`stripAnsi`/`fuzzyMatch` tests remain.
|
||||
[`packages/bare-os-booter/test.js`](../../packages/bare-os-booter/test.js) includes unit coverage for **`parseCompletionContext`**, **`rankCompletionItems`**, **`suggestGhostFromHistory`**, **`completeLine`** with a mock VFS (e.g. **`kill`** + process table), and a large-list ranking budget check. Older **`fish-readline`** history/`stripAnsi`/`fuzzyMatch` tests remain.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,22 +1,22 @@
|
||||
# Syscall and socket bridge contract
|
||||
|
||||
Single reference for **`ctx.bareOsSyscall**` POSIX-shaped ops and the optional `**BARE_OS_POSIX_SOCKET_FD_BRIDGE**` path. Normative JSON lives in `**/proc/bare_os/syscalls.json**` (`**schemaVersion` 10** — includes **`posix_fadvise**`, `**socketMsgSurface**`) and `**kernel/etc/bare-os/syscalls.example.json`**.
|
||||
Single reference for **`ctx.bareOsSyscall`** POSIX-shaped ops and the optional **`BARE_OS_POSIX_SOCKET_FD_BRIDGE`** path. Normative JSON lives in **`/proc/bare_os/syscalls.json`** (`**schemaVersion` 10** — includes **`posix_fadvise`**, **`socketMsgSurface`**) and **`kernel/etc/bare-os/syscalls.example.json`**.
|
||||
|
||||
## POSIX XSH names
|
||||
|
||||
Generated **`posixXsh.namesCsv**` includes `**socket**`, `**bind**`, `**listen**`, `**accept**`, `**connect**`, `**send**`, `**recv**`, `**recvfrom**`, `**sendmsg**`, `**recvmsg**`, `**shutdown**`, `**poll**`, `**select**`, etc. Each row in `**opsDetail**` lists `**mapsTo**`, `**errnoHint**`, and `**posixAlignment`**.
|
||||
Generated **`posixXsh.namesCsv`** includes **`socket`**, **`bind`**, **`listen`**, **`accept`**, **`connect`**, **`send`**, **`recv`**, **`recvfrom`**, **`sendmsg`**, **`recvmsg`**, **`shutdown`**, **`poll`**, **`select`**, etc. Each row in **`opsDetail`** lists **`mapsTo`**, **`errnoHint`**, and **`posixAlignment`**.
|
||||
|
||||
## Socket FD bridge (env)
|
||||
|
||||
Enable with **`BARE_OS_POSIX_SOCKET_FD_BRIDGE=1**`. Requires `**ctx.bare**` to expose `**bareTcp**` and/or `**bareDgram**` (Holepunch `**bare-tcp**` / `**bare-dgram`** bundles).
|
||||
Enable with **`BARE_OS_POSIX_SOCKET_FD_BRIDGE=1`**. Requires **`ctx.bare`** to expose **`bareTcp`** and/or **`bareDgram`** (Holepunch **`bare-tcp`** / **`bare-dgram`** bundles).
|
||||
|
||||
| Transport | Flow | Notes |
|
||||
| --- | --- | --- |
|
||||
| **SOCK_STREAM** | **`bind` → `listen` → `accept**`, or `**connect**` | `**connect**` installs the same `**tcpRecvQueue` + `data**` path as `**accept**`. `**poll`/`select`**: readable when the queue has data, when the peer has half-closed / FIN (**EOF** recv), or after a socket error; writable when local **SHUT_WR** is not set. |
|
||||
| **SOCK_DGRAM** | **`bind**` (passive UDP), or `**connect**` | `**recv`/`recvfrom`/`recvmsg**` dequeue datagrams; `**poll`/`select**` for `**connected**` or `**udp_bound`** states. |
|
||||
| **SOCK_DGRAM send** | After **`bind**` without `**connect**` | Syscall args must include `**port**` and `**host**` (or `**address**`) for each `**send**`/`**sendmsg**`. After `**connect**` on a bound socket, `**send**`/`**sendmsg`** may omit destination (connected mode). |
|
||||
| **SOCK_DGRAM recvmsg** | Bound or connected | **`recvmsg**` returns `**msgHdr.name**` from `**rinfo**` when the datagram source is known; `**controllen` 0** on receive (see **`socketMsgSurface`**). |
|
||||
| **SOCK_STREAM sendmsg + SCM_RIGHTS** | Connected | With **`BARE_OS_POSIX_SOCKET_SCM_RIGHTS**`, `**sendmsg**` accepts the same JSON `**cmsgs**` / `**msgHdr.cmsgs**` `**{ fds: number[] }**` entries as datagram bridge fds (`**prepareBridgeSendmsg**`); logical dups appear in `**scmRightsLocalDup`** on the syscall result. |
|
||||
| **SOCK_STREAM** | **`bind` → `listen` → `accept**`, or **`connect`** | **`connect`** installs the same `**tcpRecvQueue` + `data**` path as **`accept`**. `**poll`/`select`**: readable when the queue has data, when the peer has half-closed / FIN (**EOF** recv), or after a socket error; writable when local **SHUT_WR** is not set. |
|
||||
| **SOCK_DGRAM** | **`bind`** (passive UDP), or **`connect`** | `**recv`/`recvfrom`/`recvmsg**` dequeue datagrams; `**poll`/`select**` for **`connected`** or **`udp_bound`** states. |
|
||||
| **SOCK_DGRAM send** | After **`bind`** without **`connect`** | Syscall args must include **`port`** and **`host`** (or **`address`**) for each **`send`**/**`sendmsg`**. After **`connect`** on a bound socket, **`send`**`/`**sendmsg`** may omit destination (connected mode). |
|
||||
| **SOCK_DGRAM recvmsg** | Bound or connected | **`recvmsg`** returns **`msgHdr.name`** from **`rinfo`** when the datagram source is known; `**controllen` 0** on receive (see **`socketMsgSurface`**). |
|
||||
| **SOCK_STREAM sendmsg + SCM_RIGHTS** | Connected | With **`BARE_OS_POSIX_SOCKET_SCM_RIGHTS`**, **`sendmsg`** accepts the same JSON **`cmsgs`** / **`msgHdr.cmsgs`** `**{ fds: number[] }**` entries as datagram bridge fds (**`prepareBridgeSendmsg`**); logical dups appear in **`scmRightsLocalDup`** on the syscall result. |
|
||||
|
||||
### Queues and caps
|
||||
|
||||
@@ -28,21 +28,21 @@ Enable with **`BARE_OS_POSIX_SOCKET_FD_BRIDGE=1**`. Requires `**ctx.bare**` to e
|
||||
|
||||
**Operational profile:** without **`BARE_OS_POSIX_SOCKET_FD_BRIDGE`**, socket syscalls remain ENOSYS-shaped. With the bridge, ancillary handling follows the table below.
|
||||
|
||||
- **Ancillary control** on **`sendmsg**`: non-empty binary `**control**` / `**controllen**`, or malformed `**cmsgs**`, → `**ENOTSUP**` + `**ancillaryReject`**.
|
||||
- **`recvmsg**`: `**controllen` 0**; **`msgHdr.name**` filled from UDP `**rinfo`** when present.
|
||||
- **`logicalScmRightsOnSend**` (schemas **4–5**): when `**BARE_OS_POSIX_SOCKET_SCM_RIGHTS=1**`, `**cmsgs**` and `**msgHdr.cmsgs**` may contain only objects `**{ fds: number[] }**`. Each fd is duplicated; the syscall result includes `**scmRightsLocalDup: [{ from, to }]**`. Applies to **SOCK_STREAM** connected fds and **SOCK_DGRAM** connected/bound fds (same code path). Cap via `**BARE_OS_POSIX_SOCKET_SCM_RIGHTS_MAX_FDS**` (default **4**, max **16**). Idle / listen / bound-only bridge sockets reject dup. `**shutdown**` refcount-per-alias destroys the underlying slot when the last fd closes. This is **logical** duplication in the guest FD table (not host `**SCM_RIGHTS**`); `**recvmsg**` does not surface ancillary data. Without the env flag, non-empty `**cmsgs**` remain `**ENOTSUP**`. Parser unit tests: `**packages/bare-os-booter/test.socket-scm-rights.js**`. Schema **5** documents stream `**sendmsg`** parity explicitly (behavior unchanged from schema **4**).
|
||||
- **Ancillary control** on **`sendmsg`**: non-empty binary **`control`** / **`controllen`**, or malformed **`cmsgs`**, → **`ENOTSUP`** + **`ancillaryReject`**.
|
||||
- **`recvmsg`**: `**controllen` 0**; **`msgHdr.name`** filled from UDP **`rinfo`** when present.
|
||||
- **`logicalScmRightsOnSend`** (schemas **4–5**): when **`BARE_OS_POSIX_SOCKET_SCM_RIGHTS=1`**, **`cmsgs`** and **`msgHdr.cmsgs`** may contain only objects `**{ fds: number[] }**`. Each fd is duplicated; the syscall result includes `**scmRightsLocalDup: [{ from, to }]**`. Applies to **SOCK_STREAM** connected fds and **SOCK_DGRAM** connected/bound fds (same code path). Cap via **`BARE_OS_POSIX_SOCKET_SCM_RIGHTS_MAX_FDS`** (default **4**, max **16**). Idle / listen / bound-only bridge sockets reject dup. **`shutdown`** refcount-per-alias destroys the underlying slot when the last fd closes. This is **logical** duplication in the guest FD table (not host **`SCM_RIGHTS`**); **`recvmsg`** does not surface ancillary data. Without the env flag, non-empty **`cmsgs`** remain **`ENOTSUP`**. Parser unit tests: **`packages/bare-os-booter/test.socket-scm-rights.js`**. Schema **5** documents stream **`sendmsg`** parity explicitly (behavior unchanged from schema **4**).
|
||||
|
||||
## TCP **`shutdown`** / half-close
|
||||
|
||||
**`ctx.bareOsSyscall('shutdown', { fd, how })`** on a connected TCP bridge fd:
|
||||
|
||||
- **`how: 0**` — **SHUT_RD**: further `**recv**` drains the queue then returns **EOF** (`**bytesReceived: 0**`, `**eof: true`**).
|
||||
- **`how: 1**` — **SHUT_WR**: `**sock.end()**` when available; further `**send`/`sendmsg**` return `**EPIPE`**-shaped errors.
|
||||
- **`how: 0**` — **SHUT_RD**: further **`recv`** drains the queue then returns **EOF** (`**bytesReceived: 0**`, `**eof: true`**).
|
||||
- **`how: 1**` — **SHUT_WR**: `**sock.end()**` when available; further `**send`/`sendmsg**` return **`EPIPE`**-shaped errors.
|
||||
- **`how: 2`** or **omitted** — full close (legacy): destroy the socket and unregister the fd when it is the last alias.
|
||||
|
||||
## Poll clock
|
||||
|
||||
**`ctx.bareOsPosixPoll**` returns `**pollClock**`: `**monotonic_hrtime**` when `**bare-hrtime**` loads, else `**Date_now**`, for timeout / `**waitedMs`** measurement.
|
||||
**`ctx.bareOsPosixPoll`** returns **`pollClock`**: **`monotonic_hrtime`** when **`bare-hrtime`** loads, else **`Date_now`**, for timeout / **`waitedMs`** measurement.
|
||||
|
||||
## Related docs
|
||||
|
||||
|
||||
@@ -1,17 +1,17 @@
|
||||
# Vault and key-rotation threat model (Bare OS)
|
||||
|
||||
Bare OS keeps **Ed25519** account material sealed for the personal Hyperdrive using **`bare-crypto**` (see `**identity-session.js`**). This note is intentionally short: it records **what the guest trusts** and **what operators must still verify on the host**.
|
||||
Bare OS keeps **Ed25519** account material sealed for the personal Hyperdrive using **`bare-crypto`** (see **`identity-session.js`**). This note is intentionally short: it records **what the guest trusts** and **what operators must still verify on the host**.
|
||||
|
||||
## Trust boundaries
|
||||
|
||||
- **Guest image (`/bin`, kernel, booter)** is assumed **integrity-checked** by your release process (manifest signing, Pear channel policy, or offline LKG keys). Compromised image ⇒ full session compromise regardless of vault design.
|
||||
- **Personal drive** is writable by the unlocked session. In **guest** mode the stock VFS **denies** read/write/chmod/unlink on **`/.bare/account**`, `**/.bare/vault/****`, and `**/.bare/vault-rotation-audit.ndjson**` so ciphertext and rotation logs are not visible without unlocking (`**BARE_OS_GUEST_BARE_READ_ALL=1**` lifts this for tests). `**ctx.bareOsAppendVaultRotationCheckpoint**` appends **plaintext NDJSON audit rows** to `**/.bare/vault-rotation-audit.ndjson**` — useful for continuity evidence, **not** a secret store. Do not place raw private keys there. After `**saveVaultToDrive**` / `**logout --save**`, a row with `**kind**`: `**vault_save**` and `**fileCount`** is appended when the personal drive is writable.
|
||||
- **Personal drive** is writable by the unlocked session. In **guest** mode the stock VFS **denies** read/write/chmod/unlink on **`/.bare/account`**, **`/.bare/vault/`****, and **`/.bare/vault-rotation-audit.ndjson`** so ciphertext and rotation logs are not visible without unlocking (**`BARE_OS_GUEST_BARE_READ_ALL=1`** lifts this for tests). **`ctx.bareOsAppendVaultRotationCheckpoint`** appends **plaintext NDJSON audit rows** to **`/.bare/vault-rotation-audit.ndjson`** — useful for continuity evidence, **not** a secret store. Do not place raw private keys there. After **`saveVaultToDrive`** / `**logout --save**`, a row with **`kind`**: **`vault_save`** and **`fileCount`** is appended when the personal drive is writable.
|
||||
- **Host Corestore / filesystem** holds material the guest cannot fully audit. Treat disk encryption, backups, and multi-device signing policy as **operator responsibilities**.
|
||||
|
||||
## Rotation
|
||||
|
||||
- **`BARE_OS_ACCOUNT_KEY_ROTATION_STATE_JSON`** (env) may describe overlapping validity windows for signing keys. Checkpoints on disk should list **which key** signed **which artifact** and **when**, so rollback does not silently accept stale trust.
|
||||
- **`/proc/bare_os/security_posture.json**` (`**accountKeyRotationContinuity**`, schema **2**) mirrors only **structural** hints (`**stateKeyCount**`, `**rotationHintPresent`**) — never raw private material — so operators can audit continuity without exposing vault bytes.
|
||||
- **`/proc/bare_os/security_posture.json`** (**`accountKeyRotationContinuity`**, schema **2**) mirrors only **structural** hints (**`stateKeyCount`**, **`rotationHintPresent`**) — never raw private material — so operators can audit continuity without exposing vault bytes.
|
||||
|
||||
## Operational guidance
|
||||
|
||||
@@ -20,13 +20,13 @@ Bare OS keeps **Ed25519** account material sealed for the personal Hyperdrive us
|
||||
|
||||
## Crypto parameters (audit checklist)
|
||||
|
||||
- **Ed25519** is used for **boot manifest verification** (**`verifyBootManifestEd25519`**), **extension signer pins**, **stable `hostid**` derivation from the unlocked identity public key, and **Hyperdrive discovery** material. Regression tests in `**packages/bare-os-booter/test.js`** cover manifest signature rejection; keep algorithm names and key lengths aligned across those surfaces when rotating governance tooling.
|
||||
- **AEAD / sealing** for vault snapshots should use **`bare-crypto**` primitives (ChaCha20-Poly1305 or documented equivalents) with **unique nonces per seal** and KDF parameters (PBKDF2 iteration counts or Argon2id when adopted) aligned with current `**bare-crypto**` release notes. `**bare-crypto**`-backed **tamper rejection** for sealed blobs (`**openBytes**` after flipping an authentication tag byte) is covered in `**packages/bare-os-booter/test.identity.js**` (run via `**brittle-bare`**, same as account encode/decode).
|
||||
- **Ed25519** is used for **boot manifest verification** (**`verifyBootManifestEd25519`**), **extension signer pins**, **stable `hostid**` derivation from the unlocked identity public key, and **Hyperdrive discovery** material. Regression tests in **`packages/bare-os-booter/test.js`** cover manifest signature rejection; keep algorithm names and key lengths aligned across those surfaces when rotating governance tooling.
|
||||
- **AEAD / sealing** for vault snapshots should use **`bare-crypto`** primitives (ChaCha20-Poly1305 or documented equivalents) with **unique nonces per seal** and KDF parameters (PBKDF2 iteration counts or Argon2id when adopted) aligned with current **`bare-crypto`** release notes. **`bare-crypto`**-backed **tamper rejection** for sealed blobs (**`openBytes`** after flipping an authentication tag byte) is covered in **`packages/bare-os-booter/test.identity.js`** (run via **`brittle-bare`**, same as account encode/decode).
|
||||
- Compare envelope layout with Holepunch **`safe-sodium-buffer`** guidance where applicable: avoid reusing `(key, nonce)` pairs; zeroize sensitive `Uint8Array` copies in host bridges when the runtime allows.
|
||||
- **`savevault` / `logout --save`**: verify `bareOsKeySchema` version bumps include migration notes in the booter changelog when ciphertext layout changes. **`identity-session.js**` keeps a single-session Ed25519 account model: `**logout --save**` persists the encrypted vault snapshot and mirrors a `**vault_save**` audit row when the personal drive is writable; `**login` / `unlock**` rehydrate keys through the same `**bare-crypto**` paths used for `**hostid**` and boot-manifest verification. Extension `**kernel.ext.d**` scripts pinned by `**extensionSignerPins**` in `**boot.policy.json**` must ship a `**signaturePointer**` and verify with `**ctx.bareOsVerifyBootManifestSignature`** before execution (strict boot fails closed) so vault-bearing sessions do not load unsigned extension code when pins are declared.
|
||||
- **`savevault` / `logout --save`**: verify `bareOsKeySchema` version bumps include migration notes in the booter changelog when ciphertext layout changes. **`identity-session.js`** keeps a single-session Ed25519 account model: `**logout --save**` persists the encrypted vault snapshot and mirrors a **`vault_save`** audit row when the personal drive is writable; `**login` / `unlock**` rehydrate keys through the same **`bare-crypto`** paths used for **`hostid`** and boot-manifest verification. Extension **`kernel.ext.d`** scripts pinned by **`extensionSignerPins`** in **`boot.policy.json`** must ship a **`signaturePointer`** and verify with **`ctx.bareOsVerifyBootManifestSignature`** before execution (strict boot fails closed) so vault-bearing sessions do not load unsigned extension code when pins are declared.
|
||||
|
||||
## Seeder multisig verification (guest-visible hint)
|
||||
|
||||
The Pear seeder may set **`BARE_OS_SEEDER_MULTISIG_VERIFY_RESULT**` (`**ok**` / `**failed**` / `**skipped**`) when `**logPearMultisigKernelHint**` runs. The stock booter copies a redacted sketch into `**/proc/bare_os/security_posture.json**` under `**pearMultisigSeeder.verifyResult**` so operators can see **whether** multisig verification ran — not the signing keys or raw `**pear.multisig.json`** payload.
|
||||
The Pear seeder may set **`BARE_OS_SEEDER_MULTISIG_VERIFY_RESULT`** (**`ok`** / **`failed`** / **`skipped`**) when **`logPearMultisigKernelHint`** runs. The stock booter copies a redacted sketch into **`/proc/bare_os/security_posture.json`** under **`pearMultisigSeeder.verifyResult`** so operators can see **whether** multisig verification ran — not the signing keys or raw **`pear.multisig.json`** payload.
|
||||
|
||||
See also: [environment appendix](environment-and-posix-appendix.md), [handbook ch.4 — booter runtime](../../handbook/04-the-booter-runtime.md).
|
||||
|
||||
@@ -7,16 +7,16 @@ Stock routing is implemented in `packages/bare-os-booter/lib/vfs.js` (`createVfs
|
||||
| `pseudo` | `/proc`, `/sys`, `/dev` | Synthetic trees; not Hyperdrive bytes |
|
||||
| `volatile` | `/run`, `/tmp` | Session / ephemeral; often personal-backed |
|
||||
| `mount` | `/mnt`, `/media`, `/mount` | Optional union / HDMS mounts |
|
||||
| `personal` | `/home/…`, `/root…`, **`/.bare/****` | Personal Hyperdrive view; physical prefixes may nest under `**/.bare-os/acct/<id>/…**` when `**BARE_OS_PERSONAL_ACCT_PREFIX=1**`. With that flag, logical `**/.bare/account**` and `**/.bare/vault/****` resolve to `**/.bare-os/acct/<id>/.bare/…**` on the personal drive (per-session identity isolation); without the flag, `**/.bare/****` stays at the personal root as before. **Exception:** when an HDMS (or mount-map) entry with label `**www**` is present, `**$HOME/.www**` and `**/home/<active>/.www**` are routed to that `**www**` drive’s root instead of the personal home tree (same path class for policy helpers; different backing `**drive`** in `route()`). |
|
||||
| `personal` | `/home/…`, `/root…`, **`/.bare/**`** | Personal Hyperdrive view; physical prefixes may nest under `**/.bare-os/acct/<id>/…**` when **`BARE_OS_PERSONAL_ACCT_PREFIX=1`**. With that flag, logical **`/.bare/account`** and **`/.bare/vault/`**** resolve to `**/.bare-os/acct/<id>/.bare/…**` on the personal drive (per-session identity isolation); without the flag, **`/.bare/`**** stays at the personal root as before. **Exception:** when an HDMS (or mount-map) entry with label **`www`** is present, **`$HOME/.www`** and **`/home/<active>/.www`** are routed to that **`www`** drive’s root instead of the personal home tree (same path class for policy helpers; different backing **`drive`** in `route()`). |
|
||||
| `system` | `/boot`, `/bin`, `/lib`, `/etc`, `/usr`, `/var`, default | System image Hyperdrive |
|
||||
| `snapshot` | `/snapshots`, `/snapshots/system/…` | Read-only **system** checkout views when **`BARE_OS_VFS_SNAPSHOTS=1`** and `drive.checkout` exists |
|
||||
|
||||
**Policy helper:** `evaluateBareOsVfsPathPolicy(path, rules)` returns **`verdict`** (`allow` \| `deny` \| `neutral`), **`matched**` (including `**audit**` hits), `**auditHits**`, and `**metrics`** (`rulesEvaluated`, `matchCount`). Rules may use **`effect**`: `**allow**`, `**deny**`, or `**audit**` (audit records a match but does not override the verdict; later `**allow`/`deny`** rules still apply).
|
||||
**Policy helper:** `evaluateBareOsVfsPathPolicy(path, rules)` returns **`verdict`** (`allow` \| `deny` \| `neutral`), **`matched`** (including **`audit`** hits), **`auditHits`**, and **`metrics`** (`rulesEvaluated`, `matchCount`). Rules may use **`effect`**: **`allow`**, **`deny`**, or **`audit`** (audit records a match but does not override the verdict; later `**allow`/`deny`** rules still apply).
|
||||
|
||||
**Env rules:** `parseBareOsVfsPolicyRulesFromEnv(env)` reads **`BARE_OS_VFS_POLICY_RULES_JSON`** as `{ "rules": [ { "id", "effect", "pathClass?", "prefix?" } ] }` for tooling that merges policy stacks.
|
||||
|
||||
**Batch / diff helpers:** `bareOsVfsBatchPut(drive, puts)` and `bareOsHyperdriveDiffCollect(drive, a, b, opts)` in the same module (used from **`ctx.bareOsVfsBatchWrite**` / `**ctx.bareOsHyperdriveDiffCollect`** in the booter).
|
||||
**Batch / diff helpers:** `bareOsVfsBatchPut(drive, puts)` and `bareOsHyperdriveDiffCollect(drive, a, b, opts)` in the same module (used from **`ctx.bareOsVfsBatchWrite`** / **`ctx.bareOsHyperdriveDiffCollect`** in the booter).
|
||||
|
||||
Rule evaluation is **advisory** unless a caller enforces **`verdict`**; stock VFS routing still uses `createVfs` internals and boot policy (`denyVfsPrefixes`, …).
|
||||
|
||||
**ACL / xattr sidecars (utilities, not a separate path class):** advisory ACL and extended-attribute views may use synthetic JSON files such as **`/.bare_acl.json**` and `**/.bare_xattr.json`** next to the affected directory (see [handbook ch.9](../../handbook/09-posix-utilities-shell-and-vfs.md) and [`kernel/etc/bare-os/vfs-sidecar-xattr-acl.example.json`](../../kernel/etc/bare-os/vfs-sidecar-xattr-acl.example.json)).
|
||||
**ACL / xattr sidecars (utilities, not a separate path class):** advisory ACL and extended-attribute views may use synthetic JSON files such as **`/.bare_acl.json`** and **`/.bare_xattr.json`** next to the affected directory (see [handbook ch.9](../../handbook/09-posix-utilities-shell-and-vfs.md) and [`kernel/etc/bare-os/vfs-sidecar-xattr-acl.example.json`](../../kernel/etc/bare-os/vfs-sidecar-xattr-acl.example.json)).
|
||||
|
||||
Reference in New Issue
Block a user