feat(bare-os): kernel wave 3 — bits3, seed RPCs, policy, proc, CI schemas
Add third capability word (STOCK_V3) and word2 tail bits; seed RPCs snapshot_hints and peer_firewall_stats; /proc mirrors (snapshot_hints, pear_trust, rlimits, hdms_health, initd_graph) and /proc/net/udp; boot policy v3 (requireFeatureBits2/3, Pear IPC allowlist, VFS deny prefixes, initd restart cap); VFS enforcement for boot-policy path denies; delegate in-flight caps; gated shell local/declare; initd path conditions, ordered suspend/resume, OnInactiveSec timers; vfs.watch swarm/replication; validate-example-schemas.mjs + ajv in pretest; extend verify-ctx for V3; bump ctx API to 1.12.0; ADR 001, protocol, handbook, dev-guide, and reference docs; seeder/kernel parity and booter tests. Chore: Prettier table alignment in CHANGELOG and READMEs; compact bareOsRequestPearReload signature in bare-os-ctx.d.ts.
This commit is contained in:
Raven Scott
@@ -21,58 +21,60 @@ It is intentionally **not** a full Node `process` object. Think of it as the “
|
||||
|
||||
The following are set on `ctx` before the kernel starts (unless noted as overwritten later):
|
||||
|
||||
| Field | Role |
|
||||
| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **`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, **`pseudoFsPaths`**, and **`features`** (including **`jobControl`**, **`shellHereString`**, **`bootReadyPseudoFs`**, **`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. |
|
||||
| **`bareOsAdvertisedKernelBits`** / **`bareOsSeedCapabilityBits`** | Unsigned bitmasks: effective stock features (minus env-disabled bits such as crypto urandom) and last seed **`bare_os.capabilities`** **`bits`**, if any. |
|
||||
| **`bareOsSystemRevision`** | **Frozen** **`{ currentId, pendingId, slot }`** from host env (**`BARE_OS_SYSTEM_REVISION_*`**) for Pear-style OTA hints. |
|
||||
| **`bareOsRegisterSuspendHook` / `bareOsRegisterResumeHook`** | Register callbacks; **`bareOsInvokeSuspendHooks`** / **`bareOsInvokeResumeHooks`** run them (host may call around **`Bare.suspend`** / **`Bare.wakeup`**). The booter also registers **bare-initd** so units with stop/start paths run in order on suspend/resume. |
|
||||
| **`bareOsRequestKernelReload()`** | Throws **`BARE_OS_KERNEL_RELOAD`** when **`BARE_OS_KERNEL_HOT_RELOAD=1`** so the booter re-reads **`/boot/init.js`**. |
|
||||
| **`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) |
|
||||
| **`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) |
|
||||
| **`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) |
|
||||
| **`requestBooterExit(code)`** | Ends the session from `/bin/exit` or equivalent |
|
||||
| **`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). |
|
||||
| **`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: 3`** alongside **`telemetrySchemaVersion`** where applicable (see [kernel extensions](../docs/reference/kernel-extensions.md)). |
|
||||
| **`bareOsSubscribeHdmsLifecycle(fn)`** | After HDMS **`activate`** / before **`deactivate`**, run callbacks with **`{ kind, labels? }`**. |
|
||||
| **`bareOsAwaitInitdUnits(names, timeoutMs)`** | Resolves when all listed initd units are **`active`** (polls **`getBareServiceRuntime`**); returns **`false`** on timeout. |
|
||||
| **`bareOsGetResourceStatus()`** | Returns a plain object snapshot (pipeline limits, exec depth, IPC **`stats()`**, session counters, swarm peer count)—mirrors **`/proc/bare_os_resources`**. Session may include **`execLineWallMsTotal`**. |
|
||||
| **`bareOsReadProcMetricsLive()`** | Returns the same object as reading **`/proc/bare_os/metrics_live.json`** (coalesced; interval from **`BARE_OS_PROC_POLL_MS`**). |
|
||||
| **`bareOsRegisterVirtualFile(name, reader, opts?)`** | Registers **`/run/bare-os/virtual/<name>`** content; **`reader`** may be a function or **`{ read }`**; may return string or **`Uint8Array`** (sync or async). Optional **`opts`**: **`etag`**, **`mime`** (default **`text/plain`**), **`ttlMs`** (optional cache hint). Gated by runtime cap **`virtualRegisterFiles`**. |
|
||||
| **`bareOsSandboxRunScript(source, argv?, opts?)`** | Runs script source with a **restricted `ctx`** (personal-drive writes only; identity/virtual registration disabled). Respects **`raceWithAbortAndTimeout`** opts. Disable with **`BARE_OS_SANDBOX_SCRIPT=0`**. See [Chapter 9](09-security-and-trust.md). |
|
||||
| **`bareOsBootFileSha256Hex(buf)`** | **`sha256` hex for boot manifest checks** (`BARE_OS_BOOT_MANIFEST` + `/etc/bare-os/boot.manifest.json` on the stock kernel). |
|
||||
| **`bareOsRegisterBootPhaseHook(phase, fn)`** / **`bareOsInvokeBootPhaseHooks(ev)`** | Hooks around stock **`kernel/init.js`** phases; **`ev`** includes **`phase`**, **`when`** (`before` / `after`), **`label`**. **`phase`** may be `*` or `before:rc` style. |
|
||||
| **`bareOsInvalidateVirtualFile(name)`** / **`bareOsUpdateVirtualFileMeta(name, patch)`** | Virtual files under **`/run/bare-os/virtual/`**; **`patch`** may update **`etag`** / **`version`**. |
|
||||
| **`bareOsRequestPearReload(opts?)`** | **`async`** — returns **`{ requested, hint, env }`**; with **`{ persistRequest: true }`** writes **`~/.bare-os/pear-reload.request`** and may **`process.emit('bare-os:pear-reload', …)`** on Node. |
|
||||
| **`bareOsVerifyBootManifestSignature(manifestBytes, signatureBytes, publicKeyHex?)`** | Ed25519 verify helper used when **`BARE_OS_BOOT_MANIFEST_SIGN=1`**; public key from arg or **`BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`**. |
|
||||
| **`bareOsRequestMirror(opts?)`** / **`bareOsExportPersonalSnapshot(opts?)`** | **`async`** host bridges returning **`{ ok, hint }`**; on Node emit **`bare-os:mirror-request`** / **`bare-os:export-personal-snapshot`**. |
|
||||
| **`bareOsPearIpcEmit(channel, payload)`** | **`boolean`** — forwards structured **`payload`** to the host when registered (**`bare-os:pear-ipc`** on Node). Align channel names with your **[pear-ipc](https://github.com/holepunchto/pear-ipc)** consumer. |
|
||||
| **`bareOsPearIpcRequest(channel, payload, opts?)`** | **`Promise<unknown>`** — correlates **`bareOsIpcReqId`** on **`payload`**; host must **`process.emit('bare-os:pear-ipc-response', { bareOsIpcReqId, result?, error? })`** before **`opts.timeoutMs`** (default 30s). |
|
||||
| **`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. See [HTTP: curl and wget](../docs/reference/http-curl-and-wget.md). |
|
||||
| Field | Role |
|
||||
| ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **`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, **`pseudoFsPaths`**, and **`features`** (including **`jobControl`**, **`shellHereString`**, **`bootReadyPseudoFs`**, **`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. |
|
||||
| **`bareOsAdvertisedKernelBits`** / **`bareOsSeedCapabilityBits`** | Unsigned bitmasks: effective stock features (minus env-disabled bits such as crypto urandom) and last seed **`bare_os.capabilities`** **`bits`**, if any. |
|
||||
| **`bareOsAdvertisedKernelBits2`** / **`bareOsSeedCapabilityBits2`** | Second word (**`bits2`**) for the same pair (always mask with **`>>> 0`**). |
|
||||
| **`bareOsAdvertisedKernelBits3`** / **`bareOsSeedCapabilityBits3`** | Third word (**`bits3`**) when the protocol and seeder expose it. |
|
||||
| **`bareOsSystemRevision`** | **Frozen** **`{ currentId, pendingId, slot }`** from host env (**`BARE_OS_SYSTEM_REVISION_*`**) for Pear-style OTA hints. |
|
||||
| **`bareOsRegisterSuspendHook` / `bareOsRegisterResumeHook`** | Register callbacks; **`bareOsInvokeSuspendHooks`** / **`bareOsInvokeResumeHooks`** run them (host may call around **`Bare.suspend`** / **`Bare.wakeup`**). The booter also registers **bare-initd** so units with stop/start paths run in **reverse boot order** on suspend and **forward boot order** on resume, aligned with the initd DAG. |
|
||||
| **`bareOsRequestKernelReload()`** | Throws **`BARE_OS_KERNEL_RELOAD`** when **`BARE_OS_KERNEL_HOT_RELOAD=1`** so the booter re-reads **`/boot/init.js`**. |
|
||||
| **`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) |
|
||||
| **`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) |
|
||||
| **`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) |
|
||||
| **`requestBooterExit(code)`** | Ends the session from `/bin/exit` or equivalent |
|
||||
| **`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). |
|
||||
| **`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: 3`** alongside **`telemetrySchemaVersion`** where applicable (see [kernel extensions](../docs/reference/kernel-extensions.md)). |
|
||||
| **`bareOsSubscribeHdmsLifecycle(fn)`** | After HDMS **`activate`** / before **`deactivate`**, run callbacks with **`{ kind, labels? }`**. |
|
||||
| **`bareOsAwaitInitdUnits(names, timeoutMs)`** | Resolves when all listed initd units are **`active`** (polls **`getBareServiceRuntime`**); returns **`false`** on timeout. |
|
||||
| **`bareOsGetResourceStatus()`** | Returns a plain object snapshot (pipeline limits, exec depth, IPC **`stats()`**, session counters, swarm peer count)—mirrors **`/proc/bare_os_resources`**. Session may include **`execLineWallMsTotal`**. |
|
||||
| **`bareOsReadProcMetricsLive()`** | Returns the same object as reading **`/proc/bare_os/metrics_live.json`** (coalesced; interval from **`BARE_OS_PROC_POLL_MS`**). |
|
||||
| **`bareOsRegisterVirtualFile(name, reader, opts?)`** | Registers **`/run/bare-os/virtual/<name>`** content; **`reader`** may be a function or **`{ read }`**; may return string or **`Uint8Array`** (sync or async). Optional **`opts`**: **`etag`**, **`mime`** (default **`text/plain`**), **`ttlMs`** (optional cache hint). Gated by runtime cap **`virtualRegisterFiles`**. |
|
||||
| **`bareOsSandboxRunScript(source, argv?, opts?)`** | Runs script source with a **restricted `ctx`** (personal-drive writes only; identity/virtual registration disabled). Respects **`raceWithAbortAndTimeout`** opts. Disable with **`BARE_OS_SANDBOX_SCRIPT=0`**. See [Chapter 9](09-security-and-trust.md). |
|
||||
| **`bareOsBootFileSha256Hex(buf)`** | **`sha256` hex for boot manifest checks** (`BARE_OS_BOOT_MANIFEST` + `/etc/bare-os/boot.manifest.json` on the stock kernel). |
|
||||
| **`bareOsRegisterBootPhaseHook(phase, fn)`** / **`bareOsInvokeBootPhaseHooks(ev)`** | Hooks around stock **`kernel/init.js`** phases; **`ev`** includes **`phase`**, **`when`** (`before` / `after`), **`label`**. **`phase`** may be `*` or `before:rc` style. |
|
||||
| **`bareOsInvalidateVirtualFile(name)`** / **`bareOsUpdateVirtualFileMeta(name, patch)`** | Virtual files under **`/run/bare-os/virtual/`**; **`patch`** may update **`etag`** / **`version`**. |
|
||||
| **`bareOsRequestPearReload(opts?)`** | **`async`** — returns **`{ requested, hint, env }`**; with **`{ persistRequest: true }`** writes **`~/.bare-os/pear-reload.request`** and may **`process.emit('bare-os:pear-reload', …)`** on Node. |
|
||||
| **`bareOsVerifyBootManifestSignature(manifestBytes, signatureBytes, publicKeyHex?)`** | Ed25519 verify helper used when **`BARE_OS_BOOT_MANIFEST_SIGN=1`**; public key from arg or **`BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`**. |
|
||||
| **`bareOsRequestMirror(opts?)`** / **`bareOsExportPersonalSnapshot(opts?)`** | **`async`** host bridges returning **`{ ok, hint }`**; on Node emit **`bare-os:mirror-request`** / **`bare-os:export-personal-snapshot`**. |
|
||||
| **`bareOsPearIpcEmit(channel, payload)`** | **`boolean`** — forwards structured **`payload`** to the host when registered (**`bare-os:pear-ipc`** on Node). Align channel names with your **[pear-ipc](https://github.com/holepunchto/pear-ipc)** consumer. |
|
||||
| **`bareOsPearIpcRequest(channel, payload, opts?)`** | **`Promise<unknown>`** — correlates **`bareOsIpcReqId`** on **`payload`**; host must **`process.emit('bare-os:pear-ipc-response', { bareOsIpcReqId, result?, error? })`** before **`opts.timeoutMs`** (default 30s). |
|
||||
| **`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. See [HTTP: curl and wget](../docs/reference/http-curl-and-wget.md). |
|
||||
|
||||
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_*`**, **`BARE_OS_SHELL_STREAMING`**, **`BARE_OS_SHELL_STREAMING_MULT`**, **`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_VFS_WATCH`**, **`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_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.
|
||||
|
||||
@@ -96,11 +98,11 @@ 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:
|
||||
|
||||
| Field | When |
|
||||
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **`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)) |
|
||||
| Field | When |
|
||||
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **`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)) |
|
||||
|
||||
Always use the `ctx` passed into **`run`**, not a global, so pipeline stdin works.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user