feat(kernel): giant-phase boot hooks, proc snapshot, and kernel UX tools
- Add BARE_OS_BOOT_SAFE_MODE, BOOT_TRANSACTION_JOURNAL, BOOT_CHECKPOINT in stock kernel; kernel.ext.d requires/after/before ordering; boot-ready subsystems.kernel.giantPhase adjunct - Expose /proc/bare_os/giant_phase_program.json via bare-os-giant-phase; wire VFS, baretop snapshot, and ctx batch read - Add /bin/kernel-doctor and /bin/kernel-explain; verify-giant-phase-doc in pretest; giant-phase-benchmark-harness stub - Bump bareOsCtxApiVersion to 1.23.0; sync seeder kernel/init.js and runtime caps; extend booter tests for proc listing and safe mode Docs: giant-phase-kernel-program.md, feature-roadmap, kernel-extensions, compatibility-matrix, environment appendix, handbook 06/11, developer guide, users-manual 07, scripts README; booter CHANGELOG
This commit is contained in:
Raven Scott
@@ -28,7 +28,9 @@ The repository’s default kernel ([`kernel/init.js`](../kernel/init.js)) is int
|
||||
- `status = await ctx.execLine(line)` inside try/catch (`console.error` on failure).
|
||||
- If `status === 'exit'`, break.
|
||||
|
||||
Set **`BARE_OS_BOOT_TRACE=1`** (or **`true`**) in the environment to log boot phase timings on stderr as **`[boot] phase: Nms`**. Use **`BARE_OS_BOOT_TRACE=json`** for one JSON object per phase (**`{"phase":"…","ms":n}`**) on stderr. The same phases are also delivered to **`ctx.bareOsSubscribeBootEvent`** subscribers as NDJSON-shaped objects. The booter emits additional **`booter:*`** phases (**`vfs`**, **`ctx`**, **`repl`**, **`initd`**, **`kernel_invoke`**) and records them under **`booterPhases`** in **`/run/bare-os/boot.json`**. **`BARE_OS_BOOT_ALLOWLIST=1`** with **`/etc/bare-os/boot.allow`** restricts the first token of lines in trusted rc/onboot snippets. Inspect **`ctx.bareOsRuntimeCaps`** for pipeline limits, quotas, pseudo paths, and **`features`** (including **`httpDelegate`**, **`gitDelegate`**, **`systemctlDelegate`**, **`vfsWatch`**, **`ipcFanout`**).
|
||||
Set **`BARE_OS_BOOT_TRACE=1`** (or **`true`**) in the environment to log boot phase timings on stderr as **`[boot] phase: Nms`**. Use **`BARE_OS_BOOT_TRACE=json`** for one JSON object per phase (**`{"phase":"…","ms":n}`**) on stderr. The same phases are also delivered to **`ctx.bareOsSubscribeBootEvent`** subscribers as NDJSON-shaped objects.
|
||||
|
||||
**Giant-phase boot hooks** (see [giant-phase-kernel-program.md](./giant-phase-kernel-program.md)): **`BARE_OS_BOOT_SAFE_MODE`** skips **`rc.d`**, **`kernel.ext.d`**, and **`onboot`**; **`BARE_OS_BOOT_TRANSACTION_JOURNAL`** appends phase NDJSON to **`/run/bare-os/boot-transaction.ndjson`**; **`BARE_OS_BOOT_CHECKPOINT`** refreshes **`/run/bare-os/boot-checkpoint.json`** after each phase. Extension drop-ins may use **`requires`**, **`after`**, and **`before`** for ordering alongside **`dependsOn`**. The booter emits additional **`booter:*`** phases (**`vfs`**, **`ctx`**, **`repl`**, **`initd`**, **`kernel_invoke`**) and records them under **`booterPhases`** in **`/run/bare-os/boot.json`**. **`BARE_OS_BOOT_ALLOWLIST=1`** with **`/etc/bare-os/boot.allow`** restricts the first token of lines in trusted rc/onboot snippets. Inspect **`ctx.bareOsRuntimeCaps`** for pipeline limits, quotas, pseudo paths, and **`features`** (including **`httpDelegate`**, **`gitDelegate`**, **`systemctlDelegate`**, **`vfsWatch`**, **`ipcFanout`**).
|
||||
|
||||
**Boot policy v5** (optional **`/etc/bare-os/boot.policy.json`** fields when **`BARE_OS_BOOT_POLICY=1`**): **`requireKernelCapabilitiesHostTransportDelegates`** and **`requireInitJsSha256`** (64-char lowercase hex of raw **`/boot/init.js`** via **`ctx.bareOsBootFileSha256Hex`**). **`BARE_OS_KERNEL_PROFILE_WARM=1`** enables **`ctx.bareOsRequestKernelProfileReload()`** for a warm **`start(ctx)`** re-run without dropping the swarm session (same machinery as hot reload).
|
||||
|
||||
|
||||
@@ -50,6 +50,7 @@ This project is **experimental research software**. APIs described here follow t
|
||||
- **[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`**.
|
||||
- **[Giant phase kernel program (100 items)](giant-phase-kernel-program.md)** — Mega-kernel governance, boot hooks, proc snapshot, Bare stack pointers.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,48 @@
|
||||
# Giant Phase Kernel Super-Feature Program
|
||||
|
||||
This document is the **governance board** for the single-phase mega-kernel expansion: acceptance criteria, traceability to Holepunch Bare stacks (no Node `node:*` built-ins in guest paths), and operator-facing env/proc hooks.
|
||||
|
||||
## Acceptance criteria (global)
|
||||
|
||||
1. **Bare-only runtime**: Guest code uses `bare-*` / `pear-*` modules per [bare-node](https://github.com/holepunchto/bare-node) mapping (local mirror: `holepunch-repos/holepunchto_repos/bare-node/README.md`).
|
||||
2. **Contracts**: Any wire, `ctx` API, boot policy, or `/proc` shape change bumps the artifacts in [compatibility-matrix.md](../docs/reference/compatibility-matrix.md).
|
||||
3. **Docs**: Each workstream updates [feature-roadmap.md](../docs/reference/feature-roadmap.md), [kernel-extensions.md](../docs/reference/kernel-extensions.md), and the relevant handbook / users-manual / schema files.
|
||||
4. **Tests**: Stock kernel and booter tests cover new boot env flags and proc JSON where applicable.
|
||||
|
||||
## Program version
|
||||
|
||||
| Artifact | Value |
|
||||
|----------|--------|
|
||||
| Giant phase schema | **1** (see `/proc/bare_os/giant_phase_program.json`) |
|
||||
| Primary proc path | `/proc/bare_os/giant_phase_program.json` |
|
||||
| Legacy underscore alias | `/proc/bare_os_giant_phase_program.json` |
|
||||
|
||||
## Environment hooks (stock kernel + booter)
|
||||
|
||||
| Variable | Purpose |
|
||||
|----------|---------|
|
||||
| `BARE_OS_BOOT_SAFE_MODE` | `1` / `true` — skip `rc.d`, `kernel.ext.d`, and `onboot` after policy merge (recovery-oriented). |
|
||||
| `BARE_OS_BOOT_TRANSACTION_JOURNAL` | `1` / `true` / `ndjson` — append boot phase records to `/run/bare-os/boot-transaction.ndjson` when `ctx.vfs` supports it. |
|
||||
| `BARE_OS_BOOT_CHECKPOINT` | `1` / `true` — write `/run/bare-os/boot-checkpoint.json` after each boot phase (last-wins resume hint). |
|
||||
| `BARE_OS_GIANT_PHASE_PROGRAM_JSON` | Optional override JSON merged into the giant-phase proc snapshot (bounded; non-secret). |
|
||||
|
||||
## kernel.ext.d drop-in extensions
|
||||
|
||||
In addition to `scripts`, `id`, `dependsOn`, and `signaturePointer`, drop-ins may set:
|
||||
|
||||
- **`requires`** — string array, merged into `dependsOn` (same semantics).
|
||||
- **`after`** — extension ids that must load before this drop-in (appended to `dependsOn`).
|
||||
- **`before`** — extension ids that must load **after** this drop-in (those ids gain a dependency on this drop-in’s `id`).
|
||||
|
||||
## 100-item traceability matrix
|
||||
|
||||
Items **1–100** map to the approved plan (boot graph, journal, safe mode, extension ordering, module policy, process/IPC, VFS, networking, security, telemetry, upgrades, dev UX, benchmarks). Implementation status:
|
||||
|
||||
- **Shipped in tree**: boot safe mode, transaction journal, checkpoints, `before`/`after`/`requires` for `kernel.ext.d`, `/proc/bare_os/giant_phase_program.json`, `/bin/kernel-doctor`, `/bin/kernel-explain`, governance doc, doc cross-links.
|
||||
- **Framework / operator hooks**: remaining items are tracked via env-driven proc sketches (wave 9–11 pattern), boot policy versions, and [feature-roadmap.md](../docs/reference/feature-roadmap.md) mega-kernel waves — extend those rows as each capability hardens.
|
||||
|
||||
## See also
|
||||
|
||||
- [03-kernel-boot-init.md](./03-kernel-boot-init.md)
|
||||
- [02-the-context-object.md](./02-the-context-object.md)
|
||||
- [Handbook ch.11 — Roadmap](../handbook/11-kernel-roadmap-and-research.md)
|
||||
Reference in New Issue
Block a user