Docs updates

This commit is contained in:
Raven Scott
2026-04-04 21:41:32 -04:00
parent 346bb71ffe
commit 57ba71899b
23 changed files with 509 additions and 477 deletions
+1 -1
View File
@@ -1,6 +1,6 @@
{
"schemaVersion": 1,
"generatedAt": "2026-04-05T01:23:01.987Z",
"generatedAt": "2026-04-05T01:31:52.581Z",
"normativeManifest": "packages/bare-os-booter/lib/bare-module-manifest.json",
"buildTool": "packages/bare-os-bare-libs/build.mjs",
"bundles": [
+1
View File
@@ -52,6 +52,7 @@ This directory holds the split **file-by-file inventory** that used to live in t
- **Kernel program status tables** — [Feature roadmap status](feature-roadmap.md)
- **VFS path classes (policy sketch)** — [vfs-path-classes.md](vfs-path-classes.md)
- **Kernel security subsystems** — [kernel-security-subsystems.md](kernel-security-subsystems.md)
- **Vault / encryption threat model** — [vault-threat-model.md](vault-threat-model.md)
- **Observability contracts** — [observability-contracts.md](observability-contracts.md)
- **Kernel extensions (short index)** — [kernel-extensions-capability-specs.md](kernel-extensions-capability-specs.md)
- **Kernel extensions (generated TOC)** — [kernel-extensions-generated-toc.md](kernel-extensions-generated-toc.md)
@@ -23,7 +23,7 @@ The list below is one **bullet per variable** in the form **name — component
- `BARE_OS_NO_SPLASH` — Booter — If `1`, skip TTY splash (plain logs / non-TTY behavior unchanged)
- `BARE_OS_LOCAL_SEED` — paths — Overrides local seed path helper (`defaultLocalSeedCorestorePath`); booter does not local-boot
- `BARE_OS_SKIP_REPL` — Booter — If `1`, readline returns null — non-interactive exit
- `BARE_OS_BOOT_TRACE` — Stock kernel (`init.js`) — If `1` or `true`, log each boot phase duration on stderr as `[boot] phase: Nms`; if `json`, log `{"phase":"…","ms":n}` per phase; **`ndjson`** adds **`sessionId`** / **`ts`** (same shape as `ctx.bareOsEmitBootEvent`)
- `BARE_OS_BOOT_TRACE` — Stock kernel (bundled **`/boot/init.js`** from [`kernel/lib/init/init-main.js`](../../kernel/lib/init/init-main.js) via [`scripts/bundle-kernel-init.mjs`](../../scripts/bundle-kernel-init.mjs)) — If `1` or `true`, log each boot phase duration on stderr as `[boot] phase: Nms`; if `json`, log `{"phase":"…","ms":n}` per phase; **`ndjson`** adds **`sessionId`** / **`ts`** (same shape as `ctx.bareOsEmitBootEvent`)
- `BARE_OS_BOOT_SAFE_MODE` — Stock kernel — **`1`** / **`true`** skips **`rc.d`**, **`kernel.ext.d`**, **`onboot`** after boot policy merge.
- `BARE_OS_BOOT_TRANSACTION_JOURNAL` — Stock kernel — **`1`**, **`true`**, or **`ndjson`** appends phase records to **`/run/bare-os/boot-transaction.ndjson`** when **`ctx.vfs`** supports it.
- `BARE_OS_BOOT_CHECKPOINT` — Stock kernel — **`1`** / **`true`** writes **`/run/bare-os/boot-checkpoint.json`** after each completed boot phase.
@@ -41,7 +41,7 @@ The list below is one **bullet per variable** in the form **name — component
- `MANWIDTH``/bin/man` — Wrap width for manual text (default `72`; minimum `40`)
- `NO_COLOR``/bin/man` — If set, disable ANSI bold for section headings on a TTY
**Host → session passthrough** (booter copies into **`shellEnv`** when the host sets a non-empty value): `BARE_OS_PIPELINE_MAX_STAGES`, `BARE_OS_PIPELINE_MAX_BYTES`, `BARE_OS_PIPELINE_MAX_LINES`, `BARE_OS_SHELL_STREAMING`, `BARE_OS_SHELL_STREAMING_MULT`, `BARE_OS_SHELL_CMDSUBST`, `BARE_OS_SHELL_CMDSUBST_MAX_BYTES`, `BARE_OS_SHELL_PARAM_EXPANSION`, `BARE_OS_SHELL_PARAM_EXPANSION_V2`, `BARE_OS_SHELL_PARAM_EXPANSION_V3`, `BARE_OS_ENV_DASH_S`, `BARE_OS_VFS_WATCH_PSEUDO`, `BARE_OS_VFS_WATCH_SWARM`, `BARE_OS_SHELL_LOCAL_DECLARE`, `BARE_OS_DIAGNOSTICS_SUBSCRIBE`, `BARE_OS_AUTOPASS_INVITE_URL`, `BARE_OS_BIN_WORKER_OFFLOAD`, `BARE_OS_BIN_WORKER_ALLOW`, `BARE_OS_BOOT_PROFILE`, `BARE_OS_ONBOOT`, `BARE_OS_BOOT_STRICT`, `BARE_OS_RC_D_SKIP`, `BARE_OS_BOOT_MINIMAL`, `BARE_OS_BOOT_SKIP`, `BARE_OS_BOOT_SAFE_MODE`, `BARE_OS_BOOT_TRANSACTION_JOURNAL`, `BARE_OS_BOOT_CHECKPOINT`, `BARE_OS_BOOT_DRY_RUN`, `BARE_OS_BOOT_POLICY_PATH`, `BARE_OS_BOOT_ROLLBACK_APPLY`, `BARE_OS_BOOT_BUNDLE_DIGEST_HEX`, `BARE_OS_REQUIRE_CTX_API_MIN`, `BARE_OS_BOOT_ABI_STRICT`, `BARE_OS_LOADER_AUDIT`, `BARE_OS_DELEGATE_TRACE`, `BARE_OS_DNS_PROFILE`, `BARE_OS_BOOT_TRACE`, `BARE_OS_KERNEL_PROGRAM_PROC_JSON`, `BARE_OS_GIANT_PHASE_PROGRAM_JSON`, `BARE_OS_KERNEL_SELFTEST`, `BARE_OS_SELFTEST_FORMAT`, `BARE_OS_AUDIT`, `BARE_OS_AUDIT_JSON`, `BARE_OS_AUDIT_REDACT`, `BARE_OS_IMAGE_DIGEST`, `BARE_OS_EXEC_MAX_DEPTH`, `BARE_OS_EXEC_LINE_BUDGET_MS`, `BARE_OS_IPC_MAX_BYTES`, `BARE_OS_IPC_CHANNEL_MAX_BYTES`, `BARE_OS_IPC_RPC_TOKEN`, `BARE_OS_IPC_FANOUT`, `BARE_OS_IPC_JSON_MAX_BYTES`, `BARE_OS_IPC_NAMESPACE`, `BARE_OS_VFS_WATCH`, `BARE_OS_VFS_UNION_PREFIXES`, `BARE_OS_VFS_UNION_WRITE_DENY`, `BARE_OS_VFS_BIN_CACHE`, `BARE_OS_BOOT_ALLOWLIST`, `BARE_OS_BOOT_MANIFEST`, `BARE_OS_BOOT_MANIFEST_SIGN`, `BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`, `BARE_OS_BOOT_POLICY`, `BARE_OS_BOOT_POLICY_STRICT`, `BARE_OS_LAZY_PERSONAL_DRIVE`, `BARE_OS_SYSTEM_REVISION_ID`, `BARE_OS_SYSTEM_REVISION_PENDING`, `BARE_OS_SYSTEM_SLOT`, `BARE_OS_DELEGATE_ALLOW`, `BARE_OS_DELEGATE_MAX_PER_MIN`, `BARE_OS_DELEGATE_MAX_CONCURRENT`, `BARE_OS_DELEGATE_GIT_MAX_PER_MIN`, `BARE_OS_DELEGATE_CURL_MAX_PER_MIN`, `BARE_OS_DELEGATE_WGET_MAX_PER_MIN`, `BARE_OS_DELEGATE_SYSTEMCTL_MAX_PER_MIN`, `BARE_OS_DELEGATE_GIT_MAX_CONCURRENT`, `BARE_OS_DELEGATE_CURL_MAX_CONCURRENT`, `BARE_OS_DELEGATE_WGET_MAX_CONCURRENT`, `BARE_OS_DELEGATE_SYSTEMCTL_MAX_CONCURRENT`, `BARE_OS_DELEGATE_AUDIT_ONLY`, `BARE_OS_DNS_ALLOWLIST`, `BARE_OS_KERNEL_HOT_RELOAD`, `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_PROC_POLL_MS`, `BARE_OS_SEED_RPC_HANDSHAKE`, `BARE_OS_SEED_CAP_STRICT`, `BARE_OS_SEED_CAP_FAIL`, `BARE_OS_OFFLINE_LKG_BOOT`, `BARE_OS_LKG_SYSTEM_KEY_HEX`, `BARE_OS_HOST_STORAGE_JSON`, `BARE_OS_BOOT_POLICY_DENY_EXEC_LINE_BUILTINS`, `BARE_OS_BOOT_POLICY_ALLOWED_CTX_METHODS`, `BARE_OS_SUBPROCESS_BRIDGE_JOBS_JSON`, `BARE_OS_IPC_AUDIT`, `BARE_OS_HTTP_ALLOWLIST`, `BARE_OS_HTTP_DENYLIST`, `BARE_OS_TLS_PIN_SHA256`, `BARE_OS_BARE_MODULES`, `BARE_OS_BARE_DRIVE_BUNDLES`, `BARE_OS_PEAR_CHANNEL`, `BARE_OS_PEAR_RELEASE`, `PEAR_CHANNEL`, `BARE_OS_FIND_EXEC_MAX`, `BARE_OS_YES_MAX_LINES`, `BARE_OS_SHUF_MAX_LINES`, `BARE_OS_SPLIT_MAX_FILES`, `BARE_OS_NPROC`, `BARE_OS_BLIND_BOOTSTRAP_URL`, `BARE_OS_BLIND_BOOTSTRAP_JSON`, `BARE_OS_MIRROR_READ_KEY`, `BARE_OS_PEAR_TRUST_JSON`, `BARE_OS_HOST_BUNDLE_EVALUATE`, **`TERM`**, **`COLORTERM`**.
**Host → session passthrough** (booter copies into **`shellEnv`** when the host sets a non-empty value; canonical list in [`packages/bare-os-booter/index.js`](../../packages/bare-os-booter/index.js)): `BARE_OS_PIPELINE_MAX_STAGES`, `BARE_OS_PIPELINE_MAX_BYTES`, `BARE_OS_PIPELINE_MAX_LINES`, `BARE_OS_SHELL_STREAMING`, `BARE_OS_SHELL_STREAMING_MULT`, `BARE_OS_SHELL_CMDSUBST`, `BARE_OS_SHELL_CMDSUBST_MAX_BYTES`, `BARE_OS_SHELL_PARAM_EXPANSION`, `BARE_OS_SHELL_PARAM_EXPANSION_V2`, `BARE_OS_SHELL_PARAM_EXPANSION_V3`, `BARE_OS_ENV_DASH_S`, `BARE_OS_VFS_WATCH_PSEUDO`, `BARE_OS_VFS_WATCH_SWARM`, `BARE_OS_SHELL_LOCAL_DECLARE`, `BARE_OS_DIAGNOSTICS_SUBSCRIBE`, `BARE_OS_AUTOPASS_INVITE_URL`, `BARE_OS_BIN_WORKER_OFFLOAD`, `BARE_OS_BIN_WORKER_ALLOW`, `BARE_OS_BIN_WORKER_CPU_MS_MAX`, `BARE_OS_BOOT_PROFILE`, `BARE_OS_ONBOOT`, `BARE_OS_BOOT_STRICT`, `BARE_OS_RC_D_SKIP`, `BARE_OS_BOOT_MINIMAL`, `BARE_OS_BOOT_SKIP`, `BARE_OS_BOOT_SAFE_MODE`, `BARE_OS_BOOT_TRANSACTION_JOURNAL`, `BARE_OS_BOOT_CHECKPOINT`, `BARE_OS_BOOT_DRY_RUN`, `BARE_OS_BOOT_POLICY_PATH`, `BARE_OS_BOOT_ROLLBACK_APPLY`, `BARE_OS_BOOT_BUNDLE_DIGEST_HEX`, `BARE_OS_REQUIRE_CTX_API_MIN`, `BARE_OS_BOOT_ABI_STRICT`, `BARE_OS_LOADER_AUDIT`, `BARE_OS_DELEGATE_TRACE`, `BARE_OS_DNS_PROFILE`, `BARE_OS_BOOT_TRACE`, `BARE_OS_KERNEL_PROGRAM_PROC_JSON`, `BARE_OS_GIANT_PHASE_PROGRAM_JSON`, `BARE_OS_KERNEL_SELFTEST`, `BARE_OS_SELFTEST_FORMAT`, `BARE_OS_AUDIT`, `BARE_OS_AUDIT_JSON`, `BARE_OS_AUDIT_REDACT`, `BARE_OS_IMAGE_DIGEST`, `BARE_OS_EXEC_MAX_DEPTH`, `BARE_OS_EXEC_LINE_BUDGET_MS`, `BARE_OS_IPC_MAX_BYTES`, `BARE_OS_IPC_CHANNEL_MAX_BYTES`, `BARE_OS_IPC_RPC_TOKEN`, `BARE_OS_IPC_FANOUT`, `BARE_OS_IPC_JSON_MAX_BYTES`, `BARE_OS_IPC_NAMESPACE`, `BARE_OS_VFS_WATCH`, `BARE_OS_VFS_UNION_PREFIXES`, `BARE_OS_VFS_UNION_WRITE_DENY`, `BARE_OS_VFS_HYPERBLOBS_DEDUP`, `BARE_OS_VFS_BIN_CACHE`, `BARE_OS_BOOT_ALLOWLIST`, `BARE_OS_BOOT_MANIFEST`, `BARE_OS_BOOT_MANIFEST_SIGN`, `BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`, `BARE_OS_BOOT_POLICY`, `BARE_OS_BOOT_POLICY_STRICT`, `BARE_OS_LAZY_PERSONAL_DRIVE`, `BARE_OS_SYSTEM_REVISION_ID`, `BARE_OS_SYSTEM_REVISION_PENDING`, `BARE_OS_SYSTEM_SLOT`, `BARE_OS_DELEGATE_ALLOW`, `BARE_OS_DELEGATE_MAX_PER_MIN`, `BARE_OS_DELEGATE_MAX_CONCURRENT`, `BARE_OS_DELEGATE_GIT_MAX_PER_MIN`, `BARE_OS_DELEGATE_CURL_MAX_PER_MIN`, `BARE_OS_DELEGATE_WGET_MAX_PER_MIN`, `BARE_OS_DELEGATE_SYSTEMCTL_MAX_PER_MIN`, `BARE_OS_DELEGATE_GIT_MAX_CONCURRENT`, `BARE_OS_DELEGATE_CURL_MAX_CONCURRENT`, `BARE_OS_DELEGATE_WGET_MAX_CONCURRENT`, `BARE_OS_DELEGATE_SYSTEMCTL_MAX_CONCURRENT`, `BARE_OS_DELEGATE_AUDIT_ONLY`, `BARE_OS_DNS_ALLOWLIST`, `BARE_OS_KERNEL_HOT_RELOAD`, `BARE_OS_KERNEL_EXT_D_HOT_RELOAD`, `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_PROC_POLL_MS`, `BARE_OS_TIMER_EVERY_MS_MONOTONIC`, `BARE_OS_TRACE_ID`, `BARE_OS_SEED_RPC_HANDSHAKE`, `BARE_OS_SEED_CAP_STRICT`, `BARE_OS_SEED_CAP_FAIL`, `BARE_OS_OFFLINE_LKG_BOOT`, `BARE_OS_LKG_SYSTEM_KEY_HEX`, `BARE_OS_HOST_STORAGE_JSON`, `BARE_OS_BOOT_POLICY_DENY_EXEC_LINE_BUILTINS`, `BARE_OS_BOOT_POLICY_ALLOWED_CTX_METHODS`, `BARE_OS_SUBPROCESS_BRIDGE_JOBS_JSON`, `BARE_OS_IPC_AUDIT`, `BARE_OS_HTTP_ALLOWLIST`, `BARE_OS_HTTP_DENYLIST`, `BARE_OS_TLS_PIN_SHA256`, `BARE_OS_BARE_MODULES`, `BARE_OS_BARE_DRIVE_BUNDLES`, `BARE_OS_PEAR_CHANNEL`, `BARE_OS_PEAR_RELEASE`, `PEAR_CHANNEL`, `BARE_OS_FIND_EXEC_MAX`, `BARE_OS_XARGS_MAX_PROCS`, `BARE_OS_YES_MAX_LINES`, `BARE_OS_SHUF_MAX_LINES`, `BARE_OS_SPLIT_MAX_FILES`, `BARE_OS_NPROC`, `BARE_OS_BLIND_BOOTSTRAP_URL`, `BARE_OS_BLIND_BOOTSTRAP_JSON`, `BARE_OS_MIRROR_READ_KEY`, `BARE_OS_PEER_FIREWALL_E2E_JSON`, `BARE_OS_PEAR_SECURE_ENCLAVE_JSON`, `BARE_OS_ACCOUNT_KEY_ROTATION_STATE_JSON`, `BARE_OS_PEAR_TRUST_JSON`, `BARE_OS_HOST_BUNDLE_EVALUATE`, **`TERM`**, **`COLORTERM`**. *(Many additional operator JSON pointers and version pins are also copied from the same loop; see source.)*
- `BARE_OS_VFS_UNION_PREFIXES` — Booter / VFS — Comma-separated logical path prefixes where **`readFile`** may union system + overlay sources.
- `BARE_OS_VFS_UNION_WRITE_DENY` — Booter / VFS — When **`1`** / **`true`**, block **`writeFile`** / **`unlink`** on paths under union read prefixes (read-only union overlay).
@@ -59,12 +59,20 @@ The list below is one **bullet per variable** in the form **name — component
- `BARE_OS_DELEGATE_ALLOW` — Host delegates — Comma list **`git`**, **`curl`**, **`wget`**, **`systemctl`** — empty = all allowed.
- `BARE_OS_DNS_ALLOWLIST` — curl / wget — Optional host allowlist for http(s) URLs (`*.example.com` suffix form supported).
- `BARE_OS_KERNEL_HOT_RELOAD` — Booter — Dev: allow **`ctx.bareOsRequestKernelReload()`** to re-read **`/boot/init.js`**.
- `BARE_OS_KERNEL_EXT_D_HOT_RELOAD` — Stock kernel — When **`1`** / **`true`**, after boot the kernel exposes **`ctx.bareOsReloadKernelExtDropinsSafe()`**, which re-scans **`/etc/bare-os/kernel.ext.d`** and runs only extension scripts not yet recorded (**append-only**; does not unload). When **`ctx.vfs.writeFile`** exists, each reload appends **`kernelExtReloadSchemaVersion`** lines to **`/run/bare-os/kernel-ext-reload.ndjson`**.
- `BARE_OS_VFS_HYPERBLOBS_DEDUP` — Booter / features proc — When **`1`** / **`true`**, surfaces an operator hint under **`/proc/bare_os/features`** that host mirror / hyperblob pipelines may use content-defined chunking; the guest VFS does not enable hyperblobs by itself.
- `BARE_OS_XARGS_MAX_PROCS`**`/bin/xargs`** — Raises the cap for **`-P`** parallelism (still bounded by a hard maximum of **32** and by delegate concurrency when **`runBinCommand`** uses workers); default effective cap **8** when unset.
- `BARE_OS_PEER_FIREWALL_E2E_JSON` — Booter / replication proc — Optional operator JSON merged into **`/proc/bare_os/replication`** for peer-firewall end-to-end checks (**invalid JSON yields an error object** in proc).
- `BARE_OS_PEAR_SECURE_ENCLAVE_JSON` — Booter / security posture — Non-secret JSON pointer for optional Pear secure-enclave key storage hints; treat as opaque unless host policy attests hardware backing (see [vault threat model](vault-threat-model.md)).
- `BARE_OS_ACCOUNT_KEY_ROTATION_STATE_JSON` — Booter / security posture — Non-secret JSON for signing continuity across overlapping trust windows during account key rotation (not private keys).
- `BARE_OS_TIMER_EVERY_MS_MONOTONIC` — bare-cron / timers — When **`1`** / **`true`**, **`EveryMs=`** timer units may use monotonic scheduling where supported.
- `BARE_OS_TRACE_ID` — Booter / telemetry — Optional correlation id mirrored into telemetry NDJSON lines when set.
- `BARE_OS_IPC_NAMESPACE` — VFS / mkfifo / initd — Prefix simulated FIFO keys as **`<ns>__<name>`** while logical paths stay **`/run/bare-os/ipc/<name>`**.
- `BARE_OS_SANDBOX_SCRIPT``ctx.bareOsSandboxRunScript` — Set **`0`** / **`false`** to disable sandbox script helper.
- `BARE_OS_SANDBOX_WORKER` — Booter — When **`1`**, defers **`bareOsSandboxRunScript`** on a **fresh microtask** (async boundary); **not** a separate thread or isolate.
- `BARE_OS_INITD_MAX_PARALLEL` — bare-initd — Max concurrent unit **starts** per DAG level (integer ≥ **1**; default **1**).
- `BARE_OS_INITD_JOURNAL_MAX_LINES` — bare-initd / unit journals — Cap lines retained per unit NDJSON journal under **`/run/bare-os/unit-journal/`**.
- `BARE_OS_TELEMETRY_NDJSON` — Booter — Absolute or **`~/…`** path in the **guest VFS**: append capped NDJSON telemetry records (**`telemetrySchemaVersion` / `lifecycleSchemaVersion`**: **5** (stock Capability word 6+), **`ts`**, …) mirroring structured boot/kernel events.
- `BARE_OS_TELEMETRY_NDJSON` — Booter — Absolute or **`~/…`** path in the **guest VFS**: append capped NDJSON telemetry records (**`telemetrySchemaVersion` / `lifecycleSchemaVersion`** follow stock **`BARE_OS_LIFECYCLE_SCHEMA_VERSION`**, currently **10** in the tree; **`ts`**, …) mirroring structured boot/kernel events.
- `BARE_OS_TELEMETRY_OTEL_JSONL` — Booter / var-log — Guest VFS path for OTLP-inspired JSON lines (var-log mirrors).
- `BARE_OS_PROC_POLL_MS` — VFS — Coalescing interval for **`/proc/bare_os/metrics_live.json`** and poll cadence for related pseudo metrics reads (25060000).
- `BARE_OS_SHELL_PARAM_EXPANSION` — Shell — When **`1`**, enable **`${VAR:-word}`** and **`${VAR#prefix}`** in **`expandWord`**.
@@ -76,7 +84,8 @@ The list below is one **bullet per variable** in the form **name — component
- `BARE_OS_SHELL_LOCAL_DECLARE` — Shell — When **`1`**, **`local`** and read-only **`declare -r`** apply per shell line (shallow **`vfs.env`** copy).
- `BARE_OS_DIAGNOSTICS_SUBSCRIBE` — Booter — When **`1`**, **`ctx.bareOsDiagnosticsSubscribe`** receives structured booter events.
- `BARE_OS_AUTOPASS_INVITE_URL``/proc/bare_os/hdms_hints.json` — Optional operator invite URL hint (guest does not fetch it).
- `BARE_OS_BIN_WORKER_OFFLOAD`**`runBinCommand`** (Bare) — When **`1`** on **Bare** (not Node), may run **`awk`** / **`sed`** / **`jq`** in a **`bare-worker`** thread; falls back in-process on failure. With **`BARE_OS_BIN_WORKER_ALLOW`** (comma list) for future expansion.
- `BARE_OS_BIN_WORKER_OFFLOAD`**`runBinCommand`** (Bare) — When **`1`** on **Bare** (not Node), may run **`awk`** / **`sed`** / **`jq`** in a **`bare-worker`** thread; falls back in-process on failure. With **`BARE_OS_BIN_WORKER_ALLOW`** (comma list) for future expansion (**`textproc:*`**, **`mathproc:*`**, **`mediaproc:*`**, **`sysproc:*`**, **`metaproc:*`**, … — see [kernel-extensions.md](kernel-extensions.md)).
- `BARE_OS_BIN_WORKER_CPU_MS_MAX` — Booter — Optional per-invocation CPU-time budget hint (ms) for **`bare-worker`** **`/bin`** offload; surfaced in operator metrics / worker budget snapshots.
- `BARE_OS_EXEC_LINE_BUDGET_MS` — Booter — Reject top-level **`execLine`** when cumulative wall time exceeds budget.
- `BARE_OS_DELEGATE_MAX_PER_MIN` — Host delegates — Global per-minute cap (sliding window) on delegate invocations.
- `BARE_OS_DELEGATE_*_MAX_PER_MIN` — Host delegates — Per-kind override (**`GIT`**, **`CURL`**, **`WGET`**, **`SYSTEMCTL`**).
@@ -139,7 +148,7 @@ The list below is one **bullet per variable** in the form **name — component
- **VFS** — Two-drive unified paths; **`$HOME`** maps to the personal Hyperdrive; writable mounts under **`/mnt`** when HDMS allows. **`mkdir`/`rmdir`**, **`chmod`** (octal + symbolic subset), **`symlink`/`readlink`**, **`stat`/`lstat`**, **`rm`** recursive, **`watch()`** on Hyperdrive paths (optional host **`BARE_OS_VFS_WATCH=0`** to disable). Synthetic **`/proc`**, **`/sys`**, **`/run`**, **`/dev`** for introspection (quotas JSON, boot JSON, initd snapshot, union policy, seed handshake, virtual registry, etc.). Optional union read overlays (**`BARE_OS_VFS_UNION_PREFIXES`**) with optional write deny (**`BARE_OS_VFS_UNION_WRITE_DENY`**). Empty dirs use **`.bareos_empty`** (same idea as `git-fs-adapter`).
- **Shell** — Pipelines, **`;`**, **`&&`** / \*\*` — — `**, redirects, quoting, **`$VAR`**, **`$?`**, optional **`${VAR:-word}`** / **`${VAR#prefix}`** when **`BARE*OS_SHELL_PARAM_EXPANSION=1`**, **`jobs`** / **`fg`** / **`wait`**, optional background **`&`** segments, builtins including bounded **`if`**, **`while`**, **`for`**, **`case`** (caps **`BARE_OS_SHELL_LOOP_MAX`**, **`BARE_OS_SHELL_CASE_MAX_BRANCHES`**). Optional bounded **`$(…)`** when **`BARE_OS_SHELL_CMDSUBST=1`**; optional larger pipeline capture via **`BARE_OS_SHELL_STREAMING`** / **`BARE_OS_SHELL_STREAMING_MULT`**. Branching uses **`ctx.exitCode`**. Bounded pipeline capture (**`BARE_OS_PIPELINE*\*`**, **`ctx.bareOsRuntimeCaps`**); optional boot-snippet allowlist (**`BARE_OS_BOOT_ALLOWLIST`** + **`/etc/bare-os/boot.allow`**). No subshells or full POSIX **`sh`\*\*.
- **Ownership** — Display and permission checks use **`UID`/`GID`** and mode bits; **`chown`/`chgrp`** update **`metadata.bareOs`** on the **personal** writable tree (not a multi-user host kernel).
- **Utilities** — Tier-1 JS **`/bin`** (**~113** commands; see [§12.10](package-bare-os-coreutils-and-ci.md#1210-package-bare-os-coreutils)): text tools include **`paste`**, **`split`**, **`tac`**, **`rev`**, **`expand`**, **`unexpand`**, **`fold`**, **`fmt`**, **`comm`**, **`cmp`**, **`join`**, **`pr`**, **`yes`** (line-capped via **`BARE_OS_YES_MAX_LINES`** / **`getconf`**), **`shuf`** (capped via **`BARE_OS_SHUF_MAX_LINES`**), **`tsort`**, **`factor`**, **`expr`** (integer-focused subset), **`numfmt`** (**`--to=iec`** / **`--to=si`**). Checksums: **`md5sum`** (bundled MD5), **`sha1sum`**, **`sha256sum`**, **`sha512sum`** (Web Crypto where available), **`sum`**, **`base32`**, **`basenc`** (**`--base16`**). Files: **`truncate`**, **`unlink`**, **`install`**, **`df`** (synthetic Hyperdrive row; **`-h`** human sizes), **`sync`** (no-op), **`timeout`** (wall-clock cap; exit **124** on timeout when **`BARE_OS_FEATURE_ABORT_TIMEOUT`** is advertised). Session stubs: **`arch`**, **`groups`**, **`hostid`**, **`nproc`**, **`uptime`**, **`users`**, **`who`**. Plus earlier parity: **`man`**, **`sed`** (including **`-z`**, **`BARE_OS_SED_NULL_MAX_RECORDS`**), **`awk`**, **`grep`** (**`-r`** with **`--include`/`--exclude`/`--exclude-dir`**, **`BARE_OS_GREP_FILTER_MAX`**), **`cp`** (**`-u`/`-v`/`-p`**), **`mv`**, **`find`** (**`-regex`**, **`-exec`/`-ok`**, **`BARE_OS_FIND_EXEC_MAX`**), **`mktemp`**, **`git-pear`**, **`cksum`**, **`getconf`** (includes pipeline / cap names + **`-a`**), **`xargs`**, **`dircolors`**, **`theme`**, **`ls`**, **`uniq`**, **`realpath`**, **`base64`**, **`rm`** **`-d`**, **`stat`** **`%F`**. **`dir`** / **`vdir`** call **`ls`**. Large **`sed`/`awk`** are not byte-identical to GNU on all inputs. **`mkfifo`** → **`/run/bare-os/ipc/`**. Online help: **`/share/man/man.json`** and **`man`**.
- **Utilities** — Tier-1 JS **`/bin`** (**~113** commands; see [§12.10](package-bare-os-coreutils-and-ci.md#1210-package-bare-os-coreutils)): text tools include **`paste`**, **`split`**, **`tac`**, **`rev`**, **`expand`**, **`unexpand`**, **`fold`**, **`fmt`**, **`comm`**, **`cmp`**, **`join`**, **`pr`**, **`yes`** (line-capped via **`BARE_OS_YES_MAX_LINES`** / **`getconf`**), **`shuf`** (capped via **`BARE_OS_SHUF_MAX_LINES`**), **`tsort`**, **`factor`**, **`expr`** (integer-focused subset), **`numfmt`** (**`--to=iec`** / **`--to=si`**). Checksums: **`md5sum`** (bundled MD5), **`sha1sum`**, **`sha256sum`**, **`sha512sum`** (Web Crypto where available), **`sum`**, **`base32`**, **`basenc`** (**`--base16`**). Files: **`truncate`**, **`unlink`**, **`install`**, **`df`** (synthetic Hyperdrive row; **`-h`** human sizes), **`sync`** (no-op), **`timeout`** (wall-clock cap; exit **124** on timeout when **`BARE_OS_FEATURE_ABORT_TIMEOUT`** is advertised). Session stubs: **`arch`**, **`groups`**, **`hostid`**, **`nproc`**, **`uptime`**, **`users`**, **`who`**. Plus earlier parity: **`man`**, **`sed`** (including **`-z`**, **`BARE_OS_SED_NULL_MAX_RECORDS`**), **`awk`**, **`grep`** (**`-r`** with **`--include`/`--exclude`/`--exclude-dir`**, **`BARE_OS_GREP_FILTER_MAX`**), **`cp`** (**`-u`/`-v`/`-p`**), **`mv`**, **`find`** (**`-regex`**, **`-exec`/`-ok`**, **`BARE_OS_FIND_EXEC_MAX`**), **`mktemp`**, **`git-pear`**, **`cksum`**, **`getconf`** (static name table plus live **`vfs.env`** overrides for caps; **`-a`**), **`xargs`** (**`-P`** cap raised via **`BARE_OS_XARGS_MAX_PROCS`**, hard max **32**), **`getfacl`** / **`setfacl`** (POSIX-style ACL **view/edit** against synthetic **`/.bare_acl.json`** sidecars; see handbook ch.9), **`dircolors`**, **`theme`**, **`ls`**, **`uniq`**, **`realpath`**, **`base64`**, **`rm`** **`-d`**, **`stat`** **`%F`**. **`dir`** / **`vdir`** call **`ls`**. Large **`sed`/`awk`** are not byte-identical to GNU on all inputs. **`mkfifo`** → **`/run/bare-os/ipc/`**; optional logical process groups via **`ctx.bareOsIpc.assignProcessGroup`** / **`signalProcessGroup`** (POSIX **`setpgid`** / **`killpg`** analog for IPC routing). Machine-readable per-command POSIX hints: stock **`/etc/bare-os/posix_utilities.json`** (path echoed in **`/proc/bare_os_features`** and **`metrics_live`**). Online help: **`/share/man/man.json`** and **`man`**.
- **Process tooling note** — **`ps`** and **`kill`** operate on Bare OS synthetic process rows (`pid` 1..3 for kernel/booter/shell); they do not target host OS processes.
- **Additional utility coverage** — **`dd`** (block-copy subset) and **`logger`** (structured append to **`/var/log/messages`**) are available as Tier-1 commands.
- **Mount tooling note** — **`mount`** / **`umount`** are Hyperdrive/HDMS-backed commands for `/mnt/<label>` and are not host-kernel mount syscalls.
+2 -2
View File
@@ -705,7 +705,7 @@ Governed kernel expansion: [developer-guide/kernel-program.md](../../developer-g
## Kernel program backlog — batch B (100 items)
Second batch of the same governed program. Traceability: [developer-guide/kernel-program.md](../../developer-guide/kernel-program.md), **`/proc/bare_os/kernel_program.json`** schema **2**, `bareOsCtxApiVersion` **1.25.0**.
Second batch of the same governed program. Traceability: [developer-guide/kernel-program.md](../../developer-guide/kernel-program.md), **`/proc/bare_os/kernel_program.json`** schema **2**, `bareOsCtxApiVersion` **1.30.0**.
| # | Item | Status |
| ---: | --- | --- |
@@ -770,7 +770,7 @@ Second batch of the same governed program. Traceability: [developer-guide/kernel
| 59 | Entropy health urandom policy proc | done |
| 60 | Security ADR cross-links | done |
| 61 | Event bus bareOsEmitKernelEvent subscribe | done |
| 62 | ReadinessCommand initd subset readinessPath | done |
| 62 | ReadinessCommand initd subset + metrics_live.initdReadiness schema 2 | done |
| 63 | kernel-triage crash bundle manifest | done |
| 64 | SLO wave11_operator_slo_v2 schema bump note | done |
| 65 | Anomaly execLine spike telemetry field env | done |
+2
View File
@@ -77,6 +77,8 @@ Seed RPC **`bare_os.capabilities`** includes **`protocolPackageVersion`**, optio
- DNS — `BARE_OS_DNS_ALLOWLIST` — Host allowlist for curl/wget http(s) URLs (`*.suffix` supported)
- IPC namespace — `BARE_OS_IPC_NAMESPACE` — Prefix FIFO keys as `<ns>__<name>` for isolation
- Kernel hot reload — `BARE_OS_KERNEL_HOT_RELOAD=1` — Dev: `ctx.bareOsRequestKernelReload()` re-reads `/boot/init.js`
- Kernel **`.ext.d` incremental reload** — `BARE_OS_KERNEL_EXT_D_HOT_RELOAD=1` — After boot, `ctx.bareOsReloadKernelExtDropinsSafe()` scans `/etc/bare-os/kernel.ext.d` and runs only **new** extension scripts (append-only; no unload); optional **`/run/bare-os/kernel-ext-reload.ndjson`**
- Hyperblobs dedup hint — `BARE_OS_VFS_HYPERBLOBS_DEDUP=1` — Surfaces under `/proc/bare_os/features` for operator pipelines (guest VFS does not auto-enable chunking)
- Kernel profile warm — `BARE_OS_KERNEL_PROFILE_WARM=1` — Dev: `ctx.bareOsRequestKernelProfileReload()` re-reads `/boot/init.js` (same loop as hot reload)
- Host `bare-os` proc — `BARE_OS_HOST_BARE_OS_PROC=1`, `BARE_OS_HOST_OS_JSON``/proc/bare_os/host_os.json` snapshot
- Replication windows — `BARE_OS_REPLICATION_SYNC_WINDOWS` — UTC `HH:MM-HH:MM` ranges; `/proc/bare_os/sync_window.json`; sets `BARE_OS_REPLICATION_SYNC_WINDOW_ACTIVE`
+1
View File
@@ -9,6 +9,7 @@ These files are **read from disk by the seeder** and written into the system dri
### 9.1 [kernel/init.js](../../kernel/init.js)
- **Staged as**: `/boot/init.js`
- **Source of truth**: Hand-authored logic lives in [`kernel/lib/init/init-main.js`](../../kernel/lib/init/init-main.js) (plus [`kernel/lib/boot/`](../../kernel/lib/boot/)); the staged file is produced by [`scripts/bundle-kernel-init.mjs`](../../scripts/bundle-kernel-init.mjs). Keep [`packages/bare-os-seeder/kernel/`](../../packages/bare-os-seeder/kernel/) in byte parity after changes.
- **Contract**: Must define a top-level `async function start(ctx)` (see [kernel-runner.js](../../packages/bare-os-booter/lib/kernel-runner.js)).
- **Behavior** (see [handbook/06-kernel-and-binaries.md](../../handbook/06-kernel-and-binaries.md)):
- Prints `/etc/os-release`, optional `/etc/motd`, optional profile `rc`, `/etc/bare-os/rc`, sorted digit-prefixed `/etc/bare-os/rc.d/*`, optional `/etc/bare-os/rc.local`, then banner / issue.
+3 -1
View File
@@ -10,6 +10,8 @@ Stock booter modules under `packages/bare-os-booter/lib/`:
| `bare-os-audit-chain.js` | In-memory hash-linked audit rows; **`ctx.bareOsAuditLogAppend`**. |
| `bare-os-acl-eval.js` | Advisory **`evaluateBareOsAcl`**; **`ctx.bareOsAclEvaluate`**. |
`/proc/bare_os/security_posture.json` (**schema 3**) aggregates non-secret snapshots: account profile, active handle counts, audit chain head/length, vault rotation checkpoint path, and policy flags.
`/proc/bare_os/security_posture.json` (**schema 3**) aggregates non-secret snapshots: account profile, active handle counts, audit chain head/length, vault rotation checkpoint path, and policy flags. Host env may supply **`BARE_OS_PEAR_SECURE_ENCLAVE_JSON`** (opaque Pear enclave pointer) and **`BARE_OS_ACCOUNT_KEY_ROTATION_STATE_JSON`** (rotation continuity metadata — not secret keys); both are merged only when non-empty.
**Threat model and encryption posture:** [vault-threat-model.md](vault-threat-model.md) (encryption at rest, AEAD, operator assumptions).
**Documentation parity:** When changing any of the above APIs or proc schemas, update `handbook/04-the-booter-runtime.md`, `packages/bare-os-booter/lib/bare-os-ctx.d.ts`, `lib/bare-os-ctx-api.js`, and this file.
+2 -1
View File
@@ -2,7 +2,8 @@
Bare OS mirrors structured **boot** and **kernel** events to optional sinks:
- **Boot trace**`BARE_OS_BOOT_TRACE` (`json` / `ndjson`) from the stock kernel (`kernel/init.js`), including canonical **`stage`** plus legacy **`phase`** fields on each line.
- **Boot trace**`BARE_OS_BOOT_TRACE` (`json` / `ndjson`) from the stock bundled kernel ([`kernel/lib/init/init-main.js`](../../kernel/lib/init/init-main.js) → `/boot/init.js`), including canonical **`stage`** plus legacy **`phase`** fields on each line.
- **Kernel extension reload audit** — When `BARE_OS_KERNEL_EXT_D_HOT_RELOAD` is enabled and `ctx.bareOsReloadKernelExtDropinsSafe()` runs, append-only lines (**`kernelExtReloadSchemaVersion`**) may be written to **`/run/bare-os/kernel-ext-reload.ndjson`** (guest VFS), alongside existing **`loader-audit.ndjson`** when `BARE_OS_LOADER_AUDIT` is on.
- **Telemetry NDJSON**`BARE_OS_TELEMETRY_NDJSON` (guest path); schema **`telemetry-ndjson-record.schema.json`** (`telemetrySchemaVersion` / `lifecycleSchemaVersion`).
- **OTel-style JSONL**`BARE_OS_TELEMETRY_OTEL_JSONL`; schema **`otel-bare-os-jsonl.schema.json`**.
- **Audit stream** — host/session policy; see kernel extensions reference for env keys.
@@ -7,6 +7,7 @@ Former **DOCUMENTATION.md** §§12.1012.12. [Reference index →](README.md)
- **[packages/bare-os-coreutils/lib/commands.mjs](../../packages/bare-os-coreutils/lib/commands.mjs)** — **`COREUTILS_COMMANDS`**: authoritative sorted `/bin` names for **`build.mjs`** and the manual database builder (keeps the image and **`man`** coverage in sync).
- **[packages/bare-os-coreutils/build.mjs](../../packages/bare-os-coreutils/build.mjs)** — `export async function build()`: runs **`scripts/build-man-db.mjs`** (validates **`man/pages/*.json`**, writes **`kernel/share/man/man.json`** and the same path under **`packages/bare-os-seeder/kernel/share/man/`**); then for each command concatenates `lib/runtime.js`, optional **`preamble`** libs (**`md5sum`** → **`lib/md5.js`**, **`sed`** → **`lib/sed-engine.js`**, **`awk`** → **`lib/awk-engine.js`**, **`jq`** → **`lib/jq-engine.js`**, **`man`** → **`lib/man-render.js`**, **`ls`** / **`dircolors`** → lscolors helpers, **`edit`** / **`nano`** → **`lib/edit-*.js`** + shared TUI), then **`src/<name>.js`** (**`nano`** reuses **`src/edit.js`**); writes to **`kernel/bin/<name>`** and **`packages/bare-os-seeder/kernel/bin/<name>`**. CLI: **`node build.mjs`** when executed as main.
- **Manual pages** — Authoring: **`packages/bare-os-coreutils/man/pages/<name>.json`**; schema: **`man/schema.json`**. Optional **`examples`** (cheat.sh-style) and **`descriptionMode`**: **`preserve`** for preformatted text. **`scripts/ingest-handbook-for-man.mjs`** merges every **`handbook/*.md`** as **`man(7)`** at build time (**`man handbook`**, **`man handbook-01-introduction`**, …). Regenerate JSON stubs with **`node packages/bare-os-coreutils/scripts/seed-man-pages.mjs`**. Runtime: **`/bin/man`** reads **`/share/man/man.json`**. **Handbook:** [handbook/10-manpages-and-online-help.md](../../handbook/10-manpages-and-online-help.md).
- **POSIX utility index (optional image file)****`kernel/etc/bare-os/posix_utilities.json`** carries machine-readable per-command notes when staged; the booter echoes **`utilitiesIndexPath`** in **`/proc/bare_os_features`** and coalesced **`metrics_live`** (see handbook ch.9).
- **Commands** (sources under **`src/`**, same order as **`COREUTILS_COMMANDS`** in [`commands.mjs`](../../packages/bare-os-coreutils/lib/commands.mjs)): `arch`, `awk`, `base32`, `base64`, `basename`, `basenc`, `cat`, `chgrp`, `chmod`, `chown`, `cksum`, `clear`, `cmp`, `comm`, `cp`, `crontab`, `cut`, `date`, `df`, `dir`, `dirname`, `dircolors`, `du`, `edit`, `echo`, `env`, `exit`, `expand`, `expr`, `factor`, `false`, `find`, `fmt`, `fold`, `getconf`, `git-pear`, `grep`, `groups`, `head`, `hdms`, `help`, `hostid`, `hostname`, `id`, `install`, `join`, `jq`, `ln`, `login`, `logout`, `logname`, `ls`, `man`, `md5sum`, `mkdir`, `mkfifo`, `mktemp`, `mv`, `nano`, `nl`, `nproc`, `numfmt`, `od`, `paste`, `pathchk`, `pr`, `printenv`, `printf`, `pwd`, `readlink`, `realpath`, `rev`, `rm`, `rmdir`, `savevault`, `sed`, `seq`, `sha1sum`, `sha256sum`, `sha512sum`, `shuf`, `sleep`, `sort`, `split`, `stat`, `sum`, `sync`, `tac`, `tail`, `tee`, `test`, `theme`, `time`, `touch`, `tr`, `truncate`, `true`, `tsort`, `tty`, `uname`, `uniq`, `unlink`, `unexpand`, `uptime`, `users`, `vdir`, `wc`, `which`, `who`, `whoami`, `xargs`, `yes` (**112** built names). The interactive TTY editor is **`edit`**; **`nano`** is the same built script under **`/bin/nano`**, and the default shell maps **`nano``edit`** (see **`defaultShellAliases`** in [`shell.js`](../../packages/bare-os-booter/lib/shell.js)). Each built script begins with **`BARE_OS_BIN_API`** in the concatenated prelude; root **`pretest`** runs **[`scripts/verify-kernel-seeder-parity.mjs`](../../scripts/verify-kernel-seeder-parity.mjs)** to keep **`kernel/bin/*`** and **`packages/bare-os-seeder/kernel/bin/*`** in sync and to require that pragma on every staged binary. Scripts are plain **`async function run(ctx, argv)`** using **`ctx.vfs`**, **`ctx.drive`**, **`ctx.b4a`**, **`ctx.console`**, optional **`bareStdin(ctx)`**, optional **`ctx.runBinCommand`** — no ESM **`import`** in **`src/`** (Bare-safe **`AsyncFunction`** load). **`dir`** / **`vdir`** delegate to **`ls -C`** / **`ls -l`**. **Booter-delegated** (stubs under **`kernel/bin/`**, logic in **`packages/bare-os-booter/lib/`**): **`systemctl`**, **`journalctl`** (bare-initd control; **`bare-initctl`** alias; see [handbook/04-the-booter-runtime.md](../../handbook/04-the-booter-runtime.md)). **Narrative reference:** [handbook/09-posix-utilities-shell-and-vfs.md](../../handbook/09-posix-utilities-shell-and-vfs.md).
### 12.11 [packages/bare-os-booter/test.js](../../packages/bare-os-booter/test.js) and [test.identity.js](../../packages/bare-os-booter/test.identity.js)
+2
View File
@@ -18,3 +18,5 @@ Stock routing is implemented in `packages/bare-os-booter/lib/vfs.js` (`createVfs
**Batch / diff helpers:** `bareOsVfsBatchPut(drive, puts)` and `bareOsHyperdriveDiffCollect(drive, a, b, opts)` in the same module (used from **`ctx.bareOsVfsBatchWrite`** / **`ctx.bareOsHyperdriveDiffCollect`** in the booter).
Rule evaluation is **advisory** unless a caller enforces **`verdict`**; stock VFS routing still uses `createVfs` internals and boot policy (`denyVfsPrefixes`, …).
**ACL / xattr sidecars (utilities, not a separate path class):** advisory ACL and extended-attribute views may use synthetic JSON files such as **`/.bare_acl.json`** and **`/.bare_xattr.json`** next to the affected directory (see [handbook ch.9](../../handbook/09-posix-utilities-shell-and-vfs.md) and [`kernel/etc/bare-os/vfs-sidecar-xattr-acl.example.json`](../../kernel/etc/bare-os/vfs-sidecar-xattr-acl.example.json)).