Docs+handbook

2026-04-03 03:12:44 -04:00
parent d794c87b32
commit 7435f4b353
16 changed files with 1044 additions and 33 deletions
@@ -0,0 +1,37 @@
+# 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.
+
+## What it provides
+
+| Export (from `index.js`)        | Role                                                                                                 |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `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 stub, search, RPC stub, and `drive.replicate` |
+
+Subpath exports: `bare-os-protocol/constants.js`, `bare-os-protocol/messages` (compact-encoding schemas).
+
+## 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.
+
+## Tests
+
+```bash
+npm test -w bare-os-protocol
+```
+
+Runs `brittle-bare` against `test.js` (topic stability, MBR roundtrip, encodings).
+
+## Dependencies
+
+`b4a`, `compact-encoding`, `hypercore-crypto` (via constants/topic). No Hyperdrive or Hyperswarm here — this package stays small and testable.
+
+## See also
+
+- Repo root [README.md](../../README.md) and [DOCUMENTATION.md](../../DOCUMENTATION.md) §10.
+- [Handbook — Blueprints § protocol](../../handbook/02-blueprints.md) (high-level).