# Chapter 2 — Blueprints: architecture and trust

This chapter is the **aerial view**: boxes, arrows, and what is allowed to trust what. Implementation details live in later chapters.

---

## 1. Two applications, one protocol

```mermaid
flowchart LR
  subgraph publishers [Publish side]
    Seeder[bare-os-seeder]
    SysImg[System Hyperdrive]
    Seeder --> SysImg
  end
  subgraph network [Hyperswarm]
    Topic[bare-os-v1 topic]
    Disc[Drive discovery keys]
  end
  subgraph consumers [Boot side]
    Booter[bare-os-booter]
    PeerDisk[SwarmDisk MBR + blocks]
    Booter --> PeerDisk
  end
  Seeder --> Topic
  Booter --> Topic
  SysImg --> Disc
  Booter --> Disc
```

- The **seeder** is the **publisher** of the OS image (plus MBR in a small RAM map).
- The **booter** is a **consumer** that refuses to invent a local copy: it **must** see peers.

---

## 2. Two drives on the booter

```mermaid
flowchart TB
  subgraph booterProcess [Booter process]
    VFS[VFS layer]
    Sys[System Hyperdrive]
    Pers[Personal Hyperdrive]
    VFS -->|"paths outside HOME"| Sys
    VFS -->|"HOME and below"| Pers
  end
```

**Trust model (pragmatic):**

- **System drive** content is **whatever replicated from the swarm** matching the MBR keys. In dev you treat the seeder as trusted; in the wild this is “who you peer with.”
- **Personal drive** is **your** namespace (Corestore `bare-os-personal-v1`). It holds secrets, cron, dotfiles, HDMS registry, vault snapshots.

---

## 3. Protocol, MBR, and discovery

The shared package **bare-os-protocol** pins:

- `TOPIC_STRING === 'bare-os-v1'`
- `topicKey()` = `crypto.hash(b4a.from(TOPIC_STRING))`
- MBR layout: **512 bytes**, magic **`BIOS`**, primary key at offset **8**, optional failover keys at **40** and **72**

MBR layout (512 bytes, see `bare-os-protocol/constants.js`):

- Bytes **0–3**: `BIOS` magic
- Bytes **8–39**: primary system Hyperdrive public key
- Bytes **40–71**, **72–103**: optional additional keys

Protomux channel **`bare-os-v1`** carries:

- Block read requests (MBR and any indexed RAM the seeder exposes)
- Hyperdrive **replication** on the same socket
- Stubs for gossip, search, RPC (see `packages/bare-os-protocol/lib/channel.js`)

---

## 4. Execution stack inside the booter

```mermaid
flowchart TB
  Init[index.js main]
  Splash[Boot splash TTY]
  Swarm[Hyperswarm + SwarmDisk]
  ExecK[executeKernel]
  Repl[Kernel REPL session]
  Init --> Splash
  Init --> Swarm
  Swarm --> ExecK
  ExecK --> Repl
  Repl --> Kernel["runKernelFromSource /boot/init.js"]
  Kernel --> Shell["execLine → execShellLine"]
  Shell --> Bin["runBinCommand / paths / PATH"]
```

**Kernel** and **/bin** scripts are **not** separate processes. They are **`AsyncFunction`** closures in the **same** JS realm as the booter, with a **synthetic** `ctx` instead of syscalls.

---

## 5. Services after the console exists

```mermaid
flowchart LR
  Session[createKernelReplSession]
  Console[ctx.console = session.console]
  Initd[startBareInitd]
  Logger[kernel-logger wraps log/error]
  Cron[bare-cron setInterval]
  Session --> Console
  Console --> Initd
  Initd --> Logger
  Initd --> Cron
```

`stopBareInitd()` runs from **REPL session cleanup** so timers do not leak across session restarts.

---

## 6. Identity states

```mermaid
stateDiagram-v2
  [*] --> Guest
  Guest --> Unlocked: login / login --new
  Unlocked --> Guest: logout
  Unlocked --> Unlocked: HDMS active after unlock
```

- **Guest**: fixed `HOME=/home/guest`, read-oriented personal tree policy for some operations.
- **Unlocked**: `HOME` under `/home/<pubkey-prefix>`, HDMS can attach writable drives, `crontab` install/remove allowed.

---

## 7. What is _not_ here (boundary)

- No hardware kernel, no MMU, no ELF loader for native `/bin`.
- No container cgroup isolation—**commands are JS** with full host capability **of the Pear/Bare process**.
- No global consensus: **two booters** can diverge if they replicate **different** forks of the same discovery key (Hyperdrive versioning is a separate concern).

---

[← Introduction](01-introduction.md) · [Handbook home](README.md) · [Next: Protocol and disk →](03-protocol-and-disk.md)