Align Bare OS with Holepunch stack across runtime, P2P, storage, trust, and ops surfaces

Implement the 50-point Holepunch alignment roadmap with a first-pass delivery across coreutils commands, policy examples, audit tooling, and docs. This adds new operator CLIs (appctl/corestorectl/ctxbaredoctor/dhtctl/trustctl), tiered catalog and runtime-compat reports, release-checklist integration, contributor guidance, and kernel/seeder mirrored artifacts for app registry, trust, network services, corestore namespaces, and update manifest workflows.
2026-04-26 08:57:34 -04:00
parent 6f90952611
commit e59c57e538
51 changed files with 4014 additions and 8 deletions
@@ -0,0 +1,35 @@
+# Chapter 13 — Holepunch contributor track
+
+This chapter maps Holepunch repos to concrete Bare OS implementation surfaces.
+
+## Core learning path
+
+1. Networking: `hyperdht`, `hyperswarm`, `protomux`
+2. Storage: `hypercore`, `corestore`, `hyperbee`, `hyperdrive`
+3. Collaboration: `autobase`, `hyperdb`, `hyperschema`
+4. Runtime/app lifecycle: `bare-runtime`, `pear`, `pear-runtime`, `pear-ipc`
+
+## Bare OS tasks by area
+
+- Networking and control plane
+  - `/bin`: `dhtscan`, `dhttop`, `swarmdoctor`, `p2ptrace`, `peerctl`, `dhtctl`
+  - `/proc`: `swarm`, `dht_status.json`, `peer_details.json`, `route_summary.json`
+- Storage and replication
+  - `/bin`: `corestorectl`, `routeview`, `swarmmap`
+  - `/proc`: `replication`, `hyperdrive_sparse_index.json`, `union.json`
+- App lifecycle and trust
+  - `/bin`: `appctl`, `trustctl`, `ctxbaredoctor`
+  - policy examples: `kernel/etc/bare-os/apps.registry.example.json`, `trust.policy.example.json`
+
+## Suggested first contributions
+
+- Add a new `/proc/bare_os` structured snapshot and expose it through a companion command.
+- Extend `appctl` with pinned-length checkout support for release workflows.
+- Add integration tests that boot the booter, join a local swarm, and verify replicated app state.
+
+## Maintainer tooling
+
+- `npm run audit:holepunch-clones`
+- `npm run report:holepunch-runtime-compat`
+- `npm run gen:bare-catalog:tiers`
+- `node scripts/release-checklist.mjs`
@@ -70,6 +70,7 @@ Full script index: [scripts/README.md](../scripts/README.md). Gate everything wi
 - **[10 — Glossary and FAQ](10-glossary-and-faq.md)** — Quick definitions; frequent questions.
 - **[11 — Kernel + Pear cookbook](11-kernel-pear-cookbook.md)** — Boot allowlist, timers, socket IPC, `vfs.watch`, HDMS hooks, Git-in-Pear, release metadata.
 - **[12 — Bare modules and Pear ecosystem](12-bare-modules-and-pear-ecosystem.md)** — `ctx.bare`, manifest, drive bundles, Holepunch `bare-*` mirror vs guaranteed keys.
+- **[Holepunch contributor track](13-holepunch-contributor-track.md)** — practical task map from Holepunch repos to Bare OS command, proc, and policy work.
 - **[13 — Privacy, telemetry, and PII](13-privacy-telemetry-pii.md)** — Scrub lists for NDJSON / OTel mirrors; non-secret posture.
 - **[Node → Bare module map](node-to-bare-modules.md)** — Guest-safe replacements for **`node:*`** built-ins (**`bare-crypto`**, **`bare-module`**, …).
 - **[bare-boot vs kernel phases](bare-boot-kernel-phase-alignment.md)** — Conceptual map: Holepunch **`bare-boot`** stages vs stock **`kernel/init.js`**.
@@ -91,6 +92,7 @@ Full script index: [scripts/README.md](../scripts/README.md). Gate everything wi
 - [Chapter 9 — POSIX utilities and shell](../handbook/09-posix-utilities-shell-and-vfs.md)
 - [Chapter 11 — Kernel + Pear cookbook](11-kernel-pear-cookbook.md)
 - [Chapter 12 — Bare modules and Pear ecosystem](12-bare-modules-and-pear-ecosystem.md)
+- [Holepunch contributor track](13-holepunch-contributor-track.md)
 - [bare-os-coreutils README](../packages/bare-os-coreutils/README.md)
 - [bare-os-booter README](../packages/bare-os-booter/README.md)