bare-operating-system/developer-guide/adr/001-kernel-feature-bits-governance.md

ADR 001: Kernel feature bit governance (v10)

Status

Accepted

Context

Bare OS advertises optional booter and seed-channel capabilities as a versioned bitmask (bare-os-protocol kernel-feature-bits.js). Peers compare masks during the seed handshake and guests read /proc/bare_os_features. Bits must remain backward compatible: unknown bits are ignored on the wire.

Wire v2 (bare-os-protocol 0.9+): seed bare_os.capabilities, /proc/bare_os_features, and guest ctx expose eleven uint32 words under kernelCapabilityWords (semantic camelCase keys; see kernel-capability-wire.js). kernelCapabilityWireVersion is 2. Legacy v1 top-level bits … bits11 were removed in the same breaking release; numeric masks and bit positions are unchanged. Source identifiers use semantic labels (BARE_OS_KERNEL_FEATURES_STOCK_WORD_*, requireKernelCapabilities*, env mirrors). The authoritative cross-reference is docs/reference/capability-words.md.

Decisions

1. BARE_OS_KERNEL_FEATURE_BITS_DOC — Bump when the meaning of any existing bit changes or when documentation requires a breaking clarification. Seeder and booter both embed the same integer in bare_os.capabilities as doc. Mismatched doc values are informational; strict policy can be added later via boot policy files.

2. Assigning a new bit (21+) — Use the next free integer ≤ 30 (JavaScript 1 << 31 is signed-negative; avoid without >>> 0 everywhere). Each bit gets:

   • a named export BARE_OS_FEATURE_*
   • a one-line comment describing user-visible behavior
   • inclusion in BARE_OS_KERNEL_FEATURES_STOCK_WORD_PRIMARY only when the stock booter implements it end-to-end

3. /proc/bare_os_features — Must include doc, kernelCapabilityWords (effective stock masks minus env-disabled features such as crypto urandom on primary), kernelCapabilityWireVersion, and optional seedHandshake summary. The unified tree under /proc/bare_os/ duplicates the same content for stable paths (see docs/reference/kernel-extensions.md).

4. Bits 28–30 (assigned, word 1) — 28: BARE_OS_FEATURE_SEED_MANIFEST_HINTS_RPC (bare_os.manifest_hints). 29: BARE_OS_FEATURE_LIFECYCLE_TELEMETRY_V3 (NDJSON / boot events lifecycleSchemaVersion: 3). 30: BARE_OS_FEATURE_BOOT_POLICY_V2 (extended boot.policy.json fields). No further bits are assigned on word 1 without revisiting this ADR (avoid 1 << 31 in JS without >>> 0 discipline).

5. Second capability word (bits2) — BARE_OS_KERNEL_FEATURES_STOCK_WORD_EXTENDED_SEEDING_PLATFORM and named BARE_OS_FEATURE2_* constants (bits 0–31; always use >>> 0 when masking). Seed JSON bare_os.capabilities and /proc/bare_os_features include bits2 alongside bits. BARE_OS_SEED_CAP_STRICT may require both words when the booter advertises a non-zero second word. New guest-visible behavior on word 2 follows the same documentation rule as word 1: docs/reference/kernel-capabilities-index.md, docs/reference/kernel-extensions.md, and relevant handbook chapters.

6. Third capability word (bits3) — BARE_OS_KERNEL_FEATURES_STOCK_WORD_RLIMITS_DELEGATES_SHELL and BARE_OS_FEATURE3_* cover rlimits proc, boot policy v3, delegate concurrency, gated shell local, host capability probe, and CI schema validation of examples. Seed JSON and /proc/bare_os_features include bits3. BARE_OS_SEED_CAP_STRICT may require bits3 when the stock booter advertises a non-zero third word. Word 2 bits 19–31 remain on bits2; word 3 is additive and does not renumber prior assignments.

7. Fourth capability word (bits4) — BARE_OS_KERNEL_FEATURES_STOCK_WORD_OFFLINE_NET_EXTENSIONS and BARE_OS_FEATURE4_* cover offline LKG boot, /proc/bare_os/net_summary.json, boot policy v4, telemetry schema v4, kernel extension registry schema v2, roadmap contract tests (verify-kernel-capabilities-contract.mjs), host storage JSON in bootstrap proc, IPC audit, initd directory conditions, delegate fairness metrics, optional bare-worker /bin offload, and subprocess-bridge job surfacing. Seed JSON bare_os.capabilities and /proc/bare_os_features include bits4. BARE_OS_SEED_CAP_STRICT requires bits4 to cover the stock fourth word when enabled.

8. Fifth capability word (bits5) — BARE_OS_KERNEL_FEATURES_STOCK_WORD_HOST_TRANSPORT_DELEGATES and BARE_OS_FEATURE5_* cover host OS proc snapshot, subprocess bridge snapshot v2, transport stats in net summary, boot policy v5, replication sync windows, union readlink parity, warm kernel profile reload, HDMS hints v2, OTel JSONL schema v2, bin-worker pattern allowlists, staging rollback hints, dev debug proc, manifest risk metadata, replication queue metrics v2 on the seeder, typed seed RPC errors, and repo doc-verification scripts. Seed JSON bare_os.capabilities and /proc/bare_os_features include bits5. BARE_OS_SEED_CAP_STRICT requires bits5 to cover the stock fifth word when enabled.

9. Sixth capability word (bits6) — BARE_OS_KERNEL_FEATURES_STOCK_WORD_REPLICATION_OPERATOR_SURFACE and BARE_OS_FEATURE6_* group extended seed RPCs (replication plan, DHT bootstrap hints, compact ping, …), advisory replication JSON v2 fields, /proc/bare_os/*.json operator metrics, boot policy v6 (requireKernelCapabilitiesReplicationOperatorSurface, requireBooterSemver, requireCtxApiMin, extension deny/hash pins, offline LKG strict integrity), kernel extension registry schema v3 with dependency edges, Pear/Bare bridge ctx hooks, strict /proc/bare_os alias completeness (FEATURE6_STRICT_PROC_ALIAS + BARE_OS_PROC_ALIAS_STRICT), VFS/POSIX/initd/timer extensions, worker/sandbox/net-policy surfaces, telemetry NDJSON v5 / OTel schema v3 / audit v3, and CI (verify-kernel-capabilities-word-6.mjs, Pear static node: import scan). Seed JSON and /proc/bare_os_features include bits6. BARE_OS_SEED_CAP_STRICT may require bits6 when the stock sixth word is non-zero.

10. Seventh capability word (bits7) — BARE_OS_KERNEL_FEATURES_STOCK_WORD_PEAR_CORESTORE_HRPC and **BARE_OS_FEATURE7_*** add another full 32-bit word. Word 6 bits 16–31 remain reserved for future sixth-word–scoped features; new coarse groups use bits7 instead (seed RPC surface, proc JSON, boot policy v7, extension registry v4, Pear/Bare bridge stubs, VFS/env/git policy docs, initd/subprocess, worker/net, telemetry v6/OTel v4/audit v4, CI verify-kernel-capabilities-word-7.mjs). Seed JSON and /proc/bare_os_features include bits7. BARE_OS_SEED_CAP_STRICT may require bits7 when the stock seventh word is non-zero.

11. Eighth capability word (bits8) — BARE_OS_KERNEL_FEATURES_STOCK_WORD_BARE_RUNTIME_PROTO_MUX and **BARE_OS_FEATURE8_*** add the eighth 32-bit word. Word 7 high bits remain reserved for future seventh-word–scoped features; bits8 carries seed RPCs, /proc JSON, boot policy v8 (requireKernelCapabilitiesBareRuntimeProtoMux, requireBareRuntimeMin, denySeedRpcMethods, maxProtomuxChannelNameLength), extension registry v5 (compatPearBundleId), Pear/Bare structured-clone / protomux alias stubs, VFS/shell/git/curl parity, initd/subprocess/resume limits, worker ioproc:* / sandbox queue / delegate placeholders, HTTP/proxy/DNS/rocksdb proc hints, telemetry NDJSON v7 / OTel v5 / audit v5, and CI verify-kernel-capabilities-word-8.mjs. Seed JSON and /proc/bare_os_features include bits8. BARE_OS_SEED_CAP_STRICT requires bits8 to cover the stock eighth word when it is non-zero.

12. Ninth capability word (bits9) — BARE_OS_KERNEL_FEATURES_STOCK_WORD_BARE_MODULE_CRYPTO_STAGING and **BARE_OS_FEATURE9_*** add the ninth 32-bit word. Word 8 high bits remain reserved for future eighth-word–scoped features; bits9 carries Holepunch-aligned seed RPCs, /proc (bare-module, bare-crypto, pear-stage, …), boot policy v9 (requireKernelCapabilitiesBareModuleCryptoStaging, requirePearRuntimeRange, requireBareCryptoMin, denyBareModuleSpecifierPatterns, …), extension registry schema 6 surface, Pear/Bare bridge ctx, worker mediaproc:*, telemetry NDJSON schema 8 / OTel schema 6 / audit schema 6, and CI verify-kernel-capabilities-word-9.mjs. Seed JSON and /proc/bare_os_features include bits9. BARE_OS_SEED_CAP_STRICT requires bits9 to cover the stock ninth word when it is non-zero.

13. Tenth capability word (bits10) — BARE_OS_KERNEL_FEATURES_STOCK_WORD_PEAR_INSPECT_LOGGER_TLS and **BARE_OS_FEATURE10_*** add the tenth 32-bit word. Word 9 high bits remain reserved for future ninth-word–scoped features; bits10 carries additional seed RPCs, replication JSON adjuncts (bundle tier, autobase-discovery hint, token bucket v4, staging schema 7, peer firewall v5, compact ping v4, ready guard v4, mirror compaction v5, blind relay v3), /proc JSON (bare-os-proc-pear-inspect-logger-tls.js), bare_os_proc_index schema 6, boot policy v10 (requireKernelCapabilitiesPearInspectLoggerTls, requireBareBootMin, denyBareRpcMethodPatterns, extensionSignerPinsV3, bootPhasesRequireLifecycleMinSchema, …), extension registry schema 7, Pear/Bare bridge ctx, worker **sysproc:***, telemetry NDJSON schema 9 / OTel 7 / audit 7, and CI verify-kernel-capabilities-word-10.mjs. Seed JSON and /proc/bare_os_features include bits10. BARE_OS_SEED_CAP_STRICT requires bits10 to cover the stock tenth word when it is non-zero (same pattern as bits9).

14. Eleventh capability word (hypercorePackHrpcLifecycle) — BARE_OS_KERNEL_FEATURES_STOCK_WORD_HYPERCORE_PACK_HRPC_LIFECYCLE and BARE_OS_FEATURE11_* add the eleventh 32-bit word. BARE_OS_KERNEL_FEATURE_BITS_DOC is 16 after the optional Protomux cap-channel bit (BARE_OS_FEATURE8_PROTOMUX_CAP_CHANNEL) and related proc/HRPC documentation bump (no legacy bit renumbering). This word groups protocol 0.9.0 (wire v2 kernelCapabilityWords), twenty seed RPC methods (replicate budget, drive graph, protomux backpressure, Pear matrix, bundle preload, … through mirror compaction v6), bare-os-proc-hypercore-pack-hrpc-lifecycle.js with twenty /proc/bare_os/*.json surfaces, bare_os_proc_index schema 7, boot policy v11 (requireKernelCapabilitiesHypercorePackHrpcLifecycle, extensionSignerPinsV4, requireBarePackMin, requireBareAddonPolicyMin, maxHrpcAllowlistDepth, offlineLkgRequireHypercorePackHrpcLifecycle, merged denySeedRpcMethods), extension registry /proc payload schema 8, ctx API 1.22.0 (bareOsAdvertisedKernelCapabilityWords / bareOsSeedKernelCapabilityWords), worker patterns **cryptoproc:*** / **indexerproc:*, telemetry NDJSON 10 / OTel **otlSchemaVersion 8 / audit 8, and CI verify-kernel-capabilities-word-11.mjs. Seed JSON and /proc/bare_os_features include kernelCapabilityWords.hypercorePackHrpcLifecycle. BARE_OS_SEED_CAP_STRICT requires that key to cover the stock eleventh word when it is non-zero.

Deprecation (unused bits): once a bit is published in this ADR and kernel-capabilities-index.md, its numeric position is stable; if a feature is removed from the stock booter, the bit stays reserved (document as “unused / reserved”) until a major governance revision. BARE_OS_KERNEL_FEATURE_BITS_DOC bumps when semantics or this policy changes.

Consequences

• Seeder RPC bare_os.capabilities must return protocolPackageVersion, optional booterPackageVersion, featureBitsDoc, kernelCapabilityWireVersion, and kernelCapabilityWords (all eleven semantic keys; the stock seeder sends full masks today).
• CI should keep seeder and booter copies of the stock masks aligned: BARE_OS_KERNEL_FEATURES_STOCK_WORD_PRIMARY, BARE_OS_KERNEL_FEATURES_STOCK_WORD_EXTENDED_SEEDING_PLATFORM, BARE_OS_KERNEL_FEATURES_STOCK_WORD_RLIMITS_DELEGATES_SHELL, BARE_OS_KERNEL_FEATURES_STOCK_WORD_OFFLINE_NET_EXTENSIONS, BARE_OS_KERNEL_FEATURES_STOCK_WORD_HOST_TRANSPORT_DELEGATES, BARE_OS_KERNEL_FEATURES_STOCK_WORD_REPLICATION_OPERATOR_SURFACE, BARE_OS_KERNEL_FEATURES_STOCK_WORD_PEAR_CORESTORE_HRPC, BARE_OS_KERNEL_FEATURES_STOCK_WORD_BARE_RUNTIME_PROTO_MUX, BARE_OS_KERNEL_FEATURES_STOCK_WORD_BARE_MODULE_CRYPTO_STAGING, BARE_OS_KERNEL_FEATURES_STOCK_WORD_PEAR_INSPECT_LOGGER_TLS, BARE_OS_KERNEL_FEATURES_STOCK_WORD_HYPERCORE_PACK_HRPC_LIFECYCLE.

Appendix: historical checklist tables

docs/reference/feature-roadmap.md still uses ## Wave N section headings as numbered integration checklists tied to the same wire words (bits6 … bits11). Those headings are documentation structure only; they are not used in source identifiers or boot policy keys.