Add fifth feature word (STOCK_V5 / bits5) with ADR and capability docs.
Protocol: canonical seed RPC registry (seed-rpc-methods.js), bits5 on capabilities, typed seed RPC errors, richer replication_queue and staging_slot hints. Booter: /proc host_os (bare-module on Bare, node:os on Node), sync_window, debug.json, net_summary transport stats, HDMS hints/correlation, warm profile reload, subprocess bridge snapshot helpers, boot policy v5 hooks, BARE_OS_BIN_WORKER_ALLOW pattern groups, VFS symlink/union alignment, OTel JSONL schema version 2 in var-log. Seeder: pass staging/replication hints into seed channel; mirror kernel init and boot policy example. Kernel: enforce requireFeatureBits5 / requireInitJsSha256 when configured; selftests for new proc surfaces. CI/pretest: verify-doc-links, verify-man-coverage, verify-compat-matrix; extend roadmap/ctx/dts verifiers. Add otel-bare-os-jsonl schema. Docs: Wave 5 roadmap, kernel-extensions, handbook/devguide updates; bare-module manifest tier/risk sample; bare-libs README.
This commit is contained in:
Raven Scott
@@ -4,15 +4,15 @@ Single place to compare **protocol**, **booter `ctx` API**, **feature-bit docume
|
||||
|
||||
| Artifact | Location | Current (stock) |
|
||||
| --- | --- | --- |
|
||||
| **`bareOsCtxApiVersion`** | [`packages/bare-os-booter/lib/bare-os-ctx-api.js`](../../packages/bare-os-booter/lib/bare-os-ctx-api.js) | `1.13.0` |
|
||||
| **`BARE_OS_KERNEL_FEATURE_BITS_DOC`** | [`packages/bare-os-protocol/lib/kernel-feature-bits.js`](../../packages/bare-os-protocol/lib/kernel-feature-bits.js) | `6` |
|
||||
| **Capability words** | `bare_os.capabilities` RPC + `/proc/bare_os_features` | `bits`, `bits2`, `bits3`, **`bits4`** |
|
||||
| **`bareOsCtxApiVersion`** | [`packages/bare-os-booter/lib/bare-os-ctx-api.js`](../../packages/bare-os-booter/lib/bare-os-ctx-api.js) | `1.14.0` |
|
||||
| **`BARE_OS_KERNEL_FEATURE_BITS_DOC`** | [`packages/bare-os-protocol/lib/kernel-feature-bits.js`](../../packages/bare-os-protocol/lib/kernel-feature-bits.js) | `7` |
|
||||
| **Capability words** | `bare_os.capabilities` RPC + `/proc/bare_os_features` | `bits`, `bits2`, `bits3`, **`bits4`**, **`bits5`** |
|
||||
| **Lifecycle / telemetry NDJSON** | `BARE_OS_LIFECYCLE_SCHEMA_VERSION` in [`bare-os-lifecycle-schema.js`](../../packages/bare-os-booter/lib/bare-os-lifecycle-schema.js) | `4` |
|
||||
| **Protocol package** | [`bare-os-protocol` `package.json`](../../packages/bare-os-protocol/package.json) | see workspace version |
|
||||
|
||||
## Peer assumptions
|
||||
|
||||
- **Seeder** must answer **`bare_os.capabilities`** with **`bits4`** when using a current **`bare-os-protocol`** build; older seeders omit **`bits4`** (zeros) — use **`BARE_OS_SEED_CAP_STRICT`** only when peers are upgraded.
|
||||
- **Seeder** must answer **`bare_os.capabilities`** with **`bits4`** / **`bits5`** when using a current **`bare-os-protocol`** build; older seeders omit newer words (zeros) — use **`BARE_OS_SEED_CAP_STRICT`** only when peers are upgraded.
|
||||
- **Offline LKG** booters skip the swarm peer wait when **`BARE_OS_OFFLINE_LKG_BOOT=1`** and **`BARE_OS_LKG_SYSTEM_KEY_HEX`** is set; the system drive must already contain **`/boot/init.js`** in Corestore.
|
||||
|
||||
## See also
|
||||
|
||||
@@ -62,7 +62,7 @@ Former **DOCUMENTATION.md** §14, §14a. [Reference index →](README.md)
|
||||
| `BARE_OS_DELEGATE_*_MAX_CONCURRENT` | Host delegates | Per-kind in-flight cap (**`GIT`**, **`CURL`**, **`WGET`**, **`SYSTEMCTL`**). |
|
||||
| `BARE_OS_DELEGATE_AUDIT_ONLY` | Host delegates | With **`BARE_OS_AUDIT`**, log delegate calls and skip execution (**exit 0**). |
|
||||
| `BARE_OS_SEED_RPC_HANDSHAKE` | Booter | Set **`0`** / **`false`** to skip the pre-MBR **`bare_os.capabilities`** RPC against the first peer. |
|
||||
| `BARE_OS_SEED_CAP_STRICT` | Booter | When **`1`** / **`true`**, require seeder **`bits`** / **`bits2`** / **`bits3`** / **`bits4`** to cover stock booter **`STOCK_V1`** / **`STOCK_V2`** / **`STOCK_V3`** / **`STOCK_V4`** or throw. |
|
||||
| `BARE_OS_SEED_CAP_STRICT` | Booter | When **`1`** / **`true`**, require seeder **`bits`** / **`bits2`** / **`bits3`** / **`bits4`** / **`bits5`** to cover stock booter **`STOCK_V1`** / **`STOCK_V2`** / **`STOCK_V3`** / **`STOCK_V4`** / **`STOCK_V5`** or throw. |
|
||||
| `BARE_OS_SEED_CAP_FAIL` | Booter | When **`1`** / **`true`**, rethrow after a failed handshake instead of recording the error and continuing. |
|
||||
| `BARE_OS_OFFLINE_LKG_BOOT` | Booter | With **`BARE_OS_LKG_SYSTEM_KEY_HEX`** (64 hex chars), skip swarm peer wait and open the system Hyperdrive from the local Corestore (**`/boot/init.js`** must already be replicated). |
|
||||
| `BARE_OS_LKG_SYSTEM_KEY_HEX` | Booter | 32-byte Hyperdrive public key hex for offline LKG boot. |
|
||||
|
||||
@@ -25,4 +25,29 @@ This file tracks the twenty-item “kernel super-features” plan. Items are **d
|
||||
| 19 | Audit JSON v2 | done — `auditSchemaVersion: 2` on delegate/execLine/http audit lines |
|
||||
| 20 | Documentation consolidation | done — this file + linked handbook/developer-guide updates |
|
||||
|
||||
## Wave 5 (twenty-item super-feature plan)
|
||||
|
||||
| # | Item | Status |
|
||||
|---|------|--------|
|
||||
| 1 | Fifth capability word (`bits5`) + ADR §8 | done — `BARE_OS_KERNEL_FEATURES_STOCK_V5`, strict seed check, `/proc` + RPC |
|
||||
| 2 | Seeder RPC registry (no drift) | done — [`seed-rpc-methods.js`](../../packages/bare-os-protocol/lib/seed-rpc-methods.js), typed errors |
|
||||
| 3 | Replication queue + snapshot hints | done — seeder RPC `queueDepthEstimate`, `snapshotWorkflowNote`, env `BARE_OS_SEED_*` |
|
||||
| 4 | Automated compatibility matrix | done — [`scripts/verify-compat-matrix.mjs`](../../scripts/verify-compat-matrix.mjs) |
|
||||
| 5 | Host OS probe (`bare-os`) | done — `/proc/bare_os/host_os.json`, env `BARE_OS_HOST_BARE_OS_PROC` / `BARE_OS_HOST_OS_JSON` |
|
||||
| 6 | Subprocess bridge lifecycle v2 | done — `bareOsReadSubprocessBridgeSnapshot`, `BARE_OS_SUBPROCESS_BRIDGE_META_JSON` |
|
||||
| 7 | Transport observability | done — `net_summary.json` `transport` from `BARE_OS_NET_TRANSPORT_STATS_JSON` |
|
||||
| 8 | Boot policy v5 | done — `requireFeatureBits5`, `requireInitJsSha256`, schema + kernel enforcement |
|
||||
| 9 | Scheduled replication windows | done — `BARE_OS_REPLICATION_SYNC_WINDOWS`, `/proc/bare_os/sync_window.json` |
|
||||
| 10 | VFS union readlink | done — personal overlay for `readlink` under union prefixes |
|
||||
| 11 | Kernel profile warm reload | done — `BARE_OS_KERNEL_PROFILE_WARM`, `ctx.bareOsRequestKernelProfileReload` |
|
||||
| 12 | HDMS ops hints v2 | done — `BARE_OS_HDMS_SUPPORT_CORRELATION_ID`, hints schema 2 |
|
||||
| 13 | Seed channel robustness | done — RPC missing/unknown module + method errors |
|
||||
| 14 | man(1) completeness CI | done — [`scripts/verify-man-coverage.mjs`](../../scripts/verify-man-coverage.mjs) |
|
||||
| 15 | OTel JSONL schema v2 | done — `otlSchemaVersion: 2` in OTel mirror lines |
|
||||
| 16 | Bare-worker allowlist patterns | done — `BARE_OS_BIN_WORKER_ALLOW` with `textproc:*` group |
|
||||
| 17 | A/B staging rollback hints | done — seeder `previousSlot`, `rollbackHint`, `BARE_OS_SEED_STAGING_PREVIOUS_SLOT` |
|
||||
| 18 | Dev debug proc | done — `/proc/bare_os/debug.json` when `BARE_OS_KERNEL_DEBUG=1` |
|
||||
| 19 | `ctx.bare` risk metadata | done — manifest `tier`/`risk` examples + catalog docs |
|
||||
| 20 | Documentation coherence CI | done — [`scripts/verify-doc-links.mjs`](../../scripts/verify-doc-links.mjs), pretest |
|
||||
|
||||
See also [kernel-extensions.md](kernel-extensions.md) and [package-bare-os-protocol.md](package-bare-os-protocol.md).
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Kernel capabilities index (bits, env, `/proc`, `ctx`)
|
||||
|
||||
Single map from optional **feature bits** ([`packages/bare-os-protocol/lib/kernel-feature-bits.js`](../../packages/bare-os-protocol/lib/kernel-feature-bits.js)) to operator env vars, guest **`/proc`** paths, and **`ctx`** fields. Stock booter advertises **`BARE_OS_KERNEL_FEATURES_STOCK_V1`** (word 1), **`BARE_OS_KERNEL_FEATURES_STOCK_V2`** (`bits2`), **`BARE_OS_KERNEL_FEATURES_STOCK_V3`** (`bits3`), and **`BARE_OS_KERNEL_FEATURES_STOCK_V4`** (`bits4`). Governance: [`developer-guide/adr/001-kernel-feature-bits-governance.md`](../../developer-guide/adr/001-kernel-feature-bits-governance.md).
|
||||
Single map from optional **feature bits** ([`packages/bare-os-protocol/lib/kernel-feature-bits.js`](../../packages/bare-os-protocol/lib/kernel-feature-bits.js)) to operator env vars, guest **`/proc`** paths, and **`ctx`** fields. Stock booter advertises **`BARE_OS_KERNEL_FEATURES_STOCK_V1`** (word 1), **`BARE_OS_KERNEL_FEATURES_STOCK_V2`** (`bits2`), **`BARE_OS_KERNEL_FEATURES_STOCK_V3`** (`bits3`), **`BARE_OS_KERNEL_FEATURES_STOCK_V4`** (`bits4`), and **`BARE_OS_KERNEL_FEATURES_STOCK_V5`** (`bits5`). Governance: [`developer-guide/adr/001-kernel-feature-bits-governance.md`](../../developer-guide/adr/001-kernel-feature-bits-governance.md).
|
||||
|
||||
| Bit (export) | Env / behavior | `/proc` or RPC | `ctx` / notes |
|
||||
| -------------------------------- | ----------------------------------- | ------------------------------------------------ | ----------------------------------------------------- |
|
||||
@@ -101,7 +101,28 @@ Single map from optional **feature bits** ([`packages/bare-os-protocol/lib/kerne
|
||||
| 10 `FEATURE4_BIN_WORKER_ACTIVE` | with word2 bit 6 | — | bare-worker thread path for heavy `/bin` |
|
||||
| 11 `FEATURE4_SUBPROCESS_JOB_SURFACE` | `BARE_OS_SUBPROCESS_BRIDGE_JOBS_JSON` | — | `bareOsReadSubprocessBridgeJobs` |
|
||||
|
||||
**Related `ctx` (1.13.0+):** `bareOsReadProcMetricsLive()` — parsed coalesced metrics (same as `/proc/bare_os/metrics_live.json`); **`bareOsAdvertisedKernelBits4`** / **`bareOsSeedCapabilityBits4`**; **`bareOsReadDelegateFairnessSnapshot`**, **`bareOsReadSubprocessBridgeJobs`**, **`bareOsIsCtxMethodAllowed`**, **`bareOsEmitIpcAudit`**; **`bareOsEmitBlindPeerHint`**, **`bareOsHostCapability`**; Pear IPC channel names in [`bare-os-pear-ipc-registry.js`](../../packages/bare-os-booter/lib/bare-os-pear-ipc-registry.js).
|
||||
### Word 5 (`bits5`, wave 5)
|
||||
|
||||
| Bit (export) | Env / behavior | `/proc` or RPC | `ctx` / notes |
|
||||
| --- | --- | --- | --- |
|
||||
| 0 `FEATURE5_HOST_BARE_OS_PROC` | `BARE_OS_HOST_BARE_OS_PROC`, `BARE_OS_HOST_OS_JSON` | `/proc/bare_os/host_os.json` | Holepunch **`bare-os`** snapshot when loadable |
|
||||
| 1 `FEATURE5_SUBPROCESS_BRIDGE_SNAPSHOT_V2` | `BARE_OS_SUBPROCESS_BRIDGE_META_JSON` | — | `bareOsReadSubprocessBridgeSnapshot` |
|
||||
| 2 `FEATURE5_NET_SUMMARY_TRANSPORT` | `BARE_OS_NET_TRANSPORT_STATS_JSON` | merged into `net_summary.json` `transport` | operator-injected JSON |
|
||||
| 3 `FEATURE5_BOOT_POLICY_V5` | `boot.policy.json` v5 | — | `requireFeatureBits5`, `requireInitJsSha256` |
|
||||
| 4 `FEATURE5_REPLICATION_SYNC_WINDOWS` | `BARE_OS_REPLICATION_SYNC_WINDOWS` | `/proc/bare_os/sync_window.json`, `BARE_OS_REPLICATION_SYNC_WINDOW_ACTIVE` | UTC window parser |
|
||||
| 5 `FEATURE5_VFS_UNION_READLINK` | — | — | union `readlink` checks personal overlay |
|
||||
| 6 `FEATURE5_KERNEL_PROFILE_WARM` | `BARE_OS_KERNEL_PROFILE_WARM` | — | `bareOsRequestKernelProfileReload` |
|
||||
| 7 `FEATURE5_HDMS_OPS_HINTS_V2` | `BARE_OS_HDMS_SUPPORT_CORRELATION_ID` | `/proc/bare_os/hdms_hints.json` schema 2 | non-secret support id |
|
||||
| 8 `FEATURE5_TELEMETRY_OTEL_V2` | `BARE_OS_TELEMETRY_OTEL_JSONL` | — | `otlSchemaVersion: 2` lines |
|
||||
| 9 `FEATURE5_BIN_WORKER_PATTERN_ALLOW` | `BARE_OS_BIN_WORKER_ALLOW` (`textproc:*`, …) | — | extends bare-worker eligible `/bin` |
|
||||
| 10 `FEATURE5_STAGING_ROLLBACK_HINTS` | `BARE_OS_SEED_STAGING_PREVIOUS_SLOT` (seeder) | `staging_slot` RPC + replication JSON | A/B rollback hints |
|
||||
| 11 `FEATURE5_KERNEL_DEBUG_PROC` | `BARE_OS_KERNEL_DEBUG=1` | `/proc/bare_os/debug.json` | non-secret masks only |
|
||||
| 12 `FEATURE5_BARE_MANIFEST_RISK` | — | — | manifest `risk` + catalog metadata |
|
||||
| 13 `FEATURE5_REPLICATION_QUEUE_METRICS_V2` | seeder env hints | `replication_queue` RPC | depth + snapshot workflow note |
|
||||
| 14 `FEATURE5_SEED_RPC_TYPED_ERRORS` | — | seed RPC | `bare_os.rpc_unknown_method`, etc. |
|
||||
| 15 `FEATURE5_REPO_DOC_CI` | — | — | `verify-doc-links`, `verify-man-coverage`, `verify-compat-matrix` |
|
||||
|
||||
**Related `ctx` (1.14.0+):** `bareOsReadProcMetricsLive()` — parsed coalesced metrics (same as `/proc/bare_os/metrics_live.json`); **`bareOsAdvertisedKernelBits4`** / **`bareOsSeedCapabilityBits4`** / **`bareOsAdvertisedKernelBits5`** / **`bareOsSeedCapabilityBits5`**; **`bareOsReadDelegateFairnessSnapshot`**, **`bareOsReadSubprocessBridgeJobs`**, **`bareOsReadSubprocessBridgeSnapshot`**, **`bareOsRequestKernelProfileReload`**, **`bareOsIsCtxMethodAllowed`**, **`bareOsEmitIpcAudit`**; **`bareOsEmitBlindPeerHint`**, **`bareOsHostCapability`**; Pear IPC channel names in [`bare-os-pear-ipc-registry.js`](../../packages/bare-os-booter/lib/bare-os-pear-ipc-registry.js).
|
||||
|
||||
**Handbook:** [handbook/09-posix-utilities-shell-and-vfs.md](../../handbook/09-posix-utilities-shell-and-vfs.md), [handbook/04-the-booter-runtime.md](../../handbook/04-the-booter-runtime.md).
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
This document complements the [handbook](../../handbook/09-posix-utilities-shell-and-vfs.md) with a single map of optional **booter + stock kernel** features added for richer POSIX-like behavior, protocol alignment, and operations.
|
||||
|
||||
## Governance (feature bits doc v6)
|
||||
## Governance (feature bits doc v7)
|
||||
|
||||
New capability bits are governed by [ADR 001 — Kernel feature bit governance](../../developer-guide/adr/001-kernel-feature-bits-governance.md). **`BARE_OS_KERNEL_FEATURE_BITS_DOC`** must bump when semantics change. Bits **28–30** on word 1 are assigned (see ADR). **Word 2 (`bits2`)** carries wave-2 features; always mask with **`>>> 0`**. Avoid `1 << 31` on word 1 in JS without `>>> 0` discipline.
|
||||
|
||||
@@ -12,7 +12,7 @@ New capability bits are governed by [ADR 001 — Kernel feature bit governance](
|
||||
|
||||
Runtime bits are defined in `bare-os-protocol` (`kernel-feature-bits.js`) and surfaced under `/proc/bare_os_features` and the **`/proc/bare_os/`** tree. The stock booter advertises **`BARE_OS_KERNEL_FEATURES_STOCK_V1`** and **`bits2`** from **`BARE_OS_KERNEL_FEATURES_STOCK_V2`**.
|
||||
|
||||
Seed RPC **`bare_os.capabilities`** includes **`protocolPackageVersion`**, **`featureBitsDoc`**, **`doc`**, **`bits`**, **`bits2`**, **`bits3`**, **`bits4`**, **`role`**, **`protocol`**. **`bare_os.replication_status`** returns seeder-side replication hints (manifest path count, local RAM block count). **`bare_os.replication_queue`**, **`bare_os.capability_attestation`**, and **`bare_os.mbr_layout`** are optional wave-2 RPCs. **`bare_os.manifest_hints`** returns a sample of manifest paths; **`bare_os.peer_health`** returns seeder health counters; **`bare_os.staging_slot`** returns optional A/B slot hints (seeder env `BARE_OS_SEED_STAGING_SLOT`, `BARE_OS_SEED_STAGING_PENDING`). Booter mirrors hints under **`/proc/bare_os/manifest_hints`**, **`peer_health`**, **`staging_slot`**, **`net_summary.json`**, **`extensions.json`**, **`hdms_hints.json`** and embeds them in **`/proc/bare_os_replication`** JSON.
|
||||
Seed RPC **`bare_os.capabilities`** includes **`protocolPackageVersion`**, **`featureBitsDoc`**, **`doc`**, **`bits`**, **`bits2`**, **`bits3`**, **`bits4`**, **`bits5`**, **`role`**, **`protocol`**. RPC method names are listed from a single registry ([`seed-rpc-methods.js`](../../packages/bare-os-protocol/lib/seed-rpc-methods.js)); unknown methods return **`bare_os.rpc_unknown_method`**. **`bare_os.replication_status`** returns seeder-side replication hints (manifest path count, local RAM block count). **`bare_os.replication_queue`** includes bounded **`queueDepthEstimate`** and snapshot workflow notes; **`bare_os.capability_attestation`**, and **`bare_os.mbr_layout`** remain optional wave-2 RPCs. **`bare_os.manifest_hints`** returns a sample of manifest paths; **`bare_os.peer_health`** returns seeder health counters; **`bare_os.staging_slot`** returns optional A/B slot hints (seeder env `BARE_OS_SEED_STAGING_SLOT`, `BARE_OS_SEED_STAGING_PENDING`). Booter mirrors hints under **`/proc/bare_os/manifest_hints`**, **`peer_health`**, **`staging_slot`**, **`net_summary.json`**, **`extensions.json`**, **`hdms_hints.json`** and embeds them in **`/proc/bare_os_replication`** JSON.
|
||||
|
||||
**JSON Schemas** (policy, telemetry, boot trace): [`docs/schemas/`](../schemas/) (see also [reference README](./README.md)).
|
||||
|
||||
@@ -37,11 +37,11 @@ Seed RPC **`bare_os.capabilities`** includes **`protocolPackageVersion`**, **`fe
|
||||
| VFS pseudo watch | `BARE_OS_VFS_WATCH_PSEUDO=1` | `vfs.watch` on coalesced **`/proc/bare_os/metrics_live.json`** |
|
||||
| Diagnostics | `BARE_OS_DIAGNOSTICS_SUBSCRIBE=1` | `ctx.bareOsDiagnosticsSubscribe` for structured dev events |
|
||||
| HDMS / autopass hint | `BARE_OS_AUTOPASS_INVITE_URL` | Surfaced in **`/proc/bare_os/hdms_hints.json`** (guest does not open URLs) |
|
||||
| Bin worker (reserved) | `BARE_OS_BIN_WORKER_OFFLOAD=1`, `BARE_OS_BIN_WORKER_ALLOW` | Gate for future bare-thread offload; stock path remains in-process |
|
||||
| Bin worker | `BARE_OS_BIN_WORKER_OFFLOAD=1`, `BARE_OS_BIN_WORKER_ALLOW` | Offload eligible `/bin` on Bare via `bare-worker`; allow list defaults to awk/sed/jq, or patterns like `textproc:*` (cut, tr, sort, uniq, …) |
|
||||
| Exec budget | `BARE_OS_EXEC_LINE_BUDGET_MS` | Reject top-level `execLine` when session wall time exceeds budget |
|
||||
| Delegates | `BARE_OS_DELEGATE_MAX_PER_MIN`, `BARE_OS_DELEGATE_CURL_MAX_PER_MIN`, … | Per-minute caps on host delegates (sliding minute window) |
|
||||
| Delegates | `BARE_OS_DELEGATE_AUDIT_ONLY=1` | With `BARE_OS_AUDIT=1`, log delegate invocations and skip host run (exit 0) |
|
||||
| Boot policy | `BARE_OS_BOOT_POLICY=1` | Merge `skipPhases` / `denyBootPhases` from `/etc/bare-os/boot.policy.json`; optional `minKernelFeatureMask` / `requireSeedCaps`; v2 `maxExecLineDepth`, `denyEnvKeys`, `requireProcNodes`; **v3** `requireFeatureBits2`, `requireFeatureBits3`, `allowedPearIpcChannels` → session env, `denyVfsPrefixes` (VFS deny), `maxInitdRestartsPerUnit` → `BARE_OS_INITD_RESTART_MAX_DEFAULT`; **v4** `requireFeatureBits4`, `denyExecLineBuiltins` → `BARE_OS_BOOT_POLICY_DENY_EXEC_LINE_BUILTINS`, `allowedCtxMethods` → `BARE_OS_BOOT_POLICY_ALLOWED_CTX_METHODS` |
|
||||
| Boot policy | `BARE_OS_BOOT_POLICY=1` | Merge `skipPhases` / `denyBootPhases` from `/etc/bare-os/boot.policy.json`; optional `minKernelFeatureMask` / `requireSeedCaps`; v2 `maxExecLineDepth`, `denyEnvKeys`, `requireProcNodes`; **v3** `requireFeatureBits2`, `requireFeatureBits3`, `allowedPearIpcChannels` → session env, `denyVfsPrefixes` (VFS deny), `maxInitdRestartsPerUnit` → `BARE_OS_INITD_RESTART_MAX_DEFAULT`; **v4** `requireFeatureBits4`, `denyExecLineBuiltins` → `BARE_OS_BOOT_POLICY_DENY_EXEC_LINE_BUILTINS`, `allowedCtxMethods` → `BARE_OS_BOOT_POLICY_ALLOWED_CTX_METHODS`; **v5** `requireFeatureBits5`, `requireInitJsSha256` |
|
||||
| Boot policy strict | `BARE_OS_BOOT_POLICY_STRICT=1` | Abort boot when policy checks fail |
|
||||
| Lazy personal drive | `BARE_OS_LAZY_PERSONAL_DRIVE=1` | Mount personal Hyperdrive at session setup instead of immediately after kernel fetch |
|
||||
| System revision | `BARE_OS_SYSTEM_REVISION_ID`, `BARE_OS_SYSTEM_REVISION_PENDING`, `BARE_OS_SYSTEM_SLOT` | Exposed as `ctx.bareOsSystemRevision` (Pear OTA–style hints) |
|
||||
@@ -49,8 +49,16 @@ Seed RPC **`bare_os.capabilities`** includes **`protocolPackageVersion`**, **`fe
|
||||
| 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 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` |
|
||||
| Kernel debug proc | `BARE_OS_KERNEL_DEBUG=1` | `/proc/bare_os/debug.json` (masks only, no secrets) |
|
||||
| Transport stats | `BARE_OS_NET_TRANSPORT_STATS_JSON` | JSON merged into `/proc/bare_os/net_summary.json` `transport` |
|
||||
| Subprocess bridge v2 | `BARE_OS_SUBPROCESS_BRIDGE_META_JSON` | `ctx.bareOsReadSubprocessBridgeSnapshot()` meta (`supportedSignals`, `cgroupRootHint`, …) |
|
||||
| HDMS support id | `BARE_OS_HDMS_SUPPORT_CORRELATION_ID` | Non-secret string in `/proc/bare_os/hdms_hints.json` |
|
||||
| Seeder staging | `BARE_OS_SEED_STAGING_PREVIOUS_SLOT`, `BARE_OS_SEED_REPLICATION_QUEUE_DEPTH_HINT`, `BARE_OS_SEED_REPLICATION_SNAPSHOT_NOTE_JSON` | Seeder-only env for richer RPC payloads |
|
||||
| Sandbox | `BARE_OS_SANDBOX_WORKER=1` | Try `bare-worker` when available; else microtask defer |
|
||||
| Bundle tier | `BARE_OS_BUNDLE_TIER=core` | `bare-os-bare-libs` build: only manifest rows with matching `tier` (`all` = default) |
|
||||
| Bundle tier | `BARE_OS_BUNDLE_TIER=core` | `bare-os-bare-libs` build: only manifest rows with matching `tier` (`all` = default); optional per-row `risk` in manifest |
|
||||
|
||||
## POSIX utility notes
|
||||
|
||||
|
||||
@@ -39,7 +39,7 @@ Former **DOCUMENTATION.md** §§12.1–12.9 (runtime, VFS, shell, identity). [Re
|
||||
|
||||
- Builds `shellEnv` with **guest** defaults: `USER`/`LOGNAME`=`guest`, `HOME`/`PWD`=`/home/guest`, `UID`/`GID`=`65534`, `BARE_OS_IDENTITY=guest`, `BARE_OS_EXIT_STATUS`=`0`, `BARE_OS_CTX_API_VERSION`, `PATH=/bin`, `SHELL`, `HOSTNAME`, `0`. When the host sets any of the keys listed under “host → session passthrough” in [Environment variables and POSIX appendix](environment-and-posix-appendix.md#14-environment-variables-complete-list), those values are copied into `shellEnv`. Sets **`BARE_OS_BOOT_PROFILE_RESOLVED`** from **`BARE_OS_BOOT_PROFILE`** or the first line of **`/etc/bare-os/profile`**, and **`BARE_OS_SESSION_ID`** (random UUID). Seeds **`/run/bare-os/boot.json`** fields **`imageDigest`**, **`pearChannel`**, **`pearRelease`** from **`BARE_OS_IMAGE_DIGEST`**, **`BARE_OS_PEAR_CHANNEL`** / **`PEAR_CHANNEL`**, **`BARE_OS_PEAR_RELEASE`** when present.
|
||||
- **`createBareOsIpc({ maxFifoBytes, perChannelMaxBytes?, ipcRpcToken?, enableFanout?, maxJsonRpcLineBytes? })`** ([`bare-os-ipc.js`](../../packages/bare-os-booter/lib/bare-os-ipc.js)) — FIFOs under **`/run/bare-os/ipc/<name>`**; optional per-name byte caps from **`BARE_OS_IPC_CHANNEL_MAX_BYTES`**; JSON-RPC with optional token and line cap; fan-out **`fanoutPublish`/`fanoutSubscribe`**; **`stats`** includes fan-out counts when caps expose **`features.ipcFanout`**.
|
||||
- **`createVfs(drive, personalDrive, shellEnv, vfsMountRef, vfsOptions)`** → `ctx.vfs` (same `env` object as `ctx.env`). **`vfsOptions`** supply **`procSnapshot`**, dynamic **`/proc/*`** and **`/sys/*`** text (quotas JSON, **`bare_os_features`** with **`bits`**–**`bits4`** when advertised, **`bare_os_net_summary`**, net/disk stubs, session stats), **`bootProfileText`**, **`sessionText`**, **`initdRunText`**, **`bootReadyJsonText`**, mount map for **`/proc/mounts`**, **`bootStartedMs`** for **`/proc/uptime`**, etc. Exposes **`vfs.watch(logicalPath)`** for Hyperdrive-backed paths when **`BARE_OS_VFS_WATCH`** is not **`0`**.
|
||||
- **`createVfs(drive, personalDrive, shellEnv, vfsMountRef, vfsOptions)`** → `ctx.vfs` (same `env` object as `ctx.env`). **`vfsOptions`** supply **`procSnapshot`**, dynamic **`/proc/*`** and **`/sys/*`** text (quotas JSON, **`bare_os_features`** with **`bits`**–**`bits5`** when advertised, **`bare_os_net_summary`**, **`bare_os_host_os`**, **`bare_os_sync_window`**, **`bare_os_debug`**, net/disk stubs, session stats), **`bootProfileText`**, **`sessionText`**, **`initdRunText`**, **`bootReadyJsonText`**, mount map for **`/proc/mounts`**, **`bootStartedMs`** for **`/proc/uptime`**, etc. Exposes **`vfs.watch(logicalPath)`** for Hyperdrive-backed paths when **`BARE_OS_VFS_WATCH`** is not **`0`**.
|
||||
- **`applyGuestEnv(ctx)`** then **`ensureGuestHome(ctx)`** — normalizes `ctx.identity` and seeds `/.bare/` (and a guest marker) on the personal drive.
|
||||
- **`createReadLine()`** always resolves stdio first and returns `stdout` (may be `null`) alongside `readLine` so the kernel can write to the **same** stream as the REPL (including `bare-stdio` under Pear).
|
||||
- Builds `ctx`: **`bareOsCtxApiVersion`** (from [`bare-os-ctx-api.js`](../../packages/bare-os-booter/lib/bare-os-ctx-api.js)), **`bareOsRuntimeCaps`** (frozen snapshot from [`bare-os-runtime-caps.js`](../../packages/bare-os-booter/lib/bare-os-runtime-caps.js): pipeline limits, **`quotas`**, pseudo path list, feature flags such as **`vfsWatch`**, **`ipcRpcJson`**, **`initdSocketActivation`**), **`bareOsIpc`**, `disk`, `drive`, `personalDrive`, `vfs`, `env`, `console`, `b4a`, `topic: topicKey()`, `readLine`, **`writeScreen(str)`**, **`bareOsSubscribeBootEvent`** / **`bareOsEmitBootEvent`**, **`bareOsSubscribeHdmsLifecycle`**, **`bareOsAwaitInitdUnits`**, **`bareOsPublishBootReady`**, `execLine` → wraps **`execShellLine`** with optional **audit** (**`BARE_OS_AUDIT`**, **`BARE_OS_AUDIT_JSON`**, redaction), **`execLine` depth cap** (**`BARE_OS_EXEC_MAX_DEPTH`**), then the shell (returns `'ok'` or `'exit'`; updates **`BARE_OS_EXIT_STATUS`** in **`vfs.env`**; bare **`exit`** line sets status then **`requestBooterExit`**), **`runBinCommand(argv)`** → delegates to **`runBinCommand(this, argv)`** from `kernel-runner.js` (for `/bin/time` and similar), plus identity hooks for `/bin` and builtins:
|
||||
|
||||
@@ -26,6 +26,10 @@ Re-exports from `./constants.js`: `PROTOCOL_NAME`, `TOPIC_STRING`, `BLOCK_SIZE`,
|
||||
|
||||
Re-exports from `./lib/channel.js`: `setupSeedChannel`.
|
||||
|
||||
Re-exports from `./lib/seed-rpc-methods.js`: `BARE_OS_SEED_RPC_METHODS`, `BARE_OS_SEED_RPC_METHOD_SHORT_NAMES`, `BARE_OS_SEED_RPC_METHOD_SHORT_NAME_SET`.
|
||||
|
||||
Re-exports **`STOCK_V5`** and **`BARE_OS_FEATURE5_*`** from `./lib/kernel-feature-bits.js` (alongside earlier stock words).
|
||||
|
||||
### 10.3 [packages/bare-os-protocol/constants.js](../../packages/bare-os-protocol/constants.js)
|
||||
|
||||
| Export | Definition |
|
||||
@@ -59,7 +63,7 @@ Re-exports from `./lib/channel.js`: `setupSeedChannel`.
|
||||
- **Message 2**: `c.buffer` — after `chan.open()`, sends 250-byte bitfield with bit 0 set (capability gossip stub; see **`kernel-feature-bits.js`**).
|
||||
- **Message 3**: search request (`msgSearchReqEncoding`) → **message 4** returns paths from the staged manifest whose lowercase path contains the query (trimmed); empty query returns a capped prefix of all manifest paths. **`setupSeedChannel(..., { manifestPaths, searchMaxMatches })`** supplies the list (seeder collects paths during **`stageKernelTree`**).
|
||||
- **Message 4**: search response encoding.
|
||||
- **Message 5**: RPC request → **message 6** implements **`bare_os.version`**, **`bare_os.health`**, **`bare_os.kernel_info`**, **`bare_os.capabilities`** (feature bitfield JSON), **`bare_os.gossip`** (manifest count + timestamp); other modules/methods get **`success: false`** and error **`RPC not implemented on seeder`**.
|
||||
- **Message 5**: RPC request → **message 6** implements registered **`bare_os.*`** methods (see **`lib/seed-rpc-methods.js`**); **`bare_os.capabilities`** returns **`bits`**–**`bits5`** plus **`protocolPackageVersion`**. Wrong module / missing module → **`bare_os.rpc_wrong_module`** / **`bare_os.rpc_missing_module`**; unknown method → **`bare_os.rpc_unknown_method`**. Internal fallthrough → **`bare_os.rpc_internal_unreachable`**.
|
||||
- **Message 6**: RPC response encoding.
|
||||
- Calls `replicateDrive(mux.stream)` (typically `drive.replicate(stream)`).
|
||||
|
||||
@@ -73,4 +77,6 @@ Brittle tests:
|
||||
4. `msgDataEncoding` encode/decode.
|
||||
5. `msgSearchReqEncoding` encode/decode.
|
||||
6. `TOPIC_STRING === 'bare-os-v1'`.
|
||||
7. Seed RPC method list length matches **`BARE_OS_SEED_RPC_METHODS`** / **`kernel_info`** surface.
|
||||
8. **`BARE_OS_KERNEL_FEATURES_STOCK_V5`** is non-zero.
|
||||
|
||||
|
||||
@@ -12,6 +12,8 @@
|
||||
"requireFeatureBits2": { "type": "integer", "minimum": 0 },
|
||||
"requireFeatureBits3": { "type": "integer", "minimum": 0 },
|
||||
"requireFeatureBits4": { "type": "integer", "minimum": 0 },
|
||||
"requireFeatureBits5": { "type": "integer", "minimum": 0 },
|
||||
"requireInitJsSha256": { "type": "string", "minLength": 64, "maxLength": 64 },
|
||||
"maxExecLineDepth": { "type": "integer", "minimum": 1 },
|
||||
"denyEnvKeys": { "type": "array", "items": { "type": "string" } },
|
||||
"requireProcNodes": { "type": "array", "items": { "type": "string" } },
|
||||
|
||||
@@ -0,0 +1,23 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://bare-os.dev/schemas/otel-bare-os-jsonl.schema.json",
|
||||
"title": "Bare OS OTel-inspired JSON line (append to BARE_OS_TELEMETRY_OTEL_JSONL)",
|
||||
"type": "object",
|
||||
"required": ["otlSchemaVersion", "resourceLogs"],
|
||||
"additionalProperties": true,
|
||||
"properties": {
|
||||
"otlSchemaVersion": { "type": "integer", "const": 2 },
|
||||
"resourceLogs": {
|
||||
"type": "array",
|
||||
"minItems": 1,
|
||||
"items": {
|
||||
"type": "object",
|
||||
"additionalProperties": true,
|
||||
"properties": {
|
||||
"resource": { "type": "object" },
|
||||
"scopeLogs": { "type": "array" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user