Further MD Fixes
This commit is contained in:
Raven Scott
@@ -24,11 +24,11 @@
|
||||
|
||||
The **seeder** owns the **publisher** side: it stages the kernel tree into a system Hyperdrive, writes the **MBR** block that points at drive keys, and stays on the swarm so others can replicate.
|
||||
|
||||
The **booter** owns the **consumer** side: it looks up peers on the same topic, replicates the system drive, attaches or creates a **personal** drive, and starts the in-image runtime (**`/boot/init.js**`, shell, **initd** — including stock `**bare-os-www**` for `**~/.www`** on loopback — and cron as configured).
|
||||
The **booter** owns the **consumer** side: it looks up peers on the same topic, replicates the system drive, attaches or creates a **personal** drive, and starts the in-image runtime (**`/boot/init.js`**, shell, **initd** — including stock **`bare-os-www`** for **`~/.www`** on loopback — and cron as configured).
|
||||
|
||||
You almost always run them as **two separate processes** (two terminal tabs or windows). The booter needs a live seeder (or an already-replicated drive) to make progress within its boot timeout.
|
||||
|
||||
**Resilience — peer system seeding:** By default, after a node has booted it **may** serve **MBR block 0** and mirror the publisher’s early **`bare_os.***` RPC hints to other cold booters (same Hyperswarm topic) when eligibility passes. Set `**BARE_OS_PEER_SYSTEM_SEED=0**` (or `**false**` / `**no**` / `**off**`) on the **host** to turn this off. This does not remove the need for at least one trusted publisher for the first tip, but it spreads block and RPC load across up-to-date peers. Set the same `**BARE_OS_SEED_IMAGE_TIP_ID**` on the seeder and on booters (or `**BARE_OS_PEER_SEED_ADVERTISE_IMAGE_TIP_ID**` / `**BARE_OS_PEER_SEED_IMAGE_TIP_ID**` on helpers) so every node advertises one **image tip**; optional `**BARE_OS_PEER_SEED_IMAGE_TIP_ID**` on a helper still gates whether *that* node may mirror. By default `**BARE_OS_PEER_SEED_SYNTHETIC_CAPABILITIES`** stays **on** so helpers can mirror **MBR block 0** even when the pre-MBR capability RPC was skipped or incomplete — see the [environment appendix](../docs/reference/environment-and-posix-appendix.md).
|
||||
**Resilience — peer system seeding:** By default, after a node has booted it **may** serve **MBR block 0** and mirror the publisher’s early **`bare_os.*`** RPC hints to other cold booters (same Hyperswarm topic) when eligibility passes. Set **`BARE_OS_PEER_SYSTEM_SEED=0`** (or **`false`** / **`no`** / **`off`**) on the **host** to turn this off. This does not remove the need for at least one trusted publisher for the first tip, but it spreads block and RPC load across up-to-date peers. Set the same **`BARE_OS_SEED_IMAGE_TIP_ID`** on the seeder and on booters (or **`BARE_OS_PEER_SEED_ADVERTISE_IMAGE_TIP_ID`** / **`BARE_OS_PEER_SEED_IMAGE_TIP_ID`** on helpers) so every node advertises one **image tip**; optional **`BARE_OS_PEER_SEED_IMAGE_TIP_ID`** on a helper still gates whether *that* node may mirror. By default **`BARE_OS_PEER_SEED_SYNTHETIC_CAPABILITIES`** stays **on** so helpers can mirror **MBR block 0** even when the pre-MBR capability RPC was skipped or incomplete — see the [environment appendix](../docs/reference/environment-and-posix-appendix.md).
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
@@ -65,9 +65,9 @@ In a **second** terminal, start the booter:
|
||||
cd packages/bare-os-booter && node index.js
|
||||
```
|
||||
|
||||
Default store paths are under **`~/.bare-os/corestore/**` for seeder and booter unless you set `**BARE_OS_SEED_STORE**`, `**BARE_OS_BOOT_STORE**`, or the shared base `**BARE_OS_HOST_DATA**`. See each package’s `**lib/paths.js`** for how overrides compose.
|
||||
Default store paths are under **`~/.bare-os/corestore/`** for seeder and booter unless you set **`BARE_OS_SEED_STORE`**, **`BARE_OS_BOOT_STORE`**, or the shared base **`BARE_OS_HOST_DATA`**. See each package’s **`lib/paths.js`** for how overrides compose.
|
||||
|
||||
On a **fresh clone**, build **`kernel/bin/***` and `**kernel/lib/bare/**` before staging: from the repo root run `**npm run build -w bare-os-coreutils && npm run build -w bare-os-bare-libs**` (or `**npm run pretest**`, which also verifies kernel/seeder parity). Root `**npm run os:seeder**` runs those builds automatically before `**pear run --dev`**.
|
||||
On a **fresh clone**, build **`kernel/bin/*`** and **`kernel/lib/bare/`** before staging: from the repo root run `**npm run build -w bare-os-coreutils && npm run build -w bare-os-bare-libs**` (or `**npm run pretest**`, which also verifies kernel/seeder parity). Root `**npm run os:seeder**` runs those builds automatically before `**pear run --dev`**.
|
||||
|
||||
---
|
||||
|
||||
@@ -76,7 +76,7 @@ On a **fresh clone**, build **`kernel/bin/***` and `**kernel/lib/bare/**` before
|
||||
<details>
|
||||
<summary><strong>When to expand this block</strong></summary>
|
||||
|
||||
**Pear** exercises **`pear run --dev**`, hoisted `**node_modules**`, and `**BARE_OS_PEAR_***` behavior. Install the [Pear CLI](https://docs.pears.com/) first; confirm with `**pear --version`**.
|
||||
**Pear** exercises **`pear run --dev**`, hoisted **`node_modules`**, and **`BARE_OS_PEAR_*`** behavior. Install the [Pear CLI](https://docs.pears.com/) first; confirm with `**pear --version`**.
|
||||
|
||||
</details>
|
||||
|
||||
@@ -92,7 +92,7 @@ In another terminal:
|
||||
npm run os:booter
|
||||
```
|
||||
|
||||
These scripts run **`scripts/ensure-pear-node-modules.mjs**` first so Pear sees **hoisted** workspace dependencies the same way `**npm ci**` does at the repo root. Without that step, `**pear run**` from inside a package directory can miss modules that live at the root `**node_modules`**.
|
||||
These scripts run **`scripts/ensure-pear-node-modules.mjs`** first so Pear sees **hoisted** workspace dependencies the same way `**npm ci**` does at the repo root. Without that step, `**pear run**` from inside a package directory can miss modules that live at the root **`node_modules`**.
|
||||
|
||||
> **Important**
|
||||
> **`os:seeder`** is an **npm script name**, not a Pear app name. Do not type `pear run os:seeder`.
|
||||
@@ -101,34 +101,34 @@ These scripts run **`scripts/ensure-pear-node-modules.mjs**` first so Pear sees
|
||||
|
||||
## Pear channels and released keys
|
||||
|
||||
When you change **`packages/bare-os-booter/lib/bare-module-manifest.json**` or run `**npm run sync:bare-manifest**`, `**bare-module-manifest.data.mjs**` is regenerated for Pear (sync script and `**npm run build -w bare-os-bare-libs**` `**prebuild**`). From the repo root, run `**npm run verify:manifest-data**` before `**pear stage**` so the JSON and `**.data.mjs`** stay aligned.
|
||||
When you change **`packages/bare-os-booter/lib/bare-module-manifest.json`** or run `**npm run sync:bare-manifest**`, **`bare-module-manifest.data.mjs`** is regenerated for Pear (sync script and `**npm run build -w bare-os-bare-libs**` **`prebuild`**). From the repo root, run `**npm run verify:manifest-data**` before `**pear stage**` so the JSON and **`.data.mjs`** stay aligned.
|
||||
|
||||
After **`pear stage**` and `**pear release**`, you receive `**pear://…**` links that point at released artifacts. Consumers normally run those keys rather than a raw git checkout, unless they use dev mode (`**pear run --dev .`**).
|
||||
|
||||
Concrete channel names, keys, versioned links, and host-side environment variables (**`BARE_OS_PEAR_***`, HTTP allow lists, TLS pin forwarding, `**ctx.bare`** toggles) are documented in **[PEAR-RUN.md](../docs/PEAR-RUN.md)**. Keep that file open when you embed the booter in a Pear app or wire OTA reload hooks.
|
||||
Concrete channel names, keys, versioned links, and host-side environment variables (**`BARE_OS_PEAR_*`**, HTTP allow lists, TLS pin forwarding, **`ctx.bare`** toggles) are documented in **[PEAR-RUN.md](../docs/PEAR-RUN.md)**. Keep that file open when you embed the booter in a Pear app or wire OTA reload hooks.
|
||||
|
||||
---
|
||||
|
||||
## Common mistakes
|
||||
|
||||
- **Booter times out** — No peer is serving the **`bare-os-v1**` topic, or the network cannot reach bootstrap nodes. Confirm the seeder is running and check `**HYPERSWARM_BOOTSTRAP`** if you use custom bootstraps ([Handbook — Chapter 7, troubleshooting](../handbook/07-operations-and-development.md#troubleshooting)).
|
||||
- **Missing `/bin` utilities under Pear** — Run **`npm run build -w bare-os-coreutils**` (and seed again) so the image contains a fresh `**/bin`** build.
|
||||
- **Booter times out** — No peer is serving the **`bare-os-v1`** topic, or the network cannot reach bootstrap nodes. Confirm the seeder is running and check **`HYPERSWARM_BOOTSTRAP`** if you use custom bootstraps ([Handbook — Chapter 7, troubleshooting](../handbook/07-operations-and-development.md#troubleshooting)).
|
||||
- **Missing `/bin` utilities under Pear** — Run **`npm run build -w bare-os-coreutils**` (and seed again) so the image contains a fresh **`/bin`** build.
|
||||
- **Wrong working directory for the seeder** — Start the seeder from **`packages/bare-os-seeder`** (or use the npm script from root) so kernel paths resolve.
|
||||
- **Expecting full POSIX job control** — The shell supports **`jobs**`, `**fg**`, `**bg**`, `**wait**`, background `**&**`, and logical stop/resume, but not monitor mode, real host process groups, or kernel `**SIGTSTP`** (see [Handbook ch.9 — Shell](../handbook/09-posix-utilities-shell-and-vfs.md)).
|
||||
- **Expecting full POSIX job control** — The shell supports **`jobs`**, **`fg`**, **`bg`**, **`wait`**, background `**&**`, and logical stop/resume, but not monitor mode, real host process groups, or kernel **`SIGTSTP`** (see [Handbook ch.9 — Shell](../handbook/09-posix-utilities-shell-and-vfs.md)).
|
||||
|
||||
---
|
||||
|
||||
## Boot sequence in plain language
|
||||
|
||||
Once the booter has replicated enough of the **system** drive, it mounts the **personal** drive (creating one if needed), wires the merged VFS, and executes **`/boot/init.js**`. The stock kernel prints `**/etc/os-release**`, optional `**motd**`, runs `**/etc/bare-os/rc**` and sorted snippets under `**rc.d**`, then enters the interactive shell unless `**BARE_OS_SKIP_REPL**` or `**onboot**` lines consume the session. You do not need to memorize every phase to operate the system; when something fails **during** boot, enable `**BARE_OS_BOOT_TRACE`** (see [environment appendix](../docs/reference/environment-and-posix-appendix.md)) and read the phase lines on stderr.
|
||||
Once the booter has replicated enough of the **system** drive, it mounts the **personal** drive (creating one if needed), wires the merged VFS, and executes **`/boot/init.js`**. The stock kernel prints **`/etc/os-release`**, optional **`motd`**, runs **`/etc/bare-os/rc`** and sorted snippets under **`rc.d`**, then enters the interactive shell unless **`BARE_OS_SKIP_REPL`** or **`onboot`** lines consume the session. You do not need to memorize every phase to operate the system; when something fails **during** boot, enable **`BARE_OS_BOOT_TRACE`** (see [environment appendix](../docs/reference/environment-and-posix-appendix.md)) and read the phase lines on stderr.
|
||||
|
||||
Canonical **booter boot steps** (**`vfs**` → `**ctx**` → `**repl**` → `**initd**` → `**kernel_invoke`**) are summarized in [KERNEL_CONTRACT](../docs/architecture/KERNEL_CONTRACT.md).
|
||||
Canonical **booter boot steps** (**`vfs`** → **`ctx`** → **`repl`** → **`initd`** → **`kernel_invoke`**) are summarized in [KERNEL_CONTRACT](../docs/architecture/KERNEL_CONTRACT.md).
|
||||
|
||||
---
|
||||
|
||||
## Choosing Node versus Pear
|
||||
|
||||
**Node** (`node index.js` in each package) is ideal when you are debugging protocol or seeding logic quickly and want stack traces identical to your host toolchain. **Pear** tracks production embedding more closely: module layout, **`pear run --dev**`, and host `**BARE_OS_PEAR_*`** toggles matter. If a bug appears **only** under Pear, compare with a Node run using the same Corestore paths to isolate runtime differences. [PEAR-RUN.md](../docs/PEAR-RUN.md) is the channel and environment reference for Pear-specific settings.
|
||||
**Node** (`node index.js` in each package) is ideal when you are debugging protocol or seeding logic quickly and want stack traces identical to your host toolchain. **Pear** tracks production embedding more closely: module layout, **`pear run --dev**`, and host **`BARE_OS_PEAR_*`** toggles matter. If a bug appears **only** under Pear, compare with a Node run using the same Corestore paths to isolate runtime differences. [PEAR-RUN.md](../docs/PEAR-RUN.md) is the channel and environment reference for Pear-specific settings.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user