snxraven/bare-operating-system
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs updates

Browse Source
This commit is contained in:
Raven Scott
2026-04-04 08:31:39 -04:00
parent 0e53351349
commit 081e4c587c
64 changed files with 2052 additions and 1273 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/README.md
+36 -5
View File
@@ -1,8 +1,39 @@
# Documentation
- **[Reference hub](reference/README.md)** — file-level inventory (packages, kernel tree, env vars, data-flow diagram). Split from the former root `DOCUMENTATION.md`.
- **[Kernel extensions](reference/kernel-extensions.md)** — kernel feature bitfield, seed-channel RPC, and related caps.
- **[Handbook](../handbook/README.md)** — chapters on architecture, booter runtime, protocol, operations.
- **[Developer guide](../developer-guide/README.md)** — extending the image, `ctx`, coreutils, testing.
- **[Holepunch catalog](bare-holepunch-catalog.json)** — metadata used to refresh optional `ctx.bare` bundles (see root `package.json` scripts).
This directory is the **`docs/`** tree: reference material, JSON catalog inputs, and theme packs. For a gentle on-ramp to running the system, read the **[user manual](../users-manual/README.md)** first; for narrative architecture, use the **[handbook](../handbook/README.md)**; for extending `/bin` and `ctx`, use the **[developer guide](../developer-guide/README.md)**.
---
## On this page
- [User-facing docs](#user-facing-docs)
- [Reference](#reference)
- [Kernel extensions](#kernel-extensions)
- [Catalog and themes](#catalog-and-themes)
---
## User-facing docs
- **[User manual](../users-manual/README.md)** — install, seeder/booter, shell, identity, troubleshooting, and a map of the rest of the documentation.
- **[Handbook](../handbook/README.md)** — long-form explanation of design, protocol, booter runtime, identity, POSIX surface, operations, and research context.
- **[Developer guide](../developer-guide/README.md)** — practical guides for scripts, kernel `start(ctx)`, coreutils, testing, and Pear.
---
## Reference
- **[Reference hub](reference/README.md)** — file-level inventory (packages, kernel tree, environment appendix, data-flow diagram). Split from the former root `DOCUMENTATION.md`.
---
## Kernel extensions
- **[Kernel extensions](reference/kernel-extensions.md)** — kernel feature bitfield, seed-channel RPC, and related capability wiring.
---
## Catalog and themes
- **[Holepunch catalog](bare-holepunch-catalog.json)** — metadata used to refresh optional `ctx.bare` bundles (see root `package.json` scripts: `gen:bare-catalog`, `sync:bare-manifest`, `smoke:bare-manifest`).
- **[Themes](themes/README.md)** — initd/cron theme packs for the image.
docs/reference/README.md
+34 -19
View File
@@ -1,23 +1,38 @@
# File-level reference
This directory holds the split **file-by-file inventory** that used to live in the root [`DOCUMENTATION.md`](../../DOCUMENTATION.md) stub. Use it when you need paths, package roles, and environment tables without narrative walkthroughs.
This directory holds the split **file-by-file inventory** that used to live in the root [`DOCUMENTATION.md`](../../DOCUMENTATION.md) stub. Use it when you need paths, package roles, and environment variables without a narrative walkthrough.
| Former § (monolith) | Document |
| ------------------ | -------- |
| §§1–8 | [Repository layout and root metadata](repo-layout-and-root.md) |
| §9 | [Kernel image sources](kernel-image.md) |
| §10 | [Package: bare-os-protocol](package-bare-os-protocol.md) |
| §11 | [Package: bare-os-seeder](package-bare-os-seeder.md) |
| §§12.1–12.9 | [Package: bare-os-booter](package-bare-os-booter.md) |
| §§12.10–12.12 | [bare-os-coreutils, tests, and seeder build hook](package-bare-os-coreutils-and-ci.md) |
| §13 | [Architecture: end-to-end data flow](architecture-data-flow.md) |
| §14, §14a | [Environment variables and POSIX appendix](environment-and-posix-appendix.md) |
| *(kernel feature bits & handshake)* | [Kernel extensions](kernel-extensions.md) |
| *(bits → env → proc → ctx)* | [Kernel capabilities index](kernel-capabilities-index.md) |
| *(version alignment)* | [Compatibility matrix](compatibility-matrix.md) |
| *(roadmap)* | [Feature roadmap status](feature-roadmap.md) |
| §§15–16 | [Out of scope and tooling](out-of-scope-and-tooling.md) |
| *(HTTP clients)* | [curl and wget (delegation, fetch stack, policy)](http-curl-and-wget.md) |
| *(JSON Schemas)* | [Published schemas: boot policy, telemetry, boot trace](../schemas/) |
---
**Narrative docs:** [Handbook](../../handbook/README.md) (why / architecture), [Developer guide](../../developer-guide/README.md) (how to extend `run` / `start`, `ctx`).
## On this page
- [Topics (former monolith map)](#topics-former-monolith-map)
- [Narrative docs](#narrative-docs)
---
## Topics (former monolith map)
- **Repository layout and root metadata** (former §§1–8) — [Repository layout and root metadata](repo-layout-and-root.md)
- **Kernel image sources** (former §9) — [Kernel image sources](kernel-image.md)
- **Package: bare-os-protocol** (former §10) — [Package: bare-os-protocol](package-bare-os-protocol.md)
- **Package: bare-os-seeder** (former §11) — [Package: bare-os-seeder](package-bare-os-seeder.md)
- **Package: bare-os-booter** (former §§12.1–12.9) — [Package: bare-os-booter](package-bare-os-booter.md)
- **bare-os-coreutils, tests, and seeder build hook** (former §§12.10–12.12) — [bare-os-coreutils, tests, and seeder build hook](package-bare-os-coreutils-and-ci.md)
- **Architecture: end-to-end data flow** (former §13) — [Architecture: end-to-end data flow](architecture-data-flow.md)
- **Environment variables and POSIX appendix** (former §14, §14a) — [Environment variables and POSIX appendix](environment-and-posix-appendix.md)
- **Kernel feature bits and handshake** — [Kernel extensions](kernel-extensions.md)
- **Bits, env, `/proc`, and `ctx` map** — [Kernel capabilities index](kernel-capabilities-index.md)
- **Version alignment** — [Compatibility matrix](compatibility-matrix.md)
- **Roadmap status** — [Feature roadmap status](feature-roadmap.md)
- **Out of scope and tooling** (former §§15–16) — [Out of scope and tooling](out-of-scope-and-tooling.md)
- **curl and wget (delegation, fetch stack, policy)** — [curl and wget](http-curl-and-wget.md)
- **Published JSON Schemas** — [Published schemas: boot policy, telemetry, boot trace](../schemas/)
---
## Narrative docs
- **[Handbook](../../handbook/README.md)** — why the system exists and how the architecture fits together.
- **[Developer guide](../../developer-guide/README.md)** — how to extend `run` / `start`, use `ctx`, and test under Pear.
- **[User manual](../../users-manual/README.md)** — operator-oriented guide to running and using the image.
docs/reference/capability-words.md
+14 -18
View File
@@ -2,29 +2,25 @@
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.
| `kernelCapabilityWords` key | Semantic label | Stock mask constant (`bare-os-protocol`) | `boot.policy.json` required mask | Proc JSON module (`bare-os-booter`) |
| --- | --- | --- | --- | --- |
| `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` | — |
| `rlimitsDelegatesShell` | `RLIMITS_DELEGATES_SHELL` | `BARE_OS_KERNEL_FEATURES_STOCK_WORD_RLIMITS_DELEGATES_SHELL` | `requireKernelCapabilitiesRlimitsDelegatesShell` | — |
| `offlineNetExtensions` | `OFFLINE_NET_EXTENSIONS` | `BARE_OS_KERNEL_FEATURES_STOCK_WORD_OFFLINE_NET_EXTENSIONS` | `requireKernelCapabilitiesOfflineNetExtensions` | — |
| `hostTransportDelegates` | `HOST_TRANSPORT_DELEGATES` | `BARE_OS_KERNEL_FEATURES_STOCK_WORD_HOST_TRANSPORT_DELEGATES` | `requireKernelCapabilitiesHostTransportDelegates` | — |
| `replicationOperatorSurface` | `REPLICATION_OPERATOR_SURFACE` | `BARE_OS_KERNEL_FEATURES_STOCK_WORD_REPLICATION_OPERATOR_SURFACE` | `requireKernelCapabilitiesReplicationOperatorSurface` | `bare-os-proc-replication-operator-surface.js` |
| `pearCorestoreHrpc` | `PEAR_CORESTORE_HRPC` | `BARE_OS_KERNEL_FEATURES_STOCK_WORD_PEAR_CORESTORE_HRPC` | `requireKernelCapabilitiesPearCorestoreHrpc` | `bare-os-proc-pear-corestore-hrpc.js` |
| `bareRuntimeProtoMux` | `BARE_RUNTIME_PROTO_MUX` | `BARE_OS_KERNEL_FEATURES_STOCK_WORD_BARE_RUNTIME_PROTO_MUX` | `requireKernelCapabilitiesBareRuntimeProtoMux` | `bare-os-proc-bare-runtime-proto-mux.js` |
| `bareModuleCryptoStaging` | `BARE_MODULE_CRYPTO_STAGING` | `BARE_OS_KERNEL_FEATURES_STOCK_WORD_BARE_MODULE_CRYPTO_STAGING` | `requireKernelCapabilitiesBareModuleCryptoStaging` | `bare-os-proc-bare-module-crypto-staging.js` |
| `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` |
- `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` — —
- `rlimitsDelegatesShell` — `RLIMITS_DELEGATES_SHELL` — `BARE_OS_KERNEL_FEATURES_STOCK_WORD_RLIMITS_DELEGATES_SHELL` — `requireKernelCapabilitiesRlimitsDelegatesShell` — —
- `offlineNetExtensions` — `OFFLINE_NET_EXTENSIONS` — `BARE_OS_KERNEL_FEATURES_STOCK_WORD_OFFLINE_NET_EXTENSIONS` — `requireKernelCapabilitiesOfflineNetExtensions` — —
- `hostTransportDelegates` — `HOST_TRANSPORT_DELEGATES` — `BARE_OS_KERNEL_FEATURES_STOCK_WORD_HOST_TRANSPORT_DELEGATES` — `requireKernelCapabilitiesHostTransportDelegates` — —
- `replicationOperatorSurface` — `REPLICATION_OPERATOR_SURFACE` — `BARE_OS_KERNEL_FEATURES_STOCK_WORD_REPLICATION_OPERATOR_SURFACE` — `requireKernelCapabilitiesReplicationOperatorSurface` — `bare-os-proc-replication-operator-surface.js`
- `pearCorestoreHrpc` — `PEAR_CORESTORE_HRPC` — `BARE_OS_KERNEL_FEATURES_STOCK_WORD_PEAR_CORESTORE_HRPC` — `requireKernelCapabilitiesPearCorestoreHrpc` — `bare-os-proc-pear-corestore-hrpc.js`
- `bareRuntimeProtoMux` — `BARE_RUNTIME_PROTO_MUX` — `BARE_OS_KERNEL_FEATURES_STOCK_WORD_BARE_RUNTIME_PROTO_MUX` — `requireKernelCapabilitiesBareRuntimeProtoMux` — `bare-os-proc-bare-runtime-proto-mux.js`
- `bareModuleCryptoStaging` — `BARE_MODULE_CRYPTO_STAGING` — `BARE_OS_KERNEL_FEATURES_STOCK_WORD_BARE_MODULE_CRYPTO_STAGING` — `requireKernelCapabilitiesBareModuleCryptoStaging` — `bare-os-proc-bare-module-crypto-staging.js`
- `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).
**Probe env (telemetry):**
| Env var | Word |
| --- | --- |
| `BARE_OS_PROBE_ID_BARE_MODULE_CRYPTO_STAGING` | ninth word |
| `BARE_OS_PROBE_ID_PEAR_INSPECT_LOGGER_TLS` | tenth word |
| `BARE_OS_PROBE_ID_HYPERCORE_PACK_HRPC_LIFECYCLE` | eleventh word |
- `BARE_OS_PROBE_ID_BARE_MODULE_CRYPTO_STAGING` — ninth word
- `BARE_OS_PROBE_ID_PEAR_INSPECT_LOGGER_TLS` — tenth word
- `BARE_OS_PROBE_ID_HYPERCORE_PACK_HRPC_LIFECYCLE` — eleventh word
**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.
docs/reference/compatibility-matrix.md
+25 -7
View File
@@ -2,19 +2,37 @@
Single place to compare **protocol**, **booter `ctx` API**, **feature-bit document**, and **telemetry** versions. Values below match the stock tree at release time; always read source for ground truth.
| Artifact | Location | Current (stock) |
| --- | --- | --- |
| **`bareOsCtxApiVersion`** | [`packages/bare-os-booter/lib/bare-os-ctx-api.js`](../../packages/bare-os-booter/lib/bare-os-ctx-api.js) | `1.22.0` |
| **`BARE_OS_KERNEL_FEATURE_BITS_DOC`** | [`packages/bare-os-protocol/lib/kernel-feature-bits.js`](../../packages/bare-os-protocol/lib/kernel-feature-bits.js) | `15` |
| **Capability words (wire v2)** | `bare_os.capabilities` RPC + `/proc/bare_os_features` | Top-level **`kernelCapabilityWords`** object: **`primary`**, **`extendedSeedingPlatform`**, **`rlimitsDelegatesShell`**, **`offlineNetExtensions`**, **`hostTransportDelegates`**, **`replicationOperatorSurface`**, **`pearCorestoreHrpc`**, **`bareRuntimeProtoMux`**, **`bareModuleCryptoStaging`**, **`pearInspectLoggerTls`**, **`hypercorePackHrpcLifecycle`** (eleven `uint32` masks; same bit positions as legacy top-level **`bits`**…**`bits11`**) |
| **Lifecycle / telemetry NDJSON** | `BARE_OS_LIFECYCLE_SCHEMA_VERSION` in [`bare-os-lifecycle-schema.js`](../../packages/bare-os-booter/lib/bare-os-lifecycle-schema.js) | `10` |
| **Protocol package** | [`bare-os-protocol` `package.json`](../../packages/bare-os-protocol/package.json) | see workspace version |
---
## On this page
- [Version artifacts](#version-artifacts)
- [Peer assumptions](#peer-assumptions)
- [See also](#see-also)
---
## Version artifacts
**`bareOsCtxApiVersion`** (current stock: **`1.22.0`**) — Defined in [`packages/bare-os-booter/lib/bare-os-ctx-api.js`](../../packages/bare-os-booter/lib/bare-os-ctx-api.js). This is the semver string for the documented **`ctx`** contract; bump it when stable guest-visible behavior changes.
**`BARE_OS_KERNEL_FEATURE_BITS_DOC`** (current stock: **`15`**) — Exported from [`packages/bare-os-protocol/lib/kernel-feature-bits.js`](../../packages/bare-os-protocol/lib/kernel-feature-bits.js). It versions the feature-bit documentation and related governance; keep it aligned with [`developer-guide/adr/001-kernel-feature-bits-governance.md`](../../developer-guide/adr/001-kernel-feature-bits-governance.md).
**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.
---
## 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.
---
## See also
- [`kernel-extensions.md`](./kernel-extensions.md)
docs/reference/environment-and-posix-appendix.md
+99 -98
View File
@@ -2,122 +2,123 @@
Former **DOCUMENTATION.md** §14, §14a. [Reference index →](README.md)
---
## On this page
- [§14 — Environment variables (complete list)](#14-environment-variables-complete-list)
- [§14a — POSIX userland appendix](#14a-posix-userland-appendix-implemented-vs-gaps)
---
## 14. Environment variables (complete list)
| Variable | Used by | Meaning |
| ------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `BARE_OS_KERNEL_ROOT` | Seeder | Absolute path to kernel tree (default: `repo/kernel`) |
| `BARE_OS_HOST_DATA` | paths | Base directory for host state (default `~/.bare-os`; Corestore dirs live under `corestore/`) |
| `BARE_OS_SEED_STORE` | Seeder | Corestore directory (default: `~/.bare-os/corestore/seeder`) |
| `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_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_BOOT_TRACE` | Stock kernel (`init.js`) | If `1` or `true`, log each boot phase duration on stderr as `[boot] phase: Nms`; if `json`, log `{"phase":"…","ms":n}` per phase; **`ndjson`** adds **`sessionId`** / **`ts`** (same shape as `ctx.bareOsEmitBootEvent`) |
| `MANWIDTH` | `/bin/man` | Wrap width for manual text (default `72`; minimum `40`) |
| `NO_COLOR` | `/bin/man` | If set, disable ANSI bold for section headings on a TTY |
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_HOST_DATA` — paths — Base directory for host state (default `~/.bare-os`; Corestore dirs live under `corestore/`)
- `BARE_OS_SEED_STORE` — Seeder — Corestore directory (default: `~/.bare-os/corestore/seeder`)
- `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_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_BOOT_TRACE` — Stock kernel (`init.js`) — If `1` or `true`, log each boot phase duration on stderr as `[boot] phase: Nms`; if `json`, log `{"phase":"…","ms":n}` per phase; **`ndjson`** adds **`sessionId`** / **`ts`** (same shape as `ctx.bareOsEmitBootEvent`)
- `MANWIDTH` — `/bin/man` — Wrap width for manual text (default `72`; minimum `40`)
- `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): `BARE_OS_PIPELINE_MAX_STAGES`, `BARE_OS_PIPELINE_MAX_BYTES`, `BARE_OS_PIPELINE_MAX_LINES`, `BARE_OS_SHELL_STREAMING`, `BARE_OS_SHELL_STREAMING_MULT`, `BARE_OS_SHELL_CMDSUBST`, `BARE_OS_SHELL_CMDSUBST_MAX_BYTES`, `BARE_OS_SHELL_PARAM_EXPANSION`, `BARE_OS_SHELL_PARAM_EXPANSION_V2`, `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_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_TRACE`, `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_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_NAMESPACE`, `BARE_OS_VFS_WATCH`, `BARE_OS_VFS_UNION_PREFIXES`, `BARE_OS_VFS_UNION_WRITE_DENY`, `BARE_OS_VFS_BIN_CACHE`, `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_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_PROC_POLL_MS`, `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_YES_MAX_LINES`, `BARE_OS_SHUF_MAX_LINES`, `BARE_OS_SPLIT_MAX_FILES`, `BARE_OS_NPROC`, `BARE_OS_BLIND_BOOTSTRAP_URL`, `BARE_OS_BLIND_BOOTSTRAP_JSON`, `BARE_OS_MIRROR_READ_KEY`, `BARE_OS_PEAR_TRUST_JSON`, `BARE_OS_HOST_BUNDLE_EVALUATE`, **`TERM`**, **`COLORTERM`**.
| Variable | Used by | Meaning |
| ---------------------------------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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_VFS_BIN_CACHE` | VFS | When **`1`** / **`true`**, LRU read cache for **`/bin`**; invalidated on **`vfs.watch`** when enabled. |
| `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_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_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_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_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_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**; default **1**). |
| `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`**: **5** (stock Wave 6+), **`ts`**, …) mirroring structured boot/kernel events. |
| `BARE_OS_TELEMETRY_OTEL_JSONL` | Booter / var-log | Guest VFS path for OTLP-inspired JSON lines (var-log mirrors). |
| `BARE_OS_PROC_POLL_MS` | VFS | Coalescing interval for **`/proc/bare_os/metrics_live.json`** (250–60000). |
| `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_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`**. |
| `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. |
| `BARE_OS_EXEC_LINE_BUDGET_MS` | Booter | Reject top-level **`execLine`** when cumulative wall time exceeds budget. |
| `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_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**). |
| `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_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_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_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_LOOP_MAX` | Shell | Max iterations for **`while`** / **`for`** (default **10000**). |
| `BARE_OS_SHELL_CASE_MAX_BRANCHES` | Shell | Max **`case`** branches (default **32**). |
| `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_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_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_VFS_BIN_CACHE` — VFS — When **`1`** / **`true`**, LRU read cache for **`/bin`**; invalidated on **`vfs.watch`** when enabled.
- `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_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_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_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_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_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**; default **1**).
- `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`**: **5** (stock Wave 6+), **`ts`**, …) mirroring structured boot/kernel events.
- `BARE_OS_TELEMETRY_OTEL_JSONL` — Booter / var-log — Guest VFS path for OTLP-inspired JSON lines (var-log mirrors).
- `BARE_OS_PROC_POLL_MS` — VFS — Coalescing interval for **`/proc/bare_os/metrics_live.json`** (250–60000).
- `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_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`**.
- `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.
- `BARE_OS_EXEC_LINE_BUDGET_MS` — Booter — Reject top-level **`execLine`** when cumulative wall time exceeds budget.
- `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_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**).
- `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_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_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_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_LOOP_MAX` — Shell — Max iterations for **`while`** / **`for`** (default **10000**).
- `BARE_OS_SHELL_CASE_MAX_BRANCHES` — Shell — Max **`case`** branches (default **32**).
- `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_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`**.
### Wave 6 (selected)
| Variable | Used by | Meaning |
| --- | --- | --- |
| `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_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_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_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_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_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.
**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).
**Theme and color (from `~/.barerc`, `/bin/theme`, and `applyBareOsThemeFromEnv`):**
| Variable | Meaning |
| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BARE_OS_THEME` | Preset name (`default`, `nord`, `dracula`, …). Set by `theme <name>` in `~/.barerc` or `/bin/theme set`. |
| `BARE_OS_COLOR_DEPTH` | `truecolor` (default), `256` / `8bit`, or `16` / `8` / `ansi`. Downgrades truecolor **`BARE_OS_COLOR_*`** REPL sequences only; `LS_COLORS` strings stay as in the preset or `dircolors` output. |
| `BARE_OS_COLOR_PROMPT`, `COMMAND`, `PATH`, `ENVSET`, `ENVUNSET`, `GHOST`, `SEARCH` | ANSI open sequences for fish readline (set by the active theme). |
| `LS_COLORS` | GNU-style `ls` coloring; filled from the preset unless already set or **`BARE_OS_LS_COLORS_LOCKED=1`**. |
| `BARE_OS_DIRCOLORS` | Path to a dircolors-format file; when set, theme apply parses it (for the current `TERM`) into `LS_COLORS`. |
| `NO_COLOR` | When set, disables color in `ls` and other tools that honor it. |
- `BARE_OS_THEME` — Preset name (`default`, `nord`, `dracula`, …). Set by `theme <name>` in `~/.barerc` or `/bin/theme set`.
- `BARE_OS_COLOR_DEPTH` — `truecolor` (default), `256` / `8bit`, or `16` / `8` / `ansi`. Downgrades truecolor **`BARE_OS_COLOR_*`** REPL sequences only; `LS_COLORS` strings stay as in the preset or `dircolors` output.
- `BARE_OS_COLOR_PROMPT`, `COMMAND`, `PATH`, `ENVSET`, `ENVUNSET`, `GHOST`, `SEARCH` — ANSI open sequences for fish readline (set by the active theme).
- `LS_COLORS` — GNU-style `ls` coloring; filled from the preset unless already set or **`BARE_OS_LS_COLORS_LOCKED=1`**.
- `BARE_OS_DIRCOLORS` — Path to a dircolors-format file; when set, theme apply parses it (for the current `TERM`) into `LS_COLORS`.
- `NO_COLOR` — When set, disables color in `ls` and other tools that honor it.
---
## 14a. POSIX userland appendix (implemented vs gaps)
| Area | Status |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **VFS** | Two-drive unified paths; **`$HOME`** maps to the personal Hyperdrive; writable mounts under **`/mnt`** when HDMS allows. **`mkdir`/`rmdir`**, **`chmod`** (octal + symbolic subset), **`symlink`/`readlink`**, **`stat`/`lstat`**, **`rm`** recursive, **`watch()`** on Hyperdrive paths (optional host **`BARE_OS_VFS_WATCH=0`** to disable). Synthetic **`/proc`**, **`/sys`**, **`/run`**, **`/dev`** for introspection (quotas JSON, boot JSON, initd snapshot, union policy, seed handshake, virtual registry, etc.). Optional union read overlays (**`BARE_OS_VFS_UNION_PREFIXES`**) with optional write deny (**`BARE_OS_VFS_UNION_WRITE_DENY`**). Empty dirs use **`.bareos_empty`** (same idea as `git-fs-adapter`). |
| **Shell** | Pipelines, **`;`**, **`&&`** / \*\*` | | `**, redirects, quoting, **`$VAR`**, **`$?`**, optional **`${VAR:-word}`** / **`${VAR#prefix}`** when **`BARE*OS_SHELL_PARAM_EXPANSION=1`**, **`jobs`** / **`fg`** / **`wait`**, optional background **`&`** segments, builtins including bounded **`if`**, **`while`**, **`for`**, **`case`** (caps **`BARE_OS_SHELL_LOOP_MAX`**, **`BARE_OS_SHELL_CASE_MAX_BRANCHES`**). Optional bounded **`$(…)`** when **`BARE_OS_SHELL_CMDSUBST=1`**; optional larger pipeline capture via **`BARE_OS_SHELL_STREAMING`** / **`BARE_OS_SHELL_STREAMING_MULT`**. Branching uses **`ctx.exitCode`**. Bounded pipeline capture (**`BARE_OS_PIPELINE*\*`**, **`ctx.bareOsRuntimeCaps`**); optional boot-snippet allowlist (**`BARE_OS_BOOT_ALLOWLIST`** + **`/etc/bare-os/boot.allow`**). No subshells or full POSIX **`sh`\*\*. |
| **Ownership** | Display and permission checks use **`UID`/`GID`** and mode bits; **`chown`/`chgrp`** update **`metadata.bareOs`** on the **personal** writable tree (not a multi-user host kernel). |
| **Utilities** | Tier-1 JS **`/bin`** (**~113** commands; see [§12.10](package-bare-os-coreutils-and-ci.md#1210-package-bare-os-coreutils)): text tools include **`paste`**, **`split`**, **`tac`**, **`rev`**, **`expand`**, **`unexpand`**, **`fold`**, **`fmt`**, **`comm`**, **`cmp`**, **`join`**, **`pr`**, **`yes`** (line-capped via **`BARE_OS_YES_MAX_LINES`** / **`getconf`**), **`shuf`** (capped via **`BARE_OS_SHUF_MAX_LINES`**), **`tsort`**, **`factor`**, **`expr`** (integer-focused subset), **`numfmt`** (**`--to=iec`** / **`--to=si`**). Checksums: **`md5sum`** (bundled MD5), **`sha1sum`**, **`sha256sum`**, **`sha512sum`** (Web Crypto where available), **`sum`**, **`base32`**, **`basenc`** (**`--base16`**). Files: **`truncate`**, **`unlink`**, **`install`**, **`df`** (synthetic Hyperdrive row; **`-h`** human sizes), **`sync`** (no-op), **`timeout`** (wall-clock cap; exit **124** on timeout when **`BARE_OS_FEATURE_ABORT_TIMEOUT`** is advertised). Session stubs: **`arch`**, **`groups`**, **`hostid`**, **`nproc`**, **`uptime`**, **`users`**, **`who`**. Plus earlier parity: **`man`**, **`sed`** (including **`-z`**, **`BARE_OS_SED_NULL_MAX_RECORDS`**), **`awk`**, **`grep`** (**`-r`** with **`--include`/`--exclude`/`--exclude-dir`**, **`BARE_OS_GREP_FILTER_MAX`**), **`cp`** (**`-u`/`-v`/`-p`**), **`mv`**, **`find`** (**`-regex`**, **`-exec`/`-ok`**, **`BARE_OS_FIND_EXEC_MAX`**), **`mktemp`**, **`git-pear`**, **`cksum`**, **`getconf`** (includes pipeline / cap names + **`-a`**), **`xargs`**, **`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/`**. Online help: **`/share/man/man.json`** and **`man`**. |
- **VFS** — Two-drive unified paths; **`$HOME`** maps to the personal Hyperdrive; writable mounts under **`/mnt`** when HDMS allows. **`mkdir`/`rmdir`**, **`chmod`** (octal + symbolic subset), **`symlink`/`readlink`**, **`stat`/`lstat`**, **`rm`** recursive, **`watch()`** on Hyperdrive paths (optional host **`BARE_OS_VFS_WATCH=0`** to disable). Synthetic **`/proc`**, **`/sys`**, **`/run`**, **`/dev`** for introspection (quotas JSON, boot JSON, initd snapshot, union policy, seed handshake, virtual registry, etc.). Optional union read overlays (**`BARE_OS_VFS_UNION_PREFIXES`**) with optional write deny (**`BARE_OS_VFS_UNION_WRITE_DENY`**). Empty dirs use **`.bareos_empty`** (same idea as `git-fs-adapter`).
- **Shell** — Pipelines, **`;`**, **`&&`** / \*\*` — — `**, redirects, quoting, **`$VAR`**, **`$?`**, optional **`${VAR:-word}`** / **`${VAR#prefix}`** when **`BARE*OS_SHELL_PARAM_EXPANSION=1`**, **`jobs`** / **`fg`** / **`wait`**, optional background **`&`** segments, builtins including bounded **`if`**, **`while`**, **`for`**, **`case`** (caps **`BARE_OS_SHELL_LOOP_MAX`**, **`BARE_OS_SHELL_CASE_MAX_BRANCHES`**). Optional bounded **`$(…)`** when **`BARE_OS_SHELL_CMDSUBST=1`**; optional larger pipeline capture via **`BARE_OS_SHELL_STREAMING`** / **`BARE_OS_SHELL_STREAMING_MULT`**. Branching uses **`ctx.exitCode`**. Bounded pipeline capture (**`BARE_OS_PIPELINE*\*`**, **`ctx.bareOsRuntimeCaps`**); optional boot-snippet allowlist (**`BARE_OS_BOOT_ALLOWLIST`** + **`/etc/bare-os/boot.allow`**). No subshells or full POSIX **`sh`\*\*.
- **Ownership** — Display and permission checks use **`UID`/`GID`** and mode bits; **`chown`/`chgrp`** update **`metadata.bareOs`** on the **personal** writable tree (not a multi-user host kernel).
- **Utilities** — Tier-1 JS **`/bin`** (**~113** commands; see [§12.10](package-bare-os-coreutils-and-ci.md#1210-package-bare-os-coreutils)): text tools include **`paste`**, **`split`**, **`tac`**, **`rev`**, **`expand`**, **`unexpand`**, **`fold`**, **`fmt`**, **`comm`**, **`cmp`**, **`join`**, **`pr`**, **`yes`** (line-capped via **`BARE_OS_YES_MAX_LINES`** / **`getconf`**), **`shuf`** (capped via **`BARE_OS_SHUF_MAX_LINES`**), **`tsort`**, **`factor`**, **`expr`** (integer-focused subset), **`numfmt`** (**`--to=iec`** / **`--to=si`**). Checksums: **`md5sum`** (bundled MD5), **`sha1sum`**, **`sha256sum`**, **`sha512sum`** (Web Crypto where available), **`sum`**, **`base32`**, **`basenc`** (**`--base16`**). Files: **`truncate`**, **`unlink`**, **`install`**, **`df`** (synthetic Hyperdrive row; **`-h`** human sizes), **`sync`** (no-op), **`timeout`** (wall-clock cap; exit **124** on timeout when **`BARE_OS_FEATURE_ABORT_TIMEOUT`** is advertised). Session stubs: **`arch`**, **`groups`**, **`hostid`**, **`nproc`**, **`uptime`**, **`users`**, **`who`**. Plus earlier parity: **`man`**, **`sed`** (including **`-z`**, **`BARE_OS_SED_NULL_MAX_RECORDS`**), **`awk`**, **`grep`** (**`-r`** with **`--include`/`--exclude`/`--exclude-dir`**, **`BARE_OS_GREP_FILTER_MAX`**), **`cp`** (**`-u`/`-v`/`-p`**), **`mv`**, **`find`** (**`-regex`**, **`-exec`/`-ok`**, **`BARE_OS_FIND_EXEC_MAX`**), **`mktemp`**, **`git-pear`**, **`cksum`**, **`getconf`** (includes pipeline / cap names + **`-a`**), **`xargs`**, **`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/`**. Online help: **`/share/man/man.json`** and **`man`**.
**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).
docs/reference/feature-roadmap.md
+14
View File
@@ -2,6 +2,14 @@
This file tracks the twenty-item “kernel super-features” plan. Items are **done** when shipped in the stock booter/kernel unless noted.
## Checklist format and CI
**Wave 6** through **Wave 11** use **Markdown pipe tables** with numbered rows so `pretest` can verify checklist depth: [`scripts/verify-kernel-capabilities-word-6.mjs`](../../scripts/verify-kernel-capabilities-word-6.mjs) through [`verify-kernel-capabilities-word-11.mjs`](../../scripts/verify-kernel-capabilities-word-11.mjs) count lines matching `| N |` inside each wave block. Do not replace those tables with lists without updating the verifiers. Earlier blocks (the original twenty items and **Wave 5**) follow the same table style for readability and diff-friendly review.
---
## Original twenty super-features (completed baseline)
| # | Item | Status |
|---|------|--------|
| 1 | Feature-bit governance v2 + ADR | done — [developer-guide/adr/001-kernel-feature-bits-governance.md](../../developer-guide/adr/001-kernel-feature-bits-governance.md), bits 21–27, `BARE_OS_KERNEL_FEATURE_BITS_DOC=2` |
@@ -27,6 +35,8 @@ This file tracks the twenty-item “kernel super-features” plan. Items are **d
## Wave 5 (twenty-item super-feature plan)
Wave 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 |
|---|------|--------|
| 1 | Fifth capability word (`bits5`) + ADR §8 | done — `BARE_OS_KERNEL_FEATURES_STOCK_WORD_HOST_TRANSPORT_DELEGATES`, strict seed check, `/proc` + RPC |
@@ -50,6 +60,10 @@ This file tracks the twenty-item “kernel super-features” plan. Items are **d
| 19 | `ctx.bare` risk metadata | done — manifest `tier`/`risk` examples + catalog docs |
| 20 | Documentation coherence CI | done — [`scripts/verify-doc-links.mjs`](../../scripts/verify-doc-links.mjs), pretest |
## Mega-kernel waves (6–11)
Waves **6** through **11** are **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.
## Wave 6 (100-item mega kernel)
| # | Item | Status |
docs/reference/http-curl-and-wget.md
+8 -12
View File
@@ -8,12 +8,10 @@ Bare OS exposes **`curl`** and **`wget`** as familiar command names, but they ar
## Where to read more
| Topic | Location |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Flag parity and history | [`packages/bare-os-booter/CLI_PARITY.md`](../../packages/bare-os-booter/CLI_PARITY.md) |
| 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) |
- Flag parity and history — [`packages/bare-os-booter/CLI_PARITY.md`](../../packages/bare-os-booter/CLI_PARITY.md)
- 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)
---
@@ -67,12 +65,10 @@ 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.
| Variable | Role |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **`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_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.
---
docs/reference/kernel-capabilities-index.md
+22
View File
@@ -2,6 +2,28 @@
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).
---
## On this page
- [Primary word (`bits`)](#primary-word-bits)
- [Word 2 — `bits2`](#word-2--bits2--extended-seeding-platform)
- [Word 3 — `bits3`](#word-3--bits3--rlimits-delegates-shell)
- [Word 4 — `bits4`](#word-4--bits4--offline-net-extensions)
- [Word 5 — `bits5`](#word-5--bits5--host-transport-delegates)
- [Word 6](#word-6-sixth-capability-word-replicationoperatorsurface)
- [Word 7](#word-7-seventh-capability-word-pearcorestorehrpc)
- [Word 8](#word-8-eighth-capability-word-bareruntimeprotomux)
- [Word 9](#word-9-ninth-capability-word-baremodulecryptostaging)
- [Word 10](#word-10--pearinspectloggertls--bare_os_kernel_features_stock_word_pear_inspect_logger_tls)
- [Word 11](#word-11--hypercorepackhrpclifecycle--bare_os_kernel_features_stock_word_hypercore_pack_hrpc_lifecycle)
---
### Primary word (`bits`)
Each row is one **bit index** in the first capability word. Columns list **env or behavior**, **`/proc` or RPC** touchpoints, and **`ctx`** or notes. Empty cells mean “no dedicated toggle or path beyond the general capability machinery.”
| Bit (export) | Env / behavior | `/proc` or RPC | `ctx` / notes |
| -------------------------------- | ----------------------------------- | ------------------------------------------------ | ----------------------------------------------------- |
| 0 `IPC_FANOUT` | `BARE_OS_IPC_FANOUT` | `/run/bare-os/ipc/` | `bareOsIpc` |
docs/reference/kernel-extensions.md
+49 -53
View File
@@ -26,55 +26,53 @@ Seed RPC **`bare_os.capabilities`** includes **`protocolPackageVersion`**, optio
## Environment quick reference
| Area | Variable | Effect |
| --------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Seed handshake | `BARE_OS_SEED_RPC_HANDSHAKE=0` | Skip `bare_os.capabilities` RPC before MBR read |
| Seed strict | `BARE_OS_SEED_CAP_STRICT=1` | Fail boot if seeder feature bits do not cover stock booter bits |
| Seed fail | `BARE_OS_SEED_CAP_FAIL=1` | Fail boot on any handshake error |
| Pipelines | `BARE_OS_SHELL_STREAMING=1` | Multiply pipeline byte/line caps (`BARE_OS_SHELL_STREAMING_MULT`, default 4×) |
| Command subst | `BARE_OS_SHELL_CMDSUBST=1` | Enable bounded `$(…)` in words (`BARE_OS_SHELL_CMDSUBST_MAX_BYTES`) |
| 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 |
| 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 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)) |
| Proc poll | `BARE_OS_PROC_POLL_MS` | Min interval 250ms, max 60s, for coalesced **`/proc/bare_os/metrics_live.json`** |
| 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`** |
| 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`**) |
| 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 |
| 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 `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`, `bootPhasesRequireProcIndexMinSchema`, stricter extension depth / cycle diagnostics; **v10** `requireKernelCapabilitiesPearInspectLoggerTls`, `requireBareBootMin`, `denyBareRpcMethodPatterns`, `maxPearInspectDepth`, `requireBareLoggerMin`, `denyAutobaseDiscoveryChannels`, `requireBareTlsMin`, `extensionSignerPinsV3`, `offlineLkgRequirePearStamp`, `bootPhasesRequireLifecycleMinSchema` |
| Boot policy strict | `BARE_OS_BOOT_POLICY_STRICT=1` | Abort boot when policy checks fail |
| Lazy personal drive | `BARE_OS_LAZY_PERSONAL_DRIVE=1` | Mount personal Hyperdrive at session setup instead of immediately after kernel fetch |
| System revision | `BARE_OS_SYSTEM_REVISION_ID`, `BARE_OS_SYSTEM_REVISION_PENDING`, `BARE_OS_SYSTEM_SLOT` | Exposed as `ctx.bareOsSystemRevision` (Pear OTA–style hints) |
| Delegates | `BARE_OS_DELEGATE_ALLOW` | Comma list: `git`, `curl`, `wget`, `systemctl` (empty = all) |
| DNS | `BARE_OS_DNS_ALLOWLIST` | Host allowlist for curl/wget http(s) URLs (`*.suffix` supported) |
| IPC namespace | `BARE_OS_IPC_NAMESPACE` | Prefix FIFO keys as `<ns>__<name>` for isolation |
| Kernel hot reload | `BARE_OS_KERNEL_HOT_RELOAD=1` | Dev: `ctx.bareOsRequestKernelReload()` re-reads `/boot/init.js` |
| Kernel profile warm | `BARE_OS_KERNEL_PROFILE_WARM=1` | Dev: `ctx.bareOsRequestKernelProfileReload()` re-reads `/boot/init.js` (same loop as hot reload) |
| Host `bare-os` proc | `BARE_OS_HOST_BARE_OS_PROC=1`, `BARE_OS_HOST_OS_JSON` | `/proc/bare_os/host_os.json` snapshot |
| Replication windows | `BARE_OS_REPLICATION_SYNC_WINDOWS` | UTC `HH:MM-HH:MM` ranges; `/proc/bare_os/sync_window.json`; sets `BARE_OS_REPLICATION_SYNC_WINDOW_ACTIVE` |
| Kernel debug proc | `BARE_OS_KERNEL_DEBUG=1` | `/proc/bare_os/debug.json` (masks only, no secrets) |
| Transport stats | `BARE_OS_NET_TRANSPORT_STATS_JSON` | JSON merged into `/proc/bare_os/net_summary.json` `transport` |
| Subprocess bridge v2 | `BARE_OS_SUBPROCESS_BRIDGE_META_JSON` | `ctx.bareOsReadSubprocessBridgeSnapshot()` meta (`supportedSignals`, `cgroupRootHint`, …) |
| HDMS support id | `BARE_OS_HDMS_SUPPORT_CORRELATION_ID` | Non-secret string in `/proc/bare_os/hdms_hints.json` |
| 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) |
- Seed handshake — `BARE_OS_SEED_RPC_HANDSHAKE=0` — Skip `bare_os.capabilities` RPC before MBR read
- Seed strict — `BARE_OS_SEED_CAP_STRICT=1` — Fail boot if seeder feature bits do not cover stock booter bits
- Seed fail — `BARE_OS_SEED_CAP_FAIL=1` — Fail boot on any handshake error
- Pipelines — `BARE_OS_SHELL_STREAMING=1` — Multiply pipeline byte/line caps (`BARE_OS_SHELL_STREAMING_MULT`, default 4×)
- Command subst — `BARE_OS_SHELL_CMDSUBST=1` — Enable bounded `$(…)` in words (`BARE_OS_SHELL_CMDSUBST_MAX_BYTES`)
- 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
- 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 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))
- Proc poll — `BARE_OS_PROC_POLL_MS` — Min interval 250ms, max 60s, for coalesced **`/proc/bare_os/metrics_live.json`**
- 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`**
- 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`**)
- 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
- 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 `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`, `bootPhasesRequireProcIndexMinSchema`, stricter extension depth / cycle diagnostics; **v10** `requireKernelCapabilitiesPearInspectLoggerTls`, `requireBareBootMin`, `denyBareRpcMethodPatterns`, `maxPearInspectDepth`, `requireBareLoggerMin`, `denyAutobaseDiscoveryChannels`, `requireBareTlsMin`, `extensionSignerPinsV3`, `offlineLkgRequirePearStamp`, `bootPhasesRequireLifecycleMinSchema`
- Boot policy strict — `BARE_OS_BOOT_POLICY_STRICT=1` — Abort boot when policy checks fail
- Lazy personal drive — `BARE_OS_LAZY_PERSONAL_DRIVE=1` — Mount personal Hyperdrive at session setup instead of immediately after kernel fetch
- System revision — `BARE_OS_SYSTEM_REVISION_ID`, `BARE_OS_SYSTEM_REVISION_PENDING`, `BARE_OS_SYSTEM_SLOT` — Exposed as `ctx.bareOsSystemRevision` (Pear OTA–style hints)
- Delegates — `BARE_OS_DELEGATE_ALLOW` — Comma list: `git`, `curl`, `wget`, `systemctl` (empty = all)
- DNS — `BARE_OS_DNS_ALLOWLIST` — Host allowlist for curl/wget http(s) URLs (`*.suffix` supported)
- IPC namespace — `BARE_OS_IPC_NAMESPACE` — Prefix FIFO keys as `<ns>__<name>` for isolation
- Kernel hot reload — `BARE_OS_KERNEL_HOT_RELOAD=1` — Dev: `ctx.bareOsRequestKernelReload()` re-reads `/boot/init.js`
- Kernel profile warm — `BARE_OS_KERNEL_PROFILE_WARM=1` — Dev: `ctx.bareOsRequestKernelProfileReload()` re-reads `/boot/init.js` (same loop as hot reload)
- Host `bare-os` proc — `BARE_OS_HOST_BARE_OS_PROC=1`, `BARE_OS_HOST_OS_JSON` — `/proc/bare_os/host_os.json` snapshot
- Replication windows — `BARE_OS_REPLICATION_SYNC_WINDOWS` — UTC `HH:MM-HH:MM` ranges; `/proc/bare_os/sync_window.json`; sets `BARE_OS_REPLICATION_SYNC_WINDOW_ACTIVE`
- Kernel debug proc — `BARE_OS_KERNEL_DEBUG=1` — `/proc/bare_os/debug.json` (masks only, no secrets)
- Transport stats — `BARE_OS_NET_TRANSPORT_STATS_JSON` — JSON merged into `/proc/bare_os/net_summary.json` `transport`
- Subprocess bridge v2 — `BARE_OS_SUBPROCESS_BRIDGE_META_JSON` — `ctx.bareOsReadSubprocessBridgeSnapshot()` meta (`supportedSignals`, `cgroupRootHint`, …)
- HDMS support id — `BARE_OS_HDMS_SUPPORT_CORRELATION_ID` — Non-secret string in `/proc/bare_os/hdms_hints.json`
- 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)
## Wave 6 summary
@@ -94,10 +92,8 @@ Shipped as **`bits11`** + **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_HYPERCORE_PACK_H
## POSIX utility notes
| Utility | Notes |
| ------- | ---------------------------------------------------- |
| `cmp` | Two-file byte compare; exit 1 on difference |
| `wait` | Shell builtin: wait for background jobs by id or all |
- `cmp` — Two-file byte compare; exit 1 on difference
- `wait` — Shell builtin: wait for background jobs by id or all
## Cookbook snippets
docs/reference/out-of-scope-and-tooling.md
+5 -7
View File
@@ -12,10 +12,8 @@ Former **DOCUMENTATION.md** §§15–16. [Reference index →](README.md)
## 16. Version and tooling summary
| Tool | Role |
| ----------------- | ------------------------------------------------------------ |
| Node.js 20+ | Install, `brittle-node` tests, `node index.js` dev runs |
| Bare ≥2 (engines) | Intended runtime for `pear run` / `bare index.js` |
| Prettier | Format/lint at root |
| Brittle | Test runner (`brittle-bare` protocol, `brittle-node` booter) |
| GitHub Actions | `npm ci` + `npm test` on `main` |
- Node.js 20+ — Install, `brittle-node` tests, `node index.js` dev runs
- Bare ≥2 (engines) — Intended runtime for `pear run` / `bare index.js`
- Prettier — Format/lint at root
- Brittle — Test runner (`brittle-bare` protocol, `brittle-node` booter)
- GitHub Actions — `npm ci` + `npm test` on `main`
docs/reference/package-bare-os-booter.md
+7 -9
View File
@@ -6,15 +6,13 @@ Former **DOCUMENTATION.md** §§12.1–12.9 (runtime, VFS, shell, identity). [Re
### 12.1 [packages/bare-os-booter/package.json](../../packages/bare-os-booter/package.json)
| Item | Detail |
| ----------------------- | ---------------------------------------------------------------------------------------------- |
| `main` | `./index.js` |
| `scripts.start` / `dev` | `bare index.js` |
| `scripts.test` | `brittle-node test.js` |
| `dependencies` | Same hyperstack as seeder + `bare-os-protocol` + `bare-crypto` (identity account + vault AEAD) |
| `devDependencies` | `brittle` |
| `imports` | `path`, `url`, `node:url` Bare/Node conditional |
| `pear.stage.ignore` | Includes `test.js`, `test.identity.js`, `.test-data` so tests are not staged |
- `main` — `./index.js`
- `scripts.start` / `dev` — `bare index.js`
- `scripts.test` — `brittle-node test.js`
- `dependencies` — Same hyperstack as seeder + `bare-os-protocol` + `bare-crypto` (identity account + vault AEAD)
- `devDependencies` — `brittle`
- `imports` — `path`, `url`, `node:url` Bare/Node conditional
- `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/<app>/node_modules` by symlinking **each top-level** package from the root `node_modules` (matching npm’s flat hoist), and **`pear.stage.includes`** lists **`../../node_modules`** so staging can pull hoisted deps. **`npm run os:booter`** / **`npm run os:seeder`** run the script before `pear run`. After `npm install` at the root, re-run the script if hoisted packages change.
docs/reference/package-bare-os-protocol.md
+18 -22
View File
@@ -6,19 +6,17 @@ Former **DOCUMENTATION.md** §10. [Reference index →](README.md)
### 10.1 [packages/bare-os-protocol/package.json](../../packages/bare-os-protocol/package.json)
| Item | Detail |
| --------------------------- | -------------------------------------------------------------------------- |
| `name` | `bare-os-protocol` |
| `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` |
| `scripts.test` | `brittle-bare test.js` |
| `scripts.test:node` | `brittle-node test.js` |
| `engines.bare` | `>=2.0.0` |
| `dependencies` | `b4a`, `compact-encoding`, `hypercore-crypto` |
| `devDependencies` | `brittle` |
| `imports` | Conditional `fs` / `path` / `events` → `bare-*` under Bare, Node `default` |
- `name` — `bare-os-protocol`
- `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`
- `scripts.test` — `brittle-bare test.js`
- `scripts.test:node` — `brittle-node test.js`
- `engines.bare` — `>=2.0.0`
- `dependencies` — `b4a`, `compact-encoding`, `hypercore-crypto`
- `devDependencies` — `brittle`
- `imports` — Conditional `fs` / `path` / `events` → `bare-*` under Bare, Node `default`
### 10.2 [packages/bare-os-protocol/index.js](../../packages/bare-os-protocol/index.js)
@@ -32,15 +30,13 @@ Re-exports **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_*`** stock masks and **`BARE_OS
### 10.3 [packages/bare-os-protocol/constants.js](../../packages/bare-os-protocol/constants.js)
| Export | Definition |
| ------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `PROTOCOL_NAME` | `'bare-os-v1'` — Protomux channel name |
| `TOPIC_STRING` | `'bare-os-v1'` — input to swarm topic hash |
| `BLOCK_SIZE` | `512` — MBR size |
| `MBR_MAGIC` | `b4a.from('BIOS')` — first 4 bytes of MBR |
| `topicKey(b4aMod?)` | `crypto.hash(b4aMod.from(TOPIC_STRING))` — 32-byte Hyperswarm topic |
| `buildMbr(primaryKey, failoverKeys?)` | Allocates 512 bytes, writes magic at 0, primary 32-byte key at offset 8, optional keys at 40 and 72 |
| `parseMbr(mbr)` | Validates length ≥ 104, magic `BIOS`, returns `{ keys: Uint8Array[] }` (non-zero 32-byte slots) |
- `PROTOCOL_NAME` — `'bare-os-v1'` — Protomux channel name
- `TOPIC_STRING` — `'bare-os-v1'` — input to swarm topic hash
- `BLOCK_SIZE` — `512` — MBR size
- `MBR_MAGIC` — `b4a.from('BIOS')` — first 4 bytes of MBR
- `topicKey(b4aMod?)` — `crypto.hash(b4aMod.from(TOPIC_STRING))` — 32-byte Hyperswarm topic
- `buildMbr(primaryKey, failoverKeys?)` — Allocates 512 bytes, writes magic at 0, primary 32-byte key at offset 8, optional keys at 40 and 72
- `parseMbr(mbr)` — Validates length ≥ 104, magic `BIOS`, returns `{ keys: Uint8Array[] }` (non-zero 32-byte slots)
### 10.4 [packages/bare-os-protocol/lib/messages.js](../../packages/bare-os-protocol/lib/messages.js)
docs/reference/package-bare-os-seeder.md
+7 -9
View File
@@ -6,15 +6,13 @@ Former **DOCUMENTATION.md** §11. [Reference index →](README.md)
### 11.1 [packages/bare-os-seeder/package.json](../../packages/bare-os-seeder/package.json)
| Item | Detail |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `main` | `./index.js` |
| `scripts.start` / `dev` | `bare index.js` (Pear/Bare entry) |
| `dependencies` | `bare-os-protocol` (workspace `*`), `b4a`, `compact-encoding`, `corestore`, `hyperdrive`, `hyperswarm`, `protomux`, `safety-catch` |
| `engines.bare` | `>=2.0.0` |
| `pear.name` | `bare-os-seeder` |
| `pear.stage.ignore` | `.git`, `test`, `coverage`, `.DS_Store`, `node_modules/.bin`, `node_modules/.package-lock.json` |
| `imports` | `fs`, `fs/promises`, `path`, `url`, `node:url` — Bare vs `node:` shims |
- `main` — `./index.js`
- `scripts.start` / `dev` — `bare index.js` (Pear/Bare entry)
- `dependencies` — `bare-os-protocol` (workspace `*`), `b4a`, `compact-encoding`, `corestore`, `hyperdrive`, `hyperswarm`, `protomux`, `safety-catch`
- `engines.bare` — `>=2.0.0`
- `pear.name` — `bare-os-seeder`
- `pear.stage.ignore` — `.git`, `test`, `coverage`, `.DS_Store`, `node_modules/.bin`, `node_modules/.package-lock.json`
- `imports` — `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)
docs/reference/repo-layout-and-root.md
+12 -14
View File
@@ -89,20 +89,18 @@ bare-operating-system/
## 2. Root: [package.json](../../package.json)
| Field | Value / meaning |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | `bare-operating-system` |
| `private` | `true` — not published as a single npm package |
| `type` | `module` — ESM |
| `workspaces` | `["packages/*"]` — npm workspaces (protocol, coreutils, seeder, booter, …) |
| `scripts.pretest` | Runs `bare-os-coreutils` + `bare-os-bare-libs` builds, kernel/seeder parity, [`smoke:bare-manifest`](../../scripts/smoke-bare-manifest-imports.mjs) |
| `scripts.gen:bare-catalog` | Refresh [`docs/bare-holepunch-catalog.json`](../bare-holepunch-catalog.json) from GitHub + npm (see [Chapter 12](../../developer-guide/12-bare-modules-and-pear-ecosystem.md)) |
| `scripts.sync:bare-manifest` | Apply catalog → [`bare-module-manifest.json`](../../packages/bare-os-booter/lib/bare-module-manifest.json) + booter `optionalDependencies` |
| `scripts.test` | Runs `npm run test --workspaces --if-present` |
| `scripts.format` | `prettier --write .` |
| `scripts.lint` | `prettier --check .` |
| `engines.node` | `>=20` |
| `devDependencies` | `prettier@^3.4.2` |
- `name` — `bare-operating-system`
- `private` — `true` — not published as a single npm package
- `type` — `module` — ESM
- `workspaces` — `["packages/*"]` — npm workspaces (protocol, coreutils, seeder, booter, …)
- `scripts.pretest` — Runs `bare-os-coreutils` + `bare-os-bare-libs` builds, kernel/seeder parity, [`smoke:bare-manifest`](../../scripts/smoke-bare-manifest-imports.mjs)
- `scripts.gen:bare-catalog` — Refresh [`docs/bare-holepunch-catalog.json`](../bare-holepunch-catalog.json) from GitHub + npm (see [Chapter 12](../../developer-guide/12-bare-modules-and-pear-ecosystem.md))
- `scripts.sync:bare-manifest` — Apply catalog → [`bare-module-manifest.json`](../../packages/bare-os-booter/lib/bare-module-manifest.json) + booter `optionalDependencies`
- `scripts.test` — Runs `npm run test --workspaces --if-present`
- `scripts.format` — `prettier --write .`
- `scripts.lint` — `prettier --check .`
- `engines.node` — `>=20`
- `devDependencies` — `prettier@^3.4.2`
No runtime dependencies at the root; all stack deps live in workspace packages.
docs/themes/README.md
Vendored
+23 -9
View File
@@ -6,21 +6,35 @@ They are **authored in-repo** for consistency with [`bare-os-theme-presets.js`](
Naming follows common patterns (similar in spirit to catalogs like [terminalcolors.com](https://terminalcolors.com/)): `alacritty-<preset>.yml`, `warp-<preset>.yaml`, `iterm-<preset>.itermcolors`.
| File | Preset | Format | Import |
|------|--------|--------|--------|
| `alacritty-nord.yml` | `nord` | [Alacritty](https://github.com/alacritty/alacritty) YAML | Merge `colors:` into `alacritty.yml` |
| `alacritty-dracula.yml` | `dracula` | Alacritty YAML | Same |
| `warp-nord.yaml` | `nord` | [Warp](https://docs.warp.dev/appearance/custom-themes) | Theme picker / path |
| `warp-dracula.yaml` | `dracula` | Warp | Same |
| `iterm-nord.itermcolors` | `nord` | iTerm2 / Terminal.app | **Profiles → Colors → Color Presets → Import** |
| `iterm-dracula.itermcolors` | `dracula` | iTerm2 / Terminal.app | Same |
---
Additional presets (`gruvbox_dark`, `tokyo_night`, `catppuccin_mocha`, …) can be added here using the same filenames; contributions should keep parity with the JS preset names.
## On this page
- [Bundled theme files](#bundled-theme-files)
- [Preset names](#preset-names)
- [Related session variables](#related-session-variables)
---
## Bundled theme files
- **`alacritty-nord.yml`** — Preset **`nord`**. [Alacritty](https://github.com/alacritty/alacritty) YAML. **Import:** merge the `colors:` block into your `alacritty.yml`.
- **`alacritty-dracula.yml`** — Preset **`dracula`**. Alacritty YAML. **Import:** same as above.
- **`warp-nord.yaml`** — Preset **`nord`**. [Warp](https://docs.warp.dev/appearance/custom-themes) theme. **Import:** use Warp’s theme picker or point it at this path.
- **`warp-dracula.yaml`** — Preset **`dracula`**. Warp. **Import:** same as above.
- **`iterm-nord.itermcolors`** — Preset **`nord`**. iTerm2 / Terminal.app. **Import:** **Profiles → Colors → Color Presets → Import**.
- **`iterm-dracula.itermcolors`** — Preset **`dracula`**. iTerm2 / Terminal.app. **Import:** same as above.
Additional presets (`gruvbox_dark`, `tokyo_night`, `catppuccin_mocha`, …) can be added here using the same filenames; contributions should keep parity with the JavaScript preset names in the booter.
---
## Preset names
Run `theme list` in a Bare OS shell. Examples: `default`, `nord`, `dracula`, `gruvbox_dark`, `catppuccin_mocha`, `tokyo_night`, `github_dark`, `solarized_dark`.
---
## Related session variables
See [environment variables reference](../reference/environment-and-posix-appendix.md#14-environment-variables-complete-list): `BARE_OS_THEME`, `BARE_OS_COLOR_DEPTH`, `LS_COLORS`, `BARE_OS_DIRCOLORS`, and host passthrough `TERM` / `COLORTERM`.