Further MD Fixes
This commit is contained in:
Raven Scott
@@ -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):
|
||||
|
||||
|
||||
Reference in New Issue
Block a user