snxraven/bare-operating-system
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

feat: kernel roadmap wave — bits4, policy v4, Pear/Bare compatibility

Browse Source 
- protocol/booter: bits4 handshake, proc surfaces, boot policy v4, telemetry v4
- coreutils: nohup + ensure-man-pages; seed-man-pages fixes for extra pages
- kernel-runner: no static node:module (Pear); bare-module createRequire
- docs: handbook, reference, ADR, compatibility matrix, verify scripts
This commit is contained in:
Raven Scott
2026-04-04 02:51:33 -04:00
parent d775fb0628
commit f8a0dad897
190 changed files with 2717 additions and 1822 deletions
Download Patch File Download Diff File Expand all files Collapse all files
developer-guide/11-kernel-pear-cookbook.md
+7 -2
View File
@@ -10,7 +10,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). Inspect the live DAG at **`/proc/bare_os/initd_graph.json`** (same payload as **`initd_dag.json`**, optional **`dot`** field).
- **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).
- **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.
@@ -19,7 +19,8 @@ This chapter ties the Hyperdrive-resident kernel ([`kernel/init.js`](../kernel/i
- **`ctx.bareOsSubscribeBootEvent`** — Same structured events as `BARE_OS_BOOT_TRACE=ndjson` (phase, ms, sessionId); the booter also emits **`booter:*`** phases (**`vfs`**, **`ctx`**, **`repl`**, **`initd`**, **`kernel_invoke`**).
- **`/proc/bare_os_quotas`** — Pipeline limits, `BARE_OS_EXEC_MAX_DEPTH`, IPC caps, session stats.
- **`/proc/bare_os_resources`** / **`ctx.bareOsGetResourceStatus()`** — Unified snapshot for operators.
- **`/proc/bare_os_features`** — Documented kernel-feature words **`bits`** / **`bits2`** (see `bare-os-protocol` exports).
- **`/proc/bare_os_features`** — Documented kernel-feature words **`bits`**, **`bits2`**, **`bits3`**, **`bits4`** (see `bare-os-protocol` exports).
- **`/proc/bare_os/net_summary.json`** — Coalesced swarm / seed RPC hints for operators (topic, peer count, staging slot, replication queue, snapshot / firewall stats when present).
- **`ctx.vfs.watch(path)`** — Hyperdrive-backed watch when `BARE_OS_VFS_WATCH` is not `0`; returns `{ watcher, destroy, … }`. With `BARE_OS_VFS_WATCH_PSEUDO=1`, may watch coalesced `/proc/bare_os/metrics_live.json`.
## Pear / Git / HTTP
@@ -27,6 +28,10 @@ This chapter ties the Hyperdrive-resident kernel ([`kernel/init.js`](../kernel/i
- **Mirror-drive hints** — `ctx.bareOsEmitMirrorDriveHint({ label?, key? })` emits `bare-os:mirror-drive-hint` on Node-style hosts for mirror-drive–style workflows (labels/keys only; trust boundaries unchanged).
- **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`.
- **`ctx.bareOsRequestPearReload()`** — Returns hints and env strings; the host **`pear-runtime` / `pear-runtime-updater`** must perform any real reload.
### 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.
- **`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).