Further Updates to MD
This commit is contained in:
Raven Scott
@@ -83,7 +83,7 @@ A script you place in `~/exploit.js` is **your** code; the booter will still `As
|
||||
|
||||
## Host source policy (Bare-first)
|
||||
|
||||
Pear-bundled **booter** and **seeder** runtime sources under `packages/bare-os-booter/lib/` and `packages/bare-os-seeder/lib/` must stay resolvable on **Bare** as well as Node: CI runs [`scripts/verify-pear-no-static-node-import.mjs`](../scripts/verify-pear-no-static-node-import.mjs), which rejects **`from 'node:…'**` imports, `**require('node:…')**`, and `**import('node:…')**` in those trees (with path-based exceptions). Use `**#host-fs**`, `**#host-path**`, and `**#host-fs-promises`** from package `imports` instead of bare **`fs`** / **`path`** specifiers. The only deliberate **`node:module`** usage today lives in **`bare-os-boot-manifest-sig.node.js`** (Node default entry for boot manifest verification); the **`bare`** export uses **`bare-os-boot-manifest-sig.bare.js`**. For guest-visible behavior, prefer Holepunch **`bare-*`** modules per [Node → Bare module map](node-to-bare-modules.md).
|
||||
Pear-bundled **booter** and **seeder** runtime sources under `packages/bare-os-booter/lib/` and `packages/bare-os-seeder/lib/` must stay resolvable on **Bare** as well as Node: CI runs [`scripts/verify-pear-no-static-node-import.mjs`](../scripts/verify-pear-no-static-node-import.mjs), which rejects **`from 'node:…'`** imports, **`require('node:…')`**, and **`import('node:…')`** in those trees (with path-based exceptions). Use **`#host-fs`**, **`#host-path`**, and **`#host-fs-promises`** from package `imports` instead of bare **`fs`** / **`path`** specifiers. The only deliberate **`node:module`** usage today lives in **`bare-os-boot-manifest-sig.node.js`** (Node default entry for boot manifest verification); the **`bare`** export uses **`bare-os-boot-manifest-sig.bare.js`**. For guest-visible behavior, prefer Holepunch **`bare-*`** modules per [Node → Bare module map](node-to-bare-modules.md).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -73,9 +73,9 @@ The following are set on `ctx` before the kernel starts (unless noted as overwri
|
||||
- **`bareOsIsCtxMethodAllowed(name)`** — Boot policy v4: when **`BARE_OS_BOOT_POLICY_ALLOWED_CTX_METHODS`** is set, returns whether **`name`** is in the allow list (kernels should call before sensitive **`ctx`** use).
|
||||
- **`bareOsEmitIpcAudit(ev)`** — When **`BARE_OS_IPC_AUDIT=1`**, appends a JSON line to **`audit.log`** (e.g. from **`mkfifo`**).
|
||||
- **`bareOsEvaluatePeerAdmission(peerKeyHex, meta?)`** — Returns **`{ schema: 2, verdict, … }`** using optional env gates (**`BARE_OS_PEER_DENYLIST_HEX`**, **`BARE_OS_PEER_REQUIRE_CAPS_JSON`** + **`meta.caps`**, **`BARE_OS_PEER_ALLOWLIST_HEX`**, **`BARE_OS_DHT_ADDRESS_CLASS_ALLOWLIST`** + **`meta.dhtAddressClass`**). With **`BARE_OS_PEER_ADMISSION_AUDIT_NDJSON`**, emits **`peer_admission`** on the event bus (16-hex key prefix only; optional **`BARE_OS_PEER_ADMISSION_AUDIT_RATE_MS`**). See [environment appendix](../docs/reference/environment-and-posix-appendix.md).
|
||||
- **`bareOsSystemRevision`** — **Frozen** `**{ currentId, pendingId, slot }`** from host env (**`BARE_OS_SYSTEM_REVISION_*`**) for Pear-style OTA hints.
|
||||
- **`bareOsSystemRevision`** — **Frozen** **`{ currentId, pendingId, slot }`** from host env (**`BARE_OS_SYSTEM_REVISION_*`**) for Pear-style OTA hints.
|
||||
- `**bareOsRegisterSuspendHook` / `bareOsRegisterResumeHook**` — Register callbacks; **`bareOsInvokeSuspendHooks`** / **`bareOsInvokeResumeHooks`** run them (host may call around **`Bare.suspend`** / **`Bare.wakeup`**). The booter also registers **bare-initd** so units with stop/start paths run in **reverse boot order** on suspend and **forward boot order** on resume, aligned with the initd DAG.
|
||||
- `**bareOsRequestKernelReload()`** — Throws **`BARE_OS_KERNEL_RELOAD`** when **`BARE_OS_KERNEL_HOT_RELOAD=1`** so the booter re-reads **`/boot/init.js`**.
|
||||
- **`bareOsRequestKernelReload()`** — Throws **`BARE_OS_KERNEL_RELOAD`** when **`BARE_OS_KERNEL_HOT_RELOAD=1`** so the booter re-reads **`/boot/init.js`**.
|
||||
- **`bareOsRequestKernelProfileReload()`** — Throws **`BARE_OS_KERNEL_PROFILE_RELOAD`** when **`BARE_OS_KERNEL_PROFILE_WARM=1`** (same booter loop as hot reload).
|
||||
- **`bareOsRunImageScript(path)`** — **`async`** — runs trusted JS from the system image; paths must be under **`/lib/bare-os/extensions/`** (used by **`kernel.ext.d`**).
|
||||
- **`disk`** — Disk bundle used during boot (includes drives and helpers); advanced use
|
||||
@@ -87,7 +87,7 @@ The following are set on `ctx` before the kernel starts (unless noted as overwri
|
||||
- **`bare`** *(optional)* — **Frozen** map of host-loaded (and optionally drive-bundled) npm modules for in-image use (`**ctx.bare.b4a*`*, **`ctx.bare.protomux`**, …). Absent when **`BARE_OS_BARE_MODULES=0`**. See `[bare-module-manifest.json](../packages/bare-os-booter/lib/bare-module-manifest.json)` and [Chapter 12](12-bare-modules-and-pear-ecosystem.md).
|
||||
- **`topic`** — Topic key helper from protocol package (rarely needed in user scripts)
|
||||
- **`console`** — Initially the raw global; **replaced** with session-bound `log`/`error` that respect the REPL and fish-style UI
|
||||
- **`readLine`** — Placeholder async function; **replaced** with session `readLine(prompt)` that reads a line from stdin (or returns `null` when session ends). When the Fish-style editor attaches, `**ctx.bareOsRegisterCompleter(name, fn)`** / **`ctx.bareOsUnregisterCompleter(name)`** register async completion providers merged by the stock engine — see [Shell completion and REPL editor](../docs/reference/shell-completion-and-repl-editor.md).
|
||||
- **`readLine`** — Placeholder async function; **replaced** with session `readLine(prompt)` that reads a line from stdin (or returns `null` when session ends). When the Fish-style editor attaches, **`ctx.bareOsRegisterCompleter(name, fn)`** / **`ctx.bareOsUnregisterCompleter(name)`** register async completion providers merged by the stock engine — see [Shell completion and REPL editor](../docs/reference/shell-completion-and-repl-editor.md).
|
||||
- **`writeScreen`** — REPL helper for screen-oriented output; starts as no-op, then wired
|
||||
- **`runHdms(argv)`** — Entry for **`hdms`** CLI when HDMS controller is active
|
||||
- `**onIdentityUnlocked` / `onIdentityGuest**` — Hooks for HDMS lifecycle (bootstrap nodes, teardown)
|
||||
@@ -96,24 +96,24 @@ The following are set on `ctx` before the kernel starts (unless noted as overwri
|
||||
- **`shellAliases`** — Populated when the shell loads default or `~/.barerc` aliases
|
||||
- **`bareOsApplyTheme()`** / **`bareOsListThemes()`** — Re-apply **`BARE_OS_THEME`** / **`LS_COLORS`** / **`BARE_OS_DIRCOLORS`** to **`vfs.env`** (including **`BARE_OS_COLOR_DEPTH`** downgrades for **`BARE_OS_COLOR_*`**). Used by **`/bin/theme`** and documented for custom tooling (see `[bare-os-theme-presets.js](../packages/bare-os-booter/lib/bare-os-theme-presets.js)`).
|
||||
- **`runBinCommand(argv)`** — Runs a command with the **same** resolution rules as the interactive shell (used by **`time`**, **`xargs`**, and similar)
|
||||
- **`registerKernelShutdownHook(fn)`** — Register an async or sync function to run when the REPL session ends, **before** **`stopBareInitd`** and initd **disposers**. Pair with `**registerBareInitdDisposer(fn)`** in `[bare-initd.js](../packages/bare-os-booter/lib/bare-initd.js)` when you need teardown **after** shutdown hooks but still inside **`stopBareInitd`** (intervals, sync cleanup).
|
||||
- **`registerKernelShutdownHook(fn)`** — Register an async or sync function to run when the REPL session ends, **before** **`stopBareInitd`** and initd **disposers**. Pair with **`registerBareInitdDisposer(fn)`** in `[bare-initd.js](../packages/bare-os-booter/lib/bare-initd.js)` when you need teardown **after** shutdown hooks but still inside **`stopBareInitd`** (intervals, sync cleanup).
|
||||
- **`bareOsSubscribeBootEvent(fn)`** / **`bareOsEmitBootEvent(ev)`** — Subscribe to or emit structured boot lifecycle events (same shape as **`BARE_OS_BOOT_TRACE=ndjson`** records). Phase records carry **`lifecycleSchemaVersion`** and **`telemetrySchemaVersion`** set from stock **`BARE_OS_LIFECYCLE_SCHEMA_VERSION`** (see [compatibility matrix](../docs/reference/compatibility-matrix.md) and [kernel extensions](../docs/reference/kernel-extensions.md)).
|
||||
- **`bareOsSubscribeKernelEvent(fn)`** / **`bareOsEmitKernelEvent(ev)`** — Namespaced kernel event bus (e.g. **`topic: 'boot.phase'`**, **`bootStage`**); also mirrored to diagnostics subscribers with **`source: 'kernel'`**.
|
||||
- **`bareOsAcquireKeyHandle(hint?)`** — Key-broker sketch returning an **opaque** handle string (no raw key material in guest).
|
||||
- `**bareOsSubscribeHdmsLifecycle(fn)`** — After HDMS **`activate`** / before **`deactivate`**, run callbacks with **`{ kind, labels? }`**.
|
||||
- **`bareOsSubscribeHdmsLifecycle(fn)`** — After HDMS **`activate`** / before **`deactivate`**, run callbacks with **`{ kind, labels? }`**.
|
||||
- **`bareOsAwaitInitdUnits(names, timeoutMs)`** — Resolves when all listed initd units are **`active`** (polls **`getBareServiceRuntime`**); returns **`false`** on timeout.
|
||||
- **`bareOsGetResourceStatus()`** — Returns a plain object snapshot (pipeline limits, exec depth, IPC **`stats()`**, session counters, swarm peer count)—mirrors **`/proc/bare_os_resources`**. Session may include **`execLineWallMsTotal`**.
|
||||
- **`bareOsReadProcMetricsLive()`** — Returns the same object as reading **`/proc/bare_os/metrics_live.json`** (coalesced; interval from **`BARE_OS_PROC_POLL_MS`**).
|
||||
- **`bareOsRegisterVirtualFile(name, reader, opts?)`** — Registers **`/run/bare-os/virtual/<name>`** content; **`reader`** may be a function or **`{ read }`**; may return string or **`Uint8Array`** (sync or async). Optional **`opts`**: **`etag`**, **`mime`** (default **`text/plain`**), **`ttlMs`** (optional cache hint). Gated by runtime cap **`virtualRegisterFiles`**.
|
||||
- **`bareOsSandboxRunScript(source, argv?, opts?)`** — Runs script source with a **restricted `ctx`** (personal-drive writes only; identity/virtual registration disabled). Respects **`raceWithAbortAndTimeout`** opts. Disable with **`BARE_OS_SANDBOX_SCRIPT=0`**. See [Chapter 9](09-security-and-trust.md).
|
||||
- **`bareOsSandboxRunScript(source, argv?, opts?)`** — Runs script source with a **restricted `ctx**` (personal-drive writes only; identity/virtual registration disabled). Respects **`raceWithAbortAndTimeout`** opts. Disable with **`BARE_OS_SANDBOX_SCRIPT=0`**. See [Chapter 9](09-security-and-trust.md).
|
||||
- **`bareOsBootFileSha256Hex(buf)`** — `**sha256` hex for boot manifest checks** (`BARE_OS_BOOT_MANIFEST` + `/etc/bare-os/boot.manifest.json` on the stock kernel).
|
||||
- `**bareOsRegisterBootStepHook(step, fn)`** / **`bareOsInvokeBootStepHooks(ev)`** — Canonical boot hooks around stock **`kernel/init.js`** stages; **`ev`** includes **`step`** / legacy **`phase`**, **`when`** (`before` / `after`), **`label`**. The step key may be `*` or `before:rc` style. Legacy **`bareOsRegisterBootPhaseHook`** / **`bareOsInvokeBootPhaseHooks`** remain aliases.
|
||||
- **`bareOsRegisterBootStepHook(step, fn)`** / **`bareOsInvokeBootStepHooks(ev)`** — Canonical boot hooks around stock **`kernel/init.js`** stages; **`ev`** includes **`step`** / legacy **`phase`**, **`when`** (`before` / `after`), **`label`**. The step key may be `*` or `before:rc` style. Legacy **`bareOsRegisterBootPhaseHook`** / **`bareOsInvokeBootPhaseHooks`** remain aliases.
|
||||
- **`bareOsInvalidateVirtualFile(name)`** / **`bareOsUpdateVirtualFileMeta(name, patch)`** — Virtual files under **`/run/bare-os/virtual/`**; **`patch`** may update **`etag`** / **`version`**.
|
||||
- **`bareOsRequestPearReload(opts?)`** — **`async`** — returns **`{ requested, hint, env }`**; with **`{ persistRequest: true }`** writes **`~/.bare-os/pear-reload.request`** and may **`process.emit('bare-os:pear-reload', …)`** on Node.
|
||||
- **`bareOsVerifyBootManifestSignature(manifestBytes, signatureBytes, publicKeyHex?)`** — Ed25519 verify helper used when **`BARE_OS_BOOT_MANIFEST_SIGN=1`**; public key from arg or **`BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`**.
|
||||
- **`bareOsRequestMirror(opts?)`** / **`bareOsExportPersonalSnapshot(opts?)`** — **`async`** host bridges returning **`{ ok, hint }`**; on Node emit **`bare-os:mirror-request`** / **`bare-os:export-personal-snapshot`**.
|
||||
- **`bareOsPearIpcEmit(channel, payload)`** — **`boolean`** — forwards structured **`payload`** to the host when registered (**`bare-os:pear-ipc`** on Node). Align channel names with your **[pear-ipc](https://github.com/holepunchto/pear-ipc)** consumer.
|
||||
- `**bareOsPearIpcRequest(channel, payload, opts?)`** — **`Promise<unknown>`** — correlates **`bareOsIpcReqId`** on **`payload`**; host must **`process.emit('bare-os:pear-ipc-response', { bareOsIpcReqId, result?, error? })`** before **`opts.timeoutMs`** (default 30s).
|
||||
- **`bareOsPearIpcRequest(channel, payload, opts?)`** — **`Promise<unknown>`** — correlates **`bareOsIpcReqId`** on **`payload`**; host must **`process.emit('bare-os:pear-ipc-response', { bareOsIpcReqId, result?, error? })`** before **`opts.timeoutMs`** (default 30s).
|
||||
- **`bareOsEmitMirrorDriveHint(opts?)`** — Emits **`bare-os:mirror-drive-hint`** on the host with **`label`**, **`key`**, **`ts`** (mirror-drive–style operator hint).
|
||||
- **`bareOsRegisterKernelExtensionRecord(rec)`** — Appends **`{ dropin, script }`** for **`/proc/bare_os/extensions.json`** when the stock kernel loads **`kernel.ext.d`** scripts.
|
||||
- **`bareOsDiagnosticsSubscribe(fn)`** / **`bareOsDiagnosticsEmit(ev)`** — When **`BARE_OS_DIAGNOSTICS_SUBSCRIBE=1`**, subscribe to structured booter/kernel diagnostics events (dev-oriented).
|
||||
@@ -146,7 +146,7 @@ After `[createKernelReplSession](../packages/bare-os-booter/lib/repl-session.js)
|
||||
When the shell runs an external command (or a pipeline stage), it may pass a **shallow clone** of `ctx` with extra fields:
|
||||
|
||||
- **`shellStdin`** — String body for simulated stdin (pipelines and `<` redirection)
|
||||
- **`bareOsStdoutCaptured`** — **`true`** when this command’s stdout is captured into the simulated pipe or a **`>`** / **`>>`** redirect (see **`bareOsPipelineChildCtx`** in `[shell.js](../packages/bare-os-booter/lib/shell.js)`). **`ls`** uses this to print **one name per line**, matching common GNU behavior for non-terminal output.
|
||||
- **`bareOsStdoutCaptured`** — **`true`** when this command’s stdout is captured into the simulated pipe or a **`>`** / `**>>**` redirect (see **`bareOsPipelineChildCtx`** in `[shell.js](../packages/bare-os-booter/lib/shell.js)`). **`ls`** uses this to print **one name per line**, matching common GNU behavior for non-terminal output.
|
||||
- **`exitCode`** — Utilities set **`ctx.exitCode`** for conditions (**`test`**, **`grep`**, …); the shell uses it for **`&&`**, logical OR lists, and **`;`** sequencing (see `[shell.js](../packages/bare-os-booter/lib/shell.js)`)
|
||||
|
||||
Always use the `ctx` passed into **`run`**, not a global, so pipeline stdin works.
|
||||
@@ -206,7 +206,7 @@ async function run(ctx, argv) {
|
||||
}
|
||||
```
|
||||
|
||||
On **Pear**, **`ctx.bare`** is populated from the booter’s embedded **`bare-module-manifest.data.mjs`**, not from **`readFile`** of **`pear://…`** paths. Updating **`/lib/bare/bare-module-manifest.json`** on the system drive still affects **VFS warm-cache** eviction for **`/lib/bare/bundles/*`** via the helpers above, but operators must **re-stage the booter** after `**npm run sync:bare-manifest`** to change manifest metadata; when the booter runs as **`pear:`**, host **`import()`** skips **`bundle: true`** rows (drive bundles supply those keys). See [Chapter 12 — Bare modules](12-bare-modules-and-pear-ecosystem.md) and [PEAR-RUN.md](../docs/PEAR-RUN.md).
|
||||
On **Pear**, **`ctx.bare`** is populated from the booter’s embedded **`bare-module-manifest.data.mjs`**, not from **`readFile`** of **`pear://…`** paths. Updating **`/lib/bare/bare-module-manifest.json`** on the system drive still affects **VFS warm-cache** eviction for **`/lib/bare/bundles/*`** via the helpers above, but operators must **re-stage the booter** after **`npm run sync:bare-manifest`** to change manifest metadata; when the booter runs as **`pear:`**, host **`import()`** skips **`bundle: true`** rows (drive bundles supply those keys). See [Chapter 12 — Bare modules](12-bare-modules-and-pear-ecosystem.md) and [PEAR-RUN.md](../docs/PEAR-RUN.md).
|
||||
|
||||
**Read the Protomux extension registry mirror** (when `BARE_OS_PROC_PROTOMUX_EXTENSIONS_REGISTRY` is enabled on the booter):
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ async function start(ctx) {
|
||||
|
||||
There is **no `argv**` at the kernel layer—the session’s command line is whatever the **interactive user** types after boot, handled through **`ctx.readLine`** and **`ctx.execLine`**.
|
||||
|
||||
**Source of truth:** The file committed as [`kernel/init.js`](../kernel/init.js) is the concatenation of sorted [`kernel/lib/boot/`](../kernel/lib/boot/) fragments, sorted [`kernel/lib/init/fragments/`](../kernel/lib/init/fragments/) (boot policy and `kernel.ext.d` loader), and [`kernel/lib/init/init-main.js`](../kernel/lib/init/init-main.js). Run **`npm run bundle:kernel**` after edits; use `**npm run verify:init-bundle`** or full pretest to confirm the bundle matches. Never edit `init.js` directly—changes would be overwritten and CI will fail. Layout: [`kernel/lib/init/STRUCTURE.md`](../kernel/lib/init/STRUCTURE.md).
|
||||
**Source of truth:** The file committed as [`kernel/init.js`](../kernel/init.js) is the concatenation of sorted [`kernel/lib/boot/`](../kernel/lib/boot/) fragments, sorted [`kernel/lib/init/fragments/`](../kernel/lib/init/fragments/) (boot policy and `kernel.ext.d` loader), and [`kernel/lib/init/init-main.js`](../kernel/lib/init/init-main.js). Run **`npm run bundle:kernel`** after edits; use **`npm run verify:init-bundle`** or full pretest to confirm the bundle matches. Never edit `init.js` directly—changes would be overwritten and CI will fail. Layout: [`kernel/lib/init/STRUCTURE.md`](../kernel/lib/init/STRUCTURE.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -30,15 +30,15 @@ The repository’s default kernel ([`kernel/init.js`](../kernel/init.js), genera
|
||||
- `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.
|
||||
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.
|
||||
|
||||
**`BARE_OS_BOOT_PERF_DETAIL=1`** collects per-stage **`wallMs`** and optional **`bare-hrtime`** **`monotonicNs`** samples into **`/run/bare-os/boot-perf.json`** (**schema 2** when stages are present). **`BARE_OS_KERNEL_EXT_GRAPH=1`** writes **`/run/bare-os/kernel-ext-graph.json`** after **`kernel.ext.d`** ordering (and probes whether **`bare-module-traverse`** can be imported on the host).
|
||||
|
||||
**Kernel program boot hooks** (see [kernel-program.md](./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`** (each line includes a **`bootStage`**); **`BARE_OS_BOOT_CHECKPOINT`** refreshes **`/run/bare-os/boot-checkpoint.json`** after each phase (**schema 2** adds **`bootStage`**). **`BARE_OS_BOOT_DRY_RUN`** skips trusted **`execLine`** and extension scripts; **`BARE_OS_BOOT_POLICY_PATH`** / **`policyFallbackPaths`** tier policy files; rollback marker + **`BARE_OS_BOOT_ROLLBACK_APPLY`**; **`kernel.d`** snippets may start with `**# ConditionEnvironment=KEY=VAL**` comment guards; **`bareOsPublishBootReady`** includes **`subsystems.kernel.bootPhases`** with **`bootStage`** labels. 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`**).
|
||||
**Kernel program boot hooks** (see [kernel-program.md](./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`** (each line includes a **`bootStage`**); **`BARE_OS_BOOT_CHECKPOINT`** refreshes **`/run/bare-os/boot-checkpoint.json`** after each phase (**schema 2** adds **`bootStage`**). **`BARE_OS_BOOT_DRY_RUN`** skips trusted **`execLine`** and extension scripts; **`BARE_OS_BOOT_POLICY_PATH`** / **`policyFallbackPaths`** tier policy files; rollback marker + **`BARE_OS_BOOT_ROLLBACK_APPLY`**; **`kernel.d`** snippets may start with **`# ConditionEnvironment=KEY=VAL`** comment guards; **`bareOsPublishBootReady`** includes **`subsystems.kernel.bootPhases`** with **`bootStage`** labels. 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).
|
||||
**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).
|
||||
|
||||
Optional **`BARE_OS_KERNEL_SELFTEST=1`** runs built-in checks after boot snippets. Set **`BARE_OS_SELFTEST_FORMAT=tap`** for TAP on **`ctx.console.error`** (session stderr, not the host’s raw **`globalThis.console`**), or **`junit`** for a single-line XML **`testsuite`** on the same sink—matching how **`runKernelSelftest`** binds the harness. You can pass `**{ signal, timeoutMs }**` as a second argument to **`ctx.execLine`**, **`ctx.readLine`**, **`ctx.runBinCommand`**, and VFS `**readFile`/`writeFile`** for bounded waits—see [Chapter 2](02-the-context-object.md).
|
||||
Optional **`BARE_OS_KERNEL_SELFTEST=1`** runs built-in checks after boot snippets. Set **`BARE_OS_SELFTEST_FORMAT=tap`** for TAP on **`ctx.console.error`** (session stderr, not the host’s raw **`globalThis.console`**), or **`junit`** for a single-line XML **`testsuite`** on the same sink—matching how **`runKernelSelftest`** binds the harness. You can pass **`{ signal, timeoutMs }`** as a second argument to **`ctx.execLine`**, **`ctx.readLine`**, **`ctx.runBinCommand`**, and VFS `**readFile`/`writeFile`** for bounded waits—see [Chapter 2](02-the-context-object.md).
|
||||
|
||||
So the “OS personality” is mostly the **shell** (`execShellLine` behind `execLine`) plus **`/bin`**.
|
||||
|
||||
@@ -52,7 +52,7 @@ The stock kernel passes `''` as the prompt. The actual prompt rendering (fish-st
|
||||
|
||||
## Using `execLine` vs calling `runBinCommand` directly
|
||||
|
||||
- **`await ctx.execLine('ls -la')`** — Full **shell** semantics: tokenization, aliases, builtins (`cd`, `export`, …), **`;**` / `**&&**` / logical-OR lists, pipelines, redirections, then **`/bin`**
|
||||
- **`await ctx.execLine('ls -la')`** — Full **shell** semantics: tokenization, aliases, builtins (`cd`, `export`, …), **`;`** / **`&&`** / logical-OR lists, pipelines, redirections, then **`/bin`**
|
||||
- **`await ctx.runBinCommand(['ls', '-la'])`** — **Direct** utility invocation—**no** shell parsing, **no** aliases
|
||||
|
||||
Use **`execLine`** when you want users to type natural shell commands from your kernel loop. Use **`runBinCommand`** when you already have an argv array and want to avoid re-parsing.
|
||||
@@ -61,7 +61,7 @@ Use **`execLine`** when you want users to type natural shell commands from your
|
||||
|
||||
## Session termination
|
||||
|
||||
- The **`exit`** builtin (or **`/bin/exit`**) ultimately calls `**ctx.requestBooterExit(code)**`, which forces **`readLine`** to return `null` on subsequent calls and ends the loop.
|
||||
- The **`exit`** builtin (or **`/bin/exit`**) ultimately calls **`ctx.requestBooterExit(code)`**, which forces **`readLine`** to return `null` on subsequent calls and ends the loop.
|
||||
- **`BARE_OS_SKIP_REPL=1`** makes **`readLine`** return `null` immediately—useful for non-interactive smoke tests. Pair with **`BARE_OS_ONBOOT`** (one or more newline-separated lines) or **`/etc/bare-os/onboot`** so the stock kernel runs trusted **`execLine`** snippets before idle exit.
|
||||
|
||||
---
|
||||
|
||||
@@ -24,7 +24,7 @@ new AsyncFunction(
|
||||
)
|
||||
```
|
||||
|
||||
If **`run`** exists, it is **awaited** after the rest of the file. **`/bin`** commands always define **`run`**; home-directory scripts may use top-level code only (e.g. `**console.log(...)`**).
|
||||
If **`run`** exists, it is **awaited** after the rest of the file. **`/bin`** commands always define **`run`**; home-directory scripts may use top-level code only (e.g. **`console.log(...)`**).
|
||||
|
||||
---
|
||||
|
||||
@@ -76,7 +76,7 @@ async function run(ctx, argv) {
|
||||
## Git and special cases
|
||||
|
||||
- Prefer the **`git`** command for version control; it is **not** the same as evaluating `/bin/git` as JS.
|
||||
- **`command -v**` / **`type`** use **`resolveBinInPath`** (system drive PATH only) plus builtin tables.
|
||||
- **`command -v`** / **`type`** use **`resolveBinInPath`** (system drive PATH only) plus builtin tables.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -77,7 +77,7 @@ When **`BARE_OS_BARE_MODULES`** is not disabled, the booter exposes **`ctx.bare`
|
||||
|
||||
**Drive bundles (trusted image):** the system image may include **`/lib/bare/manifest.json`** and **`/lib/bare/bundles/*.js`**. Those scripts are **IIFE** bundles built by **`bare-os-bare-libs`**. The booter executes them with **`Function`** in the same trust class as seeded **`/bin`** utilities and fills **`ctx.bare`** for the listed keys. Set **`BARE_OS_BARE_DRIVE_BUNDLES=0`** to skip this step.
|
||||
|
||||
**Host resolution:** after drive merge, the booter uses dynamic **`import()**` for manifest entries that are **still missing**. When the booter loads from a **`pear:`** URL (`**pear run**`), rows with `**bundle: true**` are **not** host-`**import()**`ed (bare-module cannot resolve npm package names from that referrer; **`ctx.bare.holesail`** et al. come from **`/lib/bare/bundles/*`**). On **`file:`** checkouts and Node test harnesses, `**bundle: true`** may still be host-imported as a fallback when a drive bundle is absent. Optional packages that fail to load (for example native-only modules on the wrong host) are skipped without aborting boot.
|
||||
**Host resolution:** after drive merge, the booter uses dynamic **`import()`** for manifest entries that are **still missing**. When the booter loads from a **`pear:`** URL (**`pear run`**), rows with **`bundle: true`** are **not** host-**`import()`**ed (bare-module cannot resolve npm package names from that referrer; **`ctx.bare.holesail`** et al. come from **`/lib/bare/bundles/*`**). On **`file:`** checkouts and Node test harnesses, **`bundle: true`** may still be host-imported as a fallback when a drive bundle is absent. Optional packages that fail to load (for example native-only modules on the wrong host) are skipped without aborting boot.
|
||||
|
||||
**Hardening:** set **`BARE_OS_BARE_MODULES=0`** to omit **`ctx.bare`** entirely (the property is absent on **`ctx`**). Runtime caps **`bareCtxModules`** and **`bareDriveBundles`** mirror these toggles.
|
||||
|
||||
|
||||
@@ -54,7 +54,7 @@ From [`build.mjs`](../packages/bare-os-coreutils/build.mjs):
|
||||
runtime.js + [preamble files...] + src/foo.js → kernel/bin/foo
|
||||
```
|
||||
|
||||
**`runtime.js`** begins with a **`BARE_OS_BIN_API`** version comment (e.g. `**/* BARE_OS_BIN_API 1.0.0 */**`). Staged **`kernel/bin/*`** must contain that string so **[`scripts/verify-kernel-seeder-parity.mjs`](../../scripts/verify-kernel-seeder-parity.mjs)** can catch drift; hand-written stubs (**`systemctl`**, **`journalctl`**) carry the same pragma.
|
||||
**`runtime.js`** begins with a **`BARE_OS_BIN_API`** version comment (e.g. **`/* BARE_OS_BIN_API 1.0.0 */`**). Staged **`kernel/bin/*`** must contain that string so **[`scripts/verify-kernel-seeder-parity.mjs`](../../scripts/verify-kernel-seeder-parity.mjs)** can catch drift; hand-written stubs (**`systemctl`**, **`journalctl`**) carry the same pragma.
|
||||
|
||||
**`runtime.js`** defines helpers like **`bareStdin`**, listing time formatting, etc.—read it before reimplementing utilities.
|
||||
|
||||
@@ -62,7 +62,7 @@ runtime.js + [preamble files...] + src/foo.js → kernel/bin/foo
|
||||
|
||||
## Exit status
|
||||
|
||||
POSIX-ish utilities set **`ctx.exitCode`** (number) when they want a non-zero status. The **shell** uses **`ctx.exitCode`** for `**&&**`, **`||`**, and `**;**` lists; utilities such as **`grep`** and **`test`** set it for conditions.
|
||||
POSIX-ish utilities set **`ctx.exitCode`** (number) when they want a non-zero status. The **shell** uses **`ctx.exitCode`** for **`&&`**, **`||`**, and **`;`** lists; utilities such as **`grep`** and **`test`** set it for conditions.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -32,9 +32,9 @@ Read [`bare-initd.js`](../packages/bare-os-booter/lib/bare-initd.js) before addi
|
||||
|
||||
## Cron and timers
|
||||
|
||||
**`bare-cron`** reads **`/etc/bare-os/crontab`** on the system image (if present), then the user’s **`~/.crontab`** on the personal drive; invalid lines are logged and skipped. **`crontab`** installs/lists/removes the **user** file (requires login). Timer drop-ins under **`~/.config/bare-os/timers/*.timer`** (`**[Timer]**` **`OnCalendar=`** + **`ExecLine=`**) merge into the same minute scheduler. See [Handbook ch.4](../handbook/04-the-booter-runtime.md) and [Developer guide ch.11](11-kernel-pear-cookbook.md).
|
||||
**`bare-cron`** reads **`/etc/bare-os/crontab`** on the system image (if present), then the user’s **`~/.crontab`** on the personal drive; invalid lines are logged and skipped. **`crontab`** installs/lists/removes the **user** file (requires login). Timer drop-ins under **`~/.config/bare-os/timers/*.timer`** (**`[Timer]`** **`OnCalendar=`** + **`ExecLine=`**) merge into the same minute scheduler. See [Handbook ch.4](../handbook/04-the-booter-runtime.md) and [Developer guide ch.11](11-kernel-pear-cookbook.md).
|
||||
|
||||
**Socket-shaped activation:** initd unit drop-ins can set **`SocketActivationIpc=<fifo-name>`** so a service’s `**start()**` runs when something first **`readFile`**s that logical FIFO under **`/run/bare-os/ipc/`** (see **`bare-initd.js`**).
|
||||
**Socket-shaped activation:** initd unit drop-ins can set **`SocketActivationIpc=<fifo-name>`** so a service’s **`start()`** runs when something first **`readFile`**s that logical FIFO under **`/run/bare-os/ipc/`** (see **`bare-initd.js`**).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -13,13 +13,13 @@ npm ci
|
||||
npm test
|
||||
```
|
||||
|
||||
**`pretest`** mirrors root **`package.json`** **`scripts.pretest`**: `**npm run build -w bare-os-coreutils**`, `**npm run build -w bare-os-bare-libs**`, **`verify-kernel-seeder-parity`**, **`verify-ctx-api-feature-bits`**, **`verify-kernel-capabilities-contract`**, **`verify-kernel-capabilities-word-6`** … **`-word-11`**, **`verify-ctx-dts`**, **`validate-example-schemas`**, **`verify-doc-links`**, **`verify-man-coverage`**, **`verify-compat-matrix`**, **`gen-posix-dashboard`**, **`verify-posix-dashboard`**, **`verify-posix-compliance-matrix`**, **`verify-posix-profile-triplet`**, **`verify-pear-no-static-node-import`**, **`smoke:bare-manifest`** — so **`kernel/bin/*`**, **`kernel/lib/bare`**, **`kernel/share/man/man.json`**, **`packages/bare-os-seeder/kernel/`**, ctx semver / feature words through **`bits11`**, capability contracts, **`bare-os-ctx.d.ts`** parity, schema examples, Tier-1 **man** coverage, doc links, the compatibility matrix, and the **POSIX dashboard / compliance matrix / profile triplet** stay aligned before workspace tests. See the **POSIX verifier “pretest matrix”** diagram in [`scripts/README.md`](../scripts/README.md).
|
||||
**`pretest`** mirrors root **`package.json`** **`scripts.pretest`**: **`npm run build -w bare-os-coreutils`**, **`npm run build -w bare-os-bare-libs`**, **`verify-kernel-seeder-parity`**, **`verify-ctx-api-feature-bits`**, **`verify-kernel-capabilities-contract`**, **`verify-kernel-capabilities-word-6`** … **`-word-11`**, **`verify-ctx-dts`**, **`validate-example-schemas`**, **`verify-doc-links`**, **`verify-man-coverage`**, **`verify-compat-matrix`**, **`gen-posix-dashboard`**, **`verify-posix-dashboard`**, **`verify-posix-compliance-matrix`**, **`verify-posix-profile-triplet`**, **`verify-pear-no-static-node-import`**, **`smoke:bare-manifest`** — so **`kernel/bin/*`**, **`kernel/lib/bare`**, **`kernel/share/man/man.json`**, **`packages/bare-os-seeder/kernel/`**, ctx semver / feature words through **`bits11`**, capability contracts, **`bare-os-ctx.d.ts`** parity, schema examples, Tier-1 **man** coverage, doc links, the compatibility matrix, and the **POSIX dashboard / compliance matrix / profile triplet** stay aligned before workspace tests. See the **POSIX verifier “pretest matrix”** diagram in [`scripts/README.md`](../scripts/README.md).
|
||||
|
||||
**Kernel self-test:** with **`BARE_OS_KERNEL_SELFTEST=1`**, the stock kernel runs built-in checks (including **`/proc/bare_os_resources`**, **`/proc/bare_os_features`**, and **`/proc/bare_os/index.json`**). Use **`BARE_OS_SELFTEST_FORMAT=tap`** for CI-friendly stderr.
|
||||
|
||||
**Kernel hot reload (dev):** with **`BARE_OS_KERNEL_HOT_RELOAD=1`**, a custom kernel may call `**ctx.bareOsRequestKernelReload()**` to throw a controlled reload: the booter re-fetches **`/boot/init.js`** and runs `**start(ctx)`** again without tearing down the swarm session.
|
||||
**Kernel hot reload (dev):** with **`BARE_OS_KERNEL_HOT_RELOAD=1`**, a custom kernel may call **`ctx.bareOsRequestKernelReload()`** to throw a controlled reload: the booter re-fetches **`/boot/init.js`** and runs **`start(ctx)`** again without tearing down the swarm session.
|
||||
|
||||
**Kernel profile warm reload:** with **`BARE_OS_KERNEL_PROFILE_WARM=1`**, `**ctx.bareOsRequestKernelProfileReload()`** uses the same re-invocation loop (distinct error code for policy clarity).
|
||||
**Kernel profile warm reload:** with **`BARE_OS_KERNEL_PROFILE_WARM=1`**, **`ctx.bareOsRequestKernelProfileReload()`** uses the same re-invocation loop (distinct error code for policy clarity).
|
||||
|
||||
**Seed RPC contract:** **`packages/bare-os-protocol`** lists RPC short names in **`lib/seed-rpc-methods.js`**; **`channel.js`** rejects unknown methods with **`bare_os.rpc_unknown_method`** and wrong modules with **`bare_os.rpc_wrong_module`**. **`packages/bare-os-protocol/test.js`** asserts the registry stays non-empty.
|
||||
|
||||
@@ -29,9 +29,9 @@ Two complementary gates apply; neither is a blanket ban on the word “implement
|
||||
|
||||
| Script | Scope | Intent |
|
||||
| --- | --- | --- |
|
||||
| **`scripts/verify-runtime-no-incomplete-markers.mjs`** | Hand-authored **`kernel/init.js`** (generated bundle), **`kernel/lib/init/`**, **`kernel/lib/boot/`**, **`kernel/bin/*.js`**, **`packages/bare-os-booter/`** (excluding **`test.js`** and paths in **`docs/audit/runtime-marker-excludes.json`**) | No `**TODO` / `FIXME` / `HACK` / `XXX**` or `**throw new Error("Not implemented")`** in runtime booter/kernel sources. |
|
||||
| **`scripts/verify-runtime-no-incomplete-markers.mjs`** | Hand-authored **`kernel/init.js`** (generated bundle), **`kernel/lib/init/`**, **`kernel/lib/boot/`**, **`kernel/bin/*.js`**, **`packages/bare-os-booter/`** (excluding **`test.js`** and paths in **`docs/audit/runtime-marker-excludes.json`**) | No `**TODO` / `FIXME` / `HACK` / `XXX**` or **`throw new Error("Not implemented")`** in runtime booter/kernel sources. |
|
||||
| **`scripts/verify-bundle-markers.mjs`** | **`kernel/lib/bare/bundles/*.js`** only | Vendored Holepunch IIFEs: block incomplete-looking substrings unless the basename is allowlisted in **`docs/audit/bundle-marker-allowlist.json`** (policy: keep allowlist **empty**; fix via upstream bumps or **`scripts/sanitize-bare-bundles.mjs`**). |
|
||||
| **`scripts/verify-bundle-throws.mjs`** | Same bundles | Same idea for `**throw new Error("…not implemented…")**`-style messages; allowlist **`docs/audit/bundle-throw-allowlist.json`** stays empty by policy. |
|
||||
| **`scripts/verify-bundle-throws.mjs`** | Same bundles | Same idea for **`throw new Error("…not implemented…")`**-style messages; allowlist **`docs/audit/bundle-throw-allowlist.json`** stays empty by policy. |
|
||||
|
||||
**`packages/bare-os-coreutils`** and **`packages/bare-os-protocol`** are not scanned by **`verify-runtime-no-incomplete-markers`** today—still avoid shipping incomplete markers in shipped **`src/`** paths. **`packages/bare-os-booter/test.js`** may use **in-memory VFS fakes**, **stub HTTP hosts** (e.g. **`stub.example`** URLs), and **`AsyncFunction`**-loaded mini programs to isolate **`runBinCommand`**—those are **test doubles**, not the replicated OS. Production syscall bridges use explicit **`ENOTSUP`** / **`ENOSYS`** returns instead of placeholder throws. **`scripts/kernel-program-benchmark-harness.mjs`** suite IDs such as **`kernel_crypto_synthetic_benchmark`** name **synthetic timing fixtures** for release gates, not missing product code.
|
||||
|
||||
@@ -41,9 +41,9 @@ See also **[`docs/audit/PLACEHOLDER_BASELINE.md`](../docs/audit/PLACEHOLDER_BASE
|
||||
|
||||
## Brittle: `brittle-node` vs `brittle-bare`
|
||||
|
||||
- **`brittle-node`** runs most of **`packages/bare-os-booter/test.js`**—Hyperdrive, VFS, shell tokenizer, **`runBinCommand`** against real `/bin` bytes on disk (includes second-word (**`bits2`**) contract checks: `**@reboot**` / jitter parsing, param expansion v2, **`/proc`** stubs).
|
||||
- **`brittle-node`** runs most of **`packages/bare-os-booter/test.js`**—Hyperdrive, VFS, shell tokenizer, **`runBinCommand`** against real `/bin` bytes on disk (includes second-word (**`bits2`**) contract checks: **`@reboot`** / jitter parsing, param expansion v2, **`/proc`** stubs).
|
||||
- **`brittle-bare`** runs **`test.identity.js`** and protocol tests that need the **Bare** runtime (e.g. **bare-crypto** native pieces).
|
||||
- **`npm run test:bare**` (repo root) runs protocol tests plus the booter’s **`test:bare`** script (**`test.identity.js`**, **`test.bare-smoke.js`**) and seeder tests — a lighter Bare-native smoke path than the full **`brittle-node`** **`test.js`** harness.
|
||||
- **`npm run test:bare`** (repo root) runs protocol tests plus the booter’s **`test:bare`** script (**`test.identity.js`**, **`test.bare-smoke.js`**) and seeder tests — a lighter Bare-native smoke path than the full **`brittle-node`** **`test.js`** harness.
|
||||
|
||||
**Cold boot / `ctx.bare`:** parallel **`readFile`** for drive **`/lib/bare`** bundles is capped by **`BARE_OS_BARE_STDLIB_RESOLVE_CONCURRENCY`** (`**1`–`32**`, default **`4`**) in **`bare-os-ctx-bare.js`**; merge order stays deterministic.
|
||||
|
||||
@@ -65,9 +65,9 @@ CI installs **Bare** globally for parity (see `.github/workflows/ci.yml`). If id
|
||||
|
||||
Use the root scripts (see [README](../README.md)):
|
||||
|
||||
- **`npm run os:seeder**` and `**npm run os:booter**` (separate terminals) after **`ensure-pear-node-modules`**.
|
||||
- **`npm run os:seeder`** and **`npm run os:booter`** (separate terminals) after **`ensure-pear-node-modules`**.
|
||||
|
||||
Pear uses bundled **`node_modules`**; if resolution fails, run `**node scripts/ensure-pear-node-modules.mjs**` as documented in **`scripts/README.md`**.
|
||||
Pear uses bundled **`node_modules`**; if resolution fails, run **`node scripts/ensure-pear-node-modules.mjs`** as documented in **`scripts/README.md`**.
|
||||
|
||||
---
|
||||
|
||||
@@ -75,7 +75,7 @@ Pear uses bundled **`node_modules`**; if resolution fails, run `**node scripts/e
|
||||
|
||||
- **`BARE_OS_KERNEL_SELFTEST=1`** — stock [`kernel/init.js`](../kernel/init.js) runs a short **`execLine`** checklist after boot snippets.
|
||||
- **`BARE_OS_SELFTEST_FORMAT=tap`** — same self-test emits **TAP** lines on stderr (for parsers in CI).
|
||||
- **`node scripts/verify-kernel-seeder-parity.mjs**` — after a coreutils build, asserts **`kernel/`** and **`packages/bare-os-seeder/kernel/`** match and every **`kernel/bin/*`** file includes **`BARE_OS_BIN_API`** (root **`pretest`** runs this).
|
||||
- **`node scripts/verify-kernel-seeder-parity.mjs`** — after a coreutils build, asserts **`kernel/`** and **`packages/bare-os-seeder/kernel/`** match and every **`kernel/bin/*`** file includes **`BARE_OS_BIN_API`** (root **`pretest`** runs this).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ The **system** Hyperdrive is the **OS image**. You normally obtain it by **repli
|
||||
|
||||
**Seed capability attestation (optional):** the seeder may answer **`bare_os.capability_attestation`** with JSON from host env **`BARE_OS_SEED_CAPABILITY_ATTESTATION_JSON`** (for example a distro or **hyper-multisig** bundle). The guest does **not** verify signatures; operators verify on the host or out-of-band. **`BARE_OS_BIN_WORKER_OFFLOAD`** is a reserved gate for future isolated **`/bin`** execution—stock paths remain in-process unless a host integration supplies a worker bridge.
|
||||
|
||||
**Audit:** **`BARE_OS_AUDIT=1`** logs **`execLine`** activity to **`/var/log/bare-os/audit.log`**. **`BARE_OS_AUDIT_JSON=1`** uses JSON lines with `**auditSchemaVersion: 2**` on **`execLine`**, **delegate**, and **`httpFetch`** records; **`BARE_OS_AUDIT_REDACT=1`** (or **`true`**) masks common secret-like **`VAR=value`** patterns; `**BARE_OS_AUDIT_REDACT=TOKEN,PASSWORD`** masks named keys.
|
||||
**Audit:** **`BARE_OS_AUDIT=1`** logs **`execLine`** activity to **`/var/log/bare-os/audit.log`**. **`BARE_OS_AUDIT_JSON=1`** uses JSON lines with **`auditSchemaVersion: 2`** on **`execLine`**, **delegate**, and **`httpFetch`** records; **`BARE_OS_AUDIT_REDACT=1`** (or **`true`**) masks common secret-like **`VAR=value`** patterns; **`BARE_OS_AUDIT_REDACT=TOKEN,PASSWORD`** masks named keys.
|
||||
|
||||
**Delegated HTTP:** when the booter sets **`ctx.httpFetch`** from the host **`fetch`**, **`BARE_OS_HTTP_ALLOWLIST`** and **`BARE_OS_HTTP_DENYLIST`** restrict `**http`/`https**` URLs for `**curl`/`wget`** (host-pattern globs). Failed checks throw before the request; with audit on, allow/deny outcomes can be logged.
|
||||
|
||||
|
||||
@@ -22,9 +22,9 @@ Quick reference and repeated questions. **Canonical term definitions** (single s
|
||||
- **IPC fan-out** — `bareOsIpc.fanoutPublish` / `fanoutSubscribe` — multi-subscriber copies (bounded); disable with **`BARE_OS_IPC_FANOUT=0`**
|
||||
- **HTTP policy** — Optional **`BARE_OS_HTTP_ALLOWLIST`** / **`BARE_OS_HTTP_DENYLIST`** applied when the booter wraps **`ctx.httpFetch`**
|
||||
- **booterPhases** — Milestones recorded in **`/run/bare-os/boot.json`** (**`vfs`**, **`ctx`**, **`repl`**, **`initd`**, **`kernel_invoke`**) alongside kernel **`phases`**
|
||||
- **`~/.barerc`** — Personal shell init: **`export`**, **`alias`**, `**theme <preset>**`; parsed by **`loadBarerc`**. Builtin `**barerc reload`** reapplies without logout.
|
||||
- **`BARE_OS_THEME`** — Active color preset name; **`/bin/theme`**, **`~/.barerc`**, and `**ctx.bareOsApplyTheme()**` refresh **`BARE_OS_COLOR_*`** and usually **`LS_COLORS`**.
|
||||
- **`LS_COLORS`** — GNU-style colon-separated map consumed by `**ls --color**`; optional file via **`BARE_OS_DIRCOLORS`** and **`dircolors`**.
|
||||
- **`~/.barerc`** — Personal shell init: **`export`**, **`alias`**, **`theme <preset>`**; parsed by **`loadBarerc`**. Builtin **`barerc reload`** reapplies without logout.
|
||||
- **`BARE_OS_THEME`** — Active color preset name; **`/bin/theme`**, **`~/.barerc`**, and **`ctx.bareOsApplyTheme()`** refresh **`BARE_OS_COLOR_*`** and usually **`LS_COLORS`**.
|
||||
- **`LS_COLORS`** — GNU-style colon-separated map consumed by **`ls --color`**; optional file via **`BARE_OS_DIRCOLORS`** and **`dircolors`**.
|
||||
- **`BARE_OS_COLOR_DEPTH`** — **`truecolor`** (default), **`256`**, or **`16`** / **`ansi`** — downgrades truecolor sequences in **`BARE_OS_COLOR_*`** for the fish REPL only.
|
||||
|
||||
---
|
||||
@@ -35,7 +35,7 @@ Quick reference and repeated questions. **Canonical term definitions** (single s
|
||||
In-image scripts are not ES modules. Use inlining, bundling on the host, or the coreutils concat build. See [Chapter 5](05-modules-and-imports.md).
|
||||
|
||||
**How do I use npm packages on the device?**
|
||||
For packages listed in **`bare-module-manifest.json`**, use **`ctx.bare.<key>`** from **`run`** / **`start`** (see [Chapter 12](12-bare-modules-and-pear-ecosystem.md)). Otherwise bundle on the host, or add code to the **booter** package with normal `npm` deps.
|
||||
For packages listed in **`bare-module-manifest.json`**, use **`ctx.bare.<key>`** from `**run`** / **`start`** (see [Chapter 12](12-bare-modules-and-pear-ecosystem.md)). Otherwise bundle on the host, or add code to the **booter** package with normal `npm` deps.
|
||||
|
||||
**What’s the difference between `execLine` and `runBinCommand`?**
|
||||
`execLine` runs the **shell** (aliases, builtins, pipelines). `runBinCommand` runs **`argv`** directly. See [Chapter 3](03-kernel-boot-init.md).
|
||||
@@ -47,10 +47,10 @@ Follow [Chapter 6](06-extending-bin-coreutils.md): `src/foo.js`, `commands.mjs`,
|
||||
Not natively on the drive. Compile to JS on the host, then ship the output.
|
||||
|
||||
**Where is stdin for pipelines?**
|
||||
Shell sets **`ctx.shellStdin`** on a cloned context. Read it as a string. Coreutils use `**bareStdin(ctx)`** from prelude—user scripts must implement their own or copy the snippet. [Chapter 4](04-user-scripts-and-path.md).
|
||||
Shell sets **`ctx.shellStdin`** on a cloned context. Read it as a string. Coreutils use **`bareStdin(ctx)`** from prelude—user scripts must implement their own or copy the snippet. [Chapter 4](04-user-scripts-and-path.md).
|
||||
|
||||
**How do I exit the session from code?**
|
||||
Call **`ctx.requestBooterExit(code)**` (same as **`exit`** builtin / `/bin/exit`).
|
||||
Call **`ctx.requestBooterExit(code)`** (same as **`exit`** builtin / `/bin/exit`).
|
||||
|
||||
**Does `ctx.exitCode` control the host process exit?**
|
||||
The **host** exit code is managed by the booter after the kernel returns; utilities set **`ctx.exitCode`** for POSIX semantics inside the session. See booter `executeKernel` return path.
|
||||
@@ -62,7 +62,7 @@ Not part of the Bare OS contract for in-image code. Pear/Bare may provide some g
|
||||
A **reserved** API that **throws** until a worker/isolate story lands; see [Chapter 9](09-security-and-trust.md).
|
||||
|
||||
**How do I match my host terminal to Bare OS colors?**
|
||||
Use **`theme list**` / `**theme set <name>**` in the guest, then import the matching files under **[docs/themes](../docs/themes/README.md)** (Alacritty, Warp, iTerm2). Host **`TERM`** and **`COLORTERM`** are passed through for capability detection.
|
||||
Use **`theme list`** / **`theme set <name>`** in the guest, then import the matching files under **[docs/themes](../docs/themes/README.md)** (Alacritty, Warp, iTerm2). Host **`TERM`** and **`COLORTERM`** are passed through for capability detection.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -19,7 +19,7 @@ This chapter ties the Hyperdrive-resident kernel ([`kernel/init.js`](../kernel/i
|
||||
|
||||
- **`ctx.bareOsSubscribeBootEvent`** — Same structured events as `BARE_OS_BOOT_TRACE=ndjson` (phase, ms, sessionId); the booter also emits **`booter:*`** phases (**`vfs`**, **`ctx`**, **`repl`**, **`initd`**, **`kernel_invoke`**).
|
||||
- **`/proc/bare_os_quotas`** — Pipeline limits, `BARE_OS_EXEC_MAX_DEPTH`, IPC caps, session stats.
|
||||
- **`/proc/bare_os_resources`** / `**ctx.bareOsGetResourceStatus()`** — Unified snapshot for operators.
|
||||
- **`/proc/bare_os_resources`** / **`ctx.bareOsGetResourceStatus()`** — Unified snapshot for operators.
|
||||
- **`/proc/bare_os_features`** — Documented kernel-feature words **`bits`**, **`bits2`**, **`bits3`**, **`bits4`**, **`bits5`** (see `bare-os-protocol` exports).
|
||||
- **`/proc/bare_os/net_summary.json`** — Coalesced swarm / seed RPC hints for operators (topic, peer count, staging slot, replication queue, snapshot / firewall stats when present).
|
||||
- **`ctx.vfs.watch(path)`** — Hyperdrive-backed watch when `BARE_OS_VFS_WATCH` is not `0`; returns `{ watcher, destroy, … }`. With `BARE_OS_VFS_WATCH_PSEUDO=1`, may watch coalesced `/proc/bare_os/metrics_live.json`.
|
||||
@@ -45,15 +45,15 @@ Storage write limits use existing hooks (**`BARE_OS_VFS_QUOTA_*`**, **`BARE_OS_H
|
||||
|
||||
- **Mirror-drive hints** — `ctx.bareOsEmitMirrorDriveHint({ label?, key? })` emits `bare-os:mirror-drive-hint` on Node-style hosts for mirror-drive–style workflows (labels/keys only; trust boundaries unchanged).
|
||||
- **Release metadata** — Host can set `BARE_OS_PEAR_CHANNEL`, `BARE_OS_PEAR_RELEASE`, and `BARE_OS_IMAGE_DIGEST`; they appear in `/run/bare-os/boot.json`.
|
||||
- **`ctx.bareOsRequestPearReload()**` — Returns hints and env strings; the host `**pear-runtime` / `pear-runtime-updater**` must perform any real reload. A successful host reload can swap the Pear **booter** bundle so a new **`bare-module-manifest.data.mjs`** (from `**npm run sync:bare-manifest**` at staging time) takes effect; **`ctx.bareOsRequestPearReload`** does not rewrite **`ctx.bare`** in-process—expect a new guest boot for an updated host import list. Drive-only edits to **`/lib/bare/bare-module-manifest.json`** still merge bundles from the image without re-staging Pear.
|
||||
- **`ctx.bareOsPearUpdaterDelegate()**` (async, `**bareOsCtxApiVersion` 1.32.0+**) — Surfaces non-secret updater state without bundling **`pear-runtime-updater`** in the stock booter. Host options: set **`BARE_OS_PEAR_UPDATER_SNAPSHOT_JSON`** to a JSON string for a fixed operator snapshot, or **`BARE_OS_PEAR_UPDATER_MODULE`** to an ESM URL/path whose default export (or **`getPearUpdaterState`** / **`bareOsPearUpdaterSnapshot`**) is an `**async function**` returning a plain object (for example `**{ version, updating, updated }**` mirroring your **`PearRuntimeUpdater`** instance). See [`bare-os-pear-updater-bridge.js`](../packages/bare-os-booter/lib/bare-os-pear-updater-bridge.js).
|
||||
- **`ctx.bareOsRequestPearReload()`** — Returns hints and env strings; the host `**pear-runtime` / `pear-runtime-updater**` must perform any real reload. A successful host reload can swap the Pear **booter** bundle so a new **`bare-module-manifest.data.mjs`** (from **`npm run sync:bare-manifest`** at staging time) takes effect; **`ctx.bareOsRequestPearReload`** does not rewrite **`ctx.bare`** in-process—expect a new guest boot for an updated host import list. Drive-only edits to **`/lib/bare/bare-module-manifest.json`** still merge bundles from the image without re-staging Pear.
|
||||
- **`ctx.bareOsPearUpdaterDelegate()`** (async, `**bareOsCtxApiVersion` 1.32.0+**) — Surfaces non-secret updater state without bundling **`pear-runtime-updater`** in the stock booter. Host options: set **`BARE_OS_PEAR_UPDATER_SNAPSHOT_JSON`** to a JSON string for a fixed operator snapshot, or **`BARE_OS_PEAR_UPDATER_MODULE`** to an ESM URL/path whose default export (or **`getPearUpdaterState`** / **`bareOsPearUpdaterSnapshot`**) is an **`async function`** returning a plain object (for example **`{ version, updating, updated }`** mirroring your **`PearRuntimeUpdater`** instance). See [`bare-os-pear-updater-bridge.js`](../packages/bare-os-booter/lib/bare-os-pear-updater-bridge.js).
|
||||
|
||||
### System revision and initd (OTA-friendly ordering)
|
||||
|
||||
Host env **`BARE_OS_SYSTEM_REVISION_ID`**, **`BARE_OS_SYSTEM_REVISION_PENDING`**, and **`BARE_OS_SYSTEM_SLOT`** surface as **`ctx.bareOsSystemRevision`** and in **`/proc/bare_os/provenance`**. For Pear OTA flows, gate user units on pending work: e.g. **`ConditionPathExists=`** on a host-written marker file, or **`After=`** a unit whose **`ReadinessPath=`** checks **`/proc/bare_os/provenance`** JSON (parse in a small **`exec:`** gate). Combine with `**ctx.bareOsRequestPearReload()`** so the host applies the new bundle before initd restarts dependents.
|
||||
Host env **`BARE_OS_SYSTEM_REVISION_ID`**, **`BARE_OS_SYSTEM_REVISION_PENDING`**, and **`BARE_OS_SYSTEM_SLOT`** surface as **`ctx.bareOsSystemRevision`** and in **`/proc/bare_os/provenance`**. For Pear OTA flows, gate user units on pending work: e.g. **`ConditionPathExists=`** on a host-written marker file, or **`After=`** a unit whose **`ReadinessPath=`** checks **`/proc/bare_os/provenance`** JSON (parse in a small **`exec:`** gate). Combine with **`ctx.bareOsRequestPearReload()`** so the host applies the new bundle before initd restarts dependents.
|
||||
- **`git-pear`** — `/bin/git-pear help` documents Git-in-Pear (`gip-transport`, `gip-remote`, `git+pear://` remotes).
|
||||
- **HTTP** — Delegated **`curl`** / **`wget`** resolve **`fetch`** via **`ctx.httpFetch`** (policy-wrapped when the booter supplies it), then **`ctx.bare.fetch`** from host **`BARE_OS_BARE_MODULES`** and drive **`/lib/bare/bundles`**, then **`globalThis.fetch`**. **`ensureBareFetchGlobals`** may install **`bare-fetch`** or **`bare-https`** when no native fetch exists. **`BARE_OS_HTTP_ALLOWLIST`**, **`BARE_OS_HTTP_DENYLIST`**, **`BARE_OS_DNS_ALLOWLIST`**, and **`BARE_OS_TLS_PIN_SHA256`** (and **`init.bareOsCurlTls`** for **`curl`**) narrow outbound access. Canonical doc: [HTTP: curl and wget](../docs/reference/http-curl-and-wget.md).
|
||||
- **SSH (`bare-openssh`)** — The stock booter loads **`bare-ssh2`** from the workspace package **`bare-os-openssh`** (vendored upstream under **`vendor/bare-ssh2`**). Initd starts **`bare-openssh`** automatically unless disabled. `**npm run build -w bare-os-openssh**` stages **`/bin/sshd`**, **`/etc/ssh/sshd_config`**, and merged man pages into **`kernel/`** and the seeder mirror. Implementation: [`packages/bare-os-booter/lib/bare-openssh.js`](../packages/bare-os-booter/lib/bare-openssh.js). Host **`BARE_OS_SSH_LISTEN_PORT`** and **`BARE_OS_SSH_BIND_ALL`** are copied into guest **`vfs.env`** when set on the host.
|
||||
- **SSH (`bare-openssh`)** — The stock booter loads **`bare-ssh2`** from the workspace package **`bare-os-openssh`** (vendored upstream under **`vendor/bare-ssh2`**). Initd starts **`bare-openssh`** automatically unless disabled. **`npm run build -w bare-os-openssh`** stages **`/bin/sshd`**, **`/etc/ssh/sshd_config`**, and merged man pages into **`kernel/`** and the seeder mirror. Implementation: [`packages/bare-os-booter/lib/bare-openssh.js`](../packages/bare-os-booter/lib/bare-openssh.js). Host **`BARE_OS_SSH_LISTEN_PORT`** and **`BARE_OS_SSH_BIND_ALL`** are copied into guest **`vfs.env`** when set on the host.
|
||||
|
||||
## Building the image
|
||||
|
||||
|
||||
@@ -8,11 +8,11 @@ This chapter ties together **Holepunch `bare-*` packages**, the **Pear** host ru
|
||||
|
||||
1. **`/lib/bare` (system image, primary)** — **`bare-os-bare-libs`** builds **one IIFE per manifest row** into **`kernel/lib/bare/bundles/`** (mirrored on the seeded Hyperdrive). It also copies **`bare-module-manifest.json`** into **`kernel/lib/bare/`**. **`manifest.json`** lists successful bundles; stale **`bundles/*.js`** files are **pruned** on each successful build. At boot, drive bundles run **first** (unless **`BARE_OS_BARE_DRIVE_BUNDLES=0`**).
|
||||
|
||||
2. **Pear booter (`bare-module-manifest.data.mjs`)** — The stock booter package ships **`packages/bare-os-booter/lib/bare-module-manifest.json`** (normative JSON, edited or synced from the catalog) and a generated sibling **`bare-module-manifest.data.mjs`** that `**export default**` the same object. Under `**pear run**`, **`import.meta.url`** is `**pear://…**`; **`bare-fs`** cannot open **`pear:`** URLs passed as **`URL`** instances because normalization uses **`bare-url.fileURLToPath`** ( **`file:`** only). Therefore `**loadBareModuleManifest()**` reads the embedded **`.data.mjs`** on Pear so the manifest stays in the traced module graph. On **`file:`** dev checkouts it prefers the JSON on disk (live edits) and falls back to the embedded copy if the file is missing. Regenerate **`.data.mjs`** with `**npm run sync:bare-manifest**` or `**node scripts/generate-bare-module-manifest-data.mjs**`; CI runs `**npm run verify:manifest-data`**.
|
||||
2. **Pear booter (`bare-module-manifest.data.mjs`)** — The stock booter package ships **`packages/bare-os-booter/lib/bare-module-manifest.json`** (normative JSON, edited or synced from the catalog) and a generated sibling **`bare-module-manifest.data.mjs`** that **`export default`** the same object. Under **`pear run`**, **`import.meta.url`** is **`pear://…`**; **`bare-fs`** cannot open **`pear:`** URLs passed as **`URL`** instances because normalization uses **`bare-url.fileURLToPath`** ( **`file:`** only). Therefore **`loadBareModuleManifest()`** reads the embedded **`.data.mjs`** on Pear so the manifest stays in the traced module graph. On **`file:`** dev checkouts it prefers the JSON on disk (live edits) and falls back to the embedded copy if the file is missing. Regenerate **`.data.mjs`** with **`npm run sync:bare-manifest`** or **`node scripts/generate-bare-module-manifest-data.mjs`**; CI runs **`npm run verify:manifest-data`**.
|
||||
|
||||
3. **`ctx.bare` (host fallback)** — Unless **`BARE_OS_BARE_HOST_IMPORTS=0`**, the booter then `**import()**`s manifest packages **still missing** after drive merge. Under `**pear run**` (booter **`import.meta.url`** is **`pear:`**), `**bundle: true**` rows are **skipped** for host `**import()**` (keys come from **`/lib/bare/bundles/*`** only; avoids bare-module `**MODULE_NOT_FOUND` / referrer** errors for npm names like **`holesail`**). Under **`file:`** dev trees, `**bundle: true**` may still be host-imported when the drive bundle did not fill the key. Remaining host imports cover native or Bare-only packages that could not be bundled, or when the image is older than the manifest. Set **`BARE_OS_BARE_HOST_IMPORTS=0`** for a **fully image-local** `ctx.bare` (no Pear host `node_modules` participation). Disable all `ctx.bare` with **`BARE_OS_BARE_MODULES=0`**. For narrow harnesses, session env may set **`BARE_OS_BARE_HOST_SKIP_CTX_KEYS`** (comma-separated **`ctxKey`** list to skip) or **`BARE_OS_BARE_HOST_ONLY_CTX_KEYS`** (allowlist — only those keys are host-imported). Manifest rows may include optional **`tier`** (**`core`** vs extended) and **`risk`** (**`low`**, **`medium`**, **`high`**) for distributor policy; the build honors **`tier`** via **`BARE_OS_BUNDLE_TIER`**.
|
||||
3. **`ctx.bare` (host fallback)** — Unless **`BARE_OS_BARE_HOST_IMPORTS=0`**, the booter then **`import()`**s manifest packages **still missing** after drive merge. Under **`pear run`** (booter **`import.meta.url`** is **`pear:`**), **`bundle: true`** rows are **skipped** for host **`import()`** (keys come from **`/lib/bare/bundles/*`** only; avoids bare-module `**MODULE_NOT_FOUND` / referrer** errors for npm names like **`holesail`**). Under **`file:`** dev trees, **`bundle: true`** may still be host-imported when the drive bundle did not fill the key. Remaining host imports cover native or Bare-only packages that could not be bundled, or when the image is older than the manifest. Set **`BARE_OS_BARE_HOST_IMPORTS=0`** for a **fully image-local** `ctx.bare` (no Pear host `node_modules` participation). Disable all `ctx.bare` with **`BARE_OS_BARE_MODULES=0`**. For narrow harnesses, session env may set **`BARE_OS_BARE_HOST_SKIP_CTX_KEYS`** (comma-separated **`ctxKey`** list to skip) or **`BARE_OS_BARE_HOST_ONLY_CTX_KEYS`** (allowlist — only those keys are host-imported). Manifest rows may include optional **`tier`** (**`core`** vs extended) and **`risk`** (**`low`**, **`medium`**, **`high`**) for distributor policy; the build honors **`tier`** via **`BARE_OS_BUNDLE_TIER`**.
|
||||
|
||||
**Boot cold path / stdlib budget:** the stock booter measures drive merge + host **`import()**` resolution for **`ctx.bare`** and sets **`BARE_OS_BOOT_BARE_STDLIB_RESOLUTION_MS`** before the guest starts. Operators may set **`BARE_OS_BOOT_BUDGET_MS_BARE_STDLIB`** to log **`boot-perf.json`** / stderr warnings when resolution exceeds the budget; combine with **`BARE_OS_BUNDLE_TIER=core`** (or a smaller manifest) to shrink cold I/O. Use `**node scripts/kernel-microbench.mjs`** for regression-shaped timings (not a literal Pear cold boot).
|
||||
**Boot cold path / stdlib budget:** the stock booter measures drive merge + host **`import()`** resolution for **`ctx.bare`** and sets **`BARE_OS_BOOT_BARE_STDLIB_RESOLUTION_MS`** before the guest starts. Operators may set **`BARE_OS_BOOT_BUDGET_MS_BARE_STDLIB`** to log **`boot-perf.json`** / stderr warnings when resolution exceeds the budget; combine with **`BARE_OS_BUNDLE_TIER=core`** (or a smaller manifest) to shrink cold I/O. Use **`node scripts/kernel-microbench.mjs`** for regression-shaped timings (not a literal Pear cold boot).
|
||||
|
||||
4. **The full mirror (discoverability)** — A local checkout of Holepunch repos (for example **`holepunchto_repos`** under your Pear tooling tree) lists on the order of **150+** repositories whose names start with **`bare-`**. Many are **native addons**, **platform-specific** (mobile, GUI, FFmpeg, …), or **developer tools**. The **manifest** can list them for `ctx.bare`, but only rows that bundle cleanly become real drive IIFEs; the rest rely on host import or stubs until you trim the manifest.
|
||||
|
||||
@@ -28,9 +28,9 @@ This chapter ties together **Holepunch `bare-*` packages**, the **Pear** host ru
|
||||
npm install
|
||||
```
|
||||
|
||||
This refreshes **[`docs/bare-holepunch-catalog.json`](../docs/bare-holepunch-catalog.json)** (every **`holepunchto/bare-*`** repo plus npm **`latest`**, minus [`scripts/bare-catalog-overrides.json`](../scripts/bare-catalog-overrides.json)), then merges published packages into **[`bare-module-manifest.json`](../packages/bare-os-booter/lib/bare-module-manifest.json)** and **replaces** booter **`optionalDependencies`** from that catalog (anything not **`includedInBooter`** is dropped). CI runs `**npm run gen:bare-catalog:check**` so the committed catalog’s **`entries`** (and **`source`**) stay in sync with live npm/GitHub.
|
||||
This refreshes **[`docs/bare-holepunch-catalog.json`](../docs/bare-holepunch-catalog.json)** (every **`holepunchto/bare-*`** repo plus npm **`latest`**, minus [`scripts/bare-catalog-overrides.json`](../scripts/bare-catalog-overrides.json)), then merges published packages into **[`bare-module-manifest.json`](../packages/bare-os-booter/lib/bare-module-manifest.json)** and **replaces** booter **`optionalDependencies`** from that catalog (anything not **`includedInBooter`** is dropped). CI runs **`npm run gen:bare-catalog:check`** so the committed catalog’s **`entries`** (and **`source`**) stay in sync with live npm/GitHub.
|
||||
|
||||
**[`scripts/bare-ctx-import-overrides.json`](../scripts/bare-ctx-import-overrides.json)** adjusts a few packages for **`ctx.bare`** / esbuild: namespace exports (`**export: ***`), **`bare-node-runtime/global`** as a side-effect entry, etc. Edit this when npm packages have no default export or need a subpath.
|
||||
**[`scripts/bare-ctx-import-overrides.json`](../scripts/bare-ctx-import-overrides.json)** adjusts a few packages for **`ctx.bare`** / esbuild: namespace exports (**`export: *`**), **`bare-node-runtime/global`** as a side-effect entry, etc. Edit this when npm packages have no default export or need a subpath.
|
||||
|
||||
- **Add or remove a `ctx.bare` entry by hand** — Edit the manifest and booter **`dependencies`** / **`optionalDependencies`** as needed. The **`bundle`** field in the manifest is **legacy metadata**; **`bare-os-bare-libs`** attempts **every** row. Prefer the catalog + sync path for **`bare-*`** rows so **`ctxKey`** and semver ranges stay consistent.
|
||||
|
||||
@@ -40,13 +40,13 @@ This chapter ties together **Holepunch `bare-*` packages**, the **Pear** host ru
|
||||
npm run build -w bare-os-bare-libs
|
||||
```
|
||||
|
||||
Optional **`BARE_OS_BUNDLE_TIER=core`** builds only manifest rows with `**"tier": "core"**` (default tier when omitted). Use **`all`** or unset for the full catalog.
|
||||
Optional **`BARE_OS_BUNDLE_TIER=core`** builds only manifest rows with **`"tier": "core"`** (default tier when omitted). Use **`all`** or unset for the full catalog.
|
||||
|
||||
Then re-run the seeder so **`kernel/lib/bare/`** is copied into the Hyperdrive (the seeder invokes this build automatically when running from a `file:` URL). Check **`manifest.json`** → **`bundleStats`** after a build for how many IIFEs succeeded vs stub-only.
|
||||
|
||||
- **Node vs Pear/Bare** — On **Node**, **`buildBareCtxObjectFromHost`** skips manifest rows with `**nativeHint: true**` so optional Bare-native packages are not `**import()`**’d (avoids stray failures and unhandled rejections from addons). On **Pear/Bare**, the full manifest is loaded in parallel.
|
||||
- **Node vs Pear/Bare** — On **Node**, **`buildBareCtxObjectFromHost`** skips manifest rows with **`nativeHint: true`** so optional Bare-native packages are not **`import()`**’d (avoids stray failures and unhandled rejections from addons). On **Pear/Bare**, the full manifest is loaded in parallel.
|
||||
|
||||
- **Pear** — Continue to use **`node scripts/ensure-pear-node-modules.mjs packages/bare-os-booter**` before `**pear run**` so hoisted **`node_modules`** resolve like npm (see [PEAR-RUN.md](../docs/PEAR-RUN.md)). After any manifest or catalog edit, run `**npm run sync:bare-manifest**` before `**pear stage**` so **`bare-module-manifest.data.mjs`** matches the JSON.
|
||||
- **Pear** — Continue to use **`node scripts/ensure-pear-node-modules.mjs packages/bare-os-booter`** before **`pear run`** so hoisted **`node_modules`** resolve like npm (see [PEAR-RUN.md](../docs/PEAR-RUN.md)). After any manifest or catalog edit, run **`npm run sync:bare-manifest`** before **`pear stage`** so **`bare-module-manifest.data.mjs`** matches the JSON.
|
||||
|
||||
- **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)).
|
||||
|
||||
@@ -62,15 +62,15 @@ This chapter ties together **Holepunch `bare-*` packages**, the **Pear** host ru
|
||||
|
||||
## Pear IPC channel registry
|
||||
|
||||
**`ctx.bareOsPearIpcEmit(channel, payload)**` is a host bridge for [pear-ipc](https://github.com/holepunchto/pear-ipc)-style messaging. Well-known **`channel`** strings are listed in **`packages/bare-os-booter/lib/bare-os-pear-ipc-registry.js`** and mirrored as JSON under **`/proc/bare_os/pear_ipc.json`** (and the flat **`/proc/bare_os_pear_ipc_registry`** alias) so operators and kernels share one vocabulary for reload, mirror, and telemetry hints.
|
||||
**`ctx.bareOsPearIpcEmit(channel, payload)`** is a host bridge for [pear-ipc](https://github.com/holepunchto/pear-ipc)-style messaging. Well-known **`channel`** strings are listed in **`packages/bare-os-booter/lib/bare-os-pear-ipc-registry.js`** and mirrored as JSON under **`/proc/bare_os/pear_ipc.json`** (and the flat **`/proc/bare_os_pear_ipc_registry`** alias) so operators and kernels share one vocabulary for reload, mirror, and telemetry hints.
|
||||
|
||||
**`ctx.bareOsPearIpcRequest(channel, payload, { timeoutMs? })**` correlates **`bareOsIpcReqId`** on **`payload`** and awaits `**process.emit('bare-os:pear-ipc-response', { bareOsIpcReqId, result?, error? })**` on Node-style hosts. Use for request/response pairs alongside **`bareOsPearIpcEmit`**.
|
||||
**`ctx.bareOsPearIpcRequest(channel, payload, { timeoutMs? })`** correlates **`bareOsIpcReqId`** on **`payload`** and awaits **`process.emit('bare-os:pear-ipc-response', { bareOsIpcReqId, result?, error? })`** on Node-style hosts. Use for request/response pairs alongside **`bareOsPearIpcEmit`**.
|
||||
|
||||
**Mirror-drive hints:** **`ctx.bareOsEmitMirrorDriveHint({ label?, key? })**` emits **`bare-os:mirror-drive-hint`** for Holepunch-style snapshot workflows (see [kernel extensions](../docs/reference/kernel-extensions.md)).
|
||||
**Mirror-drive hints:** **`ctx.bareOsEmitMirrorDriveHint({ label?, key? })`** emits **`bare-os:mirror-drive-hint`** for Holepunch-style snapshot workflows (see [kernel extensions](../docs/reference/kernel-extensions.md)).
|
||||
|
||||
**Blind-peer style hint:** **`ctx.bareOsEmitBlindPeerHint(payload)**` forwards a **capped** JSON object on Pear IPC as **`bare_os_blind_peer_hint`** (topic/key material stays opaque strings; the guest does not verify blind-relay crypto).
|
||||
**Blind-peer style hint:** **`ctx.bareOsEmitBlindPeerHint(payload)`** forwards a **capped** JSON object on Pear IPC as **`bare_os_blind_peer_hint`** (topic/key material stays opaque strings; the guest does not verify blind-relay crypto).
|
||||
|
||||
**Host-only eval probe:** **`ctx.bareOsHostCapability('bundleEvaluate')**` is **`true`** when the host advertises **`BARE_OS_HOST_BUNDLE_EVALUATE=1`**, documenting an optional **[`cross-worker`](https://github.com/holepunchto/cross-worker)** / **[`bare-bundle-evaluate`](https://github.com/holepunchto/bare-bundle-evaluate)** path. Actual evaluation still happens **outside** the guest VFS trust boundary.
|
||||
**Host-only eval probe:** **`ctx.bareOsHostCapability('bundleEvaluate')`** is **`true`** when the host advertises **`BARE_OS_HOST_BUNDLE_EVALUATE=1`**, documenting an optional **[`cross-worker`](https://github.com/holepunchto/cross-worker)** / **[`bare-bundle-evaluate`](https://github.com/holepunchto/bare-bundle-evaluate)** path. Actual evaluation still happens **outside** the guest VFS trust boundary.
|
||||
|
||||
**`bare-fetch` content encodings (Capability word 6 doc alignment)** — When the host **`fetch`** implementation is Holepunch **`bare-fetch`**, **Content-Encoding** negotiation may include **`br`** and **`zstd`** in addition to **`gzip`** depending on platform support. In-image scripts should not assume a fixed encoding list; treat **`Accept-Encoding`** as host-defined. SPDX license identifiers on catalog rows (when present) are **metadata for distributors**, not a runtime guarantee inside the guest.
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@ Operators running Bare OS as part of a service should maintain a **subprocessor
|
||||
|
||||
- NDJSON lifecycle / telemetry: see **`BARE_OS_LIFECYCLE_SCHEMA_VERSION`** (**10** in stock tree) and rows in [`docs/reference/compatibility-matrix.md`](../docs/reference/compatibility-matrix.md).
|
||||
- OTel-inspired lines: **`otlSchemaVersion: 7`**, example [`kernel/etc/bare-os/otel-jsonl.example.json`](../kernel/etc/bare-os/otel-jsonl.example.json), schema [`docs/schemas/otel-bare-os-jsonl.schema.json`](../docs/schemas/otel-bare-os-jsonl.schema.json).
|
||||
- Audit JSON: **`auditSchemaVersion: 7**` (delegate depth / Capability word 9–10 RPC classes); optional **`requestSmugglingClass`** remains default **`none`** in stock emitters where applicable.
|
||||
- Audit JSON: **`auditSchemaVersion: 7`** (delegate depth / Capability word 9–10 RPC classes); optional **`requestSmugglingClass`** remains default **`none`** in stock emitters where applicable.
|
||||
|
||||
## Related
|
||||
|
||||
|
||||
@@ -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). 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).
|
||||
**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).
|
||||
|
||||
---
|
||||
|
||||
@@ -36,7 +36,7 @@ This project is **experimental research software**. APIs described here follow t
|
||||
- You want to drop a **`hello.js`** on your personal drive and run it from the shell without misunderstanding the execution model.
|
||||
- You plan to add or change a **`/bin`** utility and need the no-`import` contract and build steps.
|
||||
- You are modifying the **booter** or **seeder** Pear apps and need to separate “host ESM” from “in-image `AsyncFunction`.”
|
||||
- You are debugging **`async function run(ctx, argv)**` or `**start(ctx)`** and need a map of `ctx`.
|
||||
- You are debugging **`async function run(ctx, argv)`** or **`start(ctx)`** and need a map of `ctx`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ Bare OS advertises optional booter and seed-channel capabilities as a versioned
|
||||
|
||||
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-capabilities-index.md), [`docs/reference/kernel-extensions.md`](../../docs/reference/kernel-extensions.md), and relevant handbook chapters.
|
||||
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-capabilities-index.md), [`docs/reference/kernel-extensions.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.
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ Operators asked for a **bounded** path to validate WebAssembly modules in the sa
|
||||
|
||||
## Decision
|
||||
|
||||
- Expose **`ctx.bareOsWasmKernelCompile(buf, opts?)**` only when the host sets **`BARE_OS_WASM_KERNEL=1`** (or **`true`**), copied into session **`shellEnv`** like other passthrough keys.
|
||||
- Expose **`ctx.bareOsWasmKernelCompile(buf, opts?)`** only when the host sets **`BARE_OS_WASM_KERNEL=1`** (or **`true`**), copied into session **`shellEnv`** like other passthrough keys.
|
||||
- Implementation calls **`WebAssembly.compile`** on a **size-capped** **`Uint8Array`** (default max **512 KiB**; override via **`opts.maxBytes`**). **No instantiation**, **no imports**, and **no execution** — compile-only probe suitable for static validation and export-name listing when the engine exposes **`WebAssembly.Module.exports`**.
|
||||
- Code lives in **`packages/bare-os-booter/lib/bare-os-wasm-kernel.js`** and uses **`globalThis`** only (Bare/V8).
|
||||
|
||||
|
||||
@@ -24,7 +24,7 @@ Prefer **boot stage** / **boot step** / **capability word** language in new pros
|
||||
## `ctx` methods
|
||||
|
||||
- New APIs use **`bareOs…`** camelCase on the injected context object.
|
||||
- Canonical boot hook names: **`bareOsRegisterBootStepHook`**, **`bareOsInvokeBootStepHooks`**, **`bareOsEmitBareBootStepHint`**. Legacy `**…BootPhase…`** methods remain as thin wrappers.
|
||||
- Canonical boot hook names: **`bareOsRegisterBootStepHook`**, **`bareOsInvokeBootStepHooks`**, **`bareOsEmitBareBootStepHint`**. Legacy **`…BootPhase…`** methods remain as thin wrappers.
|
||||
|
||||
## `/proc` and wire-visible paths
|
||||
|
||||
|
||||
Reference in New Issue
Block a user