# bare-os-protocol

Shared **wire format and constants** for the Bare operating system monorepo: Hyperswarm topic, 512-byte MBR layout, and Protomux **bare-os-v1** seed-channel message shapes.

**When to use:** depend on this package when building a **compatible seeder or booter**, fuzz-testing **MBR/topic** stability, or reusing **kernel feature bit** masks in tooling.

**Documentation:** [Concepts — P2P](../../docs/concepts/p2p-swarm-and-protomux.md) · [Protocol reference](../../docs/reference/package-bare-os-protocol.md) · [Handbook ch.3](../../handbook/03-protocol-and-disk.md) · [Kernel extensions](../../docs/reference/kernel-extensions.md).

```mermaid
flowchart LR
  T[bare-os-v1 topic]
  C[Protomux channel]
  M[MBR block 0]
  T --> C
  M --> H[Hyperdrive keys]
```

## What it provides

- **`PROTOCOL_NAME`, `TOPIC_STRING`** — Protomux channel name and swarm topic input string (`bare-os-v1`)
- **`topicKey()`** — 32-byte topic for `swarm.join()`
- **`BLOCK_SIZE`, `MBR_MAGIC`** — 512-byte MBR, magic `BIOS` at offset 0
- **`buildMbr` / `parseMbr`** — Pack/unpack primary + optional failover Hyperdrive keys
- **`setupSeedChannel`** — Wire Protomux messages 0–6 for RAM block reads, gossip bitfield, manifest path **search**, **RPC** (incl. `bare_os.capabilities` with **`bits`** … **`bits11`** when non-zero, typed errors for unknown RPC methods, `bare_os.replication_status`, `bare_os.replication_queue`, extended RPC short names in **`seed-rpc-methods.js`**, `bare_os.gossip`), and `drive.replicate`. Message 0/1 is role-agnostic: any peer with `localRAM` block `0` can answer MBR reads.

Subpath exports: `bare-os-protocol/constants.js`, `bare-os-protocol/messages` (compact-encoding schemas), `bare-os-protocol/kernel-feature-bits.js` (documented booter capability words **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_*`**; **`BARE_OS_KERNEL_FEATURE_BITS_DOC`** — see source; surfaced in **`/proc/bare_os_features`** and **`/proc/bare_os/`**), `bare-os-protocol/lib/seed-rpc-methods.js` (authoritative **`bare_os.*`** RPC name list for **`kernel_info`**), `bare-os-protocol/protocol-meta.js` (**`BARE_OS_PROTOCOL_PACKAGE_VERSION`** for the seed handshake).

## Consumers

- **[bare-os-seeder](../bare-os-seeder)** — builds MBR, serves block 0 over the channel, replicates the system Hyperdrive.
- **[bare-os-booter](../bare-os-booter)** — parses MBR from `SwarmDisk`, opens system drives, uses the same channel on the client side, and can mirror block `0` plus captured seed RPC snapshots after successful boot and eligibility checks.

## Tests

```bash
npm test -w bare-os-protocol
```

Runs `brittle-bare` against `test.js` (topic stability, MBR roundtrip, encodings).

## Dependencies

`b4a`, `compact-encoding` **3.x** (v3 **`c.buffer`** is strict; **`c.optionalBuffer`** is the old nullable behavior), `hypercore-crypto` **3.7**. No Hyperdrive or Hyperswarm here — this package stays small and testable.

## See also

- Repo root [README.md](../../README.md) and [protocol reference](../../docs/reference/package-bare-os-protocol.md) §10.
- [Handbook — Blueprints § protocol](../../handbook/02-blueprints.md) (high-level).