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

Update Docs

Browse Source
This commit is contained in:
Raven Scott
2026-04-22 21:59:13 -04:00
parent 32446dfdef
commit 9487e24ef3
13 changed files with 41 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
developer-guide/02-the-context-object.md
+2 -2
View File
@@ -59,7 +59,7 @@ 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, `**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**`).
@@ -121,7 +121,7 @@ The following are set on `ctx` before the kernel starts (unless noted as overwri
- `**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_***`, `**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.
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)`).