Further MD Fixes
This commit is contained in:
Raven Scott
@@ -10,7 +10,7 @@ You might paste a file into your home directory on the personal Hyperdrive that
|
||||
|
||||
The **booter** and **seeder** Pear packages, by contrast, are normal **ESM** projects: they use `import`, npm dependencies, and Pear bundling. They run on the **host** and _host_ the environment that evaluates in-image code.
|
||||
|
||||
When the **`bare-os**` npm module is available on that host, the booter may attach a read-only `**ctx.bareOsHostStats**` snapshot (`**loadavg**`, `**cpus**`, `**networkInterfaces`**, …)—still **not** a general “run Node in the image” escape hatch; see [Chapter 2](02-the-context-object.md).
|
||||
When the **`bare-os`** npm module is available on that host, the booter may attach a read-only **`ctx.bareOsHostStats`** snapshot (**`loadavg`**, **`cpus`**, **`networkInterfaces`**, …)—still **not** a general “run Node in the image” escape hatch; see [Chapter 2](02-the-context-object.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -52,7 +52,7 @@ Two entry shapes matter:
|
||||
- **`async function start(ctx)`** — `/boot/init.js` on the **system** drive — `ctx` — `runKernelFromSource` wraps the source and calls `start(ctx)`
|
||||
- **`async function run(ctx, argv)`** (optional for user scripts) — `/bin/*` always; or a `*.js` file resolved from the shell — `ctx`, `argv` (string array) — `runScriptFromSource` runs the file body, then **awaits** `run(ctx, argv)` if defined
|
||||
|
||||
The booter **injects** `ctx` and `argv`. Kernel **`start**` is required; for shell scripts, top-level statements may stand alone, or you may **define** `**run**` like `**/bin`** utilities. Top-level `import` is invalid in that evaluated string because the engine is not loading an ES module—it is compiling a function body.
|
||||
The booter **injects** `ctx` and `argv`. Kernel **`start`** is required; for shell scripts, top-level statements may stand alone, or you may **define** **`run`** like **`/bin`** utilities. Top-level `import` is invalid in that evaluated string because the engine is not loading an ES module—it is compiling a function body.
|
||||
|
||||
Shebang lines (`#!/usr/bin/env bare`) are stripped before compile ([`stripShebang`](../packages/bare-os-booter/lib/kernel-runner.js)) so the first token the parser sees is valid JavaScript.
|
||||
|
||||
@@ -83,7 +83,7 @@ A script you place in `~/exploit.js` is **your** code; the booter will still `As
|
||||
|
||||
## Host source policy (Bare-first)
|
||||
|
||||
Pear-bundled **booter** and **seeder** runtime sources under `packages/bare-os-booter/lib/` and `packages/bare-os-seeder/lib/` must stay resolvable on **Bare** as well as Node: CI runs [`scripts/verify-pear-no-static-node-import.mjs`](../scripts/verify-pear-no-static-node-import.mjs), which rejects **`from 'node:…'**` imports, `**require('node:…')**`, and `**import('node:…')**` in those trees (with path-based exceptions). Use `**#host-fs**`, `**#host-path**`, and `**#host-fs-promises`** from package `imports` instead of bare **`fs**` / `**path**` specifiers. The only deliberate `**node:module**` usage today lives in `**bare-os-boot-manifest-sig.node.js**` (Node default entry for boot manifest verification); the `**bare**` export uses `**bare-os-boot-manifest-sig.bare.js**`. For guest-visible behavior, prefer Holepunch `**bare-*`** modules per [Node → Bare module map](node-to-bare-modules.md).
|
||||
Pear-bundled **booter** and **seeder** runtime sources under `packages/bare-os-booter/lib/` and `packages/bare-os-seeder/lib/` must stay resolvable on **Bare** as well as Node: CI runs [`scripts/verify-pear-no-static-node-import.mjs`](../scripts/verify-pear-no-static-node-import.mjs), which rejects **`from 'node:…'**` imports, `**require('node:…')**`, and `**import('node:…')**` in those trees (with path-based exceptions). Use `**#host-fs**`, `**#host-path**`, and `**#host-fs-promises`** from package `imports` instead of bare **`fs`** / **`path`** specifiers. The only deliberate **`node:module`** usage today lives in **`bare-os-boot-manifest-sig.node.js`** (Node default entry for boot manifest verification); the **`bare`** export uses **`bare-os-boot-manifest-sig.bare.js`**. For guest-visible behavior, prefer Holepunch **`bare-*`** modules per [Node → Bare module map](node-to-bare-modules.md).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -50,7 +50,7 @@ flowchart TB
|
||||
|
||||
|
||||
|
||||
Canonical **booter boot steps** before the kernel runs: `**vfs`** → **`ctx`** → **`repl`** → **`initd`** → **`kernel_invoke`** — see [KERNEL_CONTRACT](../docs/architecture/KERNEL_CONTRACT.md) and [bare-boot-kernel-phase-alignment](bare-boot-kernel-phase-alignment.md).
|
||||
Canonical **booter boot steps** before the kernel runs: **`vfs`** → **`ctx`** → **`repl`** → **`initd`** → **`kernel_invoke`** — see [KERNEL_CONTRACT](../docs/architecture/KERNEL_CONTRACT.md) and [bare-boot-kernel-phase-alignment](bare-boot-kernel-phase-alignment.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -59,15 +59,15 @@ Canonical **booter boot steps** before the kernel runs: `**vfs`** → **`ctx`**
|
||||
The following are set on `ctx` before the kernel starts (unless noted as overwritten later):
|
||||
|
||||
- **`bareOsCtxApiVersion`** — String semver for the documented **`ctx`** contract (e.g. **`1.10.0`**). Bump in `[bare-os-ctx-api.js](../packages/bare-os-booter/lib/bare-os-ctx-api.js)` when you make breaking changes to stable fields.
|
||||
- **`bareOsRuntimeCaps`** — **Frozen** snapshot from `[bare-os-runtime-caps.js](../packages/bare-os-booter/lib/bare-os-runtime-caps.js)`: `**ctxApiVersion**`, simulated **pipeline** limits (includes `**pipeline.envKeys**` for `**BARE_OS_PIPELINE_***`, `**BARE_OS_PIPELINE_ABS_MAX_*`**, streaming multiplier aliases), `**pseudoFsPaths`**, and **`features`** (including **`jobControl`**, **`shellHereString`**, **`bootReadyPseudoFs`**, **`bootEventSubscribe`**, **`kernelEventSubscribe`**, **`keyBrokerHandleSketch`**, **`vfsChown`**, **`auditLog`**, **`initdRequiresWants`**, **`seederRpcExtended`**, **`bareCtxModules`**, **`bareDriveBundles`**, …).
|
||||
- **`bareOsRuntimeCaps`** — **Frozen** snapshot from `[bare-os-runtime-caps.js](../packages/bare-os-booter/lib/bare-os-runtime-caps.js)`: **`ctxApiVersion`**, simulated **pipeline** limits (includes **`pipeline.envKeys`** for **`BARE_OS_PIPELINE_*`**, **`BARE_OS_PIPELINE_ABS_MAX_*`**, streaming multiplier aliases), **`pseudoFsPaths`**, and **`features`** (including **`jobControl`**, **`shellHereString`**, **`bootReadyPseudoFs`**, **`bootEventSubscribe`**, **`kernelEventSubscribe`**, **`keyBrokerHandleSketch`**, **`vfsChown`**, **`auditLog`**, **`initdRequiresWants`**, **`seederRpcExtended`**, **`bareCtxModules`**, **`bareDriveBundles`**, …).
|
||||
- **`bareOsPublishBootReady(patch)`** — Kernel-only: merge **`patch`** into the session boot-ready state exposed as **`/run/bare-os/boot.json`** and **`/run/bare-os/ready`**. The booter pre-seeds **`imageDigest`**, **`pearChannel`**, **`pearRelease`** from host env when set (see **`BARE_OS_IMAGE_DIGEST`**, **`BARE_OS_PEAR_CHANNEL`**, **`BARE_OS_PEAR_RELEASE`**, **`PEAR_CHANNEL`**).
|
||||
- **`bareOsSessionStats`** — Mutable **`{ execLineCount, pipelineBytesTotal }`** mirrored in **`/proc/bare_os_session_stats`**.
|
||||
- **`bareOsBootStartedMs`** — Epoch milliseconds when the booter started building the session (used for synthetic **`/proc/uptime`**).
|
||||
- **`bareOsSkipRepl`** — **`true`** when **`BARE_OS_SKIP_REPL=1`** (non-interactive stdin); kernels may shorten banners.
|
||||
- **`bareOsAdvertisedKernelCapabilityWords`** / **`bareOsSeedKernelCapabilityWords`** — **Frozen** maps of eleven `**uint32`** masks (wire v2 semantic keys: **`primary`**, **`extendedSeedingPlatform`**, … **`hypercorePackHrpcLifecycle`**). Advertised values reflect stock masks minus env-disabled bits (e.g. crypto urandom); seed map mirrors last **`bare_os.capabilities`** handshake when present, else **`null`**. Always mask with **`>>> 0`** when testing bits.
|
||||
- **`bareOsAdvertisedKernelCapabilityWords`** / **`bareOsSeedKernelCapabilityWords`** — **Frozen** maps of eleven **`uint32`** masks (wire v2 semantic keys: **`primary`**, **`extendedSeedingPlatform`**, … **`hypercorePackHrpcLifecycle`**). Advertised values reflect stock masks minus env-disabled bits (e.g. crypto urandom); seed map mirrors last **`bare_os.capabilities`** handshake when present, else **`null`**. Always mask with **`>>> 0`** when testing bits.
|
||||
- **`bareOsReadDelegateFairnessSnapshot()`** — Returns delegate inflight counts and per-minute rate-bucket sample (same data folded into **`/proc/bare_os/metrics_live.json`** schema 2).
|
||||
- **`bareOsReadSubprocessBridgeJobs()`** — Parses host **`BARE_OS_SUBPROCESS_BRIDGE_JOBS_JSON`** when the bridge is wired (hint-only; guest does not spawn).
|
||||
- **`bareOsReadSubprocessBridgeSnapshot()`** — Schema **2** object: `**jobs`** plus **`meta`** from **`BARE_OS_SUBPROCESS_BRIDGE_META_JSON`** (`supportedSignals`, `cgroupRootHint`, `exitReasonCodes`). Host **`BARE_OS_BARE_SUBPROCESS_BRIDGE`** / **`BARE_OS_BARE_SUBPROCESS_TIMEOUT_MS`** affect **`kernel-runner`** defaults for **`runBin`** when the bridge is enabled.
|
||||
- **`bareOsReadSubprocessBridgeSnapshot()`** — Schema **2** object: **`jobs`** plus **`meta`** from **`BARE_OS_SUBPROCESS_BRIDGE_META_JSON`** (`supportedSignals`, `cgroupRootHint`, `exitReasonCodes`). Host **`BARE_OS_BARE_SUBPROCESS_BRIDGE`** / **`BARE_OS_BARE_SUBPROCESS_TIMEOUT_MS`** affect **`kernel-runner`** defaults for **`runBin`** when the bridge is enabled.
|
||||
- **`bareOsReadSnapshotHintsJson()`** — Same object as **`/proc/bare_os/snapshot_hints.json`** (seed RPC + optional **`bareOsSnapshotHandles`** on the interactive ctx), without a VFS read.
|
||||
- **`bareOsListMirrorMounts()`** — Lists **`/mirror/auxN`** paths for **`disk.auxiliaryDrives`** (read-only); aligns with **`/proc/mounts`** mirror rows for mirror-drive style workflows.
|
||||
- **`bareOsIsCtxMethodAllowed(name)`** — Boot policy v4: when **`BARE_OS_BOOT_POLICY_ALLOWED_CTX_METHODS`** is set, returns whether **`name`** is in the allow list (kernels should call before sensitive **`ctx`** use).
|
||||
@@ -80,14 +80,14 @@ The following are set on `ctx` before the kernel starts (unless noted as overwri
|
||||
- **`bareOsRunImageScript(path)`** — **`async`** — runs trusted JS from the system image; paths must be under **`/lib/bare-os/extensions/`** (used by **`kernel.ext.d`**).
|
||||
- **`disk`** — Disk bundle used during boot (includes drives and helpers); advanced use
|
||||
- **`drive`** — **System** Hyperdrive (`ctx.drive` is the OS image: `/bin`, `/boot`, …)
|
||||
- `**personalDrive`** — **Personal** Hyperdrive (mutable per-user state; VFS maps `**$HOME`** to **`/.bare-os/home/<HOME-basename>/…`** and session **`/var/log`** to **`/.bare-os/var/log/<basename>/…`** so guest vs unlocked trees do not share the same keys)
|
||||
- **`personalDrive`** — **Personal** Hyperdrive (mutable per-user state; VFS maps **`$HOME`** to **`/.bare-os/home/<HOME-basename>/…`** and session **`/var/log`** to **`/.bare-os/var/log/<basename>/…`** so guest vs unlocked trees do not share the same keys)
|
||||
- **`vfs`** — Path layer: resolves logical paths, routes to system vs personal drive, implements `mkdir`, `readFile`, etc. See `[vfs.js](../packages/bare-os-booter/lib/vfs.js)`
|
||||
- **`env`** — Shell environment object (`HOME`, `PATH`, `USER`, …), same object as **`vfs.env`**. Mutated by builtins (`export`, `cd` updates `PWD`, identity unlock updates user fields). After each **`execLine`**, **`BARE_OS_EXIT_STATUS`** holds the last command’s exit code as a decimal string (POSIX **`$?`** parity); use **`$?`** or **`${?}`** in shell words for expansion.
|
||||
- **`b4a`** — **`b4a`** module (byte helpers); used to convert Hyperdrive buffers to strings
|
||||
- **`bare`** *(optional)* — **Frozen** map of host-loaded (and optionally drive-bundled) npm modules for in-image use (`**ctx.bare.b4a*`*, **`ctx.bare.protomux`**, …). Absent when **`BARE_OS_BARE_MODULES=0`**. See `[bare-module-manifest.json](../packages/bare-os-booter/lib/bare-module-manifest.json)` and [Chapter 12](12-bare-modules-and-pear-ecosystem.md).
|
||||
- **`topic`** — Topic key helper from protocol package (rarely needed in user scripts)
|
||||
- **`console`** — Initially the raw global; **replaced** with session-bound `log`/`error` that respect the REPL and fish-style UI
|
||||
- `**readLine`** — Placeholder async function; **replaced** with session `readLine(prompt)` that reads a line from stdin (or returns `null` when session ends). When the Fish-style editor attaches, `**ctx.bareOsRegisterCompleter(name, fn)`** / **`ctx.bareOsUnregisterCompleter(name)`** register async completion providers merged by the stock engine — see [Shell completion and REPL editor](../docs/reference/shell-completion-and-repl-editor.md).
|
||||
- **`readLine`** — Placeholder async function; **replaced** with session `readLine(prompt)` that reads a line from stdin (or returns `null` when session ends). When the Fish-style editor attaches, `**ctx.bareOsRegisterCompleter(name, fn)`** / **`ctx.bareOsUnregisterCompleter(name)`** register async completion providers merged by the stock engine — see [Shell completion and REPL editor](../docs/reference/shell-completion-and-repl-editor.md).
|
||||
- **`writeScreen`** — REPL helper for screen-oriented output; starts as no-op, then wired
|
||||
- **`runHdms(argv)`** — Entry for **`hdms`** CLI when HDMS controller is active
|
||||
- `**onIdentityUnlocked` / `onIdentityGuest**` — Hooks for HDMS lifecycle (bootstrap nodes, teardown)
|
||||
@@ -95,8 +95,8 @@ The following are set on `ctx` before the kernel starts (unless noted as overwri
|
||||
- `**applyUnlock` / `applyRegister` / `applyLogin` / `applyLogout` / `saveVault**` — Identity and vault operations used by **`login`**, **`logout`**, **`savevault`**
|
||||
- **`shellAliases`** — Populated when the shell loads default or `~/.barerc` aliases
|
||||
- **`bareOsApplyTheme()`** / **`bareOsListThemes()`** — Re-apply **`BARE_OS_THEME`** / **`LS_COLORS`** / **`BARE_OS_DIRCOLORS`** to **`vfs.env`** (including **`BARE_OS_COLOR_DEPTH`** downgrades for **`BARE_OS_COLOR_*`**). Used by **`/bin/theme`** and documented for custom tooling (see `[bare-os-theme-presets.js](../packages/bare-os-booter/lib/bare-os-theme-presets.js)`).
|
||||
- **`runBinCommand(argv)`** — Runs a command with the **same** resolution rules as the interactive shell (used by `**time`**, **`xargs`**, and similar)
|
||||
- **`registerKernelShutdownHook(fn)`** — Register an async or sync function to run when the REPL session ends, **before** `**stopBareInitd`** and initd **disposers**. Pair with `**registerBareInitdDisposer(fn)`** in `[bare-initd.js](../packages/bare-os-booter/lib/bare-initd.js)` when you need teardown **after** shutdown hooks but still inside `**stopBareInitd`** (intervals, sync cleanup).
|
||||
- **`runBinCommand(argv)`** — Runs a command with the **same** resolution rules as the interactive shell (used by **`time`**, **`xargs`**, and similar)
|
||||
- **`registerKernelShutdownHook(fn)`** — Register an async or sync function to run when the REPL session ends, **before** **`stopBareInitd`** and initd **disposers**. Pair with `**registerBareInitdDisposer(fn)`** in `[bare-initd.js](../packages/bare-os-booter/lib/bare-initd.js)` when you need teardown **after** shutdown hooks but still inside **`stopBareInitd`** (intervals, sync cleanup).
|
||||
- **`bareOsSubscribeBootEvent(fn)`** / **`bareOsEmitBootEvent(ev)`** — Subscribe to or emit structured boot lifecycle events (same shape as **`BARE_OS_BOOT_TRACE=ndjson`** records). Phase records carry **`lifecycleSchemaVersion`** and **`telemetrySchemaVersion`** set from stock **`BARE_OS_LIFECYCLE_SCHEMA_VERSION`** (see [compatibility matrix](../docs/reference/compatibility-matrix.md) and [kernel extensions](../docs/reference/kernel-extensions.md)).
|
||||
- **`bareOsSubscribeKernelEvent(fn)`** / **`bareOsEmitKernelEvent(ev)`** — Namespaced kernel event bus (e.g. **`topic: 'boot.phase'`**, **`bootStage`**); also mirrored to diagnostics subscribers with **`source: 'kernel'`**.
|
||||
- **`bareOsAcquireKeyHandle(hint?)`** — Key-broker sketch returning an **opaque** handle string (no raw key material in guest).
|
||||
@@ -117,21 +117,21 @@ The following are set on `ctx` before the kernel starts (unless noted as overwri
|
||||
- **`bareOsEmitMirrorDriveHint(opts?)`** — Emits **`bare-os:mirror-drive-hint`** on the host with **`label`**, **`key`**, **`ts`** (mirror-drive–style operator hint).
|
||||
- **`bareOsRegisterKernelExtensionRecord(rec)`** — Appends **`{ dropin, script }`** for **`/proc/bare_os/extensions.json`** when the stock kernel loads **`kernel.ext.d`** scripts.
|
||||
- **`bareOsDiagnosticsSubscribe(fn)`** / **`bareOsDiagnosticsEmit(ev)`** — When **`BARE_OS_DIAGNOSTICS_SUBSCRIBE=1`**, subscribe to structured booter/kernel diagnostics events (dev-oriented).
|
||||
- **`bareOsHostStats`** *(optional)* — When the `**bare-os*`* npm module loads on the host, a **frozen** snapshot: `**hostname`**, **`loadavg`**, **`cpus`**, **`networkInterfaces`**, optional **`memoryUsage`**, **`peerCount`** (swarm peers during session build), **`atMs`**.
|
||||
- **`httpFetch`** *(optional)* — When the booter can build a policy-wrapped `**fetch*`*, it sets this field; delegated **`curl`** / **`wget`** prefer **`resolveBareOsFetchFn`**, which uses **`ctx.httpFetch`** first, then **`ctx.bare.fetch`** (including **`/lib/bare/bundles`** merge, with **`.default`** unwrap), then **`globalThis.fetch`**. On hosts without native fetch, **`ensureBareFetchGlobals`** may install **`bare-fetch`** or **`bare-https`**. Optional **HTTP allow/deny** (`**BARE_OS_HTTP_ALLOWLIST`**, **`BARE_OS_HTTP_DENYLIST`**) and audit hooks when **`BARE_OS_AUDIT`** is on. In-guest **`/bin/agent`** uses the same **`ctx.httpFetch`** for OpenAI-compatible **`/chat/completions`** and for the **`web_fetch`** tool (allowlist every API and **`web_fetch`** target host). See [HTTP: curl and wget](../docs/reference/http-curl-and-wget.md) and **`man agent`**.
|
||||
- **`bareOsHrpcRequest(service, method, payload)`** — **`async`** — stock **HRPC** bridge for versioned `**service.method`** routes (for example **`bare_os.pkg_index_get`**, **`vfs.readText`**). **`payload`** must be an object; non-stock routes are denied unless the host replaces this method or enables **`BARE_OS_HRPC_EMIT_UNLISTED`**. Optional **`BARE_OS_HRPC_ALLOWLIST_JSON`** restricts the stock table (see schema `[bare-os-hrpc-allowlist.schema.json](../docs/schemas/bare-os-hrpc-allowlist.schema.json)`); env is documented in [environment appendix §14](../docs/reference/environment-and-posix-appendix.md#14-environment-variables-complete-list). **`ctx.bareOsHrpcAllowlistProbe`** stays aligned with the same parser.
|
||||
- **`bareOsHostStats`** *(optional)* — When the `**bare-os*`* npm module loads on the host, a **frozen** snapshot: **`hostname`**, **`loadavg`**, **`cpus`**, **`networkInterfaces`**, optional **`memoryUsage`**, **`peerCount`** (swarm peers during session build), **`atMs`**.
|
||||
- **`httpFetch`** *(optional)* — When the booter can build a policy-wrapped `**fetch*`*, it sets this field; delegated **`curl`** / **`wget`** prefer **`resolveBareOsFetchFn`**, which uses **`ctx.httpFetch`** first, then **`ctx.bare.fetch`** (including **`/lib/bare/bundles`** merge, with **`.default`** unwrap), then **`globalThis.fetch`**. On hosts without native fetch, **`ensureBareFetchGlobals`** may install **`bare-fetch`** or **`bare-https`**. Optional **HTTP allow/deny** (**`BARE_OS_HTTP_ALLOWLIST`**, **`BARE_OS_HTTP_DENYLIST`**) and audit hooks when **`BARE_OS_AUDIT`** is on. In-guest **`/bin/agent`** uses the same **`ctx.httpFetch`** for OpenAI-compatible **`/chat/completions`** and for the **`web_fetch`** tool (allowlist every API and **`web_fetch`** target host). See [HTTP: curl and wget](../docs/reference/http-curl-and-wget.md) and **`man agent`**.
|
||||
- **`bareOsHrpcRequest(service, method, payload)`** — **`async`** — stock **HRPC** bridge for versioned **`service.method`** routes (for example **`bare_os.pkg_index_get`**, **`vfs.readText`**). **`payload`** must be an object; non-stock routes are denied unless the host replaces this method or enables **`BARE_OS_HRPC_EMIT_UNLISTED`**. Optional **`BARE_OS_HRPC_ALLOWLIST_JSON`** restricts the stock table (see schema `[bare-os-hrpc-allowlist.schema.json](../docs/schemas/bare-os-hrpc-allowlist.schema.json)`); env is documented in [environment appendix §14](../docs/reference/environment-and-posix-appendix.md#14-environment-variables-complete-list). **`ctx.bareOsHrpcAllowlistProbe`** stays aligned with the same parser.
|
||||
|
||||
Kernel boot composition lives on the **system image** (`/boot/init.js`, `/etc/bare-os/rc`, `/etc/bare-os/rc.d/`, optional `**/etc/bare-os/rc.local`**, optional **`/etc/bare-os/kernel.d/`** (same digit-prefix rules as **`rc.d`**), optional **`/etc/bare-os/profile`** / **`rc.profile.*`**, **`/etc/bare-os/onboot`**), not on `ctx`—extend the image or hooks like **`registerKernelShutdownHook`** rather than adding boot fields to the context object. The booter seeds **`ctx.env`** from the host for **`BARE_OS_PIPELINE_*`** (including **`BARE_OS_PIPELINE_ABS_MAX_BYTES**`, `**BARE_OS_PIPELINE_ABS_MAX_LINES`**), **`BARE_OS_SHELL_STREAMING`**, **`BARE_OS_SHELL_STREAMING_MULT`** (alias **`BARE_OS_STREAMING_MULTIPLIER**`), **`BARE_OS_SHELL_CMDSUBST`**, **`BARE_OS_SHELL_CMDSUBST_MAX_BYTES`**, boot profile / audit / IPC / HTTP policy keys (**`BARE_OS_IPC_CHANNEL_MAX_BYTES`**, **`BARE_OS_IPC_MAX_CHANNELS`**, **`BARE_OS_POSIX_MQ_MAX_MSGS**`, **`BARE_OS_POSIX_MQ_MSG_BYTES**`, …), **`BARE_OS_VFS_WATCH`**, **`BARE_OS_VFS_MAX_OPEN`**, **`BARE_OS_VFS_UNION_PREFIXES`**, **`BARE_OS_VFS_UNION_WRITE_DENY`**, **`BARE_OS_VFS_BIN_CACHE`**, **`BARE_OS_IMAGE_DIGEST`**, Pear channel fields, **`BARE_OS_BOOT_MANIFEST`**, **`BARE_OS_BOOT_MANIFEST_SIGN`**, **`BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`**, **`BARE_OS_BOOT_POLICY`**, **`BARE_OS_SANDBOX_SCRIPT`**, **`BARE_OS_SANDBOX_WORKER`**, **`BARE_OS_INITD_MAX_PARALLEL`**, **`BARE_OS_INITD_JOURNAL_MAX_LINES`**, **`BARE_OS_URANDOM_CRYPTO`**, **`BARE_OS_TELEMETRY_NDJSON`**, **`BARE_OS_TELEMETRY_OTEL_JSONL`** / **`BARE_OS_TELEMETRY_OTEL**`, **`BARE_OS_EXEC_LINE_BUDGET_MS`** / **`BARE_OS_TIMER_BUDGET_MS**`, **`BARE_OS_SEED_RPC_HANDSHAKE`**, **`BARE_OS_SEED_CAP_STRICT`**, **`BARE_OS_SEED_CAP_FAIL`**, **`BARE_OS_BLIND_BOOTSTRAP_URL`**, **`BARE_OS_BLIND_BOOTSTRAP_JSON`**, **`BARE_OS_MIRROR_READ_KEY`**, **`BARE_OS_FIND_EXEC_MAX`**, **`BARE_OS_YES_MAX_LINES`**, **`BARE_OS_SHUF_MAX_LINES`**, **`BARE_OS_SPLIT_MAX_FILES`**, **`BARE_OS_NPROC`**, **`TERM`**, **`COLORTERM`**, **`PEAR_CHANNEL`**, and the rest of the passthrough table in [environment appendix §14](../docs/reference/environment-and-posix-appendix.md#14-environment-variables-complete-list); always sets **`BARE_OS_BOOT_PROFILE_RESOLVED`** and **`BARE_OS_SESSION_ID`**. When **`ctx.httpFetch`** handles **`curl`**, check optional **`init.bareOsCurlTls`** (`insecure`, **`caPem`**, **`pinnedSha256`**) for **`--cacert`** / **`-k`** semantics.
|
||||
Kernel boot composition lives on the **system image** (`/boot/init.js`, `/etc/bare-os/rc`, `/etc/bare-os/rc.d/`, optional **`/etc/bare-os/rc.local`**, optional **`/etc/bare-os/kernel.d/`** (same digit-prefix rules as **`rc.d`**), optional **`/etc/bare-os/profile`** / **`rc.profile.*`**, **`/etc/bare-os/onboot`**), not on `ctx`—extend the image or hooks like **`registerKernelShutdownHook`** rather than adding boot fields to the context object. The booter seeds **`ctx.env`** from the host for **`BARE_OS_PIPELINE_*`** (including **`BARE_OS_PIPELINE_ABS_MAX_BYTES`**, **`BARE_OS_PIPELINE_ABS_MAX_LINES`**), **`BARE_OS_SHELL_STREAMING`**, **`BARE_OS_SHELL_STREAMING_MULT`** (alias **`BARE_OS_STREAMING_MULTIPLIER`**), **`BARE_OS_SHELL_CMDSUBST`**, **`BARE_OS_SHELL_CMDSUBST_MAX_BYTES`**, boot profile / audit / IPC / HTTP policy keys (**`BARE_OS_IPC_CHANNEL_MAX_BYTES`**, **`BARE_OS_IPC_MAX_CHANNELS`**, **`BARE_OS_POSIX_MQ_MAX_MSGS`**, **`BARE_OS_POSIX_MQ_MSG_BYTES`**, …), **`BARE_OS_VFS_WATCH`**, **`BARE_OS_VFS_MAX_OPEN`**, **`BARE_OS_VFS_UNION_PREFIXES`**, **`BARE_OS_VFS_UNION_WRITE_DENY`**, **`BARE_OS_VFS_BIN_CACHE`**, **`BARE_OS_IMAGE_DIGEST`**, Pear channel fields, **`BARE_OS_BOOT_MANIFEST`**, **`BARE_OS_BOOT_MANIFEST_SIGN`**, **`BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`**, **`BARE_OS_BOOT_POLICY`**, **`BARE_OS_SANDBOX_SCRIPT`**, **`BARE_OS_SANDBOX_WORKER`**, **`BARE_OS_INITD_MAX_PARALLEL`**, **`BARE_OS_INITD_JOURNAL_MAX_LINES`**, **`BARE_OS_URANDOM_CRYPTO`**, **`BARE_OS_TELEMETRY_NDJSON`**, **`BARE_OS_TELEMETRY_OTEL_JSONL`** / **`BARE_OS_TELEMETRY_OTEL`**, **`BARE_OS_EXEC_LINE_BUDGET_MS`** / **`BARE_OS_TIMER_BUDGET_MS`**, **`BARE_OS_SEED_RPC_HANDSHAKE`**, **`BARE_OS_SEED_CAP_STRICT`**, **`BARE_OS_SEED_CAP_FAIL`**, **`BARE_OS_BLIND_BOOTSTRAP_URL`**, **`BARE_OS_BLIND_BOOTSTRAP_JSON`**, **`BARE_OS_MIRROR_READ_KEY`**, **`BARE_OS_FIND_EXEC_MAX`**, **`BARE_OS_YES_MAX_LINES`**, **`BARE_OS_SHUF_MAX_LINES`**, **`BARE_OS_SPLIT_MAX_FILES`**, **`BARE_OS_NPROC`**, **`TERM`**, **`COLORTERM`**, **`PEAR_CHANNEL`**, and the rest of the passthrough table in [environment appendix §14](../docs/reference/environment-and-posix-appendix.md#14-environment-variables-complete-list); always sets **`BARE_OS_BOOT_PROFILE_RESOLVED`** and **`BARE_OS_SESSION_ID`**. When **`ctx.httpFetch`** handles **`curl`**, check optional **`init.bareOsCurlTls`** (`insecure`, **`caPem`**, **`pinnedSha256`**) for **`--cacert`** / **`-k`** semantics.
|
||||
|
||||
After `[createVfs](../packages/bare-os-booter/lib/vfs.js)`, **`ctx.vfs.watch(logicalPath)`** returns a Hyperdrive watcher when **`BARE_OS_VFS_WATCH`** is not disabled. With **`BARE_OS_VFS_WATCH_PSEUDO=1`**, **`vfs.watch`** may also poll coalesced **`/proc/bare_os/metrics_live.json`** (interval from **`BARE_OS_PROC_POLL_MS`**). **`ctx.bareOsIpc`** exposes FIFO `**push`/`take**` (optional per-channel byte caps from **`BARE_OS_IPC_CHANNEL_MAX_BYTES`**), optional JSON-RPC `**pushJson`/`takeJson**` (max line size, optional RPC token), `**fanoutPublish`/`fanoutSubscribe**`, **`createDuplexBridge`**, **`duplexJsonRoundTrip`** (one JSON request / one JSON reply over a duplex side — useful for unit-to-unit or guest–helper protocols without pulling **`bare-rpc`** into **`/bin`**), `**assignProcessGroup`/`signalProcessGroup**` (synthetic `**setpgid`/`killpg` analog** for IPC routing), and `**stats`** (see `[bare-os-ipc.js](../packages/bare-os-booter/lib/bare-os-ipc.js)`).
|
||||
After `[createVfs](../packages/bare-os-booter/lib/vfs.js)`, **`ctx.vfs.watch(logicalPath)`** returns a Hyperdrive watcher when **`BARE_OS_VFS_WATCH`** is not disabled. With **`BARE_OS_VFS_WATCH_PSEUDO=1`**, **`vfs.watch`** may also poll coalesced **`/proc/bare_os/metrics_live.json`** (interval from **`BARE_OS_PROC_POLL_MS`**). **`ctx.bareOsIpc`** exposes FIFO `**push`/`take**` (optional per-channel byte caps from **`BARE_OS_IPC_CHANNEL_MAX_BYTES`**), optional JSON-RPC `**pushJson`/`takeJson**` (max line size, optional RPC token), `**fanoutPublish`/`fanoutSubscribe**`, **`createDuplexBridge`**, **`duplexJsonRoundTrip`** (one JSON request / one JSON reply over a duplex side — useful for unit-to-unit or guest–helper protocols without pulling **`bare-rpc`** into **`/bin`**), `**assignProcessGroup`/`signalProcessGroup**` (synthetic `**setpgid`/`killpg` analog** for IPC routing), and **`stats`** (see `[bare-os-ipc.js](../packages/bare-os-booter/lib/bare-os-ipc.js)`).
|
||||
|
||||
When **`BARE_OS_KERNEL_EXT_D_HOT_RELOAD=1`**, the stock kernel may define **`ctx.bareOsReloadKernelExtDropinsSafe()`** to append-only load new **`kernel.ext.d`** scripts after boot (see [handbook ch.6](../handbook/06-kernel-and-binaries.md)).
|
||||
|
||||
**Initd / long-running services:** prefer `**duplexJsonRoundTrip`** or `**pushJson`/`takeJson**` for structured messages with byte limits already enforced by IPC options. A dedicated **`bare-rpc`** dependency is optional on the host or in **`ctx.bare`** if you need richer framing; the stock image documents the FIFO-level building blocks only.
|
||||
**Initd / long-running services:** prefer **`duplexJsonRoundTrip`** or `**pushJson`/`takeJson**` for structured messages with byte limits already enforced by IPC options. A dedicated **`bare-rpc`** dependency is optional on the host or in **`ctx.bare`** if you need richer framing; the stock image documents the FIFO-level building blocks only.
|
||||
|
||||
After `[createKernelReplSession](../packages/bare-os-booter/lib/repl-session.js)` returns:
|
||||
|
||||
- **`ctx.execLine(line, opts?)`** runs a **full shell line** (tokenize, builtins, pipelines, `**/bin`** resolution). Optional **`opts`**: **`{ signal?: AbortSignal, timeoutMs?: number }`** (deadline for the shell pipeline work).
|
||||
- **`ctx.execLine(line, opts?)`** runs a **full shell line** (tokenize, builtins, pipelines, **`/bin`** resolution). Optional **`opts`**: **`{ signal?: AbortSignal, timeoutMs?: number }`** (deadline for the shell pipeline work).
|
||||
- **`ctx.readLine(prompt, opts?)`** prompts and reads user input; same optional **`opts`** for abort/timeout.
|
||||
- **`ctx.runBinCommand(argv, opts?)`** passes through abort/timeout to the delegated command runner.
|
||||
- **`ctx.vfs.readFile(path, opts?)`** and **`ctx.vfs.writeFile(path, buf, opts?)`** accept `**signal`/`timeoutMs**` in **`opts`** (writeFile merges with **`executable`**).
|
||||
@@ -145,9 +145,9 @@ After `[createKernelReplSession](../packages/bare-os-booter/lib/repl-session.js)
|
||||
|
||||
When the shell runs an external command (or a pipeline stage), it may pass a **shallow clone** of `ctx` with extra fields:
|
||||
|
||||
- `**shellStdin`** — String body for simulated stdin (pipelines and `<` redirection)
|
||||
- **`shellStdin`** — String body for simulated stdin (pipelines and `<` redirection)
|
||||
- **`bareOsStdoutCaptured`** — **`true`** when this command’s stdout is captured into the simulated pipe or a **`>`** / **`>>`** redirect (see **`bareOsPipelineChildCtx`** in `[shell.js](../packages/bare-os-booter/lib/shell.js)`). **`ls`** uses this to print **one name per line**, matching common GNU behavior for non-terminal output.
|
||||
- `**exitCode`** — Utilities set **`ctx.exitCode`** for conditions (**`test`**, **`grep`**, …); the shell uses it for **`&&`**, logical OR lists, and **`;`** sequencing (see `[shell.js](../packages/bare-os-booter/lib/shell.js)`)
|
||||
- **`exitCode`** — Utilities set **`ctx.exitCode`** for conditions (**`test`**, **`grep`**, …); the shell uses it for **`&&`**, logical OR lists, and **`;`** sequencing (see `[shell.js](../packages/bare-os-booter/lib/shell.js)`)
|
||||
|
||||
Always use the `ctx` passed into **`run`**, not a global, so pipeline stdin works.
|
||||
|
||||
@@ -158,7 +158,7 @@ Always use the `ctx` passed into **`run`**, not a global, so pipeline stdin work
|
||||
- No `**require*`*, no **`import`** helper—the in-image script is not a CommonJS or ESM module.
|
||||
- No automatic **`fetch`** guarantee—depends on host/Pear globals; do not rely on it for portable `/bin` utilities.
|
||||
- **`process`** may exist on Bare/Node hosts but **do not** depend on it for utilities meant to run identically under Pear; use `ctx.console` and `ctx.env`.
|
||||
- **bare-initd control** is not a `**ctx`** method: use **`/bin/systemctl`** (or **`journalctl`**; **`bare-initctl`** is a legacy alias), which the booter handles via delegation—same pattern as **`git`** / **`curl`**.
|
||||
- **bare-initd control** is not a **`ctx`** method: use **`/bin/systemctl`** (or **`journalctl`**; **`bare-initctl`** is a legacy alias), which the booter handles via delegation—same pattern as **`git`** / **`curl`**.
|
||||
|
||||
---
|
||||
|
||||
@@ -206,7 +206,7 @@ async function run(ctx, argv) {
|
||||
}
|
||||
```
|
||||
|
||||
On **Pear**, `**ctx.bare`** is populated from the booter’s embedded **`bare-module-manifest.data.mjs`**, not from **`readFile`** of **`pear://…`** paths. Updating **`/lib/bare/bare-module-manifest.json`** on the system drive still affects **VFS warm-cache** eviction for `**/lib/bare/bundles/*`** via the helpers above, but operators must **re-stage the booter** after `**npm run sync:bare-manifest`** to change manifest metadata; when the booter runs as **`pear:`**, host **`import()`** skips **`bundle: true`** rows (drive bundles supply those keys). See [Chapter 12 — Bare modules](12-bare-modules-and-pear-ecosystem.md) and [PEAR-RUN.md](../docs/PEAR-RUN.md).
|
||||
On **Pear**, **`ctx.bare`** is populated from the booter’s embedded **`bare-module-manifest.data.mjs`**, not from **`readFile`** of **`pear://…`** paths. Updating **`/lib/bare/bare-module-manifest.json`** on the system drive still affects **VFS warm-cache** eviction for **`/lib/bare/bundles/*`** via the helpers above, but operators must **re-stage the booter** after `**npm run sync:bare-manifest`** to change manifest metadata; when the booter runs as **`pear:`**, host **`import()`** skips **`bundle: true`** rows (drive bundles supply those keys). See [Chapter 12 — Bare modules](12-bare-modules-and-pear-ecosystem.md) and [PEAR-RUN.md](../docs/PEAR-RUN.md).
|
||||
|
||||
**Read the Protomux extension registry mirror** (when `BARE_OS_PROC_PROTOMUX_EXTENSIONS_REGISTRY` is enabled on the booter):
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Chapter 3 — Kernel: `/boot/init.js` and `start(ctx)`
|
||||
|
||||
The **kernel** in Bare OS is not a microkernel and not a scheduler. It is a **JavaScript file** on the system Hyperdrive at **`/boot/init.js**`, loaded as UTF-8 text and executed with `**runKernelFromSource`** in [`kernel-runner.js`](../packages/bare-os-booter/lib/kernel-runner.js). The booter expects a top-level:
|
||||
The **kernel** in Bare OS is not a microkernel and not a scheduler. It is a **JavaScript file** on the system Hyperdrive at **`/boot/init.js`**, loaded as UTF-8 text and executed with **`runKernelFromSource`** in [`kernel-runner.js`](../packages/bare-os-booter/lib/kernel-runner.js). The booter expects a top-level:
|
||||
|
||||
```js
|
||||
async function start(ctx) {
|
||||
@@ -8,7 +8,7 @@ async function start(ctx) {
|
||||
}
|
||||
```
|
||||
|
||||
There is **no `argv**` at the kernel layer—the session’s command line is whatever the **interactive user** types after boot, handled through `**ctx.readLine**` and `**ctx.execLine`**.
|
||||
There is **no `argv**` at the kernel layer—the session’s command line is whatever the **interactive user** types after boot, handled through **`ctx.readLine`** and **`ctx.execLine`**.
|
||||
|
||||
**Source of truth:** The file committed as [`kernel/init.js`](../kernel/init.js) is the concatenation of sorted [`kernel/lib/boot/`](../kernel/lib/boot/) fragments, sorted [`kernel/lib/init/fragments/`](../kernel/lib/init/fragments/) (boot policy and `kernel.ext.d` loader), and [`kernel/lib/init/init-main.js`](../kernel/lib/init/init-main.js). Run **`npm run bundle:kernel**` after edits; use `**npm run verify:init-bundle`** or full pretest to confirm the bundle matches. Never edit `init.js` directly—changes would be overwritten and CI will fail. Layout: [`kernel/lib/init/STRUCTURE.md`](../kernel/lib/init/STRUCTURE.md).
|
||||
|
||||
@@ -18,11 +18,11 @@ There is **no `argv**` at the kernel layer—the session’s command line is wha
|
||||
|
||||
The repository’s default kernel ([`kernel/init.js`](../kernel/init.js), generated as above) is intentionally small:
|
||||
|
||||
1. Print **`/etc/os-release**` and optional `**/etc/motd`** (errors logged, not fatal).
|
||||
2. Optional **profile** snippet **`/etc/bare-os/rc.profile.<name>**` when `**BARE_OS_BOOT_PROFILE**` or the first line of `**/etc/bare-os/profile`** names a safe profile string.
|
||||
3. Run **`/etc/bare-os/rc**`, then sorted digit-prefixed `**/etc/bare-os/rc.d/***`, then optional `**/etc/bare-os/rc.local**`, then sorted digit-prefixed `**/etc/bare-os/kernel.d/***` (same naming rules as `**rc.d**`), then optional `**/etc/bare-os/kernel.ext.d/*.json`** extension lists (see [Handbook ch.6](../handbook/06-kernel-and-binaries.md)).
|
||||
4. Print session banner (from **`/etc/bare-os/banner**`, `**/etc/issue`**, or a built-in hint).
|
||||
5. If **`ctx.bareOsSkipRepl`**: run every non-empty, non-`#` line from **`BARE_OS_ONBOOT**` (newline-separated), or if that env is unset, the same from `**/etc/bare-os/onboot**` in file order, via `**execLine**`; then fall through to the loop (where `**readLine**` returns `**null`** immediately).
|
||||
1. Print **`/etc/os-release`** and optional **`/etc/motd`** (errors logged, not fatal).
|
||||
2. Optional **profile** snippet **`/etc/bare-os/rc.profile.<name>`** when **`BARE_OS_BOOT_PROFILE`** or the first line of **`/etc/bare-os/profile`** names a safe profile string.
|
||||
3. Run **`/etc/bare-os/rc`**, then sorted digit-prefixed **`/etc/bare-os/rc.d/*`**, then optional **`/etc/bare-os/rc.local`**, then sorted digit-prefixed **`/etc/bare-os/kernel.d/*`** (same naming rules as **`rc.d`**), then optional **`/etc/bare-os/kernel.ext.d/*.json`** extension lists (see [Handbook ch.6](../handbook/06-kernel-and-binaries.md)).
|
||||
4. Print session banner (from **`/etc/bare-os/banner`**, **`/etc/issue`**, or a built-in hint).
|
||||
5. If **`ctx.bareOsSkipRepl`**: run every non-empty, non-`#` line from **`BARE_OS_ONBOOT`** (newline-separated), or if that env is unset, the same from **`/etc/bare-os/onboot`** in file order, via **`execLine`**; then fall through to the loop (where **`readLine`** returns **`null`** immediately).
|
||||
6. Loop forever:
|
||||
- `line = await ctx.readLine('')`
|
||||
- If `line == null`, break (session end / EOF).
|
||||
@@ -30,15 +30,15 @@ The repository’s default kernel ([`kernel/init.js`](../kernel/init.js), genera
|
||||
- `status = await ctx.execLine(line)` inside try/catch (`console.error` on failure).
|
||||
- If `status === 'exit'`, break.
|
||||
|
||||
Set **`BARE_OS_BOOT_TRACE=1**` (or `**true**`) in the environment to log boot phase timings on stderr as `**[boot] phase: Nms**`. Use `**BARE_OS_BOOT_TRACE=json**` for one JSON object per phase (`**{"phase":"…","ms":n}**`) on stderr. The same phases are also delivered to `**ctx.bareOsSubscribeBootEvent`** subscribers as NDJSON-shaped objects.
|
||||
Set **`BARE_OS_BOOT_TRACE=1`** (or **`true`**) in the environment to log boot phase timings on stderr as `**[boot] phase: Nms**`. Use **`BARE_OS_BOOT_TRACE=json`** for one JSON object per phase (`**{"phase":"…","ms":n}**`) on stderr. The same phases are also delivered to **`ctx.bareOsSubscribeBootEvent`** subscribers as NDJSON-shaped objects.
|
||||
|
||||
**`BARE_OS_BOOT_PERF_DETAIL=1**` collects per-stage `**wallMs**` and optional `**bare-hrtime**` `**monotonicNs**` samples into `**/run/bare-os/boot-perf.json**` (**schema 2** when stages are present). `**BARE_OS_KERNEL_EXT_GRAPH=1**` writes `**/run/bare-os/kernel-ext-graph.json**` after `**kernel.ext.d**` ordering (and probes whether `**bare-module-traverse`** can be imported on the host).
|
||||
**`BARE_OS_BOOT_PERF_DETAIL=1`** collects per-stage **`wallMs`** and optional **`bare-hrtime`** **`monotonicNs`** samples into **`/run/bare-os/boot-perf.json`** (**schema 2** when stages are present). **`BARE_OS_KERNEL_EXT_GRAPH=1`** writes **`/run/bare-os/kernel-ext-graph.json`** after **`kernel.ext.d`** ordering (and probes whether **`bare-module-traverse`** can be imported on the host).
|
||||
|
||||
**Kernel program boot hooks** (see [kernel-program.md](./kernel-program.md)): **`BARE_OS_BOOT_SAFE_MODE**` skips `**rc.d**`, `**kernel.ext.d**`, and `**onboot**`; `**BARE_OS_BOOT_TRANSACTION_JOURNAL**` appends phase NDJSON to `**/run/bare-os/boot-transaction.ndjson**` (each line includes a `**bootStage**`); `**BARE_OS_BOOT_CHECKPOINT**` refreshes `**/run/bare-os/boot-checkpoint.json**` after each phase (**schema 2** adds `**bootStage**`). `**BARE_OS_BOOT_DRY_RUN**` skips trusted `**execLine**` and extension scripts; `**BARE_OS_BOOT_POLICY_PATH**` / `**policyFallbackPaths**` tier policy files; rollback marker + `**BARE_OS_BOOT_ROLLBACK_APPLY**`; `**kernel.d**` snippets may start with `**# ConditionEnvironment=KEY=VAL**` comment guards; `**bareOsPublishBootReady**` includes `**subsystems.kernel.bootPhases**` with `**bootStage**` labels. Extension drop-ins may use `**requires**`, `**after**`, and `**before**` for ordering alongside `**dependsOn**`. The booter emits additional `**booter:***` phases (`**vfs**`, `**ctx**`, `**repl**`, `**initd**`, `**kernel_invoke**`) and records them under `**booterPhases**` in `**/run/bare-os/boot.json**`. `**BARE_OS_BOOT_ALLOWLIST=1**` with `**/etc/bare-os/boot.allow**` restricts the first token of lines in trusted rc/onboot snippets. Inspect `**ctx.bareOsRuntimeCaps**` for pipeline limits, quotas, pseudo paths, and `**features**` (including `**httpDelegate**`, `**gitDelegate**`, `**systemctlDelegate**`, `**vfsWatch**`, `**ipcFanout`**).
|
||||
**Kernel program boot hooks** (see [kernel-program.md](./kernel-program.md)): **`BARE_OS_BOOT_SAFE_MODE`** skips **`rc.d`**, **`kernel.ext.d`**, and **`onboot`**; **`BARE_OS_BOOT_TRANSACTION_JOURNAL`** appends phase NDJSON to **`/run/bare-os/boot-transaction.ndjson`** (each line includes a **`bootStage`**); **`BARE_OS_BOOT_CHECKPOINT`** refreshes **`/run/bare-os/boot-checkpoint.json`** after each phase (**schema 2** adds **`bootStage`**). **`BARE_OS_BOOT_DRY_RUN`** skips trusted **`execLine`** and extension scripts; **`BARE_OS_BOOT_POLICY_PATH`** / **`policyFallbackPaths`** tier policy files; rollback marker + **`BARE_OS_BOOT_ROLLBACK_APPLY`**; **`kernel.d`** snippets may start with `**# ConditionEnvironment=KEY=VAL**` comment guards; **`bareOsPublishBootReady`** includes **`subsystems.kernel.bootPhases`** with **`bootStage`** labels. Extension drop-ins may use **`requires`**, **`after`**, and **`before`** for ordering alongside **`dependsOn`**. The booter emits additional **`booter:*`** phases (**`vfs`**, **`ctx`**, **`repl`**, **`initd`**, **`kernel_invoke`**) and records them under **`booterPhases`** in **`/run/bare-os/boot.json`**. **`BARE_OS_BOOT_ALLOWLIST=1`** with **`/etc/bare-os/boot.allow`** restricts the first token of lines in trusted rc/onboot snippets. Inspect **`ctx.bareOsRuntimeCaps`** for pipeline limits, quotas, pseudo paths, and **`features`** (including **`httpDelegate`**, **`gitDelegate`**, **`systemctlDelegate`**, **`vfsWatch`**, **`ipcFanout`**).
|
||||
|
||||
**Boot policy v5** (optional **`/etc/bare-os/boot.policy.json**` fields when `**BARE_OS_BOOT_POLICY=1**`): `**requireKernelCapabilitiesHostTransportDelegates**` and `**requireInitJsSha256**` (64-char lowercase hex of raw `**/boot/init.js**` via `**ctx.bareOsBootFileSha256Hex**`). `**BARE_OS_KERNEL_PROFILE_WARM=1**` enables `**ctx.bareOsRequestKernelProfileReload()**` for a warm `**start(ctx)`** re-run without dropping the swarm session (same machinery as hot reload).
|
||||
**Boot policy v5** (optional **`/etc/bare-os/boot.policy.json`** fields when **`BARE_OS_BOOT_POLICY=1`**): **`requireKernelCapabilitiesHostTransportDelegates`** and **`requireInitJsSha256`** (64-char lowercase hex of raw **`/boot/init.js`** via **`ctx.bareOsBootFileSha256Hex`**). **`BARE_OS_KERNEL_PROFILE_WARM=1`** enables `**ctx.bareOsRequestKernelProfileReload()**` for a warm `**start(ctx)`** re-run without dropping the swarm session (same machinery as hot reload).
|
||||
|
||||
Optional **`BARE_OS_KERNEL_SELFTEST=1**` runs built-in checks after boot snippets. Set `**BARE_OS_SELFTEST_FORMAT=tap**` for TAP on `**ctx.console.error**` (session stderr, not the host’s raw `**globalThis.console**`), or `**junit**` for a single-line XML `**testsuite**` on the same sink—matching how `**runKernelSelftest**` binds the harness. You can pass `**{ signal, timeoutMs }**` as a second argument to `**ctx.execLine**`, `**ctx.readLine**`, `**ctx.runBinCommand**`, and VFS `**readFile`/`writeFile`** for bounded waits—see [Chapter 2](02-the-context-object.md).
|
||||
Optional **`BARE_OS_KERNEL_SELFTEST=1`** runs built-in checks after boot snippets. Set **`BARE_OS_SELFTEST_FORMAT=tap`** for TAP on **`ctx.console.error`** (session stderr, not the host’s raw **`globalThis.console`**), or **`junit`** for a single-line XML **`testsuite`** on the same sink—matching how **`runKernelSelftest`** binds the harness. You can pass `**{ signal, timeoutMs }**` as a second argument to **`ctx.execLine`**, **`ctx.readLine`**, **`ctx.runBinCommand`**, and VFS `**readFile`/`writeFile`** for bounded waits—see [Chapter 2](02-the-context-object.md).
|
||||
|
||||
So the “OS personality” is mostly the **shell** (`execShellLine` behind `execLine`) plus **`/bin`**.
|
||||
|
||||
@@ -52,17 +52,17 @@ The stock kernel passes `''` as the prompt. The actual prompt rendering (fish-st
|
||||
|
||||
## Using `execLine` vs calling `runBinCommand` directly
|
||||
|
||||
- **`await ctx.execLine('ls -la')`** — Full **shell** semantics: tokenization, aliases, builtins (`cd`, `export`, …), **`;**` / `**&&**` / logical-OR lists, pipelines, redirections, then `**/bin`**
|
||||
- **`await ctx.execLine('ls -la')`** — Full **shell** semantics: tokenization, aliases, builtins (`cd`, `export`, …), **`;**` / `**&&**` / logical-OR lists, pipelines, redirections, then **`/bin`**
|
||||
- **`await ctx.runBinCommand(['ls', '-la'])`** — **Direct** utility invocation—**no** shell parsing, **no** aliases
|
||||
|
||||
Use **`execLine**` when you want users to type natural shell commands from your kernel loop. Use `**runBinCommand`** when you already have an argv array and want to avoid re-parsing.
|
||||
Use **`execLine`** when you want users to type natural shell commands from your kernel loop. Use **`runBinCommand`** when you already have an argv array and want to avoid re-parsing.
|
||||
|
||||
---
|
||||
|
||||
## Session termination
|
||||
|
||||
- The **`exit**` builtin (or `**/bin/exit**`) ultimately calls `**ctx.requestBooterExit(code)**`, which forces `**readLine`** to return `null` on subsequent calls and ends the loop.
|
||||
- **`BARE_OS_SKIP_REPL=1**` makes `**readLine`** return `null` immediately—useful for non-interactive smoke tests. Pair with **`BARE_OS_ONBOOT**` (one or more newline-separated lines) or `**/etc/bare-os/onboot**` so the stock kernel runs trusted `**execLine`** snippets before idle exit.
|
||||
- The **`exit`** builtin (or **`/bin/exit`**) ultimately calls `**ctx.requestBooterExit(code)**`, which forces **`readLine`** to return `null` on subsequent calls and ends the loop.
|
||||
- **`BARE_OS_SKIP_REPL=1`** makes **`readLine`** return `null` immediately—useful for non-interactive smoke tests. Pair with **`BARE_OS_ONBOOT`** (one or more newline-separated lines) or **`/etc/bare-os/onboot`** so the stock kernel runs trusted **`execLine`** snippets before idle exit.
|
||||
|
||||
---
|
||||
|
||||
@@ -71,9 +71,9 @@ Use **`execLine**` when you want users to type natural shell commands from your
|
||||
1. **Keep the loop async**—never block on synchronous host APIs that might hang the Pear app.
|
||||
2. **Catch errors** around `execLine` so a typo does not tear down the whole session unless you want that.
|
||||
3. **Do not assume `import`**—the kernel source is the same `AsyncFunction` model as `/bin` (Chapter 1).
|
||||
4. To add **startup services**, prefer hooks already wired in the booter (**`startBareInitd**`)—stock units include `**bare-os-www**` (loopback HTTP for `**~/.www**`, see [Handbook ch.4](../handbook/04-the-booter-runtime.md#bare-os-www-static-http-for-www))—or a small kernel that calls `**runBinCommand`** after banner; see [Chapter 7](07-apps-beyond-the-shell.md).
|
||||
4. To add **startup services**, prefer hooks already wired in the booter (**`startBareInitd`**)—stock units include **`bare-os-www`** (loopback HTTP for **`~/.www`**, see [Handbook ch.4](../handbook/04-the-booter-runtime.md#bare-os-www-static-http-for-www))—or a small kernel that calls **`runBinCommand`** after banner; see [Chapter 7](07-apps-beyond-the-shell.md).
|
||||
5. To run code when the session ends, use **`ctx.registerKernelShutdownHook(fn)`** (runs before initd disposers); see [Chapter 2 — `ctx`](02-the-context-object.md).
|
||||
6. After **`login**`, `**~/.barerc**` is reloaded automatically via `**applyUnlockedEnv**`—see [Handbook — Identity](../handbook/05-identity-vault-and-hdms.md). The stock `**init.js**` does not re-print the boot banner; use `**onIdentityUnlocked`** or a custom kernel loop if you want that.
|
||||
6. After **`login`**, **`~/.barerc`** is reloaded automatically via **`applyUnlockedEnv`**—see [Handbook — Identity](../handbook/05-identity-vault-and-hdms.md). The stock **`init.js`** does not re-print the boot banner; use **`onIdentityUnlocked`** or a custom kernel loop if you want that.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ This chapter is the practical “how do I run my own `.js` file?” guide. Resol
|
||||
|
||||
## The entrypoint contract (again)
|
||||
|
||||
The booter evaluates your file as the body of an async function with parameters **`ctx**` and `**argv**`. Top-level statements run first (like a small **Node** script). Optionally, define a top-level `**run**` for the same contract as `**/bin`** utilities:
|
||||
The booter evaluates your file as the body of an async function with parameters **`ctx`** and **`argv`**. Top-level statements run first (like a small **Node** script). Optionally, define a top-level **`run`** for the same contract as **`/bin`** utilities:
|
||||
|
||||
```js
|
||||
async function run(ctx, argv) {
|
||||
@@ -24,7 +24,7 @@ new AsyncFunction(
|
||||
)
|
||||
```
|
||||
|
||||
If **`run**` exists, it is **awaited** after the rest of the file. `**/bin**` commands always define `**run**`; home-directory scripts may use top-level code only (e.g. `**console.log(...)`**).
|
||||
If **`run`** exists, it is **awaited** after the rest of the file. **`/bin`** commands always define **`run`**; home-directory scripts may use top-level code only (e.g. `**console.log(...)`**).
|
||||
|
||||
---
|
||||
|
||||
@@ -33,15 +33,15 @@ If **`run**` exists, it is **awaited** after the rest of the file. `**/bin**` co
|
||||
When the user types a command, roughly:
|
||||
|
||||
1. **Git delegation** — If the command is **`git`** (and not `./git`), the booter runs the **hosted** git CLI instead of `/bin/git` bytes.
|
||||
2. **Path with slash** — If `argv[0]` contains **`/**`, treat as a path: resolve via `**ctx.vfs`**, read bytes from the routed drive, evaluate as script.
|
||||
2. **Path with slash** — If `argv[0]` contains **`/`**, treat as a path: resolve via **`ctx.vfs`**, read bytes from the routed drive, evaluate as script.
|
||||
3. **Ends with `.js`** — Resolve `cmd` as a logical path (e.g. `foo.js` in `$PWD`), read from VFS if found, evaluate.
|
||||
4. **PATH search** — For each directory in **`$PATH`** (default `/bin`), try **`unixPathResolve(dir, cmd)`** on the **system** drive only; first hit wins.
|
||||
|
||||
Implications:
|
||||
|
||||
- **`./my.js**` and `**/home/user/my.js`** use **VFS** (personal or system as appropriate).
|
||||
- **`./my.js`** and **`/home/user/my.js`** use **VFS** (personal or system as appropriate).
|
||||
- **`hello.js`** in the current directory is tried **before** `/bin` if the file exists on the routed drive.
|
||||
- **`ls**` resolves to `**/bin/ls`** on the system drive (unless shadowed by a same-named `*.js` in cwd—know this edge case).
|
||||
- **`ls`** resolves to **`/bin/ls`** on the system drive (unless shadowed by a same-named `*.js` in cwd—know this edge case).
|
||||
|
||||
---
|
||||
|
||||
@@ -53,7 +53,7 @@ A leading line like `#!/usr/bin/env bare` is **stripped** before compilation. It
|
||||
|
||||
## Stdin in pipelines
|
||||
|
||||
The shell does **not** give your script a POSIX `fd 0`. For pipeline stages, stdin is simulated: the shell captures **`console.log**` output from the left stage as a **string** and passes `**ctx.shellStdin`** on a cloned `ctx` to the right stage. Utilities that want stdin read **`bareStdin(ctx)`** from the **coreutils prelude**—but **user scripts on the home drive do not get that prelude** unless you copy the helper into your file.
|
||||
The shell does **not** give your script a POSIX `fd 0`. For pipeline stages, stdin is simulated: the shell captures **`console.log`** output from the left stage as a **string** and passes **`ctx.shellStdin`** on a cloned `ctx` to the right stage. Utilities that want stdin read **`bareStdin(ctx)`** from the **coreutils prelude**—but **user scripts on the home drive do not get that prelude** unless you copy the helper into your file.
|
||||
|
||||
Minimal stdin read in a user script:
|
||||
|
||||
@@ -68,15 +68,15 @@ async function run(ctx, argv) {
|
||||
|
||||
## Environment and `cd`
|
||||
|
||||
- **`ctx.env**` is the same object mutated by `**export**` and `**cd**` (via `**vfs.chdir**` and `**PWD`**).
|
||||
- Paths like **`~/doc**` are expanded by the VFS when you use `**vfs.readFile**` and friends—prefer `**ctx.vfs`** over raw drive access for user-level scripts.
|
||||
- **`ctx.env`** is the same object mutated by **`export`** and **`cd`** (via **`vfs.chdir`** and **`PWD`**).
|
||||
- Paths like **`~/doc`** are expanded by the VFS when you use **`vfs.readFile`** and friends—prefer **`ctx.vfs`** over raw drive access for user-level scripts.
|
||||
|
||||
---
|
||||
|
||||
## Git and special cases
|
||||
|
||||
- Prefer the **`git`** command for version control; it is **not** the same as evaluating `/bin/git` as JS.
|
||||
- **`command -v**` / `**type**` use `**resolveBinInPath`** (system drive PATH only) plus builtin tables.
|
||||
- **`command -v**` / **`type`** use **`resolveBinInPath`** (system drive PATH only) plus builtin tables.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -73,13 +73,13 @@ Use this for **new protocols**, **drive encryption**, **alternate kernels**, etc
|
||||
|
||||
## `ctx.bare` — Holepunch-style modules without `import`
|
||||
|
||||
When **`BARE_OS_BARE_MODULES**` is not disabled, the booter exposes `**ctx.bare`**: a **frozen** object whose keys are defined by [`bare-module-manifest.json`](../packages/bare-os-booter/lib/bare-module-manifest.json). Each entry names an npm package and a stable **`ctxKey**` (for example `**b4a**`, `**protomux**`, `**compactEncoding**`, `**holesail`**).
|
||||
When **`BARE_OS_BARE_MODULES`** is not disabled, the booter exposes **`ctx.bare`**: a **frozen** object whose keys are defined by [`bare-module-manifest.json`](../packages/bare-os-booter/lib/bare-module-manifest.json). Each entry names an npm package and a stable **`ctxKey`** (for example **`b4a`**, **`protomux`**, **`compactEncoding`**, **`holesail`**).
|
||||
|
||||
**Drive bundles (trusted image):** the system image may include **`/lib/bare/manifest.json**` and `**/lib/bare/bundles/*.js**`. Those scripts are **IIFE** bundles built by `**bare-os-bare-libs**`. The booter executes them with `**Function**` in the same trust class as seeded `**/bin**` utilities and fills `**ctx.bare**` for the listed keys. Set `**BARE_OS_BARE_DRIVE_BUNDLES=0`** to skip this step.
|
||||
**Drive bundles (trusted image):** the system image may include **`/lib/bare/manifest.json`** and **`/lib/bare/bundles/*.js`**. Those scripts are **IIFE** bundles built by **`bare-os-bare-libs`**. The booter executes them with **`Function`** in the same trust class as seeded **`/bin`** utilities and fills **`ctx.bare`** for the listed keys. Set **`BARE_OS_BARE_DRIVE_BUNDLES=0`** to skip this step.
|
||||
|
||||
**Host resolution:** after drive merge, the booter uses dynamic **`import()**` for manifest entries that are **still missing**. When the booter loads from a `**pear:**` URL (`**pear run**`), rows with `**bundle: true**` are **not** host-`**import()**`ed (bare-module cannot resolve npm package names from that referrer; `**ctx.bare.holesail**` et al. come from `**/lib/bare/bundles/***`). On `**file:**` checkouts and Node test harnesses, `**bundle: true`** may still be host-imported as a fallback when a drive bundle is absent. Optional packages that fail to load (for example native-only modules on the wrong host) are skipped without aborting boot.
|
||||
**Host resolution:** after drive merge, the booter uses dynamic **`import()**` for manifest entries that are **still missing**. When the booter loads from a **`pear:`** URL (`**pear run**`), rows with `**bundle: true**` are **not** host-`**import()**`ed (bare-module cannot resolve npm package names from that referrer; **`ctx.bare.holesail`** et al. come from **`/lib/bare/bundles/*`**). On **`file:`** checkouts and Node test harnesses, `**bundle: true`** may still be host-imported as a fallback when a drive bundle is absent. Optional packages that fail to load (for example native-only modules on the wrong host) are skipped without aborting boot.
|
||||
|
||||
**Hardening:** set **`BARE_OS_BARE_MODULES=0**` to omit `**ctx.bare**` entirely (the property is absent on `**ctx**`). Runtime caps `**bareCtxModules**` and `**bareDriveBundles`** mirror these toggles.
|
||||
**Hardening:** set **`BARE_OS_BARE_MODULES=0`** to omit **`ctx.bare`** entirely (the property is absent on **`ctx`**). Runtime caps **`bareCtxModules`** and **`bareDriveBundles`** mirror these toggles.
|
||||
|
||||
Full ecosystem context: [Chapter 12 — Bare modules and Pear ecosystem](12-bare-modules-and-pear-ecosystem.md).
|
||||
|
||||
@@ -87,7 +87,7 @@ Full ecosystem context: [Chapter 12 — Bare modules and Pear ecosystem](12-bare
|
||||
|
||||
## Pear and Bare globals
|
||||
|
||||
Under Pear/Bare, some globals (e.g. **`Bare**`) may exist for **host** exit and lifecycle. In-image utilities should still prefer `**ctx**` for I/O to stay consistent when the same script pattern is tested under different harnesses. Prefer `**ctx.bare.***` over relying on `**Bare**`-specific package side effects when you need `**bare-url**` / `**bare-path`** on the Pear runtime.
|
||||
Under Pear/Bare, some globals (e.g. **`Bare`**) may exist for **host** exit and lifecycle. In-image utilities should still prefer **`ctx`** for I/O to stay consistent when the same script pattern is tested under different harnesses. Prefer **`ctx.bare.*`** over relying on **`Bare`**-specific package side effects when you need **`bare-url`** / **`bare-path`** on the Pear runtime.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@ Each command source under **`packages/bare-os-coreutils/src/<name>.js`** must:
|
||||
- Define **`async function run(ctx, argv)`**.
|
||||
- Contain **no top-level `import` or `export`**—the file is concatenated into a single script string for `AsyncFunction` loading.
|
||||
|
||||
Shared helpers live in **`packages/bare-os-coreutils/lib/**` and are **prepended** at build time, not imported. `**bare-os-lscolors**` lives in `**packages/bare-os-lscolors/**` as a small workspace package so `**bare-os-booter`** can `import` it under Pear (cross-package paths into **`bare-os-coreutils**` resolve to unsupported `**pear://dev/...`** URLs).
|
||||
Shared helpers live in **`packages/bare-os-coreutils/lib/`** and are **prepended** at build time, not imported. **`bare-os-lscolors`** lives in **`packages/bare-os-lscolors/`** as a small workspace package so **`bare-os-booter`** can `import` it under Pear (cross-package paths into **`bare-os-coreutils`** resolve to unsupported **`pear://dev/...`** URLs).
|
||||
|
||||
---
|
||||
|
||||
@@ -21,7 +21,7 @@ Shared helpers live in **`packages/bare-os-coreutils/lib/**` and are **prepended
|
||||
2. **Register** the name in **`packages/bare-os-coreutils/lib/commands.mjs`** (`COREUTILS_COMMANDS`—keep sorted).
|
||||
3. **Add a man page** `packages/bare-os-coreutils/man/pages/foo.json` (build fails if missing).
|
||||
4. **Optional:** seed examples via **`scripts/seed-man-pages.mjs`** or edit JSON directly.
|
||||
5. **Optional preamble:** if `foo` needs a large engine file (or several helpers, like **`edit**` / `**nano**` with `**lib/edit-*.js**`), add to `**preamble`** in [`build.mjs`](../packages/bare-os-coreutils/build.mjs):
|
||||
5. **Optional preamble:** if `foo` needs a large engine file (or several helpers, like **`edit`** / **`nano`** with **`lib/edit-*.js`**), add to **`preamble`** in [`build.mjs`](../packages/bare-os-coreutils/build.mjs):
|
||||
|
||||
```js
|
||||
const preamble = {
|
||||
@@ -40,7 +40,7 @@ const preamble = {
|
||||
npm run build -w bare-os-coreutils
|
||||
```
|
||||
|
||||
This runs **`build-man-db.mjs**` (manual database) and writes `**kernel/bin/foo`** plus the seeder mirror.
|
||||
This runs **`build-man-db.mjs`** (manual database) and writes **`kernel/bin/foo`** plus the seeder mirror.
|
||||
|
||||
7. **Re-seed / replicate** so peers get the new `/bin/foo`.
|
||||
|
||||
@@ -54,21 +54,21 @@ From [`build.mjs`](../packages/bare-os-coreutils/build.mjs):
|
||||
runtime.js + [preamble files...] + src/foo.js → kernel/bin/foo
|
||||
```
|
||||
|
||||
**`runtime.js**` begins with a `**BARE_OS_BIN_API**` version comment (e.g. `**/* BARE_OS_BIN_API 1.0.0 */**`). Staged `**kernel/bin/*`** must contain that string so **[`scripts/verify-kernel-seeder-parity.mjs`](../../scripts/verify-kernel-seeder-parity.mjs)** can catch drift; hand-written stubs (**`systemctl**`, `**journalctl`**) carry the same pragma.
|
||||
**`runtime.js`** begins with a **`BARE_OS_BIN_API`** version comment (e.g. `**/* BARE_OS_BIN_API 1.0.0 */**`). Staged **`kernel/bin/*`** must contain that string so **[`scripts/verify-kernel-seeder-parity.mjs`](../../scripts/verify-kernel-seeder-parity.mjs)** can catch drift; hand-written stubs (**`systemctl`**, **`journalctl`**) carry the same pragma.
|
||||
|
||||
**`runtime.js**` defines helpers like `**bareStdin`**, listing time formatting, etc.—read it before reimplementing utilities.
|
||||
**`runtime.js`** defines helpers like **`bareStdin`**, listing time formatting, etc.—read it before reimplementing utilities.
|
||||
|
||||
---
|
||||
|
||||
## Exit status
|
||||
|
||||
POSIX-ish utilities set **`ctx.exitCode**` (number) when they want a non-zero status. The **shell** uses `**ctx.exitCode**` for `**&&**`, `**||**`, and `**;**` lists; utilities such as `**grep**` and `**test`** set it for conditions.
|
||||
POSIX-ish utilities set **`ctx.exitCode`** (number) when they want a non-zero status. The **shell** uses **`ctx.exitCode`** for `**&&**`, **`||`**, and `**;**` lists; utilities such as **`grep`** and **`test`** set it for conditions.
|
||||
|
||||
---
|
||||
|
||||
## Tests
|
||||
|
||||
Add or extend tests under **`packages/bare-os-booter/test.js**` using `**runBinCommand`** with a Hyperdrive that has the built `/bin/foo` bytes—follow existing **`grep**`, `**ls**`, `**cat`** patterns.
|
||||
Add or extend tests under **`packages/bare-os-booter/test.js`** using **`runBinCommand`** with a Hyperdrive that has the built `/bin/foo` bytes—follow existing **`grep`**, **`ls`**, **`cat`** patterns.
|
||||
|
||||
---
|
||||
|
||||
@@ -76,16 +76,16 @@ Add or extend tests under **`packages/bare-os-booter/test.js**` using `**runBinC
|
||||
|
||||
- Update **man page** JSON (required by build).
|
||||
- Optional: handbook chapter 9 cross-links for POSIX alignment.
|
||||
- Optional: TypeScript shapes in [`packages/bare-os-booter/lib/bare-os-ctx.d.ts`](../packages/bare-os-booter/lib/bare-os-ctx.d.ts) (**`BareOsKernelContext**`, `**BareOsBinRun`**) for host-side editors.
|
||||
- Optional: TypeScript shapes in [`packages/bare-os-booter/lib/bare-os-ctx.d.ts`](../packages/bare-os-booter/lib/bare-os-ctx.d.ts) (**`BareOsKernelContext`**, **`BareOsBinRun`**) for host-side editors.
|
||||
|
||||
Large multi-file preambles (**`edit**` / `**nano**`, `**baretop**`, `**agent**`, `**chat`**, …) are defined in [`build.mjs`](../packages/bare-os-coreutils/build.mjs) **`preamble**` — copy that pattern when a command needs many `**lib/*.js**` chunks; for `**agent`**-sized features prefer editing [`packages/bare-os-coreutils/lib/agent-*.js`](../packages/bare-os-coreutils/lib/) and **`man agent`** rather than growing unrelated commands’ preambles.
|
||||
Large multi-file preambles (**`edit`** / **`nano`**, **`baretop`**, **`agent`**, **`chat`**, …) are defined in [`build.mjs`](../packages/bare-os-coreutils/build.mjs) **`preamble`** — copy that pattern when a command needs many **`lib/*.js`** chunks; for **`agent`**-sized features prefer editing [`packages/bare-os-coreutils/lib/agent-*.js`](../packages/bare-os-coreutils/lib/) and **`man agent`** rather than growing unrelated commands’ preambles.
|
||||
|
||||
## See also
|
||||
|
||||
- [Chapter 5 — Modules](05-modules-and-imports.md)
|
||||
- [Chapter 8 — Testing](08-testing-and-debugging.md)
|
||||
- [kernel/README.md](../kernel/README.md)
|
||||
- **`agent**` / `**chat`** — large preamble examples: [`build.mjs`](../packages/bare-os-coreutils/build.mjs), [`packages/bare-os-coreutils/README.md`](../packages/bare-os-coreutils/README.md)
|
||||
- **`agent`** / **`chat`** — large preamble examples: [`build.mjs`](../packages/bare-os-coreutils/build.mjs), [`packages/bare-os-coreutils/README.md`](../packages/bare-os-coreutils/README.md)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -32,21 +32,21 @@ Read [`bare-initd.js`](../packages/bare-os-booter/lib/bare-initd.js) before addi
|
||||
|
||||
## Cron and timers
|
||||
|
||||
**`bare-cron**` reads `**/etc/bare-os/crontab**` on the system image (if present), then the user’s `**~/.crontab**` on the personal drive; invalid lines are logged and skipped. `**crontab**` installs/lists/removes the **user** file (requires login). Timer drop-ins under `**~/.config/bare-os/timers/*.timer**` (`**[Timer]**` `**OnCalendar=**` + `**ExecLine=`**) merge into the same minute scheduler. See [Handbook ch.4](../handbook/04-the-booter-runtime.md) and [Developer guide ch.11](11-kernel-pear-cookbook.md).
|
||||
**`bare-cron`** reads **`/etc/bare-os/crontab`** on the system image (if present), then the user’s **`~/.crontab`** on the personal drive; invalid lines are logged and skipped. **`crontab`** installs/lists/removes the **user** file (requires login). Timer drop-ins under **`~/.config/bare-os/timers/*.timer`** (`**[Timer]**` **`OnCalendar=`** + **`ExecLine=`**) merge into the same minute scheduler. See [Handbook ch.4](../handbook/04-the-booter-runtime.md) and [Developer guide ch.11](11-kernel-pear-cookbook.md).
|
||||
|
||||
**Socket-shaped activation:** initd unit drop-ins can set **`SocketActivationIpc=<fifo-name>**` so a service’s `**start()**` runs when something first `**readFile**`s that logical FIFO under `**/run/bare-os/ipc/**` (see `**bare-initd.js`**).
|
||||
**Socket-shaped activation:** initd unit drop-ins can set **`SocketActivationIpc=<fifo-name>`** so a service’s `**start()**` runs when something first **`readFile`**s that logical FIFO under **`/run/bare-os/ipc/`** (see **`bare-initd.js`**).
|
||||
|
||||
---
|
||||
|
||||
## HDMS and `/mnt`
|
||||
|
||||
After identity unlock, optional **HDMS** mounts may appear under **`/mnt**`. Utilities use `**ctx.vfs**`; HDMS integration is advanced and covered narratively in the handbook (identity + HDMS chapter). User scripts should prefer `**vfs.readFile**` / `**writeFile`** over hard-coding drive objects.
|
||||
After identity unlock, optional **HDMS** mounts may appear under **`/mnt`**. Utilities use **`ctx.vfs`**; HDMS integration is advanced and covered narratively in the handbook (identity + HDMS chapter). User scripts should prefer **`vfs.readFile`** / **`writeFile`** over hard-coding drive objects.
|
||||
|
||||
---
|
||||
|
||||
## Replacing the kernel
|
||||
|
||||
A heavier “app” might ship a **different `/boot/init.js**`—for example a menu-driven UI using `**readLine**` or a non-interactive worker when `**BARE_OS_SKIP_REPL=1`**. You still have the **single JavaScript realm** per session; there is no fork into a second Bare process from inside the image.
|
||||
A heavier “app” might ship a **different `/boot/init.js**`—for example a menu-driven UI using **`readLine`** or a non-interactive worker when **`BARE_OS_SKIP_REPL=1`**. You still have the **single JavaScript realm** per session; there is no fork into a second Bare process from inside the image.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -13,15 +13,15 @@ npm ci
|
||||
npm test
|
||||
```
|
||||
|
||||
**`pretest**` mirrors root `**package.json**` `**scripts.pretest**`: `**npm run build -w bare-os-coreutils**`, `**npm run build -w bare-os-bare-libs**`, `**verify-kernel-seeder-parity**`, `**verify-ctx-api-feature-bits**`, `**verify-kernel-capabilities-contract**`, `**verify-kernel-capabilities-word-6**` … `**-word-11**`, `**verify-ctx-dts**`, `**validate-example-schemas**`, `**verify-doc-links**`, `**verify-man-coverage**`, `**verify-compat-matrix**`, `**gen-posix-dashboard**`, `**verify-posix-dashboard**`, `**verify-posix-compliance-matrix**`, `**verify-posix-profile-triplet**`, `**verify-pear-no-static-node-import**`, `**smoke:bare-manifest**` — so `**kernel/bin/***`, `**kernel/lib/bare**`, `**kernel/share/man/man.json**`, `**packages/bare-os-seeder/kernel/**`, ctx semver / feature words through `**bits11**`, capability contracts, `**bare-os-ctx.d.ts`** parity, schema examples, Tier-1 **man** coverage, doc links, the compatibility matrix, and the **POSIX dashboard / compliance matrix / profile triplet** stay aligned before workspace tests. See the **POSIX verifier “pretest matrix”** diagram in [`scripts/README.md`](../scripts/README.md).
|
||||
**`pretest`** mirrors root **`package.json`** **`scripts.pretest`**: `**npm run build -w bare-os-coreutils**`, `**npm run build -w bare-os-bare-libs**`, **`verify-kernel-seeder-parity`**, **`verify-ctx-api-feature-bits`**, **`verify-kernel-capabilities-contract`**, **`verify-kernel-capabilities-word-6`** … **`-word-11`**, **`verify-ctx-dts`**, **`validate-example-schemas`**, **`verify-doc-links`**, **`verify-man-coverage`**, **`verify-compat-matrix`**, **`gen-posix-dashboard`**, **`verify-posix-dashboard`**, **`verify-posix-compliance-matrix`**, **`verify-posix-profile-triplet`**, **`verify-pear-no-static-node-import`**, **`smoke:bare-manifest`** — so **`kernel/bin/*`**, **`kernel/lib/bare`**, **`kernel/share/man/man.json`**, **`packages/bare-os-seeder/kernel/`**, ctx semver / feature words through **`bits11`**, capability contracts, **`bare-os-ctx.d.ts`** parity, schema examples, Tier-1 **man** coverage, doc links, the compatibility matrix, and the **POSIX dashboard / compliance matrix / profile triplet** stay aligned before workspace tests. See the **POSIX verifier “pretest matrix”** diagram in [`scripts/README.md`](../scripts/README.md).
|
||||
|
||||
**Kernel self-test:** with **`BARE_OS_KERNEL_SELFTEST=1**`, the stock kernel runs built-in checks (including `**/proc/bare_os_resources**`, `**/proc/bare_os_features**`, and `**/proc/bare_os/index.json**`). Use `**BARE_OS_SELFTEST_FORMAT=tap`** for CI-friendly stderr.
|
||||
**Kernel self-test:** with **`BARE_OS_KERNEL_SELFTEST=1`**, the stock kernel runs built-in checks (including **`/proc/bare_os_resources`**, **`/proc/bare_os_features`**, and **`/proc/bare_os/index.json`**). Use **`BARE_OS_SELFTEST_FORMAT=tap`** for CI-friendly stderr.
|
||||
|
||||
**Kernel hot reload (dev):** with **`BARE_OS_KERNEL_HOT_RELOAD=1**`, a custom kernel may call `**ctx.bareOsRequestKernelReload()**` to throw a controlled reload: the booter re-fetches `**/boot/init.js**` and runs `**start(ctx)`** again without tearing down the swarm session.
|
||||
**Kernel hot reload (dev):** with **`BARE_OS_KERNEL_HOT_RELOAD=1`**, a custom kernel may call `**ctx.bareOsRequestKernelReload()**` to throw a controlled reload: the booter re-fetches **`/boot/init.js`** and runs `**start(ctx)`** again without tearing down the swarm session.
|
||||
|
||||
**Kernel profile warm reload:** with **`BARE_OS_KERNEL_PROFILE_WARM=1**`, `**ctx.bareOsRequestKernelProfileReload()`** uses the same re-invocation loop (distinct error code for policy clarity).
|
||||
**Kernel profile warm reload:** with **`BARE_OS_KERNEL_PROFILE_WARM=1`**, `**ctx.bareOsRequestKernelProfileReload()`** uses the same re-invocation loop (distinct error code for policy clarity).
|
||||
|
||||
**Seed RPC contract:** **`packages/bare-os-protocol**` lists RPC short names in `**lib/seed-rpc-methods.js**`; `**channel.js**` rejects unknown methods with `**bare_os.rpc_unknown_method**` and wrong modules with `**bare_os.rpc_wrong_module**`. `**packages/bare-os-protocol/test.js`** asserts the registry stays non-empty.
|
||||
**Seed RPC contract:** **`packages/bare-os-protocol`** lists RPC short names in **`lib/seed-rpc-methods.js`**; **`channel.js`** rejects unknown methods with **`bare_os.rpc_unknown_method`** and wrong modules with **`bare_os.rpc_wrong_module`**. **`packages/bare-os-protocol/test.js`** asserts the registry stays non-empty.
|
||||
|
||||
### CI marker scope (first-party vs vendored bundles)
|
||||
|
||||
@@ -29,11 +29,11 @@ Two complementary gates apply; neither is a blanket ban on the word “implement
|
||||
|
||||
| Script | Scope | Intent |
|
||||
| --- | --- | --- |
|
||||
| **`scripts/verify-runtime-no-incomplete-markers.mjs**` | Hand-authored `**kernel/init.js**` (generated bundle), `**kernel/lib/init/**`, `**kernel/lib/boot/**`, `**kernel/bin/*.js**`, `**packages/bare-os-booter/**` (excluding `**test.js**` and paths in `**docs/audit/runtime-marker-excludes.json**`) | No `**TODO` / `FIXME` / `HACK` / `XXX**` or `**throw new Error("Not implemented")`** in runtime booter/kernel sources. |
|
||||
| **`scripts/verify-bundle-markers.mjs**` | `**kernel/lib/bare/bundles/*.js**` only | Vendored Holepunch IIFEs: block incomplete-looking substrings unless the basename is allowlisted in `**docs/audit/bundle-marker-allowlist.json**` (policy: keep allowlist **empty**; fix via upstream bumps or `**scripts/sanitize-bare-bundles.mjs`**). |
|
||||
| **`scripts/verify-bundle-throws.mjs**` | Same bundles | Same idea for `**throw new Error("…not implemented…")**`-style messages; allowlist `**docs/audit/bundle-throw-allowlist.json`** stays empty by policy. |
|
||||
| **`scripts/verify-runtime-no-incomplete-markers.mjs`** | Hand-authored **`kernel/init.js`** (generated bundle), **`kernel/lib/init/`**, **`kernel/lib/boot/`**, **`kernel/bin/*.js`**, **`packages/bare-os-booter/`** (excluding **`test.js`** and paths in **`docs/audit/runtime-marker-excludes.json`**) | No `**TODO` / `FIXME` / `HACK` / `XXX**` or `**throw new Error("Not implemented")`** in runtime booter/kernel sources. |
|
||||
| **`scripts/verify-bundle-markers.mjs`** | **`kernel/lib/bare/bundles/*.js`** only | Vendored Holepunch IIFEs: block incomplete-looking substrings unless the basename is allowlisted in **`docs/audit/bundle-marker-allowlist.json`** (policy: keep allowlist **empty**; fix via upstream bumps or **`scripts/sanitize-bare-bundles.mjs`**). |
|
||||
| **`scripts/verify-bundle-throws.mjs`** | Same bundles | Same idea for `**throw new Error("…not implemented…")**`-style messages; allowlist **`docs/audit/bundle-throw-allowlist.json`** stays empty by policy. |
|
||||
|
||||
**`packages/bare-os-coreutils**` and `**packages/bare-os-protocol**` are not scanned by `**verify-runtime-no-incomplete-markers**` today—still avoid shipping incomplete markers in shipped `**src/**` paths. `**packages/bare-os-booter/test.js**` may use **in-memory VFS fakes**, **stub HTTP hosts** (e.g. `**stub.example**` URLs), and `**AsyncFunction**`-loaded mini programs to isolate `**runBinCommand**`—those are **test doubles**, not the replicated OS. Production syscall bridges use explicit `**ENOTSUP**` / `**ENOSYS**` returns instead of placeholder throws. `**scripts/kernel-program-benchmark-harness.mjs**` suite IDs such as `**kernel_crypto_synthetic_benchmark`** name **synthetic timing fixtures** for release gates, not missing product code.
|
||||
**`packages/bare-os-coreutils`** and **`packages/bare-os-protocol`** are not scanned by **`verify-runtime-no-incomplete-markers`** today—still avoid shipping incomplete markers in shipped **`src/`** paths. **`packages/bare-os-booter/test.js`** may use **in-memory VFS fakes**, **stub HTTP hosts** (e.g. **`stub.example`** URLs), and **`AsyncFunction`**-loaded mini programs to isolate **`runBinCommand`**—those are **test doubles**, not the replicated OS. Production syscall bridges use explicit **`ENOTSUP`** / **`ENOSYS`** returns instead of placeholder throws. **`scripts/kernel-program-benchmark-harness.mjs`** suite IDs such as **`kernel_crypto_synthetic_benchmark`** name **synthetic timing fixtures** for release gates, not missing product code.
|
||||
|
||||
See also **[`docs/audit/PLACEHOLDER_BASELINE.md`](../docs/audit/PLACEHOLDER_BASELINE.md)** and **[`packages/bare-os-bare-libs/README.md`](../packages/bare-os-bare-libs/README.md)** § Bundle health, markers, and upstream closure.
|
||||
|
||||
@@ -41,13 +41,13 @@ See also **[`docs/audit/PLACEHOLDER_BASELINE.md`](../docs/audit/PLACEHOLDER_BASE
|
||||
|
||||
## Brittle: `brittle-node` vs `brittle-bare`
|
||||
|
||||
- **`brittle-node**` runs most of `**packages/bare-os-booter/test.js**`—Hyperdrive, VFS, shell tokenizer, `**runBinCommand`** against real `/bin` bytes on disk (includes second-word (**`bits2**`) contract checks: `**@reboot**` / jitter parsing, param expansion v2, `**/proc`** stubs).
|
||||
- **`brittle-bare**` runs `**test.identity.js`** and protocol tests that need the **Bare** runtime (e.g. **bare-crypto** native pieces).
|
||||
- **`npm run test:bare**` (repo root) runs protocol tests plus the booter’s `**test:bare**` script (`**test.identity.js**`, `**test.bare-smoke.js**`) and seeder tests — a lighter Bare-native smoke path than the full `**brittle-node**` `**test.js`** harness.
|
||||
- **`brittle-node`** runs most of **`packages/bare-os-booter/test.js`**—Hyperdrive, VFS, shell tokenizer, **`runBinCommand`** against real `/bin` bytes on disk (includes second-word (**`bits2`**) contract checks: `**@reboot**` / jitter parsing, param expansion v2, **`/proc`** stubs).
|
||||
- **`brittle-bare`** runs **`test.identity.js`** and protocol tests that need the **Bare** runtime (e.g. **bare-crypto** native pieces).
|
||||
- **`npm run test:bare**` (repo root) runs protocol tests plus the booter’s **`test:bare`** script (**`test.identity.js`**, **`test.bare-smoke.js`**) and seeder tests — a lighter Bare-native smoke path than the full **`brittle-node`** **`test.js`** harness.
|
||||
|
||||
**Cold boot / `ctx.bare`:** parallel **`readFile**` for drive `**/lib/bare**` bundles is capped by `**BARE_OS_BARE_STDLIB_RESOLVE_CONCURRENCY**` (`**1`–`32**`, default `**4**`) in `**bare-os-ctx-bare.js`**; merge order stays deterministic.
|
||||
**Cold boot / `ctx.bare`:** parallel **`readFile`** for drive **`/lib/bare`** bundles is capped by **`BARE_OS_BARE_STDLIB_RESOLVE_CONCURRENCY`** (`**1`–`32**`, default **`4`**) in **`bare-os-ctx-bare.js`**; merge order stays deterministic.
|
||||
|
||||
**Diagnostics:** with **`BARE_OS_DIAGNOSTICS_SUBSCRIBE=1**`, `**ctx.bareOsDiagnosticsSubscribe`** receives structured booter events (phase timing, optional kernel echoes) for local debugging—do not enable in untrusted production shells.
|
||||
**Diagnostics:** with **`BARE_OS_DIAGNOSTICS_SUBSCRIBE=1`**, **`ctx.bareOsDiagnosticsSubscribe`** receives structured booter events (phase timing, optional kernel echoes) for local debugging—do not enable in untrusted production shells.
|
||||
|
||||
CI installs **Bare** globally for parity (see `.github/workflows/ci.yml`). If identity tests fail locally, ensure **`bare`** is installed and on `PATH`.
|
||||
|
||||
@@ -65,9 +65,9 @@ CI installs **Bare** globally for parity (see `.github/workflows/ci.yml`). If id
|
||||
|
||||
Use the root scripts (see [README](../README.md)):
|
||||
|
||||
- **`npm run os:seeder**` and `**npm run os:booter**` (separate terminals) after `**ensure-pear-node-modules`**.
|
||||
- **`npm run os:seeder**` and `**npm run os:booter**` (separate terminals) after **`ensure-pear-node-modules`**.
|
||||
|
||||
Pear uses bundled **`node_modules**`; if resolution fails, run `**node scripts/ensure-pear-node-modules.mjs**` as documented in `**scripts/README.md`**.
|
||||
Pear uses bundled **`node_modules`**; if resolution fails, run `**node scripts/ensure-pear-node-modules.mjs**` as documented in **`scripts/README.md`**.
|
||||
|
||||
---
|
||||
|
||||
@@ -75,7 +75,7 @@ Pear uses bundled **`node_modules**`; if resolution fails, run `**node scripts/e
|
||||
|
||||
- **`BARE_OS_KERNEL_SELFTEST=1`** — stock [`kernel/init.js`](../kernel/init.js) runs a short **`execLine`** checklist after boot snippets.
|
||||
- **`BARE_OS_SELFTEST_FORMAT=tap`** — same self-test emits **TAP** lines on stderr (for parsers in CI).
|
||||
- **`node scripts/verify-kernel-seeder-parity.mjs**` — after a coreutils build, asserts `**kernel/**` and `**packages/bare-os-seeder/kernel/**` match and every `**kernel/bin/***` file includes `**BARE_OS_BIN_API**` (root `**pretest`** runs this).
|
||||
- **`node scripts/verify-kernel-seeder-parity.mjs**` — after a coreutils build, asserts **`kernel/`** and **`packages/bare-os-seeder/kernel/`** match and every **`kernel/bin/*`** file includes **`BARE_OS_BIN_API`** (root **`pretest`** runs this).
|
||||
|
||||
---
|
||||
|
||||
@@ -85,13 +85,13 @@ Pear uses bundled **`node_modules**`; if resolution fails, run `**node scripts/e
|
||||
- `invalid manual database` — Forgot to build coreutils after changing commands list
|
||||
- `kernel/bin missing BARE_OS_BIN_API pragma` — Rebuild coreutils or add pragma to hand-maintained **`kernel/bin/*`** stubs
|
||||
- Identity test skips / fails on Node only — Expected—run under **`brittle-bare`**
|
||||
- Session exits immediately — **`BARE_OS_SKIP_REPL=1**` or `**readLine`** returns null
|
||||
- Session exits immediately — **`BARE_OS_SKIP_REPL=1`** or **`readLine`** returns null
|
||||
|
||||
---
|
||||
|
||||
## Media (`ffmpeg` / `ffprobe`) and sandboxing
|
||||
|
||||
**`mediaproc:***` `**BARE_OS_BIN_WORKER_OFFLOAD**` routes `**ffmpeg**` and `**ffprobe**` through `**bare-thread**` when enabled. Keep input paths inside the **two-drive VFS** (no host path escapes), cap wall time with `**BARE_OS_BIN_WORKER_WALL_MS`**, and treat media tools as **delegated compute**: never pass untrusted filter graphs from guest scripts without a capability review. See [kernel-extensions.md](../docs/reference/kernel-extensions.md) for worker class bits.
|
||||
**`mediaproc:*`** **`BARE_OS_BIN_WORKER_OFFLOAD`** routes **`ffmpeg`** and **`ffprobe`** through **`bare-thread`** when enabled. Keep input paths inside the **two-drive VFS** (no host path escapes), cap wall time with **`BARE_OS_BIN_WORKER_WALL_MS`**, and treat media tools as **delegated compute**: never pass untrusted filter graphs from guest scripts without a capability review. See [kernel-extensions.md](../docs/reference/kernel-extensions.md) for worker class bits.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -8,43 +8,43 @@ Bare OS is **research software**. It is not a hardened multi-tenant OS. Still, d
|
||||
|
||||
The **system** Hyperdrive is the **OS image**. You normally obtain it by **replicating** from peers that share the project’s discovery topology (see handbook protocol chapters). The codebase assumes you **trust** that image the same way you would trust an installer ISO from a vendor you chose.
|
||||
|
||||
**`/bin**` and `**/boot`** bytes are executed as JavaScript. A malicious seeder could ship hostile `/bin` scripts. Mitigation is **social and operational**: use keys and peers you trust, verify releases, run your own seeder for development.
|
||||
**`/bin`** and **`/boot`** bytes are executed as JavaScript. A malicious seeder could ship hostile `/bin` scripts. Mitigation is **social and operational**: use keys and peers you trust, verify releases, run your own seeder for development.
|
||||
|
||||
**Boot snippet tightening:** with **`BARE_OS_BOOT_ALLOWLIST=1**`, the stock kernel only runs lines from trusted `**rc**`, `**rc.d**`, `**rc.local**`, `**kernel.d**`, and `**onboot**` whose first shell token appears in `**/etc/bare-os/boot.allow**` (plus builtins such as `**export**`, `**cd**`, `**:**`). Pair with `**BARE_OS_BOOT_STRICT=1`** to exit the session on the first disallowed or failing line.
|
||||
**Boot snippet tightening:** with **`BARE_OS_BOOT_ALLOWLIST=1`**, the stock kernel only runs lines from trusted **`rc`**, **`rc.d`**, **`rc.local`**, **`kernel.d`**, and **`onboot`** whose first shell token appears in **`/etc/bare-os/boot.allow`** (plus builtins such as **`export`**, **`cd`**, **`:`**). Pair with **`BARE_OS_BOOT_STRICT=1`** to exit the session on the first disallowed or failing line.
|
||||
|
||||
**Boot manifest integrity:** **`BARE_OS_BOOT_MANIFEST=1**` makes the stock kernel compare `**/etc/bare-os/boot.manifest.json**` to an expected digest (`**ctx.bareOsBootFileSha256Hex**`). `**BARE_OS_BOOT_MANIFEST_SIGN=1**` adds **Ed25519** verification of the **raw manifest bytes** against `**/etc/bare-os/boot.manifest.sig**`, using `**ctx.bareOsVerifyBootManifestSignature**` and `**BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`** (64 hex chars). Rotation is operational: ship a new public key in host env and a matching signature file on the system image. This does **not** replace image trust—you still choose peers and seed sources carefully.
|
||||
**Boot manifest integrity:** **`BARE_OS_BOOT_MANIFEST=1`** makes the stock kernel compare **`/etc/bare-os/boot.manifest.json`** to an expected digest (**`ctx.bareOsBootFileSha256Hex`**). **`BARE_OS_BOOT_MANIFEST_SIGN=1`** adds **Ed25519** verification of the **raw manifest bytes** against **`/etc/bare-os/boot.manifest.sig`**, using **`ctx.bareOsVerifyBootManifestSignature`** and **`BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`** (64 hex chars). Rotation is operational: ship a new public key in host env and a matching signature file on the system image. This does **not** replace image trust—you still choose peers and seed sources carefully.
|
||||
|
||||
**Seed capability attestation (optional):** the seeder may answer **`bare_os.capability_attestation**` with JSON from host env `**BARE_OS_SEED_CAPABILITY_ATTESTATION_JSON**` (for example a distro or **hyper-multisig** bundle). The guest does **not** verify signatures; operators verify on the host or out-of-band. `**BARE_OS_BIN_WORKER_OFFLOAD**` is a reserved gate for future isolated `**/bin`** execution—stock paths remain in-process unless a host integration supplies a worker bridge.
|
||||
**Seed capability attestation (optional):** the seeder may answer **`bare_os.capability_attestation`** with JSON from host env **`BARE_OS_SEED_CAPABILITY_ATTESTATION_JSON`** (for example a distro or **hyper-multisig** bundle). The guest does **not** verify signatures; operators verify on the host or out-of-band. **`BARE_OS_BIN_WORKER_OFFLOAD`** is a reserved gate for future isolated **`/bin`** execution—stock paths remain in-process unless a host integration supplies a worker bridge.
|
||||
|
||||
**Audit:** **`BARE_OS_AUDIT=1**` logs `**execLine**` activity to `**/var/log/bare-os/audit.log**`. `**BARE_OS_AUDIT_JSON=1**` uses JSON lines with `**auditSchemaVersion: 2**` on `**execLine**`, **delegate**, and `**httpFetch**` records; `**BARE_OS_AUDIT_REDACT=1**` (or `**true**`) masks common secret-like `**VAR=value**` patterns; `**BARE_OS_AUDIT_REDACT=TOKEN,PASSWORD`** masks named keys.
|
||||
**Audit:** **`BARE_OS_AUDIT=1`** logs **`execLine`** activity to **`/var/log/bare-os/audit.log`**. **`BARE_OS_AUDIT_JSON=1`** uses JSON lines with `**auditSchemaVersion: 2**` on **`execLine`**, **delegate**, and **`httpFetch`** records; **`BARE_OS_AUDIT_REDACT=1`** (or **`true`**) masks common secret-like **`VAR=value`** patterns; `**BARE_OS_AUDIT_REDACT=TOKEN,PASSWORD`** masks named keys.
|
||||
|
||||
**Delegated HTTP:** when the booter sets **`ctx.httpFetch**` from the host `**fetch**`, `**BARE_OS_HTTP_ALLOWLIST**` and `**BARE_OS_HTTP_DENYLIST**` restrict `**http`/`https**` URLs for `**curl`/`wget`** (host-pattern globs). Failed checks throw before the request; with audit on, allow/deny outcomes can be logged.
|
||||
**Delegated HTTP:** when the booter sets **`ctx.httpFetch`** from the host **`fetch`**, **`BARE_OS_HTTP_ALLOWLIST`** and **`BARE_OS_HTTP_DENYLIST`** restrict `**http`/`https**` URLs for `**curl`/`wget`** (host-pattern globs). Failed checks throw before the request; with audit on, allow/deny outcomes can be logged.
|
||||
|
||||
**Host CLI delegates:** **`git**`, `**curl**`, `**wget**`, and `**systemctl**`-family commands can be restricted with `**BARE_OS_DELEGATE_ALLOW**` (comma list; empty = all). Optional per-minute caps use `**BARE_OS_DELEGATE_MAX_PER_MIN**` and per-kind `**BARE_OS_DELEGATE_*_MAX_PER_MIN**`. With `**BARE_OS_AUDIT=1**`, `**BARE_OS_DELEGATE_AUDIT_ONLY=1`** logs delegate invocations and skips the host run (**exit 0**) for audit-only environments.
|
||||
**Host CLI delegates:** **`git`**, **`curl`**, **`wget`**, and **`systemctl`**-family commands can be restricted with **`BARE_OS_DELEGATE_ALLOW`** (comma list; empty = all). Optional per-minute caps use **`BARE_OS_DELEGATE_MAX_PER_MIN`** and per-kind **`BARE_OS_DELEGATE_*_MAX_PER_MIN`**. With **`BARE_OS_AUDIT=1`**, **`BARE_OS_DELEGATE_AUDIT_ONLY=1`** logs delegate invocations and skips the host run (**exit 0**) for audit-only environments.
|
||||
|
||||
**DNS allowlist:** **`BARE_OS_DNS_ALLOWLIST**` optionally constrains http(s) hostnames for `**curl`/`wget**` before fetch (suffix wildcard `***.example.com`** supported).
|
||||
**DNS allowlist:** **`BARE_OS_DNS_ALLOWLIST`** optionally constrains http(s) hostnames for `**curl`/`wget**` before fetch (suffix wildcard **`*.example.com`** supported).
|
||||
|
||||
**DNSSEC:** the stock guest **does not validate DNSSEC**; resolvers and TLS stacks on the **host** own DNSSEC, DANE, and related policy. Do not infer DNS security properties from Bare OS delegate behavior alone.
|
||||
|
||||
**IPC JSON-RPC:** when **`BARE_OS_IPC_RPC_TOKEN**` is set, `**pushJson**` payloads must include matching `**bareOsIpcToken**` or the push throws. Line size is capped (`**BARE_OS_IPC_JSON_MAX_BYTES`**, default 256 KiB).
|
||||
**IPC JSON-RPC:** when **`BARE_OS_IPC_RPC_TOKEN`** is set, **`pushJson`** payloads must include matching **`bareOsIpcToken`** or the push throws. Line size is capped (**`BARE_OS_IPC_JSON_MAX_BYTES`**, default 256 KiB).
|
||||
|
||||
**Sandboxed scripts:** **`ctx.bareOsSandboxRunScript(source, argv?, opts?)`** runs in-image JS with a **restricted `ctx`**: writes are limited to the personal namespace (same routing rules as `isPersonalRoute`), and identity / vault / virtual-file registration hooks are disabled. Disable entirely with **`BARE_OS_SANDBOX_SCRIPT=0**`. `**BARE_OS_SANDBOX_WORKER=1**` prefers `**bare-worker**` when the host provides it, else defers on a **fresh microtask**; neither path is a hardware isolate. For **documented** stronger separation, operators may compose Holepunch `**cross-worker**` / `**bare-bundle-evaluate**` patterns (see comments in `**packages/bare-os-booter/lib/bare-os-sandbox.js`**). This remains **not** a guaranteed security boundary—treat sandboxing as a trust reducer.
|
||||
**Sandboxed scripts:** **`ctx.bareOsSandboxRunScript(source, argv?, opts?)`** runs in-image JS with a **restricted `ctx`**: writes are limited to the personal namespace (same routing rules as `isPersonalRoute`), and identity / vault / virtual-file registration hooks are disabled. Disable entirely with **`BARE_OS_SANDBOX_SCRIPT=0`**. **`BARE_OS_SANDBOX_WORKER=1`** prefers **`bare-worker`** when the host provides it, else defers on a **fresh microtask**; neither path is a hardware isolate. For **documented** stronger separation, operators may compose Holepunch **`cross-worker`** / **`bare-bundle-evaluate`** patterns (see comments in **`packages/bare-os-booter/lib/bare-os-sandbox.js`**). This remains **not** a guaranteed security boundary—treat sandboxing as a trust reducer.
|
||||
|
||||
**WebAssembly and native FFI (policy):** a future **guest WASM** runtime must map **imports** to **capability-gated** **`ctx.vfs`** / IPC surfaces only—never raw host syscalls. **Native `bare-addon**` loading belongs on the **Pear host** with explicit allowlists; the replicated **system** image should not ship unsigned addons. Pair WASM/FFI plans with `**boot.policy.json**` `**denyKernelSyscalls**` / `**allowedCtxMethods`** and treat both as **experimental** until a dedicated ADR lands.
|
||||
**WebAssembly and native FFI (policy):** a future **guest WASM** runtime must map **imports** to **capability-gated** **`ctx.vfs`** / IPC surfaces only—never raw host syscalls. **Native `bare-addon**` loading belongs on the **Pear host** with explicit allowlists; the replicated **system** image should not ship unsigned addons. Pair WASM/FFI plans with **`boot.policy.json`** **`denyKernelSyscalls`** / **`allowedCtxMethods`** and treat both as **experimental** until a dedicated ADR lands.
|
||||
|
||||
**Provenance:** **`/proc/bare_os_provenance**` (and `**/proc/bare_os/provenance`**) combines boot manifest digest, optional signing flags, and Pear channel hints for operators (see [kernel extensions](../docs/reference/kernel-extensions.md)).
|
||||
**Provenance:** **`/proc/bare_os_provenance`** (and **`/proc/bare_os/provenance`**) combines boot manifest digest, optional signing flags, and Pear channel hints for operators (see [kernel extensions](../docs/reference/kernel-extensions.md)).
|
||||
|
||||
**Pear trust summary (operator):** **`/proc/bare_os/pear_trust.json**` reflects optional host JSON from `**BARE_OS_PEAR_TRUST_JSON`** (e.g. multisig-link style metadata). The **guest does not verify** multisig or Pear channel signatures—operators validate on the host or out-of-band.
|
||||
**Pear trust summary (operator):** **`/proc/bare_os/pear_trust.json`** reflects optional host JSON from **`BARE_OS_PEAR_TRUST_JSON`** (e.g. multisig-link style metadata). The **guest does not verify** multisig or Pear channel signatures—operators validate on the host or out-of-band.
|
||||
|
||||
**Pear IPC allowlist:** when **`boot.policy.json**` sets `**allowedPearIpcChannels**`, the stock kernel copies it to `**BARE_OS_BOOT_POLICY_PEAR_IPC_CHANNELS**` so `**ctx.bareOsPearIpcEmit`** only forwards listed channels.
|
||||
**Pear IPC allowlist:** when **`boot.policy.json`** sets **`allowedPearIpcChannels`**, the stock kernel copies it to **`BARE_OS_BOOT_POLICY_PEAR_IPC_CHANNELS`** so **`ctx.bareOsPearIpcEmit`** only forwards listed channels.
|
||||
|
||||
**Documented bare-subprocess bridge:** feature bit **`BARE_OS_FEATURE2_BARE_SUBPROCESS_BRIDGE`** names an **optional**, **default-off** host integration pattern using Holepunch **[`bare-subprocess`](https://github.com/holepunchto/bare-subprocess)** for long-running delegated commands with a message bridge back to **`ctx**`. Stock images do not enable it unless a distributor wires env + allowlists explicitly. Capability word 5 adds `**bareOsReadSubprocessBridgeSnapshot**` with optional `**cgroupRootHint**` / signal lists from `**BARE_OS_SUBPROCESS_BRIDGE_META_JSON`** — these are **host-supplied hints only**; the guest must not treat them as a Linux security boundary.
|
||||
**Documented bare-subprocess bridge:** feature bit **`BARE_OS_FEATURE2_BARE_SUBPROCESS_BRIDGE`** names an **optional**, **default-off** host integration pattern using Holepunch **[`bare-subprocess`](https://github.com/holepunchto/bare-subprocess)** for long-running delegated commands with a message bridge back to **`ctx`**. Stock images do not enable it unless a distributor wires env + allowlists explicitly. Capability word 5 adds **`bareOsReadSubprocessBridgeSnapshot`** with optional **`cgroupRootHint`** / signal lists from **`BARE_OS_SUBPROCESS_BRIDGE_META_JSON`** — these are **host-supplied hints only**; the guest must not treat them as a Linux security boundary.
|
||||
|
||||
---
|
||||
|
||||
## Personal drive and user scripts
|
||||
|
||||
Anything you can write to **`$HOME**` can be executed if you run it—and **you** are the typical author. If you **download** a script from the network into your home directory and `**execLine`** it, you have effectively **eval’d** untrusted code with access to:
|
||||
Anything you can write to **`$HOME`** can be executed if you run it—and **you** are the typical author. If you **download** a script from the network into your home directory and **`execLine`** it, you have effectively **eval’d** untrusted code with access to:
|
||||
|
||||
- **`ctx.vfs`** (read/write personal tree),
|
||||
- **identity hooks** (if exposed through crafted shell lines),
|
||||
@@ -68,11 +68,11 @@ The project’s conservative stance: **bundle** on the host or **ship** utilitie
|
||||
|
||||
## Guest vs unlocked identity
|
||||
|
||||
Default **guest** sessions have predictable **`HOME=/home/guest**` and no Ed25519 identity. **Login** unlocks `**/.bare/account**` and changes `**ctx.vfs.env**` (user, home, keys). Applications that handle secrets should **never log** passphrases or raw keys; use existing `**login**` / `**logout`** flows.
|
||||
Default **guest** sessions have predictable **`HOME=/home/guest`** and no Ed25519 identity. **Login** unlocks **`/.bare/account`** and changes **`ctx.vfs.env`** (user, home, keys). Applications that handle secrets should **never log** passphrases or raw keys; use existing **`login`** / **`logout`** flows.
|
||||
|
||||
**`pear.multisig.json**` metadata (signer list + quorum) is validated by the same shape predicate in `**bare-os-protocol**` (seeder hint) and the bundled guest helper `**bareOsPearMultisigShapeOk**` in `**kernel/lib/boot/00-pear-multisig-shape.js`**; keep those files aligned when changing rules.
|
||||
**`pear.multisig.json`** metadata (signer list + quorum) is validated by the same shape predicate in **`bare-os-protocol`** (seeder hint) and the bundled guest helper **`bareOsPearMultisigShapeOk`** in **`kernel/lib/boot/00-pear-multisig-shape.js`**; keep those files aligned when changing rules.
|
||||
|
||||
**`BARE_OS_RC_PROPOSAL_MULTISIG_STRICT**` ties `**/etc/bare-os/rc.proposals/enabled/*.json**` to that policy before `**rc.d**`: each proposal lists approved signer public keys in `**signaturesFrom**`; the guest checks membership and quorum only (host tooling should verify signatures over proposal payloads before writing `**enabled/`**).
|
||||
**`BARE_OS_RC_PROPOSAL_MULTISIG_STRICT`** ties **`/etc/bare-os/rc.proposals/enabled/*.json`** to that policy before **`rc.d`**: each proposal lists approved signer public keys in **`signaturesFrom`**; the guest checks membership and quorum only (host tooling should verify signatures over proposal payloads before writing **`enabled/`**).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -20,12 +20,12 @@ Quick reference and repeated questions. **Canonical term definitions** (single s
|
||||
- **System drive** — Replicated OS image (`/bin`, `/boot`, `/etc`, …)
|
||||
- **VFS** — Virtual file system layer routing paths to drives + HDMS mounts
|
||||
- **IPC fan-out** — `bareOsIpc.fanoutPublish` / `fanoutSubscribe` — multi-subscriber copies (bounded); disable with **`BARE_OS_IPC_FANOUT=0`**
|
||||
- **HTTP policy** — Optional **`BARE_OS_HTTP_ALLOWLIST**` / `**BARE_OS_HTTP_DENYLIST**` applied when the booter wraps `**ctx.httpFetch`**
|
||||
- **booterPhases** — Milestones recorded in **`/run/bare-os/boot.json**` (`**vfs**`, `**ctx**`, `**repl**`, `**initd**`, `**kernel_invoke**`) alongside kernel `**phases`**
|
||||
- **`~/.barerc**` — Personal shell init: `**export**`, `**alias**`, `**theme <preset>**`; parsed by `**loadBarerc**`. Builtin `**barerc reload`** reapplies without logout.
|
||||
- **`BARE_OS_THEME**` — Active color preset name; `**/bin/theme**`, `**~/.barerc**`, and `**ctx.bareOsApplyTheme()**` refresh `**BARE_OS_COLOR_***` and usually `**LS_COLORS`**.
|
||||
- **`LS_COLORS**` — GNU-style colon-separated map consumed by `**ls --color**`; optional file via `**BARE_OS_DIRCOLORS**` and `**dircolors`**.
|
||||
- **`BARE_OS_COLOR_DEPTH**` — `**truecolor**` (default), `**256**`, or `**16**` / `**ansi**` — downgrades truecolor sequences in `**BARE_OS_COLOR_*`** for the fish REPL only.
|
||||
- **HTTP policy** — Optional **`BARE_OS_HTTP_ALLOWLIST`** / **`BARE_OS_HTTP_DENYLIST`** applied when the booter wraps **`ctx.httpFetch`**
|
||||
- **booterPhases** — Milestones recorded in **`/run/bare-os/boot.json`** (**`vfs`**, **`ctx`**, **`repl`**, **`initd`**, **`kernel_invoke`**) alongside kernel **`phases`**
|
||||
- **`~/.barerc`** — Personal shell init: **`export`**, **`alias`**, `**theme <preset>**`; parsed by **`loadBarerc`**. Builtin `**barerc reload`** reapplies without logout.
|
||||
- **`BARE_OS_THEME`** — Active color preset name; **`/bin/theme`**, **`~/.barerc`**, and `**ctx.bareOsApplyTheme()**` refresh **`BARE_OS_COLOR_*`** and usually **`LS_COLORS`**.
|
||||
- **`LS_COLORS`** — GNU-style colon-separated map consumed by `**ls --color**`; optional file via **`BARE_OS_DIRCOLORS`** and **`dircolors`**.
|
||||
- **`BARE_OS_COLOR_DEPTH`** — **`truecolor`** (default), **`256`**, or **`16`** / **`ansi`** — downgrades truecolor sequences in **`BARE_OS_COLOR_*`** for the fish REPL only.
|
||||
|
||||
---
|
||||
|
||||
@@ -35,7 +35,7 @@ Quick reference and repeated questions. **Canonical term definitions** (single s
|
||||
In-image scripts are not ES modules. Use inlining, bundling on the host, or the coreutils concat build. See [Chapter 5](05-modules-and-imports.md).
|
||||
|
||||
**How do I use npm packages on the device?**
|
||||
For packages listed in **`bare-module-manifest.json**`, use `**ctx.bare.<key>**` from `**run**` / `**start`** (see [Chapter 12](12-bare-modules-and-pear-ecosystem.md)). Otherwise bundle on the host, or add code to the **booter** package with normal `npm` deps.
|
||||
For packages listed in **`bare-module-manifest.json`**, use **`ctx.bare.<key>`** from **`run`** / **`start`** (see [Chapter 12](12-bare-modules-and-pear-ecosystem.md)). Otherwise bundle on the host, or add code to the **booter** package with normal `npm` deps.
|
||||
|
||||
**What’s the difference between `execLine` and `runBinCommand`?**
|
||||
`execLine` runs the **shell** (aliases, builtins, pipelines). `runBinCommand` runs **`argv`** directly. See [Chapter 3](03-kernel-boot-init.md).
|
||||
@@ -47,22 +47,22 @@ Follow [Chapter 6](06-extending-bin-coreutils.md): `src/foo.js`, `commands.mjs`,
|
||||
Not natively on the drive. Compile to JS on the host, then ship the output.
|
||||
|
||||
**Where is stdin for pipelines?**
|
||||
Shell sets **`ctx.shellStdin**` on a cloned context. Read it as a string. Coreutils use `**bareStdin(ctx)`** from prelude—user scripts must implement their own or copy the snippet. [Chapter 4](04-user-scripts-and-path.md).
|
||||
Shell sets **`ctx.shellStdin`** on a cloned context. Read it as a string. Coreutils use `**bareStdin(ctx)`** from prelude—user scripts must implement their own or copy the snippet. [Chapter 4](04-user-scripts-and-path.md).
|
||||
|
||||
**How do I exit the session from code?**
|
||||
Call **`ctx.requestBooterExit(code)**` (same as `**exit`** builtin / `/bin/exit`).
|
||||
Call **`ctx.requestBooterExit(code)**` (same as **`exit`** builtin / `/bin/exit`).
|
||||
|
||||
**Does `ctx.exitCode` control the host process exit?**
|
||||
The **host** exit code is managed by the booter after the kernel returns; utilities set **`ctx.exitCode`** for POSIX semantics inside the session. See booter `executeKernel` return path.
|
||||
|
||||
**What about Web APIs (`fetch`, `localStorage`)?**
|
||||
Not part of the Bare OS contract for in-image code. Pear/Bare may provide some globals on the **host**; do not rely on them for portable `/bin` tools. When Node provides **`fetch**`, the booter may set `**ctx.httpFetch`** with outbound policy—see [Chapter 2](02-the-context-object.md).
|
||||
Not part of the Bare OS contract for in-image code. Pear/Bare may provide some globals on the **host**; do not rely on them for portable `/bin` tools. When Node provides **`fetch`**, the booter may set **`ctx.httpFetch`** with outbound policy—see [Chapter 2](02-the-context-object.md).
|
||||
|
||||
**What is `bareOsSandboxRunScript`?**
|
||||
A **reserved** API that **throws** until a worker/isolate story lands; see [Chapter 9](09-security-and-trust.md).
|
||||
|
||||
**How do I match my host terminal to Bare OS colors?**
|
||||
Use **`theme list**` / `**theme set <name>**` in the guest, then import the matching files under **[docs/themes](../docs/themes/README.md)** (Alacritty, Warp, iTerm2). Host `**TERM**` and `**COLORTERM`** are passed through for capability detection.
|
||||
Use **`theme list**` / `**theme set <name>**` in the guest, then import the matching files under **[docs/themes](../docs/themes/README.md)** (Alacritty, Warp, iTerm2). Host **`TERM`** and **`COLORTERM`** are passed through for capability detection.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -10,17 +10,17 @@ 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**.
|
||||
- **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.
|
||||
- **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**.
|
||||
- **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.
|
||||
|
||||
## Observability
|
||||
|
||||
- **`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`**).
|
||||
- **`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**`, `**bits3**`, `**bits4**`, `**bits5`** (see `bare-os-protocol` exports).
|
||||
- **`/proc/bare_os_resources`** / `**ctx.bareOsGetResourceStatus()`** — Unified snapshot for operators.
|
||||
- **`/proc/bare_os_features`** — Documented kernel-feature words **`bits`**, **`bits2`**, **`bits3`**, **`bits4`**, **`bits5`** (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`.
|
||||
|
||||
@@ -30,30 +30,30 @@ Set these on the **Pear/Bare host** process before boot (the booter merges them
|
||||
|
||||
| Goal | Variables |
|
||||
| --- | --- |
|
||||
| Large pipeline bursts (`yes \| head …`, big `find`/`ls`) | Stock booter defaults **`BARE_OS_SHELL_STREAMING=1**`, `**BARE_OS_SHELL_STREAMING_MULT=2**`, `**BARE_OS_PIPELINE_MAX_BYTES**` (**512 MiB**), `**BARE_OS_PIPELINE_MAX_LINES**` (**2 M**) when unset on the host. Override with `**BARE_OS_PIPELINE_MAX_STAGES**`, `**BARE_OS_STREAMING_MULTIPLIER**` (alias for `**BARE_OS_SHELL_STREAMING_MULT`**). Absolute ceilings default to **512 MiB** / **2 M** lines (`BARE_OS_PIPELINE_ABS_MAX_BYTES` / `_LINES`). |
|
||||
| Large pipeline bursts (`yes \| head …`, big `find`/`ls`) | Stock booter defaults **`BARE_OS_SHELL_STREAMING=1`**, **`BARE_OS_SHELL_STREAMING_MULT=2`**, **`BARE_OS_PIPELINE_MAX_BYTES`** (**512 MiB**), **`BARE_OS_PIPELINE_MAX_LINES`** (**2 M**) when unset on the host. Override with **`BARE_OS_PIPELINE_MAX_STAGES`**, **`BARE_OS_STREAMING_MULTIPLIER`** (alias for **`BARE_OS_SHELL_STREAMING_MULT`**). Absolute ceilings default to **512 MiB** / **2 M** lines (`BARE_OS_PIPELINE_ABS_MAX_BYTES` / `_LINES`). |
|
||||
| Swarm | `BARE_OS_SWARM_MAX_PEERS`, `BARE_OS_SWARM_MAX_CLIENT_CONNECTIONS`, `BARE_OS_SWARM_MAX_SERVER_CONNECTIONS`, `BARE_OS_SWARM_MAX_PARALLEL` → Hyperswarm ctor. |
|
||||
| FIFOs / POSIX MQ | `BARE_OS_IPC_MAX_CHANNELS`; `BARE_OS_POSIX_MQ_MAX_MSGS`, `BARE_OS_POSIX_MQ_MSG_BYTES` (defaults for `mq_open` when attrs omitted). |
|
||||
| FD hint for scripts | `BARE_OS_VFS_MAX_OPEN` → mirrored as `RLIMIT_NOFILE` in **`/proc/bare_os/rlimits.json`**. |
|
||||
| Long sessions / cron-style `execLine` wall budget | `BARE_OS_EXEC_LINE_BUDGET_MS` or alias `BARE_OS_TIMER_BUDGET_MS`. |
|
||||
| OTL-style JSON lines | `BARE_OS_TELEMETRY_OTEL_JSONL=/abs/path` or shorthand `BARE_OS_TELEMETRY_OTEL=1` → **`/var/log/bare-os/otel.jsonl`**. |
|
||||
|
||||
**Verify after boot:** **`/proc/bare_os/capabilities.json`** (`ctxApiVersion`, pipeline caps), **`/proc/bare_os_resources**`, `**/proc/bare_os/rlimits.json**`. `**ctxApiVersion`** only changes with a booter/protocol bump, not with env tuning.
|
||||
**Verify after boot:** **`/proc/bare_os/capabilities.json`** (`ctxApiVersion`, pipeline caps), **`/proc/bare_os_resources`**, **`/proc/bare_os/rlimits.json`**. **`ctxApiVersion`** only changes with a booter/protocol bump, not with env tuning.
|
||||
|
||||
Storage write limits use existing hooks (**`BARE_OS_VFS_QUOTA_***`, `**BARE_OS_HOST_STORAGE_JSON**`, `**BARE_OS_BARE_STORAGE_QUOTA_JSON`** on bare-storage paths)—there is no separate `BARE_OS_STORAGE_QUOTA_BYTES` knob.
|
||||
Storage write limits use existing hooks (**`BARE_OS_VFS_QUOTA_*`**, **`BARE_OS_HOST_STORAGE_JSON`**, **`BARE_OS_BARE_STORAGE_QUOTA_JSON`** on bare-storage paths)—there is no separate `BARE_OS_STORAGE_QUOTA_BYTES` knob.
|
||||
|
||||
## Pear / Git / HTTP
|
||||
|
||||
- **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. A successful host reload can swap the Pear **booter** bundle so a new `**bare-module-manifest.data.mjs**` (from `**npm run sync:bare-manifest**` at staging time) takes effect; `**ctx.bareOsRequestPearReload**` does not rewrite `**ctx.bare**` in-process—expect a new guest boot for an updated host import list. Drive-only edits to `**/lib/bare/bare-module-manifest.json`** still merge bundles from the image without re-staging Pear.
|
||||
- **`ctx.bareOsPearUpdaterDelegate()**` (async, `**bareOsCtxApiVersion` 1.32.0+**) — Surfaces non-secret updater state without bundling **`pear-runtime-updater**` in the stock booter. Host options: set `**BARE_OS_PEAR_UPDATER_SNAPSHOT_JSON**` to a JSON string for a fixed operator snapshot, or `**BARE_OS_PEAR_UPDATER_MODULE**` to an ESM URL/path whose default export (or `**getPearUpdaterState**` / `**bareOsPearUpdaterSnapshot**`) is an `**async function**` returning a plain object (for example `**{ version, updating, updated }**` mirroring your `**PearRuntimeUpdater`** instance). See [`bare-os-pear-updater-bridge.js`](../packages/bare-os-booter/lib/bare-os-pear-updater-bridge.js).
|
||||
- **`ctx.bareOsRequestPearReload()**` — Returns hints and env strings; the host `**pear-runtime` / `pear-runtime-updater**` must perform any real reload. A successful host reload can swap the Pear **booter** bundle so a new **`bare-module-manifest.data.mjs`** (from `**npm run sync:bare-manifest**` at staging time) takes effect; **`ctx.bareOsRequestPearReload`** does not rewrite **`ctx.bare`** in-process—expect a new guest boot for an updated host import list. Drive-only edits to **`/lib/bare/bare-module-manifest.json`** still merge bundles from the image without re-staging Pear.
|
||||
- **`ctx.bareOsPearUpdaterDelegate()**` (async, `**bareOsCtxApiVersion` 1.32.0+**) — Surfaces non-secret updater state without bundling **`pear-runtime-updater`** in the stock booter. Host options: set **`BARE_OS_PEAR_UPDATER_SNAPSHOT_JSON`** to a JSON string for a fixed operator snapshot, or **`BARE_OS_PEAR_UPDATER_MODULE`** to an ESM URL/path whose default export (or **`getPearUpdaterState`** / **`bareOsPearUpdaterSnapshot`**) is an `**async function**` returning a plain object (for example `**{ version, updating, updated }**` mirroring your **`PearRuntimeUpdater`** instance). See [`bare-os-pear-updater-bridge.js`](../packages/bare-os-booter/lib/bare-os-pear-updater-bridge.js).
|
||||
|
||||
### 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.
|
||||
- **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.
|
||||
|
||||
## Building the image
|
||||
|
||||
|
||||
@@ -6,15 +6,15 @@ This chapter ties together **Holepunch `bare-*` packages**, the **Pear** host ru
|
||||
|
||||
## Tiers of access (image, Pear embed, host, mirror)
|
||||
|
||||
1. **`/lib/bare` (system image, primary)** — **`bare-os-bare-libs**` builds **one IIFE per manifest row** into `**kernel/lib/bare/bundles/**` (mirrored on the seeded Hyperdrive). It also copies `**bare-module-manifest.json**` into `**kernel/lib/bare/**`. `**manifest.json**` lists successful bundles; stale `**bundles/*.js**` files are **pruned** on each successful build. At boot, drive bundles run **first** (unless `**BARE_OS_BARE_DRIVE_BUNDLES=0`**).
|
||||
1. **`/lib/bare` (system image, primary)** — **`bare-os-bare-libs`** builds **one IIFE per manifest row** into **`kernel/lib/bare/bundles/`** (mirrored on the seeded Hyperdrive). It also copies **`bare-module-manifest.json`** into **`kernel/lib/bare/`**. **`manifest.json`** lists successful bundles; stale **`bundles/*.js`** files are **pruned** on each successful build. At boot, drive bundles run **first** (unless **`BARE_OS_BARE_DRIVE_BUNDLES=0`**).
|
||||
|
||||
2. **Pear booter (`bare-module-manifest.data.mjs`)** — The stock booter package ships **`packages/bare-os-booter/lib/bare-module-manifest.json**` (normative JSON, edited or synced from the catalog) and a generated sibling `**bare-module-manifest.data.mjs**` that `**export default**` the same object. Under `**pear run**`, `**import.meta.url**` is `**pear://…**`; `**bare-fs**` cannot open `**pear:**` URLs passed as `**URL**` instances because normalization uses `**bare-url.fileURLToPath**` ( `**file:**` only). Therefore `**loadBareModuleManifest()**` reads the embedded `**.data.mjs**` on Pear so the manifest stays in the traced module graph. On `**file:**` dev checkouts it prefers the JSON on disk (live edits) and falls back to the embedded copy if the file is missing. Regenerate `**.data.mjs**` with `**npm run sync:bare-manifest**` or `**node scripts/generate-bare-module-manifest-data.mjs**`; CI runs `**npm run verify:manifest-data`**.
|
||||
2. **Pear booter (`bare-module-manifest.data.mjs`)** — The stock booter package ships **`packages/bare-os-booter/lib/bare-module-manifest.json`** (normative JSON, edited or synced from the catalog) and a generated sibling **`bare-module-manifest.data.mjs`** that `**export default**` the same object. Under `**pear run**`, **`import.meta.url`** is `**pear://…**`; **`bare-fs`** cannot open **`pear:`** URLs passed as **`URL`** instances because normalization uses **`bare-url.fileURLToPath`** ( **`file:`** only). Therefore `**loadBareModuleManifest()**` reads the embedded **`.data.mjs`** on Pear so the manifest stays in the traced module graph. On **`file:`** dev checkouts it prefers the JSON on disk (live edits) and falls back to the embedded copy if the file is missing. Regenerate **`.data.mjs`** with `**npm run sync:bare-manifest**` or `**node scripts/generate-bare-module-manifest-data.mjs**`; CI runs `**npm run verify:manifest-data`**.
|
||||
|
||||
3. **`ctx.bare` (host fallback)** — Unless **`BARE_OS_BARE_HOST_IMPORTS=0**`, the booter then `**import()**`s manifest packages **still missing** after drive merge. Under `**pear run**` (booter `**import.meta.url**` is `**pear:**`), `**bundle: true**` rows are **skipped** for host `**import()**` (keys come from `**/lib/bare/bundles/***` only; avoids bare-module `**MODULE_NOT_FOUND` / referrer** errors for npm names like **`holesail**`). Under `**file:**` dev trees, `**bundle: true**` may still be host-imported when the drive bundle did not fill the key. Remaining host imports cover native or Bare-only packages that could not be bundled, or when the image is older than the manifest. Set `**BARE_OS_BARE_HOST_IMPORTS=0`** for a **fully image-local** `ctx.bare` (no Pear host `node_modules` participation). Disable all `ctx.bare` with **`BARE_OS_BARE_MODULES=0**`. For narrow harnesses, session env may set `**BARE_OS_BARE_HOST_SKIP_CTX_KEYS**` (comma-separated `**ctxKey**` list to skip) or `**BARE_OS_BARE_HOST_ONLY_CTX_KEYS**` (allowlist — only those keys are host-imported). Manifest rows may include optional `**tier**` (`**core**` vs extended) and `**risk**` (`**low**`, `**medium**`, `**high**`) for distributor policy; the build honors `**tier**` via `**BARE_OS_BUNDLE_TIER`**.
|
||||
3. **`ctx.bare` (host fallback)** — Unless **`BARE_OS_BARE_HOST_IMPORTS=0`**, the booter then `**import()**`s manifest packages **still missing** after drive merge. Under `**pear run**` (booter **`import.meta.url`** is **`pear:`**), `**bundle: true**` rows are **skipped** for host `**import()**` (keys come from **`/lib/bare/bundles/*`** only; avoids bare-module `**MODULE_NOT_FOUND` / referrer** errors for npm names like **`holesail`**). Under **`file:`** dev trees, `**bundle: true**` may still be host-imported when the drive bundle did not fill the key. Remaining host imports cover native or Bare-only packages that could not be bundled, or when the image is older than the manifest. Set **`BARE_OS_BARE_HOST_IMPORTS=0`** for a **fully image-local** `ctx.bare` (no Pear host `node_modules` participation). Disable all `ctx.bare` with **`BARE_OS_BARE_MODULES=0`**. For narrow harnesses, session env may set **`BARE_OS_BARE_HOST_SKIP_CTX_KEYS`** (comma-separated **`ctxKey`** list to skip) or **`BARE_OS_BARE_HOST_ONLY_CTX_KEYS`** (allowlist — only those keys are host-imported). Manifest rows may include optional **`tier`** (**`core`** vs extended) and **`risk`** (**`low`**, **`medium`**, **`high`**) for distributor policy; the build honors **`tier`** via **`BARE_OS_BUNDLE_TIER`**.
|
||||
|
||||
**Boot cold path / stdlib budget:** the stock booter measures drive merge + host **`import()**` resolution for `**ctx.bare**` and sets `**BARE_OS_BOOT_BARE_STDLIB_RESOLUTION_MS**` before the guest starts. Operators may set `**BARE_OS_BOOT_BUDGET_MS_BARE_STDLIB**` to log `**boot-perf.json**` / stderr warnings when resolution exceeds the budget; combine with `**BARE_OS_BUNDLE_TIER=core**` (or a smaller manifest) to shrink cold I/O. Use `**node scripts/kernel-microbench.mjs`** for regression-shaped timings (not a literal Pear cold boot).
|
||||
**Boot cold path / stdlib budget:** the stock booter measures drive merge + host **`import()**` resolution for **`ctx.bare`** and sets **`BARE_OS_BOOT_BARE_STDLIB_RESOLUTION_MS`** before the guest starts. Operators may set **`BARE_OS_BOOT_BUDGET_MS_BARE_STDLIB`** to log **`boot-perf.json`** / stderr warnings when resolution exceeds the budget; combine with **`BARE_OS_BUNDLE_TIER=core`** (or a smaller manifest) to shrink cold I/O. Use `**node scripts/kernel-microbench.mjs`** for regression-shaped timings (not a literal Pear cold boot).
|
||||
|
||||
4. **The full mirror (discoverability)** — A local checkout of Holepunch repos (for example **`holepunchto_repos**` under your Pear tooling tree) lists on the order of **150+** repositories whose names start with `**bare-`**. Many are **native addons**, **platform-specific** (mobile, GUI, FFmpeg, …), or **developer tools**. The **manifest** can list them for `ctx.bare`, but only rows that bundle cleanly become real drive IIFEs; the rest rely on host import or stubs until you trim the manifest.
|
||||
4. **The full mirror (discoverability)** — A local checkout of Holepunch repos (for example **`holepunchto_repos`** under your Pear tooling tree) lists on the order of **150+** repositories whose names start with **`bare-`**. Many are **native addons**, **platform-specific** (mobile, GUI, FFmpeg, …), or **developer tools**. The **manifest** can list them for `ctx.bare`, but only rows that bundle cleanly become real drive IIFEs; the rest rely on host import or stubs until you trim the manifest.
|
||||
|
||||
---
|
||||
|
||||
@@ -28,11 +28,11 @@ This chapter ties together **Holepunch `bare-*` packages**, the **Pear** host ru
|
||||
npm install
|
||||
```
|
||||
|
||||
This refreshes **[`docs/bare-holepunch-catalog.json`](../docs/bare-holepunch-catalog.json)** (every **`holepunchto/bare-***` repo plus npm `**latest`**, minus [`scripts/bare-catalog-overrides.json`](../scripts/bare-catalog-overrides.json)), then merges published packages into **[`bare-module-manifest.json`](../packages/bare-os-booter/lib/bare-module-manifest.json)** and **replaces** booter **`optionalDependencies**` from that catalog (anything not `**includedInBooter**` is dropped). CI runs `**npm run gen:bare-catalog:check**` so the committed catalog’s `**entries**` (and `**source`**) stay in sync with live npm/GitHub.
|
||||
This refreshes **[`docs/bare-holepunch-catalog.json`](../docs/bare-holepunch-catalog.json)** (every **`holepunchto/bare-*`** repo plus npm **`latest`**, minus [`scripts/bare-catalog-overrides.json`](../scripts/bare-catalog-overrides.json)), then merges published packages into **[`bare-module-manifest.json`](../packages/bare-os-booter/lib/bare-module-manifest.json)** and **replaces** booter **`optionalDependencies`** from that catalog (anything not **`includedInBooter`** is dropped). CI runs `**npm run gen:bare-catalog:check**` so the committed catalog’s **`entries`** (and **`source`**) stay in sync with live npm/GitHub.
|
||||
|
||||
**[`scripts/bare-ctx-import-overrides.json`](../scripts/bare-ctx-import-overrides.json)** adjusts a few packages for **`ctx.bare**` / esbuild: namespace exports (`**export: ***`), `**bare-node-runtime/global`** as a side-effect entry, etc. Edit this when npm packages have no default export or need a subpath.
|
||||
**[`scripts/bare-ctx-import-overrides.json`](../scripts/bare-ctx-import-overrides.json)** adjusts a few packages for **`ctx.bare`** / esbuild: namespace exports (`**export: ***`), **`bare-node-runtime/global`** as a side-effect entry, etc. Edit this when npm packages have no default export or need a subpath.
|
||||
|
||||
- **Add or remove a `ctx.bare` entry by hand** — Edit the manifest and booter **`dependencies**` / `**optionalDependencies**` as needed. The `**bundle**` field in the manifest is **legacy metadata**; `**bare-os-bare-libs**` attempts **every** row. Prefer the catalog + sync path for `**bare-***` rows so `**ctxKey`** and semver ranges stay consistent.
|
||||
- **Add or remove a `ctx.bare` entry by hand** — Edit the manifest and booter **`dependencies`** / **`optionalDependencies`** as needed. The **`bundle`** field in the manifest is **legacy metadata**; **`bare-os-bare-libs`** attempts **every** row. Prefer the catalog + sync path for **`bare-*`** rows so **`ctxKey`** and semver ranges stay consistent.
|
||||
|
||||
- **Refresh `/lib/bare` on the image** — From the repo root:
|
||||
|
||||
@@ -40,39 +40,39 @@ This chapter ties together **Holepunch `bare-*` packages**, the **Pear** host ru
|
||||
npm run build -w bare-os-bare-libs
|
||||
```
|
||||
|
||||
Optional **`BARE_OS_BUNDLE_TIER=core**` builds only manifest rows with `**"tier": "core"**` (default tier when omitted). Use `**all`** or unset for the full catalog.
|
||||
Optional **`BARE_OS_BUNDLE_TIER=core`** builds only manifest rows with `**"tier": "core"**` (default tier when omitted). Use **`all`** or unset for the full catalog.
|
||||
|
||||
Then re-run the seeder so **`kernel/lib/bare/`** is copied into the Hyperdrive (the seeder invokes this build automatically when running from a `file:` URL). Check **`manifest.json**` → `**bundleStats`** after a build for how many IIFEs succeeded vs stub-only.
|
||||
Then re-run the seeder so **`kernel/lib/bare/`** is copied into the Hyperdrive (the seeder invokes this build automatically when running from a `file:` URL). Check **`manifest.json`** → **`bundleStats`** after a build for how many IIFEs succeeded vs stub-only.
|
||||
|
||||
- **Node vs Pear/Bare** — On **Node**, **`buildBareCtxObjectFromHost**` skips manifest rows with `**nativeHint: true**` so optional Bare-native packages are not `**import()`**’d (avoids stray failures and unhandled rejections from addons). On **Pear/Bare**, the full manifest is loaded in parallel.
|
||||
- **Node vs Pear/Bare** — On **Node**, **`buildBareCtxObjectFromHost`** skips manifest rows with `**nativeHint: true**` so optional Bare-native packages are not `**import()`**’d (avoids stray failures and unhandled rejections from addons). On **Pear/Bare**, the full manifest is loaded in parallel.
|
||||
|
||||
- **Pear** — Continue to use **`node scripts/ensure-pear-node-modules.mjs packages/bare-os-booter**` before `**pear run**` so hoisted `**node_modules**` resolve like npm (see [PEAR-RUN.md](../docs/PEAR-RUN.md)). After any manifest or catalog edit, run `**npm run sync:bare-manifest**` before `**pear stage**` so `**bare-module-manifest.data.mjs`** matches the JSON.
|
||||
- **Pear** — Continue to use **`node scripts/ensure-pear-node-modules.mjs packages/bare-os-booter**` before `**pear run**` so hoisted **`node_modules`** resolve like npm (see [PEAR-RUN.md](../docs/PEAR-RUN.md)). After any manifest or catalog edit, run `**npm run sync:bare-manifest**` before `**pear stage**` so **`bare-module-manifest.data.mjs`** matches the JSON.
|
||||
|
||||
- **Local Holepunch clone inventory** — After editing the manifest or before a release, run **`npm run audit:holepunch-clones`** to refresh **[`docs/audit/holepunch-clone-sync-report.json`](../docs/audit/holepunch-clone-sync-report.json)** against **`BARE_OS_HOLEPUNCH_CLONES_ROOT**`. To fail CI when selected clones lag `**origin/main`**, list their directory names in **[`docs/audit/holepunch-drift-repos.json`](../docs/audit/holepunch-drift-repos.json)** and set **`BARE_OS_HOLEPUNCH_DRIFT_CHECK=1`** (see [scripts/README.md](../scripts/README.md)).
|
||||
- **Local Holepunch clone inventory** — After editing the manifest or before a release, run **`npm run audit:holepunch-clones`** to refresh **[`docs/audit/holepunch-clone-sync-report.json`](../docs/audit/holepunch-clone-sync-report.json)** against **`BARE_OS_HOLEPUNCH_CLONES_ROOT`**. To fail CI when selected clones lag **`origin/main`**, list their directory names in **[`docs/audit/holepunch-drift-repos.json`](../docs/audit/holepunch-drift-repos.json)** and set **`BARE_OS_HOLEPUNCH_DRIFT_CHECK=1`** (see [scripts/README.md](../scripts/README.md)).
|
||||
|
||||
- **`mirror-drive` (Holepunch) audit** — The stock VFS union and **`/mirror/***` overlays remain the supported read-mostly composition path. The upstream `**mirror-drive**` package is a candidate for a future **env-gated** fast path (read-only layering); treat any integration as **parity-tested** against union semantics and document **fallback** when the package is absent. See `**BARE_OS_VFS_UNION_PREFIXES**` in the environment appendix and `**ctx.bareOsEmitMirrorDriveHint`** above.
|
||||
- **`mirror-drive` (Holepunch) audit** — The stock VFS union and **`/mirror/*`** overlays remain the supported read-mostly composition path. The upstream **`mirror-drive`** package is a candidate for a future **env-gated** fast path (read-only layering); treat any integration as **parity-tested** against union semantics and document **fallback** when the package is absent. See **`BARE_OS_VFS_UNION_PREFIXES`** in the environment appendix and **`ctx.bareOsEmitMirrorDriveHint`** above.
|
||||
|
||||
---
|
||||
|
||||
## Runtime caps
|
||||
|
||||
**`ctx.bareOsRuntimeCaps.features**` includes `**bareCtxModules**`, `**bareDriveBundles**`, and `**bareHostImportsForCtx`** so kernels can see whether host fallbacks are enabled.
|
||||
**`ctx.bareOsRuntimeCaps.features`** includes **`bareCtxModules`**, **`bareDriveBundles`**, and **`bareHostImportsForCtx`** so kernels can see whether host fallbacks are enabled.
|
||||
|
||||
---
|
||||
|
||||
## Pear IPC channel registry
|
||||
|
||||
**`ctx.bareOsPearIpcEmit(channel, payload)**` is a host bridge for [pear-ipc](https://github.com/holepunchto/pear-ipc)-style messaging. Well-known `**channel**` strings are listed in `**packages/bare-os-booter/lib/bare-os-pear-ipc-registry.js**` and mirrored as JSON under `**/proc/bare_os/pear_ipc.json**` (and the flat `**/proc/bare_os_pear_ipc_registry`** alias) so operators and kernels share one vocabulary for reload, mirror, and telemetry hints.
|
||||
**`ctx.bareOsPearIpcEmit(channel, payload)**` is a host bridge for [pear-ipc](https://github.com/holepunchto/pear-ipc)-style messaging. Well-known **`channel`** strings are listed in **`packages/bare-os-booter/lib/bare-os-pear-ipc-registry.js`** and mirrored as JSON under **`/proc/bare_os/pear_ipc.json`** (and the flat **`/proc/bare_os_pear_ipc_registry`** alias) so operators and kernels share one vocabulary for reload, mirror, and telemetry hints.
|
||||
|
||||
**`ctx.bareOsPearIpcRequest(channel, payload, { timeoutMs? })**` correlates `**bareOsIpcReqId**` on `**payload**` and awaits `**process.emit('bare-os:pear-ipc-response', { bareOsIpcReqId, result?, error? })**` on Node-style hosts. Use for request/response pairs alongside `**bareOsPearIpcEmit`**.
|
||||
**`ctx.bareOsPearIpcRequest(channel, payload, { timeoutMs? })**` correlates **`bareOsIpcReqId`** on **`payload`** and awaits `**process.emit('bare-os:pear-ipc-response', { bareOsIpcReqId, result?, error? })**` on Node-style hosts. Use for request/response pairs alongside **`bareOsPearIpcEmit`**.
|
||||
|
||||
**Mirror-drive hints:** **`ctx.bareOsEmitMirrorDriveHint({ label?, key? })**` emits `**bare-os:mirror-drive-hint`** for Holepunch-style snapshot workflows (see [kernel extensions](../docs/reference/kernel-extensions.md)).
|
||||
**Mirror-drive hints:** **`ctx.bareOsEmitMirrorDriveHint({ label?, key? })**` emits **`bare-os:mirror-drive-hint`** for Holepunch-style snapshot workflows (see [kernel extensions](../docs/reference/kernel-extensions.md)).
|
||||
|
||||
**Blind-peer style hint:** **`ctx.bareOsEmitBlindPeerHint(payload)**` forwards a **capped** JSON object on Pear IPC as `**bare_os_blind_peer_hint`** (topic/key material stays opaque strings; the guest does not verify blind-relay crypto).
|
||||
**Blind-peer style hint:** **`ctx.bareOsEmitBlindPeerHint(payload)**` forwards a **capped** JSON object on Pear IPC as **`bare_os_blind_peer_hint`** (topic/key material stays opaque strings; the guest does not verify blind-relay crypto).
|
||||
|
||||
**Host-only eval probe:** **`ctx.bareOsHostCapability('bundleEvaluate')**` is `**true**` when the host advertises `**BARE_OS_HOST_BUNDLE_EVALUATE=1`**, documenting an optional **[`cross-worker`](https://github.com/holepunchto/cross-worker)** / **[`bare-bundle-evaluate`](https://github.com/holepunchto/bare-bundle-evaluate)** path. Actual evaluation still happens **outside** the guest VFS trust boundary.
|
||||
**Host-only eval probe:** **`ctx.bareOsHostCapability('bundleEvaluate')**` is **`true`** when the host advertises **`BARE_OS_HOST_BUNDLE_EVALUATE=1`**, documenting an optional **[`cross-worker`](https://github.com/holepunchto/cross-worker)** / **[`bare-bundle-evaluate`](https://github.com/holepunchto/bare-bundle-evaluate)** path. Actual evaluation still happens **outside** the guest VFS trust boundary.
|
||||
|
||||
**`bare-fetch` content encodings (Capability word 6 doc alignment)** — When the host **`fetch**` implementation is Holepunch `**bare-fetch**`, **Content-Encoding** negotiation may include `**br**` and `**zstd**` in addition to `**gzip**` depending on platform support. In-image scripts should not assume a fixed encoding list; treat `**Accept-Encoding`** as host-defined. SPDX license identifiers on catalog rows (when present) are **metadata for distributors**, not a runtime guarantee inside the guest.
|
||||
**`bare-fetch` content encodings (Capability word 6 doc alignment)** — When the host **`fetch`** implementation is Holepunch **`bare-fetch`**, **Content-Encoding** negotiation may include **`br`** and **`zstd`** in addition to **`gzip`** depending on platform support. In-image scripts should not assume a fixed encoding list; treat **`Accept-Encoding`** as host-defined. SPDX license identifiers on catalog rows (when present) are **metadata for distributors**, not a runtime guarantee inside the guest.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@ Operators running Bare OS as part of a service should maintain a **subprocessor
|
||||
|
||||
- NDJSON lifecycle / telemetry: see **`BARE_OS_LIFECYCLE_SCHEMA_VERSION`** (**10** in stock tree) and rows in [`docs/reference/compatibility-matrix.md`](../docs/reference/compatibility-matrix.md).
|
||||
- OTel-inspired lines: **`otlSchemaVersion: 7`**, example [`kernel/etc/bare-os/otel-jsonl.example.json`](../kernel/etc/bare-os/otel-jsonl.example.json), schema [`docs/schemas/otel-bare-os-jsonl.schema.json`](../docs/schemas/otel-bare-os-jsonl.schema.json).
|
||||
- Audit JSON: **`auditSchemaVersion: 7**` (delegate depth / Capability word 9–10 RPC classes); optional `**requestSmugglingClass**` remains default `**none`** in stock emitters where applicable.
|
||||
- Audit JSON: **`auditSchemaVersion: 7**` (delegate depth / Capability word 9–10 RPC classes); optional **`requestSmugglingClass`** remains default **`none`** in stock emitters where applicable.
|
||||
|
||||
## Related
|
||||
|
||||
|
||||
@@ -12,13 +12,13 @@ This project is **experimental research software**. APIs described here follow t
|
||||
|
||||
**Capability map:** [docs/reference/kernel-capabilities-index.md](../docs/reference/kernel-capabilities-index.md).
|
||||
|
||||
**Contract checks:** changing **`bareOsCtxApiVersion**` or stock kernel feature bits should keep `**scripts/verify-ctx-api-feature-bits.mjs**` green (invoked from root `**pretest`**).
|
||||
**Contract checks:** changing **`bareOsCtxApiVersion`** or stock kernel feature bits should keep **`scripts/verify-ctx-api-feature-bits.mjs`** green (invoked from root **`pretest`**).
|
||||
|
||||
**Architecture contract (boundaries):** [`docs/architecture/KERNEL_CONTRACT.md`](../docs/architecture/KERNEL_CONTRACT.md) — booter vs guest image, **`disk.os`** RPC, boot step IDs.
|
||||
|
||||
**Kernel source set:** [`docs/reference/kernel-extensions.md`](../docs/reference/kernel-extensions.md) — first-party paths (`kernel/init.js`, `kernel/lib/boot`, built `/bin`) vs vendored **`kernel/lib/bare/bundles**` (Holepunch IIFEs), CI allowlists, and seeder parity. Hand-authored code must stay free of incomplete markers; bundles are gated by `**verify-bundle-markers.mjs**`, `**verify-bundle-throws.mjs**` ( `**new Error` messages** with *not implemented* / abstract-base-class semantics — see [`docs/audit/bundle-throw-allowlist.json`](../docs/audit/bundle-throw-allowlist.json)), and **`sanitize-bare-bundles.mjs`**. Prefer shrinking the throw allowlist via upstream bundle refreshes over silent drift.
|
||||
**Kernel source set:** [`docs/reference/kernel-extensions.md`](../docs/reference/kernel-extensions.md) — first-party paths (`kernel/init.js`, `kernel/lib/boot`, built `/bin`) vs vendored **`kernel/lib/bare/bundles`** (Holepunch IIFEs), CI allowlists, and seeder parity. Hand-authored code must stay free of incomplete markers; bundles are gated by **`verify-bundle-markers.mjs`**, **`verify-bundle-throws.mjs`** ( `**new Error` messages** with *not implemented* / abstract-base-class semantics — see [`docs/audit/bundle-throw-allowlist.json`](../docs/audit/bundle-throw-allowlist.json)), and **`sanitize-bare-bundles.mjs`**. Prefer shrinking the throw allowlist via upstream bundle refreshes over silent drift.
|
||||
|
||||
**Local Holepunch mirror:** run **`npm run audit:holepunch-clones**` to refresh `**docs/audit/holepunch-clone-sync-report.json**` (schema **2**), `**holepunch-lockfile-drift.json**`, and NDJSON summaries. The sync report lists every `**bare-module-manifest.json**` entry against `**BARE_OS_HOLEPUNCH_CLONES_ROOT**` (default `**~/dev/pearcli/holepunch-repos/holepunchto_repos**`): `**gitHead**`, `**originMainHead**`, `**commitsBehindOriginMain**`, `**commitsAheadOfOriginMain**` (meaningful after `**git fetch origin main**` in each clone). `**goldenPathRows**` mirrors `**goldenPathRepos**` in `**docs/audit/holepunch-drift-repos.json**` (Bare runtime + Pear + core wire stack) for quick maintainer diff review — it is **not** a CI gate. Root `**pretest**` runs `**verify-holepunch-clone-drift.mjs**` only against `**repos[]**` in the same JSON (empty = no-op). Maintainers may set `**BARE_OS_HOLEPUNCH_DRIFT_TIER1=1**` to check `**tier1Repos[]**` instead (hypercore / hyperdrive / hyperswarm / protomux / pear / pear-runtime / bare-fs / bare-process). Regenerate the maximal npm catalog with `**node scripts/gen-bare-holepunch-catalog.mjs**` (or `**npm run gen:bare-catalog**`), then `**npm run sync:bare-manifest`** — see [scripts/README.md](../scripts/README.md).
|
||||
**Local Holepunch mirror:** run **`npm run audit:holepunch-clones**` to refresh **`docs/audit/holepunch-clone-sync-report.json`** (schema **2**), **`holepunch-lockfile-drift.json`**, and NDJSON summaries. The sync report lists every **`bare-module-manifest.json`** entry against **`BARE_OS_HOLEPUNCH_CLONES_ROOT`** (default **`~/dev/pearcli/holepunch-repos/holepunchto_repos`**): **`gitHead`**, **`originMainHead`**, **`commitsBehindOriginMain`**, **`commitsAheadOfOriginMain`** (meaningful after `**git fetch origin main**` in each clone). **`goldenPathRows`** mirrors **`goldenPathRepos`** in **`docs/audit/holepunch-drift-repos.json`** (Bare runtime + Pear + core wire stack) for quick maintainer diff review — it is **not** a CI gate. Root **`pretest`** runs **`verify-holepunch-clone-drift.mjs`** only against `**repos[]**` in the same JSON (empty = no-op). Maintainers may set **`BARE_OS_HOLEPUNCH_DRIFT_TIER1=1`** to check `**tier1Repos[]**` instead (hypercore / hyperdrive / hyperswarm / protomux / pear / pear-runtime / bare-fs / bare-process). Regenerate the maximal npm catalog with `**node scripts/gen-bare-holepunch-catalog.mjs**` (or `**npm run gen:bare-catalog**`), then `**npm run sync:bare-manifest`** — see [scripts/README.md](../scripts/README.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -71,8 +71,8 @@ Full script index: [scripts/README.md](../scripts/README.md). Gate everything wi
|
||||
- **[11 — Kernel + Pear cookbook](11-kernel-pear-cookbook.md)** — Boot allowlist, timers, socket IPC, `vfs.watch`, HDMS hooks, Git-in-Pear, release metadata.
|
||||
- **[12 — Bare modules and Pear ecosystem](12-bare-modules-and-pear-ecosystem.md)** — `ctx.bare`, manifest, drive bundles, Holepunch `bare-*` mirror vs guaranteed keys.
|
||||
- **[13 — Privacy, telemetry, and PII](13-privacy-telemetry-pii.md)** — Scrub lists for NDJSON / OTel mirrors; non-secret posture.
|
||||
- **[Node → Bare module map](node-to-bare-modules.md)** — Guest-safe replacements for **`node:***` built-ins (`**bare-crypto**`, `**bare-module`**, …).
|
||||
- **[bare-boot vs kernel phases](bare-boot-kernel-phase-alignment.md)** — Conceptual map: Holepunch **`bare-boot**` stages vs stock `**kernel/init.js`**.
|
||||
- **[Node → Bare module map](node-to-bare-modules.md)** — Guest-safe replacements for **`node:*`** built-ins (**`bare-crypto`**, **`bare-module`**, …).
|
||||
- **[bare-boot vs kernel phases](bare-boot-kernel-phase-alignment.md)** — Conceptual map: Holepunch **`bare-boot`** stages vs stock **`kernel/init.js`**.
|
||||
- **[Kernel program (governed expansion)](kernel-program.md)** — Governance, boot hooks, **`/proc/bare_os/kernel_program.json`**, Bare stack pointers, 200-item roadmap batches.
|
||||
- **[Naming conventions](naming-conventions.md)** — First-party vs vendored trees, `ctx` / env / proc naming.
|
||||
- **[Naming migrations](naming-migrations.md)** — Legacy aliases and deprecation windows for boot hooks and policy keys.
|
||||
|
||||
@@ -8,7 +8,7 @@ Accepted
|
||||
|
||||
Bare OS advertises optional booter and seed-channel capabilities as a versioned bitmask (`bare-os-protocol` `kernel-feature-bits.js`). Peers compare masks during the seed handshake and guests read `/proc/bare_os_features`. Bits must remain backward compatible: unknown bits are ignored on the wire.
|
||||
|
||||
**Wire v2 (`bare-os-protocol` 0.9+):** seed **`bare_os.capabilities**`, `**/proc/bare_os_features**`, and guest `**ctx`** expose eleven `uint32` words under **`kernelCapabilityWords`** (semantic camelCase keys; see [`kernel-capability-wire.js`](../../packages/bare-os-protocol/lib/kernel-capability-wire.js)). **`kernelCapabilityWireVersion**` is **2**. Legacy v1 top-level `**bits**` … `**bits11`** were removed in the same breaking release; **numeric masks and bit positions** are unchanged. **Source identifiers** use semantic labels (`BARE_OS_KERNEL_FEATURES_STOCK_WORD_*`, `requireKernelCapabilities*`, env mirrors). The authoritative cross-reference is [`docs/reference/capability-words.md`](../../docs/reference/capability-words.md).
|
||||
**Wire v2 (`bare-os-protocol` 0.9+):** seed **`bare_os.capabilities`**, **`/proc/bare_os_features`**, and guest **`ctx`** expose eleven `uint32` words under **`kernelCapabilityWords`** (semantic camelCase keys; see [`kernel-capability-wire.js`](../../packages/bare-os-protocol/lib/kernel-capability-wire.js)). **`kernelCapabilityWireVersion`** is **2**. Legacy v1 top-level **`bits`** … **`bits11`** were removed in the same breaking release; **numeric masks and bit positions** are unchanged. **Source identifiers** use semantic labels (`BARE_OS_KERNEL_FEATURES_STOCK_WORD_*`, `requireKernelCapabilities*`, env mirrors). The authoritative cross-reference is [`docs/reference/capability-words.md`](../../docs/reference/capability-words.md).
|
||||
|
||||
## Decisions
|
||||
|
||||
@@ -19,36 +19,36 @@ Bare OS advertises optional booter and seed-channel capabilities as a versioned
|
||||
- a one-line comment describing user-visible behavior
|
||||
- inclusion in `BARE_OS_KERNEL_FEATURES_STOCK_WORD_PRIMARY` only when the **stock booter** implements it end-to-end
|
||||
|
||||
3. **`/proc/bare_os_features`** — Must include `doc`, **`kernelCapabilityWords**` (effective stock masks minus env-disabled features such as crypto urandom on `**primary**`), `**kernelCapabilityWireVersion`**, and optional `seedHandshake` summary. The unified tree under `/proc/bare_os/` duplicates the same content for stable paths (see `docs/reference/kernel-extensions.md`).
|
||||
3. **`/proc/bare_os_features`** — Must include `doc`, **`kernelCapabilityWords`** (effective stock masks minus env-disabled features such as crypto urandom on **`primary`**), **`kernelCapabilityWireVersion`**, and optional `seedHandshake` summary. The unified tree under `/proc/bare_os/` duplicates the same content for stable paths (see `docs/reference/kernel-extensions.md`).
|
||||
|
||||
4. **Bits 28–30 (assigned, word 1)** — **28:** `BARE_OS_FEATURE_SEED_MANIFEST_HINTS_RPC` (`bare_os.manifest_hints`). **29:** `BARE_OS_FEATURE_LIFECYCLE_TELEMETRY_V3` (NDJSON / boot events `lifecycleSchemaVersion: 3`). **30:** `BARE_OS_FEATURE_BOOT_POLICY_V2` (extended `boot.policy.json` fields). **No further bits** are assigned on word 1 without revisiting this ADR (avoid `1 << 31` in JS without `>>> 0` discipline).
|
||||
|
||||
5. **Second capability word (`bits2`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_EXTENDED_SEEDING_PLATFORM**` and named `**BARE_OS_FEATURE2_***` constants (bits 0–31; always use `**>>> 0**` when masking). Seed JSON `**bare_os.capabilities**` and `**/proc/bare_os_features**` include `**bits2**` alongside `**bits**`. `**BARE_OS_SEED_CAP_STRICT`** may require both words when the booter advertises a non-zero second word. New guest-visible behavior on word 2 follows the same documentation rule as word 1: [`docs/reference/kernel-capabilities-index.md`](../../docs/reference/kernel-capabilities-index.md), [`docs/reference/kernel-extensions.md`](../../docs/reference/kernel-extensions.md), and relevant handbook chapters.
|
||||
5. **Second capability word (`bits2`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_EXTENDED_SEEDING_PLATFORM`** and named **`BARE_OS_FEATURE2_*`** constants (bits 0–31; always use `**>>> 0**` when masking). Seed JSON **`bare_os.capabilities`** and **`/proc/bare_os_features`** include **`bits2`** alongside **`bits`**. **`BARE_OS_SEED_CAP_STRICT`** may require both words when the booter advertises a non-zero second word. New guest-visible behavior on word 2 follows the same documentation rule as word 1: [`docs/reference/kernel-capabilities-index.md`](../../docs/reference/kernel-capabilities-index.md), [`docs/reference/kernel-extensions.md`](../../docs/reference/kernel-extensions.md), and relevant handbook chapters.
|
||||
|
||||
6. **Third capability word (`bits3`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_RLIMITS_DELEGATES_SHELL**` and `**BARE_OS_FEATURE3_***` cover rlimits proc, boot policy v3, delegate concurrency, gated shell `**local**`, host capability probe, and CI schema validation of examples. Seed JSON and `**/proc/bare_os_features**` include `**bits3**`. `**BARE_OS_SEED_CAP_STRICT**` may require `**bits3**` when the stock booter advertises a non-zero third word. Word 2 bits **19–31** remain on `**bits2`**; word 3 is additive and does not renumber prior assignments.
|
||||
6. **Third capability word (`bits3`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_RLIMITS_DELEGATES_SHELL`** and **`BARE_OS_FEATURE3_*`** cover rlimits proc, boot policy v3, delegate concurrency, gated shell **`local`**, host capability probe, and CI schema validation of examples. Seed JSON and **`/proc/bare_os_features`** include **`bits3`**. **`BARE_OS_SEED_CAP_STRICT`** may require **`bits3`** when the stock booter advertises a non-zero third word. Word 2 bits **19–31** remain on **`bits2`**; word 3 is additive and does not renumber prior assignments.
|
||||
|
||||
7. **Fourth capability word (`bits4`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_OFFLINE_NET_EXTENSIONS**` and `**BARE_OS_FEATURE4_***` cover offline LKG boot, `**/proc/bare_os/net_summary.json**`, boot policy v4, telemetry schema v4, kernel extension registry schema v2, roadmap contract tests (`**verify-kernel-capabilities-contract.mjs**`), host storage JSON in bootstrap proc, IPC audit, initd directory conditions, delegate fairness metrics, optional bare-worker `**/bin**` offload, and subprocess-bridge job surfacing. Seed JSON `**bare_os.capabilities**` and `**/proc/bare_os_features**` include `**bits4**`. `**BARE_OS_SEED_CAP_STRICT**` requires `**bits4`** to cover the stock fourth word when enabled.
|
||||
7. **Fourth capability word (`bits4`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_OFFLINE_NET_EXTENSIONS`** and **`BARE_OS_FEATURE4_*`** cover offline LKG boot, **`/proc/bare_os/net_summary.json`**, boot policy v4, telemetry schema v4, kernel extension registry schema v2, roadmap contract tests (**`verify-kernel-capabilities-contract.mjs`**), host storage JSON in bootstrap proc, IPC audit, initd directory conditions, delegate fairness metrics, optional bare-worker **`/bin`** offload, and subprocess-bridge job surfacing. Seed JSON **`bare_os.capabilities`** and **`/proc/bare_os_features`** include **`bits4`**. **`BARE_OS_SEED_CAP_STRICT`** requires **`bits4`** to cover the stock fourth word when enabled.
|
||||
|
||||
8. **Fifth capability word (`bits5`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_HOST_TRANSPORT_DELEGATES**` and `**BARE_OS_FEATURE5_***` cover host OS proc snapshot, subprocess bridge snapshot v2, transport stats in net summary, boot policy v5, replication sync windows, union readlink parity, warm kernel profile reload, HDMS hints v2, OTel JSONL schema v2, bin-worker pattern allowlists, staging rollback hints, dev debug proc, manifest risk metadata, replication queue metrics v2 on the seeder, typed seed RPC errors, and repo doc-verification scripts. Seed JSON `**bare_os.capabilities**` and `**/proc/bare_os_features**` include `**bits5**`. `**BARE_OS_SEED_CAP_STRICT**` requires `**bits5`** to cover the stock fifth word when enabled.
|
||||
8. **Fifth capability word (`bits5`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_HOST_TRANSPORT_DELEGATES`** and **`BARE_OS_FEATURE5_*`** cover host OS proc snapshot, subprocess bridge snapshot v2, transport stats in net summary, boot policy v5, replication sync windows, union readlink parity, warm kernel profile reload, HDMS hints v2, OTel JSONL schema v2, bin-worker pattern allowlists, staging rollback hints, dev debug proc, manifest risk metadata, replication queue metrics v2 on the seeder, typed seed RPC errors, and repo doc-verification scripts. Seed JSON **`bare_os.capabilities`** and **`/proc/bare_os_features`** include **`bits5`**. **`BARE_OS_SEED_CAP_STRICT`** requires **`bits5`** to cover the stock fifth word when enabled.
|
||||
|
||||
9. **Sixth capability word (`bits6`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_REPLICATION_OPERATOR_SURFACE**` and `**BARE_OS_FEATURE6_***` group extended seed RPCs (replication plan, DHT bootstrap hints, compact ping, …), advisory replication JSON v2 fields, `**/proc/bare_os/*.json**` operator metrics, boot policy v6 (`**requireKernelCapabilitiesReplicationOperatorSurface**`, `**requireBooterSemver**`, `**requireCtxApiMin**`, extension deny/hash pins, offline LKG strict integrity), kernel extension registry schema v3 with dependency edges, Pear/Bare bridge `**ctx**` hooks, strict `**/proc/bare_os**` alias completeness (`**FEATURE6_STRICT_PROC_ALIAS**` + `**BARE_OS_PROC_ALIAS_STRICT**`), VFS/POSIX/initd/timer extensions, worker/sandbox/net-policy surfaces, telemetry NDJSON v5 / OTel schema v3 / audit v3, and CI (`**verify-kernel-capabilities-word-6.mjs**`, Pear static `**node:**` import scan). Seed JSON and `**/proc/bare_os_features**` include `**bits6**`. `**BARE_OS_SEED_CAP_STRICT**` may require `**bits6`** when the stock sixth word is non-zero.
|
||||
9. **Sixth capability word (`bits6`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_REPLICATION_OPERATOR_SURFACE`** and **`BARE_OS_FEATURE6_*`** group extended seed RPCs (replication plan, DHT bootstrap hints, compact ping, …), advisory replication JSON v2 fields, **`/proc/bare_os/*.json`** operator metrics, boot policy v6 (**`requireKernelCapabilitiesReplicationOperatorSurface`**, **`requireBooterSemver`**, **`requireCtxApiMin`**, extension deny/hash pins, offline LKG strict integrity), kernel extension registry schema v3 with dependency edges, Pear/Bare bridge **`ctx`** hooks, strict **`/proc/bare_os`** alias completeness (**`FEATURE6_STRICT_PROC_ALIAS`** + **`BARE_OS_PROC_ALIAS_STRICT`**), VFS/POSIX/initd/timer extensions, worker/sandbox/net-policy surfaces, telemetry NDJSON v5 / OTel schema v3 / audit v3, and CI (**`verify-kernel-capabilities-word-6.mjs`**, Pear static **`node:`** import scan). Seed JSON and **`/proc/bare_os_features`** include **`bits6`**. **`BARE_OS_SEED_CAP_STRICT`** may require **`bits6`** when the stock sixth word is non-zero.
|
||||
|
||||
10. **Seventh capability word (`bits7`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_PEAR_CORESTORE_HRPC**` and `**BARE_OS_FEATURE7_***` add another full 32-bit word. **Word 6 bits 16–31** remain reserved for future sixth-word–scoped features; new coarse groups use `**bits7**` instead (seed RPC surface, proc JSON, boot policy v7, extension registry v4, Pear/Bare bridge stubs, VFS/env/git policy docs, initd/subprocess, worker/net, telemetry v6/OTel v4/audit v4, CI `**verify-kernel-capabilities-word-7.mjs**`). Seed JSON and `**/proc/bare_os_features**` include `**bits7**`. `**BARE_OS_SEED_CAP_STRICT**` may require `**bits7`** when the stock seventh word is non-zero.
|
||||
10. **Seventh capability word (`bits7`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_PEAR_CORESTORE_HRPC`** and **`BARE_OS_FEATURE7_*`** add another full 32-bit word. **Word 6 bits 16–31** remain reserved for future sixth-word–scoped features; new coarse groups use **`bits7`** instead (seed RPC surface, proc JSON, boot policy v7, extension registry v4, Pear/Bare bridge stubs, VFS/env/git policy docs, initd/subprocess, worker/net, telemetry v6/OTel v4/audit v4, CI **`verify-kernel-capabilities-word-7.mjs`**). Seed JSON and **`/proc/bare_os_features`** include **`bits7`**. **`BARE_OS_SEED_CAP_STRICT`** may require **`bits7`** when the stock seventh word is non-zero.
|
||||
|
||||
11. **Eighth capability word (`bits8`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_BARE_RUNTIME_PROTO_MUX**` and `**BARE_OS_FEATURE8_***` add the eighth 32-bit word. **Word 7 high bits** remain reserved for future seventh-word–scoped features; `**bits8**` carries seed RPCs, `**/proc**` JSON, boot policy v8 (`**requireKernelCapabilitiesBareRuntimeProtoMux**`, `**requireBareRuntimeMin**`, `**denySeedRpcMethods**`, `**maxProtomuxChannelNameLength**`), extension registry v5 (`**compatPearBundleId**`), Pear/Bare structured-clone / protomux alias stubs, VFS/shell/git/curl parity, initd/subprocess/resume limits, worker `**ioproc:***` / sandbox queue / delegate placeholders, HTTP/proxy/DNS/rocksdb proc hints, telemetry NDJSON v7 / OTel v5 / audit v5, and CI `**verify-kernel-capabilities-word-8.mjs**`. Seed JSON and `**/proc/bare_os_features**` include `**bits8**`. `**BARE_OS_SEED_CAP_STRICT**` requires `**bits8`** to cover the stock eighth word when it is non-zero.
|
||||
11. **Eighth capability word (`bits8`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_BARE_RUNTIME_PROTO_MUX`** and **`BARE_OS_FEATURE8_*`** add the eighth 32-bit word. **Word 7 high bits** remain reserved for future seventh-word–scoped features; **`bits8`** carries seed RPCs, **`/proc`** JSON, boot policy v8 (**`requireKernelCapabilitiesBareRuntimeProtoMux`**, **`requireBareRuntimeMin`**, **`denySeedRpcMethods`**, **`maxProtomuxChannelNameLength`**), extension registry v5 (**`compatPearBundleId`**), Pear/Bare structured-clone / protomux alias stubs, VFS/shell/git/curl parity, initd/subprocess/resume limits, worker **`ioproc:*`** / sandbox queue / delegate placeholders, HTTP/proxy/DNS/rocksdb proc hints, telemetry NDJSON v7 / OTel v5 / audit v5, and CI **`verify-kernel-capabilities-word-8.mjs`**. Seed JSON and **`/proc/bare_os_features`** include **`bits8`**. **`BARE_OS_SEED_CAP_STRICT`** requires **`bits8`** to cover the stock eighth word when it is non-zero.
|
||||
|
||||
12. **Ninth capability word (`bits9`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_BARE_MODULE_CRYPTO_STAGING**` and `**BARE_OS_FEATURE9_***` add the ninth 32-bit word. **Word 8 high bits** remain reserved for future eighth-word–scoped features; `**bits9**` carries Holepunch-aligned seed RPCs, `**/proc**` (bare-module, bare-crypto, pear-stage, …), boot policy v9 (`**requireKernelCapabilitiesBareModuleCryptoStaging**`, `**requirePearRuntimeRange**`, `**requireBareCryptoMin**`, `**denyBareModuleSpecifierPatterns**`, …), extension registry schema 6 surface, Pear/Bare bridge `**ctx**`, worker `**mediaproc:***`, telemetry NDJSON schema 8 / OTel schema 6 / audit schema 6, and CI `**verify-kernel-capabilities-word-9.mjs**`. Seed JSON and `**/proc/bare_os_features**` include `**bits9**`. `**BARE_OS_SEED_CAP_STRICT**` requires `**bits9`** to cover the stock ninth word when it is non-zero.
|
||||
12. **Ninth capability word (`bits9`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_BARE_MODULE_CRYPTO_STAGING`** and **`BARE_OS_FEATURE9_*`** add the ninth 32-bit word. **Word 8 high bits** remain reserved for future eighth-word–scoped features; **`bits9`** carries Holepunch-aligned seed RPCs, **`/proc`** (bare-module, bare-crypto, pear-stage, …), boot policy v9 (**`requireKernelCapabilitiesBareModuleCryptoStaging`**, **`requirePearRuntimeRange`**, **`requireBareCryptoMin`**, **`denyBareModuleSpecifierPatterns`**, …), extension registry schema 6 surface, Pear/Bare bridge **`ctx`**, worker **`mediaproc:*`**, telemetry NDJSON schema 8 / OTel schema 6 / audit schema 6, and CI **`verify-kernel-capabilities-word-9.mjs`**. Seed JSON and **`/proc/bare_os_features`** include **`bits9`**. **`BARE_OS_SEED_CAP_STRICT`** requires **`bits9`** to cover the stock ninth word when it is non-zero.
|
||||
|
||||
13. **Tenth capability word (`bits10`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_PEAR_INSPECT_LOGGER_TLS**` and `**BARE_OS_FEATURE10_***` add the tenth 32-bit word. **Word 9 high bits** remain reserved for future ninth-word–scoped features; `**bits10**` carries additional seed RPCs, replication JSON adjuncts (bundle tier, autobase-discovery hint, token bucket v4, staging schema 7, peer firewall v5, compact ping v4, ready guard v4, mirror compaction v5, blind relay v3), `**/proc**` JSON (`**bare-os-proc-pear-inspect-logger-tls.js**`), `**bare_os_proc_index**` schema **6**, boot policy v10 (`**requireKernelCapabilitiesPearInspectLoggerTls**`, `**requireBareBootMin**`, `**denyBareRpcMethodPatterns**`, `**extensionSignerPinsV3**`, `**bootPhasesRequireLifecycleMinSchema**`, …), extension registry schema **7**, Pear/Bare bridge `**ctx**`, worker `**sysproc:***`, telemetry NDJSON schema **9** / OTel **7** / audit **7**, and CI `**verify-kernel-capabilities-word-10.mjs**`. Seed JSON and `**/proc/bare_os_features**` include `**bits10**`. `**BARE_OS_SEED_CAP_STRICT**` requires `**bits10**` to cover the stock tenth word when it is non-zero (same pattern as `**bits9`**).
|
||||
13. **Tenth capability word (`bits10`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_PEAR_INSPECT_LOGGER_TLS`** and **`BARE_OS_FEATURE10_*`** add the tenth 32-bit word. **Word 9 high bits** remain reserved for future ninth-word–scoped features; **`bits10`** carries additional seed RPCs, replication JSON adjuncts (bundle tier, autobase-discovery hint, token bucket v4, staging schema 7, peer firewall v5, compact ping v4, ready guard v4, mirror compaction v5, blind relay v3), **`/proc`** JSON (**`bare-os-proc-pear-inspect-logger-tls.js`**), **`bare_os_proc_index`** schema **6**, boot policy v10 (**`requireKernelCapabilitiesPearInspectLoggerTls`**, **`requireBareBootMin`**, **`denyBareRpcMethodPatterns`**, **`extensionSignerPinsV3`**, **`bootPhasesRequireLifecycleMinSchema`**, …), extension registry schema **7**, Pear/Bare bridge **`ctx`**, worker **`sysproc:*`**, telemetry NDJSON schema **9** / OTel **7** / audit **7**, and CI **`verify-kernel-capabilities-word-10.mjs`**. Seed JSON and **`/proc/bare_os_features`** include **`bits10`**. **`BARE_OS_SEED_CAP_STRICT`** requires **`bits10`** to cover the stock tenth word when it is non-zero (same pattern as **`bits9`**).
|
||||
|
||||
14. **Eleventh capability word (`hypercorePackHrpcLifecycle`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_HYPERCORE_PACK_HRPC_LIFECYCLE**` and `**BARE_OS_FEATURE11_***` add the eleventh 32-bit word. `**BARE_OS_KERNEL_FEATURE_BITS_DOC**` is **16** after the optional Protomux cap-channel bit (`**BARE_OS_FEATURE8_PROTOMUX_CAP_CHANNEL**`) and related proc/HRPC documentation bump (no legacy bit renumbering). This word groups protocol `**0.9.0**` (wire v2 `**kernelCapabilityWords**`), twenty seed RPC methods (replicate budget, drive graph, protomux backpressure, Pear matrix, bundle preload, … through mirror compaction v6), `**bare-os-proc-hypercore-pack-hrpc-lifecycle.js**` with twenty `**/proc/bare_os/*.json**` surfaces, `**bare_os_proc_index**` schema **7**, boot policy v11 (`**requireKernelCapabilitiesHypercorePackHrpcLifecycle**`, `**extensionSignerPinsV4**`, `**requireBarePackMin**`, `**requireBareAddonPolicyMin**`, `**maxHrpcAllowlistDepth**`, `**offlineLkgRequireHypercorePackHrpcLifecycle**`, merged `**denySeedRpcMethods**`), extension registry `**/proc**` payload schema **8**, `**ctx**` API **1.22.0** (`**bareOsAdvertisedKernelCapabilityWords**` / `**bareOsSeedKernelCapabilityWords**`), worker patterns `**cryptoproc:***` / `**indexerproc:***`, telemetry NDJSON **10** / OTel `**otlSchemaVersion` 8** / audit **8**, and CI **`verify-kernel-capabilities-word-11.mjs**`. Seed JSON and `**/proc/bare_os_features**` include `**kernelCapabilityWords.hypercorePackHrpcLifecycle**`. `**BARE_OS_SEED_CAP_STRICT`** requires that key to cover the stock eleventh word when it is non-zero.
|
||||
14. **Eleventh capability word (`hypercorePackHrpcLifecycle`)** — **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_HYPERCORE_PACK_HRPC_LIFECYCLE`** and **`BARE_OS_FEATURE11_*`** add the eleventh 32-bit word. **`BARE_OS_KERNEL_FEATURE_BITS_DOC`** is **16** after the optional Protomux cap-channel bit (**`BARE_OS_FEATURE8_PROTOMUX_CAP_CHANNEL`**) and related proc/HRPC documentation bump (no legacy bit renumbering). This word groups protocol **`0.9.0`** (wire v2 **`kernelCapabilityWords`**), twenty seed RPC methods (replicate budget, drive graph, protomux backpressure, Pear matrix, bundle preload, … through mirror compaction v6), **`bare-os-proc-hypercore-pack-hrpc-lifecycle.js`** with twenty **`/proc/bare_os/*.json`** surfaces, **`bare_os_proc_index`** schema **7**, boot policy v11 (**`requireKernelCapabilitiesHypercorePackHrpcLifecycle`**, **`extensionSignerPinsV4`**, **`requireBarePackMin`**, **`requireBareAddonPolicyMin`**, **`maxHrpcAllowlistDepth`**, **`offlineLkgRequireHypercorePackHrpcLifecycle`**, merged **`denySeedRpcMethods`**), extension registry **`/proc`** payload schema **8**, **`ctx`** API **1.22.0** (**`bareOsAdvertisedKernelCapabilityWords`** / **`bareOsSeedKernelCapabilityWords`**), worker patterns **`cryptoproc:*`** / **`indexerproc:*`**, telemetry NDJSON **10** / OTel `**otlSchemaVersion` 8** / audit **8**, and CI **`verify-kernel-capabilities-word-11.mjs`**. Seed JSON and **`/proc/bare_os_features`** include **`kernelCapabilityWords.hypercorePackHrpcLifecycle`**. **`BARE_OS_SEED_CAP_STRICT`** requires that key to cover the stock eleventh word when it is non-zero.
|
||||
|
||||
**Deprecation (unused bits):** once a bit is published in this ADR and **`kernel-capabilities-index.md**`, its numeric position is **stable**; if a feature is removed from the stock booter, the bit stays reserved (document as “unused / reserved”) until a major governance revision. `**BARE_OS_KERNEL_FEATURE_BITS_DOC`** bumps when semantics or this policy changes.
|
||||
**Deprecation (unused bits):** once a bit is published in this ADR and **`kernel-capabilities-index.md`**, its numeric position is **stable**; if a feature is removed from the stock booter, the bit stays reserved (document as “unused / reserved”) until a major governance revision. **`BARE_OS_KERNEL_FEATURE_BITS_DOC`** bumps when semantics or this policy changes.
|
||||
|
||||
## Consequences
|
||||
|
||||
- Seeder RPC `bare_os.capabilities` must return `protocolPackageVersion`, optional **`booterPackageVersion**`, `**featureBitsDoc**`, `**kernelCapabilityWireVersion**`, and `**kernelCapabilityWords`** (all eleven semantic keys; the stock seeder sends full masks today).
|
||||
- CI should keep seeder and booter copies of the stock masks aligned: **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_PRIMARY**`, `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_EXTENDED_SEEDING_PLATFORM**`, `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_RLIMITS_DELEGATES_SHELL**`, `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_OFFLINE_NET_EXTENSIONS**`, `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_HOST_TRANSPORT_DELEGATES**`, `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_REPLICATION_OPERATOR_SURFACE**`, `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_PEAR_CORESTORE_HRPC**`, `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_BARE_RUNTIME_PROTO_MUX**`, `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_BARE_MODULE_CRYPTO_STAGING**`, `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_PEAR_INSPECT_LOGGER_TLS**`, `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_HYPERCORE_PACK_HRPC_LIFECYCLE`**.
|
||||
- Seeder RPC `bare_os.capabilities` must return `protocolPackageVersion`, optional **`booterPackageVersion`**, **`featureBitsDoc`**, **`kernelCapabilityWireVersion`**, and **`kernelCapabilityWords`** (all eleven semantic keys; the stock seeder sends full masks today).
|
||||
- CI should keep seeder and booter copies of the stock masks aligned: **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_PRIMARY`**, **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_EXTENDED_SEEDING_PLATFORM`**, **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_RLIMITS_DELEGATES_SHELL`**, **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_OFFLINE_NET_EXTENSIONS`**, **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_HOST_TRANSPORT_DELEGATES`**, **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_REPLICATION_OPERATOR_SURFACE`**, **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_PEAR_CORESTORE_HRPC`**, **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_BARE_RUNTIME_PROTO_MUX`**, **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_BARE_MODULE_CRYPTO_STAGING`**, **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_PEAR_INSPECT_LOGGER_TLS`**, **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_HYPERCORE_PACK_HRPC_LIFECYCLE`**.
|
||||
|
||||
## Appendix: historical checklist tables
|
||||
|
||||
|
||||
@@ -10,9 +10,9 @@ Operators asked for a **bounded** path to validate WebAssembly modules in the sa
|
||||
|
||||
## Decision
|
||||
|
||||
- Expose **`ctx.bareOsWasmKernelCompile(buf, opts?)**` only when the host sets `**BARE_OS_WASM_KERNEL=1**` (or `**true**`), copied into session `**shellEnv`** like other passthrough keys.
|
||||
- Implementation calls **`WebAssembly.compile**` on a **size-capped** `**Uint8Array**` (default max **512 KiB**; override via `**opts.maxBytes**`). **No instantiation**, **no imports**, and **no execution** — compile-only probe suitable for static validation and export-name listing when the engine exposes `**WebAssembly.Module.exports`**.
|
||||
- Code lives in **`packages/bare-os-booter/lib/bare-os-wasm-kernel.js**` and uses `**globalThis`** only (Bare/V8).
|
||||
- Expose **`ctx.bareOsWasmKernelCompile(buf, opts?)**` only when the host sets **`BARE_OS_WASM_KERNEL=1`** (or **`true`**), copied into session **`shellEnv`** like other passthrough keys.
|
||||
- Implementation calls **`WebAssembly.compile`** on a **size-capped** **`Uint8Array`** (default max **512 KiB**; override via **`opts.maxBytes`**). **No instantiation**, **no imports**, and **no execution** — compile-only probe suitable for static validation and export-name listing when the engine exposes **`WebAssembly.Module.exports`**.
|
||||
- Code lives in **`packages/bare-os-booter/lib/bare-os-wasm-kernel.js`** and uses **`globalThis`** only (Bare/V8).
|
||||
|
||||
## Consequences
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# bare-boot vs stock `kernel/init.js` phases (alignment)
|
||||
|
||||
Holepunch **`bare-boot**` stages an application on disk and hands off to a runtime. Bare OS `**kernel/init.js**` is a **session kernel** on the system Hyperdrive: it configures the guest shell environment, merges `**boot.policy.json**`, runs `**rc.d**`, `**kernel.d**`, and `**BARE_OS_ONBOOT`** lines.
|
||||
Holepunch **`bare-boot`** stages an application on disk and hands off to a runtime. Bare OS **`kernel/init.js`** is a **session kernel** on the system Hyperdrive: it configures the guest shell environment, merges **`boot.policy.json`**, runs **`rc.d`**, **`kernel.d`**, and **`BARE_OS_ONBOOT`** lines.
|
||||
|
||||
## Rough mapping (conceptual only)
|
||||
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
|
||||
Stock `/bin/kernel-doctor`, `/bin/kernel-explain`, and related tools should emit **structured, stable** objects for operators:
|
||||
|
||||
- Prefer **JSON** with a top-level **`schema**` integer and `**kind`** string (`boot`, `vfs`, `policy`, `extension`, …).
|
||||
- Human-oriented **`message**` plus machine `**code`** (stable identifier, `SCREAMING_SNAKE` or dotted namespace).
|
||||
- Prefer **JSON** with a top-level **`schema`** integer and **`kind`** string (`boot`, `vfs`, `policy`, `extension`, …).
|
||||
- Human-oriented **`message`** plus machine **`code`** (stable identifier, `SCREAMING_SNAKE` or dotted namespace).
|
||||
- Never include **secrets** (keys, tokens, raw vault bytes); redact paths under personal drive if policy requires.
|
||||
|
||||
When adding a new diagnostic surface, update **handbook**, **users-manual** troubleshooting, and **docs/reference** proc maps.
|
||||
|
||||
@@ -28,7 +28,7 @@ Two batches of **100 items** each (200 rows total) are tracked in [feature-roadm
|
||||
Highlights shipped in-tree:
|
||||
|
||||
- **Boot**: named `bootStage` on transaction journal lines and boot checkpoints (schema **2**); `BARE_OS_BOOT_DRY_RUN`; `policyFallbackPaths` merge; `BARE_OS_BOOT_POLICY_PATH`; rollback skips via `/run/bare-os/boot-rollback.marker` + `BARE_OS_BOOT_ROLLBACK_APPLY`; `requireBootBundleSha256Hex` + `BARE_OS_BOOT_BUNDLE_DIGEST_HEX`; `BARE_OS_REQUIRE_CTX_API_MIN` / `BARE_OS_BOOT_ABI_STRICT`; `initdAdmission` → initd env hints; `# ConditionEnvironment=` / `# AssertEnvironment=` guards in `kernel.d` snippets; `bootPhases` detail on `bareOsPublishBootReady`.
|
||||
- **Booter**: `/run/bare-os/services.json` seed; optional `BARE_OS_LOADER_AUDIT` → `/run/bare-os/loader-audit.ndjson`; **`bareOsEmitKernelEvent` / `bareOsSubscribeKernelEvent**`; `**bareOsAcquireKeyHandle**` (opaque key broker sketch); `**operatorSketches`** in `/proc/bare_os/kernel_program.json` (env JSON).
|
||||
- **Booter**: `/run/bare-os/services.json` seed; optional `BARE_OS_LOADER_AUDIT` → `/run/bare-os/loader-audit.ndjson`; **`bareOsEmitKernelEvent` / `bareOsSubscribeKernelEvent**`; **`bareOsAcquireKeyHandle`** (opaque key broker sketch); **`operatorSketches`** in `/proc/bare_os/kernel_program.json` (env JSON).
|
||||
- **Binaries**: `kernel-boot-diff`, `kernel-preflight`, `kernel-triage`, `kernel-manifest-validate`, `kernel-fsck`, `kernel-home-snapshot` (VFS home-tree manifest walker; see `packages/bare-os-coreutils/src/kernel-home-snapshot.js`); `kernel/lib/bare/shell-completion.json` generated from `commands.mjs`.
|
||||
- **CI**: `verify-kernel-program-proc-schema.mjs`, `verify-kernel-program-roadmap-table.mjs`, `fuzz-boot-policy-json.mjs`, `kernel-program-release-gate.mjs`, `kernel-microbench.mjs` (multi-suite microbenches: **`syscall`** — repeated `buildBareOsSyscallsProcJson` + `JSON.stringify`; **`vfs`** — adds `warmReplicationPathClassify` for warm-cache / replication path sketches; see [scripts/README.md](../scripts/README.md)).
|
||||
|
||||
@@ -59,7 +59,7 @@ In addition to `scripts`, `id`, `dependsOn`, and `signaturePointer`, drop-ins ma
|
||||
- **`after`** — extension ids that must load before this drop-in (appended to `dependsOn`).
|
||||
- **`before`** — extension ids that must load **after** this drop-in (those ids gain a dependency on this drop-in’s `id`).
|
||||
|
||||
With **`BARE_OS_KERNEL_EXT_GRAPH=1**`, the stock kernel writes `**/run/bare-os/kernel-ext-graph.json`** after ordering (shape in [`docs/schemas/kernel-ext-graph.example.json`](../docs/schemas/kernel-ext-graph.example.json)).
|
||||
With **`BARE_OS_KERNEL_EXT_GRAPH=1`**, the stock kernel writes **`/run/bare-os/kernel-ext-graph.json`** after ordering (shape in [`docs/schemas/kernel-ext-graph.example.json`](../docs/schemas/kernel-ext-graph.example.json)).
|
||||
|
||||
## batch A traceability (summary)
|
||||
|
||||
@@ -70,7 +70,7 @@ Items **1–100** map to the first approved plan (boot graph, journal, safe mode
|
||||
|
||||
## Optional Wasm kernel bridge
|
||||
|
||||
**`ctx.bareOsWasmKernelCompile**` / `**ctx.bareOsWasmKernelInstantiate**` (see `**packages/bare-os-booter/lib/bare-os-wasm-kernel.js**`) compile or instantiate a **bounded** Wasm module when `**BARE_OS_WASM_KERNEL=1**`. The booter applies `**maxBytes**`, **memory page caps**, and a **wall-clock instantiate timeout**; syscall-shaped imports (`**bare_os_pathconf**`, `**bare_os_wall_time_ms32**`, `**bare_os_umask_get**`, optional `**bare_os_monotonic_ms**` when `**BARE_OS_WASM_KERNEL_MONOTONIC_MS**`, optional `**bare_os_hostname_peek**` when `**BARE_OS_WASM_KERNEL_HOSTNAME_IMPORT**`, optional `**bare_os_ctx_api_version_peek**` when `**BARE_OS_WASM_KERNEL_CTX_API_PEEK**`, optional `**bare_os_posix_profile_peek**` when `**BARE_OS_WASM_KERNEL_POSIX_PROFILE_PEEK**`) are only constructed when `**BARE_OS_WASM_KERNEL_SYSCALL**` is enabled and the corresponding `**ctx**` hooks exist. **Parity note:** the full `**posixXsh.namesCsv**` surface ( `**clock_gettime**`, `**nanosleep**`, socket bridge ops, …) lives on `**ctx.bareOsSyscall`** in JS — it is **not** exported into the Wasm import object because those paths are async or bridge-heavy. Wasm guests should call back into JS/host shims when they need syscall parity beyond the **sync** clock / umask / pathconf imports. Treat Wasm as **untrusted**: keep modules small, gate on env, and never pass secrets into guest linear memory without a separate review.
|
||||
**`ctx.bareOsWasmKernelCompile`** / **`ctx.bareOsWasmKernelInstantiate`** (see **`packages/bare-os-booter/lib/bare-os-wasm-kernel.js`**) compile or instantiate a **bounded** Wasm module when **`BARE_OS_WASM_KERNEL=1`**. The booter applies **`maxBytes`**, **memory page caps**, and a **wall-clock instantiate timeout**; syscall-shaped imports (**`bare_os_pathconf`**, **`bare_os_wall_time_ms32`**, **`bare_os_umask_get`**, optional **`bare_os_monotonic_ms`** when **`BARE_OS_WASM_KERNEL_MONOTONIC_MS`**, optional **`bare_os_hostname_peek`** when **`BARE_OS_WASM_KERNEL_HOSTNAME_IMPORT`**, optional **`bare_os_ctx_api_version_peek`** when **`BARE_OS_WASM_KERNEL_CTX_API_PEEK`**, optional **`bare_os_posix_profile_peek`** when **`BARE_OS_WASM_KERNEL_POSIX_PROFILE_PEEK`**) are only constructed when **`BARE_OS_WASM_KERNEL_SYSCALL`** is enabled and the corresponding **`ctx`** hooks exist. **Parity note:** the full **`posixXsh.namesCsv`** surface ( **`clock_gettime`**, **`nanosleep`**, socket bridge ops, …) lives on **`ctx.bareOsSyscall`** in JS — it is **not** exported into the Wasm import object because those paths are async or bridge-heavy. Wasm guests should call back into JS/host shims when they need syscall parity beyond the **sync** clock / umask / pathconf imports. Treat Wasm as **untrusted**: keep modules small, gate on env, and never pass secrets into guest linear memory without a separate review.
|
||||
|
||||
## See also
|
||||
|
||||
|
||||
@@ -24,7 +24,7 @@ Prefer **boot stage** / **boot step** / **capability word** language in new pros
|
||||
## `ctx` methods
|
||||
|
||||
- New APIs use **`bareOs…`** camelCase on the injected context object.
|
||||
- Canonical boot hook names: **`bareOsRegisterBootStepHook**`, `**bareOsInvokeBootStepHooks**`, `**bareOsEmitBareBootStepHint**`. Legacy `**…BootPhase…`** methods remain as thin wrappers.
|
||||
- Canonical boot hook names: **`bareOsRegisterBootStepHook`**, **`bareOsInvokeBootStepHooks`**, **`bareOsEmitBareBootStepHint`**. Legacy `**…BootPhase…`** methods remain as thin wrappers.
|
||||
|
||||
## `/proc` and wire-visible paths
|
||||
|
||||
|
||||
@@ -24,11 +24,11 @@ Merge logic accepts **both** names; first-party docs should cite canonical keys
|
||||
|
||||
## Boot ready / journal payloads
|
||||
|
||||
- `bareOsPublishBootReady` may expose both `stages` / `phases` and `bootStages` / `bootPhases` mirrors for consumers. Prefer **`stages**` / `**bootStages`** in new code.
|
||||
- `bareOsPublishBootReady` may expose both `stages` / `phases` and `bootStages` / `bootPhases` mirrors for consumers. Prefer **`stages`** / **`bootStages`** in new code.
|
||||
|
||||
## Boot trace JSON (`BARE_OS_BOOT_TRACE=json`)
|
||||
|
||||
- Schema **`bootTraceSchemaVersion**`: **2** adds canonical `**step**` alongside `**stage**` and legacy `**phase**` (mirror). Parsers should prefer `**step`**.
|
||||
- Schema **`bootTraceSchemaVersion`**: **2** adds canonical **`step`** alongside **`stage`** and legacy **`phase`** (mirror). Parsers should prefer **`step`**.
|
||||
|
||||
## CI gates
|
||||
|
||||
|
||||
@@ -19,27 +19,27 @@ See also [`docs/audit/PLACEHOLDER_BASELINE.md`](../docs/audit/PLACEHOLDER_BASELI
|
||||
|
||||
**Bundle refresh governance (maintainers):** after changing Holepunch pins or `kernel/lib/bare/manifest.json`, run `npm run gen:bare-catalog` (or `:check`), `npm run build -w bare-os-bare-libs`, `npm run bundle:kernel`, then `node scripts/verify-kernel-seeder-parity.mjs`. Optional: `npm run audit:holepunch-clones` and `node scripts/verify-holepunch-clone-drift.mjs` when local clones under `BARE_OS_HOLEPUNCH_CLONES_ROOT` track upstream. Release checklist runs `report-holepunch-lockfile-drift.mjs` and clone drift verification.
|
||||
|
||||
**`kernel/init.js` is generated:** run **`node scripts/bundle-kernel-init.mjs`** after editing `kernel/lib/boot/*.js` or `kernel/lib/init/init-main.js`. **`scripts/verify-kernel-seeder-parity.mjs**` checks that the file matches that recipe and that `**kernel/**` matches `**packages/bare-os-seeder/kernel/`** byte-for-byte.
|
||||
**`kernel/init.js` is generated:** run **`node scripts/bundle-kernel-init.mjs`** after editing `kernel/lib/boot/*.js` or `kernel/lib/init/init-main.js`. **`scripts/verify-kernel-seeder-parity.mjs`** checks that the file matches that recipe and that **`kernel/`** matches **`packages/bare-os-seeder/kernel/`** byte-for-byte.
|
||||
|
||||
---
|
||||
|
||||
Bare OS **guest** code (kernel `/boot/init.js`, `/bin` utilities running in the Pear/Bare host) must **not** rely on Node’s **`node:***` built-in specifiers. Use Holepunch `**bare-*`** packages (local clones under [holepunchto](https://github.com/holepunchto)) instead. Validate `kernel/lib/bare/manifest.json` with **`kernel-manifest-validate**`; optional per-row `**dualTarget`**: `bare-only` | `dual` | `host-delegate-only` for extension policy; import-map templates live beside `package.json` on trusted images (see [kernel-program.md](./kernel-program.md)).
|
||||
Bare OS **guest** code (kernel `/boot/init.js`, `/bin` utilities running in the Pear/Bare host) must **not** rely on Node’s **`node:*`** built-in specifiers. Use Holepunch **`bare-*`** packages (local clones under [holepunchto](https://github.com/holepunchto)) instead. Validate `kernel/lib/bare/manifest.json` with **`kernel-manifest-validate`**; optional per-row **`dualTarget`**: `bare-only` | `dual` | `host-delegate-only` for extension policy; import-map templates live beside `package.json` on trusted images (see [kernel-program.md](./kernel-program.md)).
|
||||
|
||||
- `node:crypto` — [`bare-crypto`](https://github.com/holepunchto/bare-crypto) — host sets **`BARE_OS_BARE_CRYPTO_VERSION**` for boot policy `**requireBareCryptoMin`**.
|
||||
- `node:crypto` — [`bare-crypto`](https://github.com/holepunchto/bare-crypto) — host sets **`BARE_OS_BARE_CRYPTO_VERSION`** for boot policy **`requireBareCryptoMin`**.
|
||||
- `node:module` / `createRequire` — [`bare-module`](https://github.com/holepunchto/bare-module), [`bare-module-resolve`](https://github.com/holepunchto/bare-module-resolve) — boot policy may list **`denyBareModuleSpecifierPatterns`**.
|
||||
- `node:fs` — [`bare-fs`](https://github.com/holepunchto/bare-fs) — guest uses **`ctx.vfs`** for the image.
|
||||
- `node:path` — [`bare-path`](https://github.com/holepunchto/bare-path)
|
||||
- `node:url` — [`bare-url`](https://github.com/holepunchto/bare-url)
|
||||
- `node:net` / `node:tls` — [`bare-net`](https://github.com/holepunchto/bare-net), [`bare-tls`](https://github.com/holepunchto/bare-tls), [`bare-tcp`](https://github.com/holepunchto/bare-tcp)
|
||||
- `node:http` / `node:https` — [`bare-http1`](https://github.com/holepunchto/bare-http1), [`bare-https`](https://github.com/holepunchto/bare-https); **`ctx**` may expose wrapped `**fetch`**.
|
||||
- `node:http` / `node:https` — [`bare-http1`](https://github.com/holepunchto/bare-http1), [`bare-https`](https://github.com/holepunchto/bare-https); **`ctx`** may expose wrapped **`fetch`**.
|
||||
- `node:worker_threads` — [`bare-worker`](https://github.com/holepunchto/bare-worker), [`bare-thread`](https://github.com/holepunchto/bare-thread)
|
||||
- `node:diagnostics_channel` — [`bare-diagnostics-channel`](https://github.com/holepunchto/bare-diagnostics-channel)
|
||||
- WebSockets / WS upgrade paths — [`bare-ws`](https://github.com/holepunchto/bare-ws) — pair with **`bare-http1**` / `**bare-tls`** for gateways; see handbook ch.11 / transport table in [kernel-extensions.md](../docs/reference/kernel-extensions.md).
|
||||
- Inspector-style probes (non-secret) — [`bare-inspect`](https://github.com/holepunchto/bare-inspect) — boot policy **`maxPearInspectDepth**` caps nested inspect hints merged from `**boot.policy.json`**.
|
||||
- RPC-style delegates — [`bare-rpc`](https://github.com/holepunchto/bare-rpc) — boot policy **`denyBareRpcMethodPatterns**` can deny method-class patterns before they reach guest-visible `**ctx`** probes.
|
||||
- WebSockets / WS upgrade paths — [`bare-ws`](https://github.com/holepunchto/bare-ws) — pair with **`bare-http1`** / **`bare-tls`** for gateways; see handbook ch.11 / transport table in [kernel-extensions.md](../docs/reference/kernel-extensions.md).
|
||||
- Inspector-style probes (non-secret) — [`bare-inspect`](https://github.com/holepunchto/bare-inspect) — boot policy **`maxPearInspectDepth`** caps nested inspect hints merged from **`boot.policy.json`**.
|
||||
- RPC-style delegates — [`bare-rpc`](https://github.com/holepunchto/bare-rpc) — boot policy **`denyBareRpcMethodPatterns`** can deny method-class patterns before they reach guest-visible **`ctx`** probes.
|
||||
|
||||
Stock **`/bin/openssl**` is a **stub** that points integrators at `**bare-crypto`** (see [`packages/bare-os-coreutils/src/openssl.js`](../../packages/bare-os-coreutils/src/openssl.js)).
|
||||
Stock **`/bin/openssl`** is a **stub** that points integrators at **`bare-crypto`** (see [`packages/bare-os-coreutils/src/openssl.js`](../../packages/bare-os-coreutils/src/openssl.js)).
|
||||
|
||||
See also [kernel-extensions.md](../docs/reference/kernel-extensions.md), [handbook ch.11](../handbook/11-kernel-program-and-research.md), and CI **`verify-pear-no-static-node-import.mjs`**.
|
||||
|
||||
**Word 11 (hypercore / pack / HRPC lifecycle):** stock boot policy may pin **`bare-pack**` / `**bare-addon-policy**` (and related) versions via host env keys surfaced in `**boot.policy.json` v11**; Hypercore/replication-heavy guests should prefer Holepunch **`bare-***` modules over Node `**node:***` for the same capability areas as in the table above (see `**bits11**` / `**BARE_OS_KERNEL_FEATURES_STOCK_WORD_HYPERCORE_PACK_HRPC_LIFECYCLE`** in [compatibility-matrix.md](../docs/reference/compatibility-matrix.md)).
|
||||
**Word 11 (hypercore / pack / HRPC lifecycle):** stock boot policy may pin **`bare-pack`** / **`bare-addon-policy`** (and related) versions via host env keys surfaced in `**boot.policy.json` v11**; Hypercore/replication-heavy guests should prefer Holepunch **`bare-*`** modules over Node **`node:*`** for the same capability areas as in the table above (see **`bits11`** / **`BARE_OS_KERNEL_FEATURES_STOCK_WORD_HYPERCORE_PACK_HRPC_LIFECYCLE`** in [compatibility-matrix.md](../docs/reference/compatibility-matrix.md)).
|
||||
|
||||
Reference in New Issue
Block a user