- disk.os: replication_operator_sketch schema 7 + corestoreSnapshotUxHint; wire corestore into bridge

- HRPC: bare_os.pkg_index_get, route table schema 3; pkg-swarm-index list/get; pathcap-verify --trusted - POSIX: profile 1.0.17, ctx API 1.53.0, syscalls.json schema 11 + susv4Refs; JSON schemas + matrix/dashboard - Feature bits: BARE_OS_KERNEL_FEATURE_BITS_DOC 16; contract + verify scripts; ctx.d.ts + gen helper sync - Ops: BARE_OS_HOLEPUNCH_DRIFT_TIER1 + tier1Repos; mktemp avoids false XXX marker; /proc boot_budget_summary test list - Docs: contract spine, env appendix, handbook, compatibility matrix, boot budget schema, vault threat model notes Covers bare-os P2P roadmap items 1–20 where implemented in-tree; kernel/lib/bare/README left minimal per maintainer edit.
2026-04-05 15:52:59 -04:00
parent 41526508df
commit 64a1270d18
79 changed files with 1707 additions and 568 deletions
@@ -50,6 +50,8 @@ This chapter ties together **Holepunch `bare-*` packages**, the **Pear** host ru

 - **Local Holepunch clone inventory** — After editing the manifest or before a release, run **`npm run audit:holepunch-clones`** to refresh **[`docs/audit/holepunch-clone-sync-report.json`](../docs/audit/holepunch-clone-sync-report.json)** against **`BARE_OS_HOLEPUNCH_CLONES_ROOT`**. To fail CI when selected clones lag **`origin/main`**, list their directory names in **[`docs/audit/holepunch-drift-repos.json`](../docs/audit/holepunch-drift-repos.json)** and set **`BARE_OS_HOLEPUNCH_DRIFT_CHECK=1`** (see [scripts/README.md](../scripts/README.md)).

+- **`mirror-drive` (Holepunch) audit** — The stock VFS union and **`/mirror/*`** overlays remain the supported read-mostly composition path. The upstream **`mirror-drive`** package is a candidate for a future **env-gated** fast path (read-only layering); treat any integration as **parity-tested** against union semantics and document **fallback** when the package is absent. See **`BARE_OS_VFS_UNION_PREFIXES`** in the environment appendix and **`ctx.bareOsEmitMirrorDriveHint`** above.
+
 ---

 ## Runtime caps
@@ -18,7 +18,7 @@ This project is **experimental research software**. APIs described here follow t

 **Kernel source set:** [`docs/reference/kernel-extensions.md`](../docs/reference/kernel-extensions.md) — first-party paths (`kernel/init.js`, `kernel/lib/boot`, built `/bin`) vs vendored **`kernel/lib/bare/bundles`** (Holepunch IIFEs), CI allowlists, and seeder parity. Hand-authored code must stay free of incomplete markers; bundles are gated by **`verify-bundle-markers.mjs`**, **`verify-bundle-throws.mjs`** ( **`new Error` messages** with *not implemented* / abstract-base-class semantics — see [`docs/audit/bundle-throw-allowlist.json`](../docs/audit/bundle-throw-allowlist.json)), and **`sanitize-bare-bundles.mjs`**. Prefer shrinking the throw allowlist via upstream bundle refreshes over silent drift.

-**Local Holepunch mirror:** run **`npm run audit:holepunch-clones`** to refresh **`docs/audit/holepunch-clone-sync-report.json`** (schema **2**), **`holepunch-lockfile-drift.json`**, and NDJSON summaries. The sync report lists every **`bare-module-manifest.json`** entry against **`BARE_OS_HOLEPUNCH_CLONES_ROOT`** (default **`~/dev/pearcli/holepunch-repos/holepunchto_repos`**): **`gitHead`**, **`originMainHead`**, **`commitsBehindOriginMain`**, **`commitsAheadOfOriginMain`** (meaningful after **`git fetch origin main`** in each clone). **`goldenPathRows`** mirrors **`goldenPathRepos`** in **`docs/audit/holepunch-drift-repos.json`** (Bare runtime + Pear + core wire stack) for quick maintainer diff review — it is **not** a CI gate. Root **`pretest`** runs **`verify-holepunch-clone-drift.mjs`** only against **`repos[]`** in the same JSON (empty = no-op). Regenerate the maximal npm catalog with **`node scripts/gen-bare-holepunch-catalog.mjs`** (or **`npm run gen:bare-catalog`**), then **`npm run sync:bare-manifest`** — see [scripts/README.md](../scripts/README.md).
+**Local Holepunch mirror:** run **`npm run audit:holepunch-clones`** to refresh **`docs/audit/holepunch-clone-sync-report.json`** (schema **2**), **`holepunch-lockfile-drift.json`**, and NDJSON summaries. The sync report lists every **`bare-module-manifest.json`** entry against **`BARE_OS_HOLEPUNCH_CLONES_ROOT`** (default **`~/dev/pearcli/holepunch-repos/holepunchto_repos`**): **`gitHead`**, **`originMainHead`**, **`commitsBehindOriginMain`**, **`commitsAheadOfOriginMain`** (meaningful after **`git fetch origin main`** in each clone). **`goldenPathRows`** mirrors **`goldenPathRepos`** in **`docs/audit/holepunch-drift-repos.json`** (Bare runtime + Pear + core wire stack) for quick maintainer diff review — it is **not** a CI gate. Root **`pretest`** runs **`verify-holepunch-clone-drift.mjs`** only against **`repos[]`** in the same JSON (empty = no-op). Maintainers may set **`BARE_OS_HOLEPUNCH_DRIFT_TIER1=1`** to check **`tier1Repos[]`** instead (hypercore / hyperdrive / hyperswarm / protomux / pear / pear-runtime / bare-fs / bare-process). Regenerate the maximal npm catalog with **`node scripts/gen-bare-holepunch-catalog.mjs`** (or **`npm run gen:bare-catalog`**), then **`npm run sync:bare-manifest`** — see [scripts/README.md](../scripts/README.md).

 ---

@@ -41,7 +41,7 @@ Bare OS advertises optional booter and seed-channel capabilities as a versioned

 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 **15** after the wire-v2 documentation bump (JSON shape only; no bit-position changes). 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.
+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.