Updates

2026-04-03 20:33:24 -04:00
parent ae6b7f8652
commit e58a9f99d6
184 changed files with 1636 additions and 109 deletions
@@ -0,0 +1,37 @@
+# Chapter 11 — Kernel extensions and Pear workflows
+
+This chapter ties the Hyperdrive-resident kernel ([`kernel/init.js`](../kernel/init.js)), [`ctx`](./02-the-context-object.md), and Pear/Bare distribution patterns together.
+
+## Boot composition
+
+1. **Stock phases** — `os-release`, `motd`, optional `rc.profile.*`, `rc`, `rc.d`, `rc.local`, `kernel.d`, banner, `onboot` (non-interactive), optional self-test.
+2. **Strict boot** — `BARE_OS_BOOT_STRICT=1` stops on first `execLine` error in trusted snippets.
+3. **Allowlist** — `BARE_OS_BOOT_ALLOWLIST=1` plus [`/etc/bare-os/boot.allow`](../kernel/etc/bare-os/boot.allow.example) restricts the first word of each line in those snippets (builtins like `export` and `cd` stay allowed).
+
+## 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/…`.
+- **Timers** — Files in `~/.config/bare-os/timers/*.timer` with a `[Timer]` section (`OnCalendar=` five cron fields, `ExecLine=`) are evaluated on the same minute tick as `~/.crontab`.
+- **System cron** — Optional image file `/etc/bare-os/crontab` (see [crontab.example](../kernel/etc/bare-os/crontab.example)) is merged with user crontab entries.
+
+## Observability
+
+- **`ctx.bareOsSubscribeBootEvent`** — Same structured events as `BARE_OS_BOOT_TRACE=ndjson` (phase, ms, sessionId).
+- **`/proc/bare_os_quotas`** — Pipeline limits, `BARE_OS_EXEC_MAX_DEPTH`, IPC caps, session stats.
+- **`ctx.vfs.watch(path)`** — Hyperdrive-backed watch when `BARE_OS_VFS_WATCH` is not `0`; returns `{ watcher, destroy, … }`.
+
+## Pear / Git / HTTP
+
+- **Release metadata** — Host can set `BARE_OS_PEAR_CHANNEL`, `BARE_OS_PEAR_RELEASE`, and `BARE_OS_IMAGE_DIGEST`; they appear in `/run/bare-os/boot.json`.
+- **`git-pear`** — `/bin/git-pear help` documents Git-in-Pear (`gip-transport`, `gip-remote`, `git+pear://` remotes).
+- **HTTP** — Delegated `curl` tries `bare-fetch`, then optional `bare-https`, to install `globalThis.fetch` on minimal hosts.
+
+## Building the image
+
+- From the repo root, rebuild staged `/bin` utilities: `node packages/bare-os-coreutils/build.mjs`.
+- Keep [`kernel/`](../kernel/) and [`packages/bare-os-seeder/kernel/`](../packages/bare-os-seeder/kernel/) identical (`node scripts/verify-kernel-seeder-parity.mjs`).
+- Pear staging: use **`pear-build`** / app manifests in your Pear project; align `pear.json` channels with `BARE_OS_PEAR_*` env vars on the boot host.
+
+## HDMS hooks
+
+Use **`ctx.bareOsSubscribeHdmsLifecycle`** to run logic when extra drives mount after unlock (`kind: 'activate'`, `labels`) or before guest teardown (`kind: 'deactivate'`).