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

Document that seeder remains the canonical MBR publisher while eligible booted peers can mirror block 0 and captured bare_os seed RPC snapshots for cold joiners.

Browse Source 
Update onboarding, architecture diagrams, package docs, and glossary/FAQ language to keep trust boundaries and availability behavior consistent.
This commit is contained in:
Raven Scott
2026-04-25 21:32:19 -04:00
parent 95c60bb8bf
commit 51b3b97bc0
20 changed files with 74 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/reference/architecture-data-flow.md
+2
View File
@@ -7,6 +7,7 @@ Former **DOCUMENTATION.md** §13. [Reference index →](README.md)
```mermaid
sequenceDiagram
participant Seeder as bare_os_seeder
participant Helper as eligible_booted_peer
participant Swarm as Hyperswarm
participant Booter as bare_os_booter
participant Sys as System_Hyperdrive
@@ -14,6 +15,7 @@ sequenceDiagram
Seeder->>Sys: stage kernel files and MBR key in RAM map
Seeder->>Swarm: join topic plus drive discovery
Helper->>Swarm: optional block 0 and seed RPC mirror
Booter->>Swarm: join topic
Booter->>Seeder: Protomux bare_os_v1
Booter->>Seeder: read block 0 MBR
docs/reference/package-bare-os-booter.md
+4 -1
View File
@@ -75,9 +75,12 @@ See also [Kernel subsystem map](../architecture/kernel-subsystems.md) and [ADR 0
- Optional pre-MBR **`disk.rpc('bare_os', 'capabilities', …)`** when peers exist and **`BARE_OS_SEED_RPC_HANDSHAKE`** is not **`0`**/**`false`**; result stored on **`disk.seedCapabilityInfo`**; **`BARE_OS_SEED_CAP_STRICT`** / **`BARE_OS_SEED_CAP_FAIL`** tighten failure behavior.
- **`disk.read(0)`** → **`parseMbr`**.
- Stores boot provenance as **`disk.mbrKeysHex`** and **`disk.bootMbr512`** (exact 512-byte copy) for later peer-assist eligibility.
- For each MBR key: `Hyperdrive(store, driveKey)`, `ready()`, replicate on all `disk.peers`’ mux streams, join drive discovery, `findingPeers` + `swarm.flush`, poll up to 30×200ms for `/boot/init.js`.
- On success: `initPersonalDrive`, `splash.prepareForKernel()`, `executeKernel`.
Peer-assist helper path: [`lib/bare-os-peer-system-seed.js`](../../packages/bare-os-booter/lib/bare-os-peer-system-seed.js) computes **`peerSystemSeedMirror`** eligibility and builds snapshot mirrors with **`buildPeerSeedSnapshots`** (including **`mbr_layout`** from **`seedMbrLayout`**). When eligible, `index.js` writes **`bootMbr512`** into **`localRAM`** and serves mirrored **`bare_os.*`** RPC responses through **`disk.os`** for cold joiners.
**`main()`**
- `resolveStdio()` → `createBootSplash`, `splash.start()` (initial clear).
@@ -93,7 +96,7 @@ See also [Kernel subsystem map](../architecture/kernel-subsystems.md) and [ADR 0
**`SwarmDisk` class**
**State:** `localRAM`, `peers` (Set of `{ chan, mux, socket, id }`), `pendingReads`, `pendingSearches`, `pendingRpc`, counters, `drive`, `personalDrive`, `os`, **`seedCapabilityInfo`** (last **`bare_os.capabilities`** handshake or error object).
**State:** `localRAM`, `peers` (Set of `{ chan, mux, socket, id }`), `pendingReads`, `pendingSearches`, `pendingRpc`, counters, `drive`, `personalDrive`, `os`, **`seedCapabilityInfo`** (last **`bare_os.capabilities`** handshake or error object), **`mbrKeysHex`** (MBR-derived key list), **`bootMbr512`** (boot-time 512-byte copy), **`seedMbrLayout`** (optional `bare_os.mbr_layout` snapshot), and **`peerSystemSeedActive`** (helper mirroring active).
**`initPersonalDrive(store, swarm, Hyperdrive)`**