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

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

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

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

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

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 · Handbook home · Next: Protocol and disk →

4.1 KiB Raw Blame History Unescape Escape