feat: kernel roadmap wave — bits4, policy v4, Pear/Bare compatibility
- protocol/booter: bits4 handshake, proc surfaces, boot policy v4, telemetry v4 - coreutils: nohup + ensure-man-pages; seed-man-pages fixes for extra pages - kernel-runner: no static node:module (Pear); bare-module createRequire - docs: handbook, reference, ADR, compatibility matrix, verify scripts
This commit is contained in:
Raven Scott
@@ -84,7 +84,7 @@ The **important** path for boot is **0/1** + **Hyperdrive replication** on the s
|
||||
|
||||
## Kernel feature bitmask (documentation)
|
||||
|
||||
The package **`bare-os-protocol`** exports **`lib/kernel-feature-bits.js`** (re-exported from **`index.js`**) with **versioned capability words** describing optional booter / image capabilities (word 1: **`bits`**, word 2: **`bits2`**, word 3: **`bits3`**; always **`>>> 0`** when masking). Peers see a **250-byte bitfield** on **message 2** (gossip stub; bit **0** set today). The seeder answers **`bare_os.capabilities`** over **RPC** with **`doc`** / **`featureBitsDoc`**, **`bits`**, **`bits2`**, **`bits3`**, **`protocolPackageVersion`**, **`role`**, **`protocol`** so the booter can compare before MBR read (**`BARE_OS_SEED_CAP_STRICT`** covers all non-zero words the stock booter advertises). **`bare_os.replication_status`** adds seeder-local replication hints; **`bare_os.replication_queue`**, **`bare_os.capability_attestation`**, **`bare_os.mbr_layout`**, **`bare_os.snapshot_hints`**, and **`bare_os.peer_firewall_stats`** are optional RPCs (hints only; guests do not verify crypto). **`mbr_layout`** / replication JSON may surface parsed **failover key slots** (MBR offsets **40** / **72**) as hex hints for operators, plus optional **staging slot**, **manifest**, **peer health**, and **firewall** sketches when the seeder implements them. Guests read dumps under **`/proc/bare_os_features`**, **`/proc/bare_os/`**, and related **`/proc`** nodes. Unknown bits should be ignored.
|
||||
The package **`bare-os-protocol`** exports **`lib/kernel-feature-bits.js`** (re-exported from **`index.js`**) with **versioned capability words** describing optional booter / image capabilities (word 1: **`bits`**, word 2: **`bits2`**, word 3: **`bits3`**, word 4: **`bits4`**; always **`>>> 0`** when masking). Peers see a **250-byte bitfield** on **message 2** (gossip stub; bit **0** set today). The seeder answers **`bare_os.capabilities`** over **RPC** with **`doc`** / **`featureBitsDoc`**, **`bits`**, **`bits2`**, **`bits3`**, **`bits4`**, **`protocolPackageVersion`**, **`role`**, **`protocol`** so the booter can compare before MBR read (**`BARE_OS_SEED_CAP_STRICT`** covers all non-zero words the stock booter advertises). **`bare_os.replication_status`** adds seeder-local replication hints; **`bare_os.replication_queue`**, **`bare_os.capability_attestation`**, **`bare_os.mbr_layout`**, **`bare_os.snapshot_hints`**, and **`bare_os.peer_firewall_stats`** are optional RPCs (hints only; guests do not verify crypto). **`mbr_layout`** / replication JSON may surface parsed **failover key slots** (MBR offsets **40** / **72**) as hex hints for operators, plus optional **staging slot**, **manifest**, **peer health**, and **firewall** sketches when the seeder implements them. Guests read dumps under **`/proc/bare_os_features`**, **`/proc/bare_os/`**, and related **`/proc`** nodes. Unknown bits should be ignored.
|
||||
|
||||
Authoritative tables: [Kernel extensions](../docs/reference/kernel-extensions.md).
|
||||
|
||||
|
||||
@@ -76,7 +76,7 @@ Catalog detail: [Chapter 9](09-posix-utilities-shell-and-vfs.md).
|
||||
|
||||
These paths are **synthetic** (not stored on either Hyperdrive). They exist for inspection and scripting ergonomics, **not** Linux ABI compatibility. In **blog terms**: **`/proc`** is “what is this session doing?”; **`/sys`** is “tiny sysfs-shaped stubs”; **`/run`** is “volatile session state the booter owns”; **`/dev`** is “just enough device names that scripts stop crashing”; session **`/tmp`** is “scratch space that never lands on the read-only system drive.”
|
||||
|
||||
- **`/proc`**: **`version`**, **`bare_os_version`**, **`uptime`**, **`meminfo`**, **`cpuinfo`**, **`loadavg`**, **`mounts`**, **`diskstats`** (stub text), **`bare_os_quotas`** (JSON: pipeline limits, exec-depth cap, IPC cap, session stats, FIFO **`stats`**), **`bare_os_resources`**, **`bare_os_features`** (includes **`bits2`** / **`bits3`**, optional **`seedHandshake`** summary after **`bare_os.capabilities`** RPC when enabled), **`bare_os_swarm`** (bounded P2P / session snapshot when the host provides it), **`bare_os_replication`** (JSON hints: version, peers, last error; may embed **`manifestHints`**, **`peerHealth`**, **`stagingSlot`**, **`seedSnapshotHints`**, **`seedPeerFirewallStats`**, **`seedReplication`**, **`mbrKeysHex`** from seed RPCs), **`bare_os_manifest_hints`**, **`bare_os_peer_health`**, **`bare_os_staging_slot`**, **`bare_os_snapshot_hints`**, **`bare_os_provenance`** (digest / signing / Pear channel summary), **`bare_os_pear_ipc_registry`** (well-known Pear IPC channel names), **`bare_os_pear_trust`** (operator JSON from **`BARE_OS_PEAR_TRUST_JSON`**), **`bare_os_initd_dag`** / **`bare_os_initd_graph`** (initd dependency graph JSON; graph may include a **`dot`** string), **`bare_os_rlimits`** (getrlimit-shaped mirror of runtime caps), **`bare_os_hdms_health`** (non-secret mount/registry summary), **`bare_os_metrics_live`** (coalesced quotas/resources snapshot; interval **`BARE_OS_PROC_POLL_MS`**), **`bare_os_extensions.json`** / **`bare_os_hdms_hints.json`** (kernel extension registry + HDMS/autopass hints), **`bare_os_capabilities`** (human-readable dump of **`ctx.bareOsRuntimeCaps`**; **`bare_os_capabilities.json`** or **`Accept: application/json`** for machine output), **`bare_os_bootstrap`**, **`bare_os_union`** (JSON: union read prefixes + **`BARE_OS_VFS_UNION_WRITE_DENY`**), **`bare_os_seed_handshake`** (raw handshake / error object), **`bare_os_virtual_registry`** (registered virtual file metadata), **`/proc/bare_os/`** (stable names + **`index.json`** mirroring the flat **`bare_os_*`** aliases), **`net/dev`** (P2P-oriented stub), **`net/tcp`**, **`net/udp`** (header-only stubs), **`self/`** with **`environ`**, **`cmdline`**, **`cgroups`**, **`exe`**, **`fd/0`–`2`** (stub targets), plus **`bare_os_session_stats`**. **`environ`** omits keys whose names look secret-bearing (e.g. **`PASSWORD`**, **`TOKEN`**, **`VAULT`**) and only includes a small public set plus **`BARE_OS_*`** (including **`BARE_OS_SESSION_ID`**).
|
||||
- **`/proc`**: **`version`**, **`bare_os_version`**, **`uptime`**, **`meminfo`**, **`cpuinfo`**, **`loadavg`**, **`mounts`**, **`diskstats`** (stub text), **`bare_os_quotas`** (JSON: pipeline limits, exec-depth cap, IPC cap, session stats, FIFO **`stats`**), **`bare_os_resources`**, **`bare_os_features`** (includes **`bits2`** / **`bits3`** / **`bits4`**, optional **`seedHandshake`** summary after **`bare_os.capabilities`** RPC when enabled), **`bare_os_swarm`** (bounded P2P / session snapshot when the host provides it), **`bare_os_replication`** (JSON hints: version, peers, last error; may embed **`manifestHints`**, **`peerHealth`**, **`stagingSlot`**, **`seedSnapshotHints`**, **`seedPeerFirewallStats`**, **`seedReplication`**, **`mbrKeysHex`** from seed RPCs), **`bare_os_manifest_hints`**, **`bare_os_peer_health`**, **`bare_os_staging_slot`**, **`bare_os_snapshot_hints`**, **`bare_os_provenance`** (digest / signing / Pear channel summary), **`bare_os_pear_ipc_registry`** (well-known Pear IPC channel names), **`bare_os_pear_trust`** (operator JSON from **`BARE_OS_PEAR_TRUST_JSON`**), **`bare_os_initd_dag`** / **`bare_os_initd_graph`** (initd dependency graph JSON; graph may include a **`dot`** string), **`bare_os_rlimits`** (getrlimit-shaped mirror of runtime caps), **`bare_os_hdms_health`** (non-secret mount/registry summary), **`bare_os_metrics_live`** (coalesced quotas/resources snapshot; interval **`BARE_OS_PROC_POLL_MS`**; schema **2** adds delegate inflight / rate-bucket samples), **`bare_os_net_summary`** (operator rollup of swarm topic, peer count, seed RPC hints), **`bare_os_extensions.json`** / **`bare_os_hdms_hints.json`** (kernel extension registry + HDMS/autopass hints), **`bare_os_capabilities`** (human-readable dump of **`ctx.bareOsRuntimeCaps`**; **`bare_os_capabilities.json`** or **`Accept: application/json`** for machine output), **`bare_os_bootstrap`**, **`bare_os_union`** (JSON: union read prefixes + **`BARE_OS_VFS_UNION_WRITE_DENY`**), **`bare_os_seed_handshake`** (raw handshake / error object), **`bare_os_virtual_registry`** (registered virtual file metadata), **`/proc/bare_os/`** (stable names + **`index.json`** mirroring the flat **`bare_os_*`** aliases), **`net/dev`** (P2P-oriented stub), **`net/tcp`**, **`net/udp`** (header-only stubs), **`self/`** with **`environ`**, **`cmdline`**, **`cgroups`**, **`exe`**, **`fd/0`–`2`** (stub targets), plus **`bare_os_session_stats`**. **`environ`** omits keys whose names look secret-bearing (e.g. **`PASSWORD`**, **`TOKEN`**, **`VAULT`**) and only includes a small public set plus **`BARE_OS_*`** (including **`BARE_OS_SESSION_ID`**).
|
||||
- **`/sys`**: **`fs/bare_os/version`**, **`fs/bare_os/build_id`**, **`class/net/lo`** (stub **`operstate`** / **`carrier`**), **`devices/virtual/`** (placeholder tree for script portability).
|
||||
- **`/sys/fs/bare_os/version`**: same text as **`/proc/version`**.
|
||||
- **`/run/bare-os/units`**: tab-separated snapshot of **bare-initd** registered units (phase, start time, description).
|
||||
|
||||
@@ -63,7 +63,7 @@ The **prompt** (`[user@host:path] > `) is applied by the booter’s readline lay
|
||||
| **`BARE_OS_BOOT_MANIFEST`** | When **`1`** / **`true`**, the stock kernel verifies **`/etc/bare-os/boot.manifest.json`** against an expected SHA-256 (see kernel **`init.js`** and **`ctx.bareOsBootFileSha256Hex`**). Example layout: [`kernel/etc/bare-os/boot.manifest.example.json`](../kernel/etc/bare-os/boot.manifest.example.json). |
|
||||
| **`BARE_OS_BOOT_MANIFEST_SIGN`**, **`BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`** | Optional **Ed25519** over the **raw manifest bytes**: expects **`/etc/bare-os/boot.manifest.sig`** and **`ctx.bareOsVerifyBootManifestSignature`** (host/booter). Mismatch fails boot with a clear stderr line. |
|
||||
| **`ctx.bareOsRegisterBootPhaseHook` / `bareOsInvokeBootPhaseHooks`** | Kernel extensions can observe **`before:` / `after:`** stock phases (e.g. **`rc`**, **`repl`**) without replacing **`init.js`**. See [developer guide §2](../developer-guide/02-the-context-object.md). |
|
||||
| **`BARE_OS_BOOT_POLICY`**, **`/etc/bare-os/boot.policy.json`** | When enabled, merges **`skipPhases`**, **`denyBootPhases`**, optional **`minKernelFeatureMask`** / **`requireSeedCaps`**, v2 **`maxExecLineDepth`** / **`denyEnvKeys`** / **`requireProcNodes`**, and v3 **`requireFeatureBits2`** / **`requireFeatureBits3`**, **`allowedPearIpcChannels`**, **`denyVfsPrefixes`**, **`maxInitdRestartsPerUnit`** (see **[`kernel/etc/bare-os/boot.policy.example.json`](../kernel/etc/bare-os/boot.policy.example.json)** and **[`docs/schemas/boot.policy.schema.json`](../docs/schemas/boot.policy.schema.json)**). **`BARE_OS_BOOT_POLICY_STRICT`** aborts when a check fails. |
|
||||
| **`BARE_OS_BOOT_POLICY`**, **`/etc/bare-os/boot.policy.json`** | When enabled, merges **`skipPhases`**, **`denyBootPhases`**, optional **`minKernelFeatureMask`** / **`requireSeedCaps`**, v2 **`maxExecLineDepth`** / **`denyEnvKeys`** / **`requireProcNodes`**, v3 **`requireFeatureBits2`** / **`requireFeatureBits3`**, **`allowedPearIpcChannels`**, **`denyVfsPrefixes`**, **`maxInitdRestartsPerUnit`**, and v4 **`requireFeatureBits4`**, **`denyExecLineBuiltins`**, **`allowedCtxMethods`** (see **[`kernel/etc/bare-os/boot.policy.example.json`](../kernel/etc/bare-os/boot.policy.example.json)** and **[`docs/schemas/boot.policy.schema.json`](../docs/schemas/boot.policy.schema.json)**). **`BARE_OS_BOOT_POLICY_STRICT`** aborts when a check fails. |
|
||||
| **`/etc/bare-os/selftest.d/`** | Optional digit-prefixed **`*.sh`** snippets run after the main boot path when **`BARE_OS_KERNEL_SELFTEST`** is enabled (same **`execLine`** rules as other boot snippets). Pair with **`BARE_OS_SELFTEST_FORMAT=tap`** for CI-friendly stderr. |
|
||||
|
||||
### Custom `init.js` contract
|
||||
|
||||
@@ -283,6 +283,17 @@ There is still **no `import`** in **`src/*.js`** — large utilities are **vendo
|
||||
|
||||
---
|
||||
|
||||
## 8.5 Shell cookbook (without full POSIX `sh`)
|
||||
|
||||
The line shell does **not** support subshells, full **`sh`** grammar, or real background processes. Prefer these patterns:
|
||||
|
||||
- **Sequential steps** — One **`execLine`** per line in **`rc`** / **`rc.d`** (trusted), or **`;`** / **`&&`** in the REPL.
|
||||
- **Capture output** — Pipelines and **`VAR=$(command)`** (when **`BARE_OS_SHELL_CMDSUBST=1`**) instead of POSIX command groups.
|
||||
- **Conditionals** — Bounded **`if` / `fi`** (see §3); for complex logic, call a **`/bin`** helper script on the system image.
|
||||
- **Boot policy** — **`denyExecLineBuiltins`** in **`boot.policy.json`** (v4) maps to **`BARE_OS_BOOT_POLICY_DENY_EXEC_LINE_BUILTINS`** to block specific builtins (e.g. **`login`**) on locked-down images.
|
||||
|
||||
---
|
||||
|
||||
## 9. Where to read next
|
||||
|
||||
- [Chapter 6 — Kernel and `/bin` summary](06-kernel-and-binaries.md)
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
# Chapter 11 — Roadmap, ecosystem, and non-goals
|
||||
|
||||
**Time to read:** one pass. **Prerequisites:** [Preface](00-preface.md), [Chapter 3 — Protocol](03-protocol-and-disk.md).
|
||||
|
||||
---
|
||||
|
||||
## Why this chapter exists
|
||||
|
||||
Bare OS sits at the intersection of **Pear** (packaging and desktop hosts), **Bare** (embedded-first JS runtime and modules), and **Holepunch** stacks (**Hyperswarm**, **HyperDHT** holepunch, **Hyperdrive**). This chapter names **research directions** and **intentional limits** so distributors know what the project will and will not become.
|
||||
|
||||
---
|
||||
|
||||
## Ecosystem map (local clones)
|
||||
|
||||
If you maintain a checkout of **[holepunch-repos](https://github.com/holepunchto)** (or a mirror), useful adjacencies include:
|
||||
|
||||
| Area | Examples | Relevance |
|
||||
| --- | --- | --- |
|
||||
| Runtime / packaging | `pear-runtime`, `pear-stage`, `pear-ipc` | Host OTA, IPC, staging |
|
||||
| Bare modules | `bare-subprocess`, `bare-daemon`, `bare-kit`, `bare-storage` | Optional delegates, worklets, storage policy |
|
||||
| Transport | `hyperdht` (holepunch docs), `hyperswarm`, `udx-native` | NAT, relays, stream behavior |
|
||||
|
||||
Nothing in that tree *is* the Bare OS kernel: our **kernel** remains **`/boot/init.js`** on the system Hyperdrive, executed by the **booter**.
|
||||
|
||||
---
|
||||
|
||||
## Feature waves (protocol)
|
||||
|
||||
Capability words **`bits`**, **`bits2`**, **`bits3`**, **`bits4`** (see [`packages/bare-os-protocol`](../packages/bare-os-protocol/README.md)) advertise what the stock booter and seeder implement. **`BARE_OS_SEED_CAP_STRICT`** requires the seeder to cover every non-zero stock word. Governance: [`developer-guide/adr/001-kernel-feature-bits-governance.md`](../developer-guide/adr/001-kernel-feature-bits-governance.md).
|
||||
|
||||
---
|
||||
|
||||
## Intentional non-goals
|
||||
|
||||
- **No hardware MMU kernel** — no ring 0, no real **`fork`**; isolation is policy, caps, and host boundaries.
|
||||
- **No full POSIX `sh`** — line shell with bounded grammar; see [Chapter 9 §8.5](09-posix-utilities-shell-and-vfs.md).
|
||||
- **No single HTTP mirror as source of truth** — image distribution is P2P-first; offline boot is optional **LKG** + local Corestore (**`BARE_OS_OFFLINE_LKG_BOOT`**).
|
||||
|
||||
---
|
||||
|
||||
## Where to read next
|
||||
|
||||
- [Compatibility matrix](../docs/reference/compatibility-matrix.md) — versions in one place
|
||||
- [Kernel extensions](../docs/reference/kernel-extensions.md) — feature / env / proc map
|
||||
- [Handbook home](README.md)
|
||||
|
||||
_Experimental research software, not a production OS. Apache-2.0 — [LICENSE](../LICENSE)._
|
||||
@@ -45,6 +45,7 @@ The **`ctx` object is versioned** for kernels and scripts that depend on booter
|
||||
| [08 — Git on Bare OS](08-git-on-bare-os.md) | isomorphic-git, VFS adapter, HTTP modes |
|
||||
| [09 — POSIX utilities, shell, VFS](09-posix-utilities-shell-and-vfs.md) | XCU-style `/bin`, shell, divergence from Issue 7 |
|
||||
| [10 — Manual pages and online help](10-manpages-and-online-help.md) | `man(1)`, JSON DB, handbook ingest, `help` vs `man` |
|
||||
| [11 — Roadmap and research](11-kernel-roadmap-and-research.md) | Pear/Bare/holepunch context, feature waves, non-goals |
|
||||
|
||||
**Pear workflows, `ctx.bare`, drive bundles:** [developer-guide ch.11](../developer-guide/11-kernel-pear-cookbook.md) and [ch.12](../developer-guide/12-bare-modules-and-pear-ecosystem.md).
|
||||
|
||||
|
||||
Reference in New Issue
Block a user