# Chapter 3 — Protocol, MBR, and SwarmDisk

Here we connect **bare-os-protocol** to what **seeder** and **booter** actually do on the wire and in RAM.

---

## Seeder lifecycle

1. Resolve **kernel root** (`BARE_OS_KERNEL_ROOT` or vendored `kernel/`).
2. Optionally **rebuild coreutils** when running under Node (`file:` URL) — skipped under Pear.
3. Open **Corestore** + **Hyperdrive**, **`stageKernelTree`**:
   - `init.js` → `/boot/init.js`
   - `bin/*` → `/bin/*`
   - `etc/*` → `/etc/*`
4. Build **MBR** with `buildMbr(drive.key)` and store block **0** in a **`Map`** (`localRAM`).
5. **Hyperswarm** `join(topicKey())` and `join(drive.discoveryKey)`.
6. On each connection: **Protomux** + **`setupSeedChannel`**, which:
   - Answers **read index** requests from `localRAM` (index `0` → MBR)
   - Attaches **`drive.replicate(stream)`**

```mermaid
sequenceDiagram
  participant S as Seeder
  participant W as Hyperswarm
  participant B as Booter
  S->>W: join topic + discoveryKey
  B->>W: join topic
  B->>S: mux connection
  Note over B,S: Protomux bare-os-v1
  B->>S: read block 0
  S-->>B: MBR 512 bytes
  B->>S: hyperdrive replicate
```

---

## Booter: from peers to Hyperdrive

**`SwarmDisk`** (booter) mirrors the seeder’s channel handlers:

- **`read(index)`** — if not local RAM, broadcast **msg 0** to peers, await **msg 1** (timeout).
- **`addPeer`** — open channel, replicate **system** (and later **personal**) drives on the mux stream.

**Boot path:**

1. Wait until **`disk.peers.size > 0`** or **boot timeout**.
2. **`parseMbr(await disk.read(0))`** → list of 32-byte keys.
3. For each key, try `Hyperdrive(store, key)` + replicate until **`/boot/init.js`** exists.
4. Initialize **personal drive** namespace and join its discovery key.
5. Hand off to **`executeKernel`**.

There is **intentionally** no “use my checkout’s `kernel/` if the network fails” path—the project forces you to think about **availability** of the swarm.

---

## Message IDs (reference)

Aligned with `packages/bare-os-protocol/lib/channel.js` and `swarm-disk.js`:

| ID    | Direction      | Purpose              |
| ----- | -------------- | -------------------- |
| 0     | Client → peers | Read block by index  |
| 1     | Peer → client  | Data payload         |
| 2     | Gossip stub    | Bitfield buffer      |
| 3 / 4 | Search req/res | Stub (empty matches) |
| 5 / 6 | RPC req/res    | **`bare_os.version`** implemented; other methods return “not implemented” |

The **important** path for boot is **0/1** + **Hyperdrive replication** on the same socket.

---

## Personal drive replication

`SwarmDisk.initPersonalDrive` creates a **separate** Hyperdrive under a stable Corestore namespace and **`swarm.join(personalDrive.discoveryKey)`**. Your `$HOME` tree can therefore sync across **your** devices if peers share that discovery key—orthogonal to the **system** image key from the MBR.

---

## Failure modes you will see in the wild

- **Boot timeout** — no peer answered the topic (seeder not running, firewall, wrong network).
- **Invalid MBR** — corrupt block 0 or wrong magic; `parseMbr` throws.
- **Drive never completes** — replication stalled; check peer count and discovery key joins.

---

[← Blueprints](02-blueprints.md) · [Handbook home](README.md) · [Next: Booter runtime →](04-the-booter-runtime.md)