MD Formatting fixes
This commit is contained in:
Raven Scott
@@ -1,6 +1,6 @@
|
||||
# Chapter 2 — The context object (`ctx`)
|
||||
|
||||
Every in-image entrypoint—`**start(ctx)**` for the kernel or `**run(ctx, argv)**` for commands—receives a single `**ctx**` object assembled by the booter before `runKernelFromSource` or `runScriptFromSource` runs. This chapter maps the fields you can rely on, how they behave, and where they are defined in source.
|
||||
Every in-image entrypoint—**`start(ctx)`** for the kernel or **`run(ctx, argv)`** for commands—receives a single **`ctx`** object assembled by the booter before `runKernelFromSource` or `runScriptFromSource` runs. This chapter maps the fields you can rely on, how they behave, and where they are defined in source.
|
||||
|
||||
**Authoritative construction** happens in `[packages/bare-os-booter/index.js](../packages/bare-os-booter/index.js)` inside `executeKernel`, then a few fields are **replaced or augmented** when the REPL session is created (`readLine`, `console`, `execLine`, `writeScreen`).
|
||||
|
||||
@@ -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).
|
||||
|
||||
---
|
||||
|
||||
@@ -58,86 +58,86 @@ 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**`, …).
|
||||
- `**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.
|
||||
- `**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.
|
||||
- `**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).
|
||||
- `**bareOsEmitIpcAudit(ev)**` — When `**BARE_OS_IPC_AUDIT=1**`, appends a JSON line to `**audit.log**` (e.g. from `**mkfifo**`).
|
||||
- `**bareOsEvaluatePeerAdmission(peerKeyHex, meta?)**` — Returns `**{ schema: 2, verdict, … }**` using optional env gates (`**BARE_OS_PEER_DENYLIST_HEX**`, `**BARE_OS_PEER_REQUIRE_CAPS_JSON**` + `**meta.caps**`, `**BARE_OS_PEER_ALLOWLIST_HEX**`, `**BARE_OS_DHT_ADDRESS_CLASS_ALLOWLIST**` + `**meta.dhtAddressClass**`). With `**BARE_OS_PEER_ADMISSION_AUDIT_NDJSON**`, emits `**peer_admission**` on the event bus (16-hex key prefix only; optional `**BARE_OS_PEER_ADMISSION_AUDIT_RATE_MS**`). See [environment appendix](../docs/reference/environment-and-posix-appendix.md).
|
||||
- `**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**`.
|
||||
- `**bareOsRequestKernelProfileReload()**` — Throws `**BARE_OS_KERNEL_PROFILE_RELOAD**` when `**BARE_OS_KERNEL_PROFILE_WARM=1**` (same booter loop as hot reload).
|
||||
- `**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). 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
|
||||
- **`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`**, …).
|
||||
- **`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.
|
||||
- **`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.
|
||||
- **`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).
|
||||
- **`bareOsEmitIpcAudit(ev)`** — When **`BARE_OS_IPC_AUDIT=1`**, appends a JSON line to **`audit.log`** (e.g. from **`mkfifo`**).
|
||||
- **`bareOsEvaluatePeerAdmission(peerKeyHex, meta?)`** — Returns **`{ schema: 2, verdict, … }`** using optional env gates (**`BARE_OS_PEER_DENYLIST_HEX`**, **`BARE_OS_PEER_REQUIRE_CAPS_JSON`** + **`meta.caps`**, **`BARE_OS_PEER_ALLOWLIST_HEX`**, **`BARE_OS_DHT_ADDRESS_CLASS_ALLOWLIST`** + **`meta.dhtAddressClass`**). With **`BARE_OS_PEER_ADMISSION_AUDIT_NDJSON`**, emits **`peer_admission`** on the event bus (16-hex key prefix only; optional **`BARE_OS_PEER_ADMISSION_AUDIT_RATE_MS`**). See [environment appendix](../docs/reference/environment-and-posix-appendix.md).
|
||||
- **`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`**.
|
||||
- **`bareOsRequestKernelProfileReload()`** — Throws **`BARE_OS_KERNEL_PROFILE_RELOAD`** when **`BARE_OS_KERNEL_PROFILE_WARM=1`** (same booter loop as hot reload).
|
||||
- **`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). 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)
|
||||
- `**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**` 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).
|
||||
- `**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).
|
||||
- `**bareOsRegisterBootStepHook(step, fn)`** / `**bareOsInvokeBootStepHooks(ev)**` — Canonical boot hooks around stock `**kernel/init.js**` stages; `**ev**` includes `**step**` / legacy `**phase**`, `**when**` (`before` / `after`), `**label**`. The step key may be `*` or `before:rc` style. Legacy `**bareOsRegisterBootPhaseHook**` / `**bareOsInvokeBootPhaseHooks**` remain aliases.
|
||||
- `**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. 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.
|
||||
- **`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`** 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).
|
||||
- `**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).
|
||||
- `**bareOsRegisterBootStepHook(step, fn)`** / **`bareOsInvokeBootStepHooks(ev)`** — Canonical boot hooks around stock **`kernel/init.js`** stages; **`ev`** includes **`step`** / legacy **`phase`**, **`when`** (`before` / `after`), **`label`**. The step key may be `*` or `before:rc` style. Legacy **`bareOsRegisterBootPhaseHook`** / **`bareOsInvokeBootPhaseHooks`** remain aliases.
|
||||
- **`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. 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)).
|
||||
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.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**`).
|
||||
- `**ctx.console**` is session-scoped.
|
||||
- **`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`**).
|
||||
- **`ctx.console`** is session-scoped.
|
||||
|
||||
`**/run/bare-os/boot.json**` (via `**bareOsPublishBootReady**`) may include `**booterStages**` / legacy `**booterPhases**`: booter milestones (`**vfs**`, `**ctx**`, `**repl**`, `**initd**`, `**kernel_invoke**`) in addition to kernel `**stages**` / legacy `**phases**` from the stock `[kernel/init.js](../kernel/init.js)`. `**subsystems.kernel.bootStages**` (and legacy `**bootPhases**`) list `**{ label, bootStage }**` for each completed kernel boot stage, and `**subsystems.kernel.programProc**` may include `**schema: 2**`, `**programVersion: 2**`, `**bootDryRun**`.
|
||||
**`/run/bare-os/boot.json`** (via **`bareOsPublishBootReady`**) may include **`booterStages`** / legacy **`booterPhases`**: booter milestones (**`vfs`**, **`ctx`**, **`repl`**, **`initd`**, **`kernel_invoke`**) in addition to kernel **`stages`** / legacy **`phases`** from the stock `[kernel/init.js](../kernel/init.js)`. **`subsystems.kernel.bootStages`** (and legacy **`bootPhases`**) list **`{ label, bootStage }`** for each completed kernel boot stage, and **`subsystems.kernel.programProc`** may include **`schema: 2`**, **`programVersion: 2`**, **`bootDryRun`**.
|
||||
|
||||
---
|
||||
|
||||
@@ -146,19 +146,19 @@ 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)
|
||||
- `**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)`)
|
||||
- **`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.
|
||||
Always use the `ctx` passed into **`run`**, not a global, so pipeline stdin works.
|
||||
|
||||
---
|
||||
|
||||
## What is *not* on `ctx`
|
||||
|
||||
- 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**`.
|
||||
- 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`**.
|
||||
|
||||
---
|
||||
|
||||
@@ -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