Updates to MD

2026-04-25 23:18:44 -04:00
parent 0e3e5be329
commit d9d9f6ddb9
93 changed files with 368 additions and 370 deletions
@@ -11,7 +11,7 @@ This chapter ties the Hyperdrive-resident kernel ([`kernel/init.js`](../kernel/i
 ## Init, timers, and sockets

 - **bare-initd** — User drop-ins under `~/.config/bare-os/units/<name>.unit` support `SocketActivationIpc=<fifo>`; the unit’s `start` runs after the first byte is read on that logical FIFO under `/run/bare-os/ipc/…`. Optional `IdleSec=N` (with `stop`) stops the unit after N seconds without further IPC traffic; optional fragments `~/.config/bare-os/units.d/<name>/*.conf` merge before `~/.config/bare-init/units/` overrides. `ReadinessPath=` may be `exec:<execLine>` for a bounded readiness gate. **`ConditionPathExists=`** skips start when a VFS path is missing; **`AssertPathExists=`** fails the unit when missing (systemd-like, bounded absolute paths). **`ConditionPathIsDirectory=`** / **`AssertPathIsDirectory=`** do the same for directories (via **`vfs.lstat`**). Inspect the live DAG at **`/proc/bare_os/initd_graph.json`** (same payload as **`initd_dag.json`**, optional **`dot`** field).
- **bare-os-www** — Stock initd serves **`GET`/`HEAD**` from **`~/.www`** on **`127.0.0.1:8088`** by default; **`bare-holesail`** starts after it so managed **`bare-www-<port>`** rows reach the listener. **`bare-openssh`** adds **`bare-ssh-<port>`** to the same **`~/.holesail/state.json`** ( **`seed`** / **`key`** persistence); if sshd starts before **`bare-holesail`**, **`startBareUserSessionStack`** re-runs ensure after holesail is up. Handbook [ch.4 § bare-os-www](../handbook/04-the-booter-runtime.md#bare-os-www-static-http-for-www), § **bare-holesail**, § **bare-openssh**.
+- **bare-os-www** — Stock initd serves **`GET`/`HEAD**` from `**~/.www`** on **`127.0.0.1:8088`** by default; **`bare-holesail`** starts after it so managed **`bare-www-<port>`** rows reach the listener. **`bare-openssh`** adds **`bare-ssh-<port>`** to the same **`~/.holesail/state.json`** ( **`seed`** / **`key`** persistence); if sshd starts before **`bare-holesail`**, **`startBareUserSessionStack`** re-runs ensure after holesail is up. Handbook [ch.4 § bare-os-www](../handbook/04-the-booter-runtime.md#bare-os-www-static-http-for-www), § **bare-holesail**, § **bare-openssh**.
 - **Timers** — Files in `~/.config/bare-os/timers/*.timer` (max **8**) with a `[Timer]` section: either `OnCalendar=` (five cron fields) + `ExecLine=` on the same minute tick as `~/.crontab`, or `EveryMs=` (**1000**–**86400000**) + `ExecLine=` on a fixed `setInterval`, or **`OnInactiveSec=`** to run after the last timer-triggered finish plus an idle gap (one-shot or repeating; **`Persistent=`** keeps state across sessions where implemented). Optional `JitterSec=` spreads the first (or periodic) `execLine` within **0…N** seconds. Copy from `/etc/bare-os/timers/*.timer.example` on the system image when present.
 - **System cron** — Optional image file `/etc/bare-os/crontab` (see [crontab.example](../kernel/etc/bare-os/crontab.example)) is merged with user crontab entries. Lines may use `@reboot` + command (once per `bare-cron` start) and optional `JitterSec=N` prefix on the command for calendar lines.

@@ -50,7 +50,7 @@ Storage write limits use existing hooks (**`BARE_OS_VFS_QUOTA_*`**, **`BARE_OS_H

 ### System revision and initd (OTA-friendly ordering)

-Host env **`BARE_OS_SYSTEM_REVISION_ID`**, **`BARE_OS_SYSTEM_REVISION_PENDING`**, and **`BARE_OS_SYSTEM_SLOT`** surface as **`ctx.bareOsSystemRevision`** and in **`/proc/bare_os/provenance`**. For Pear OTA flows, gate user units on pending work: e.g. **`ConditionPathExists=`** on a host-written marker file, or **`After=`** a unit whose **`ReadinessPath=`** checks **`/proc/bare_os/provenance`** JSON (parse in a small **`exec:`** gate). Combine with **`ctx.bareOsRequestPearReload()`** so the host applies the new bundle before initd restarts dependents.
+Host env **`BARE_OS_SYSTEM_REVISION_ID`**, **`BARE_OS_SYSTEM_REVISION_PENDING`**, and **`BARE_OS_SYSTEM_SLOT`** surface as **`ctx.bareOsSystemRevision`** and in **`/proc/bare_os/provenance`**. For Pear OTA flows, gate user units on pending work: e.g. **`ConditionPathExists=`** on a host-written marker file, or **`After=`** a unit whose **`ReadinessPath=`** checks **`/proc/bare_os/provenance`** JSON (parse in a small **`exec:`** gate). Combine with `**ctx.bareOsRequestPearReload()`** so the host applies the new bundle before initd restarts dependents.
 - **`git-pear`** — `/bin/git-pear help` documents Git-in-Pear (`gip-transport`, `gip-remote`, `git+pear://` remotes).
 - **HTTP** — Delegated **`curl`** / **`wget`** resolve **`fetch`** via **`ctx.httpFetch`** (policy-wrapped when the booter supplies it), then **`ctx.bare.fetch`** from host **`BARE_OS_BARE_MODULES`** and drive **`/lib/bare/bundles`**, then **`globalThis.fetch`**. **`ensureBareFetchGlobals`** may install **`bare-fetch`** or **`bare-https`** when no native fetch exists. **`BARE_OS_HTTP_ALLOWLIST`**, **`BARE_OS_HTTP_DENYLIST`**, **`BARE_OS_DNS_ALLOWLIST`**, and **`BARE_OS_TLS_PIN_SHA256`** (and **`init.bareOsCurlTls`** for **`curl`**) narrow outbound access. Canonical doc: [HTTP: curl and wget](../docs/reference/http-curl-and-wget.md).
 - **SSH (`bare-openssh`)** — The stock booter loads **`bare-ssh2`** from the workspace package **`bare-os-openssh`** (vendored upstream under **`vendor/bare-ssh2`**). Initd starts **`bare-openssh`** automatically unless disabled. **`npm run build -w bare-os-openssh`** stages **`/bin/sshd`**, **`/etc/ssh/sshd_config`**, and merged man pages into **`kernel/`** and the seeder mirror. Implementation: [`packages/bare-os-booter/lib/bare-openssh.js`](../packages/bare-os-booter/lib/bare-openssh.js). Host **`BARE_OS_SSH_LISTEN_PORT`** and **`BARE_OS_SSH_BIND_ALL`** are copied into guest **`vfs.env`** when set on the host.