# Placeholder and incomplete-code baseline (authoritative)

This document classifies incomplete surfaces as of the kernel hardening pass. It is the reference for risk triage and closure tracking.

**Navigation:** [KERNEL_CONTRACT](../architecture/KERNEL_CONTRACT.md) · [documentation home](../README.md) · [contributing to docs](../CONTRIBUTING-DOCS.md).

## Severity legend

- **P0**: Affects trust, boot, security, or remote RPC surfaces.
- **P1**: User-visible CLI or guest `/bin` behavior diverges from documented contracts.
- **P2**: Operational or developer-experience gaps.
- **P3**: Third-party generated artifacts; behavior owned by upstream Bare/Holepunch bundles.

## P0 — Host RPC and swarm disk (`disk.os`)

| Item                         | Location                                                                 | Resolution |
| ---------------------------- | ------------------------------------------------------------------------ | ---------- |
| Empty `searchLocal` / `execRpc` | `packages/bare-os-booter/index.js` (wired via `bare-os-disk-os-bridge.js`) | Implemented: path substring search on system Hyperdrive; whitelisted `bare_os.*` RPC methods. |

## P1 — Guest `/bin` and host delegates

| Item                         | Location                                      | Resolution |
| ---------------------------- | --------------------------------------------- | ---------- |
| `systemctl` / `journalctl` error-only scripts | `kernel/bin/systemctl`, `kernel/bin/journalctl` | Implemented: call `ctx.bareOsRunSystemctlCli` when present (parity with `curl`). |
| `ssh-keygen` passphrase rejection | `packages/bare-os-booter/lib/services/ssh-keygen-cli.js` | Implemented: PBKDF2 + ChaCha20-Poly1305 sealed envelope (`bareOsKeySchema: 2`). |
| `basenc` base16-only messaging | `packages/bare-os-coreutils/src/basenc.js`    | Implemented: `--base64` / `--base32` (RFC-style) in addition to `--base16`. |
| `hostid` / `users` “stub” UX | `packages/bare-os-coreutils/src/hostid.js`, `users.js` | Implemented: stable hostid from Ed25519 public key when identity unlocked; `users` documents active session. |
| WARC / archive delegates labeled placeholder | `packages/bare-os-booter/lib/host/host-delegate-registry.js` | Implemented: `warc-cli.js`, `archive-cli.js` (archive maps to ustar `tar`). |
| hrpc / bundlebee / sidecar / pear-runtime-matrix | `host-delegate-registry.js` + `host-bridge-cli.js` | **Implemented:** basename delegates run probe/status/hint/cap CLIs; **`hrpc request`** now uses a functional stock **`ctx.bareOsHrpcRequest`** (validated built-in routes + allowlist) while still permitting host override when **`BARE_OS_HRPC_BRIDGE_WIRED`** is set; env JSON for allowlist / pear matrix probes. |

## P2 — Scripts and documentation

| Item                         | Location                    | Notes |
| ---------------------------- | --------------------------- | ----- |
| ~~`gen-ctx-client-stub.mjs`~~ → **`gen-ctx-client-helper.mjs`** | `scripts/` | Renamed; generates TS client version constant aligned with **`BARE_OS_CTX_API_VERSION`**. |
| Man / reference “placeholder” prose | `docs/`, `kernel/share/man/` | **Closed for stock tree:** `node scripts/verify-man-coverage.mjs` gates **186** Tier-1 commands ( **`COREUTILS_COMMANDS`** in **`packages/bare-os-coreutils/lib/commands.mjs`** ); regenerate merged man DB with **`npm run build -w bare-os-coreutils`** and **`npm run build -w bare-os-openssh`** when pages change. Narrative alignment: [handbook ch.9 §5](../../handbook/09-posix-utilities-shell-and-vfs.md#5-bin-utilities-catalog). |

## Extension multisig gate (stock kernel)

| Item | Location | Resolution |
| ---- | -------- | ---------- |
| Optional Pear multisig before **`kernel.ext.d`** | [`kernel/lib/init/init-main.js`](../../kernel/lib/init/init-main.js) (`BARE_OS_EXTENSION_MULTISIG_VERIFY`, **`/etc/bare-os/pear.multisig.json`**) | Implemented: validates **`{ signers, quorum }`** shape when the gate is active; strict boot may require the file via **`BARE_OS_BOOT_POLICY_REQUIRE_PEAR_MULTISIG`**. No additional first-party stubs — optional **`hyper-multisig verify`** remains a seeder / host **`PATH`** tool (**`BARE_OS_HYPER_MULTISIG_VERIFY`**). |

## P3 — Vendored `kernel/lib/bare/bundles/*.js`

Upstream-generated IIFEs may contain `TODO` comments, `NOT_IMPLEMENTED` helpers, and abstract stream throws. These are **not** first-party kernel policy; they are rebuilt from `bare-os-bare-libs` and mirrored under `packages/bare-os-seeder/kernel/`. **Inventory:** committed **`docs/audit/bundle-health.json`** (per-bundle bytes, regenerated by **`npm run build -w bare-os-bare-libs`**). **Marker gate:** **`scripts/verify-bundle-markers.mjs`** + **`docs/audit/bundle-marker-allowlist.json`**. **Throw gate:** **`scripts/verify-bundle-throws.mjs`** + **`docs/audit/bundle-throw-allowlist.json`** for `throw new Error("not implemented")` phrasing. **Maintainer hygiene:** optional **`BARE_OS_HOLEPUNCH_DRIFT_TIER1=1`** exercises **`tier1Repos[]`** in **`docs/audit/holepunch-drift-repos.json`** against local clones (see **`scripts/verify-holepunch-clone-drift.mjs`**). Closure strategy: upstream version bumps, allowlist shrink, or bundle post-processing — see **`kernel/lib/bare/README.md`**.

## Subsystem matrix

| Subsystem   | First-party status | Bundle / vendor |
| ----------- | ------------------ | --------------- |
| Booter / ctx | Hardened in this pass | — |
| Protocol    | No TODO scan in this file | Wire contracts in `bare-os-protocol` |
| Guest kernel (`kernel/lib/boot`) | CI: `verify-runtime-no-incomplete-markers.mjs` | — |
| Coreutils   | basenc / hostid / users updated | — |

## Review cadence

Re-run a full-repo scan before each release and append a dated section here when new gaps are introduced or closed. Maintainer automation: **`npm run audit:placeholder-baseline`** writes [`placeholder-baseline-scan.json`](placeholder-baseline-scan.json) (first-party TODO/stub phrase sweep including **`packages/bare-os-coreutils/src`**). Root **`pretest`** runs **`npm run audit:placeholder-baseline:check`**, which fails if the live scan finds hits not already recorded in the committed scan JSON or in [`placeholder-baseline-allowlist.json`](placeholder-baseline-allowlist.json) (use allowlist only for time-boxed exceptions). Compare hits to this document and **`verify-runtime-no-incomplete-markers.mjs`**. **`npm run audit:holepunch-clones`** refreshes [`holepunch-clone-sync-report.json`](holepunch-clone-sync-report.json) and [`holepunch-lockfile-drift.json`](holepunch-lockfile-drift.json). Optional strict clone lag: [`holepunch-freshness-gate.json`](holepunch-freshness-gate.json) + **`scripts/verify-holepunch-clone-freshness.mjs`** (root **`pretest`**, default **`enabled: false`**).

## 2026-04-05 — P3 bundle allowlists at target

| Closure | Notes |
| ------- | ----- |
| **Empty marker/throw allowlists** | **`docs/audit/bundle-marker-allowlist.json`** and **`bundle-throw-allowlist.json`** remain **empty**; **`node scripts/verify-bundle-markers.mjs`** and **`verify-bundle-throws.mjs`** pass on stock tree. Vendored IIFEs stay sanitized via **`scripts/sanitize-bare-bundles.mjs`** during **`npm run build -w bare-os-bare-libs`**. |

## 2026-04-05 — Placeholder-baseline scan hygiene

| Closure | Notes |
| ------- | ----- |
| **Zero stub-phrase hits** | `shell.js`: renamed internal `expandCmdsubstPlaceholder` → `expandCmdsubstEmbedded` so **`audit:placeholder-baseline`** does not false-positive on “Placeholder”. `index.js`: **`sendmsg`** error note uses “unsupported” instead of “not implemented” (behavior unchanged; wording only). |

## 2026-04-05 — Guest identity / migration / VFS policy

| Closure | Notes |
| ------- | ----- |
| **Guest `/.bare` deny** | VFS + identity hooks: sealed **`account`** / **`vault`** / rotation NDJSON; **`BARE_OS_GUEST_BARE_READ_ALL`** override; fish history reload + shell job reset on `**login`/`logout`**. |
| **Legacy root migration** | **`/.bare-os/migration/legacy-root-v1.json`**; **`BARE_OS_PERSONAL_ROOT_MIGRATE`**; guest skips lift when account exists. |
| **Acct prefix layout** | **`BARE_OS_PERSONAL_ACCT_PREFIX`** nests `**home`/`tmp`/`var/log**` under `**/.bare-os/acct/<id>/`**. |

## 2026-04-04 — Doc / sysfs alignment closure

| Closure | Notes |
| ------- | ----- |
| **`/sys` narrative** | [handbook/04-the-booter-runtime.md](../../handbook/04-the-booter-runtime.md) updated: **`/sys/class/net/lo`** is a **single** sysfs-shaped file (not separate **`operstate`** / **`carrier`** paths); stock booter **`sysClassNetLoText`** in [`packages/bare-os-booter/index.js`](../../packages/bare-os-booter/index.js) derives **`carrier`** from Hyperswarm peer count. **`/sys/devices/virtual/`** is an empty navigable tree. |
| **Kernel program guide** | [developer-guide/kernel-program.md](../../developer-guide/kernel-program.md): **`kernel-home-snapshot`** documented as implemented; CI microbench pointer updated to **`kernel-microbench.mjs`**. |
| **Protocol doc** | [docs/reference/package-bare-os-protocol.md](../../docs/reference/package-bare-os-protocol.md): **`msgRead`** described as wire shape for Protomux message 0, not an incomplete placeholder. |
| **P2 man placeholder row** | Remains for ongoing man ↔ behavior drift; re-triage per release. |
| **Protomux / Hyperswarm lock contract** | Booter test + [`packages/bare-os-booter/fixtures/protomux-hyperswarm-lock.json`](../../packages/bare-os-booter/fixtures/protomux-hyperswarm-lock.json) pin resolved **`package-lock.json`** versions; bump both when upgrading the wire stack. |
| **Bundle marker / throw allowlists** | **`bundle-marker-allowlist.json`** and **`bundle-throw-allowlist.json`** are **empty**. Upstream stream-base-class and ICO encode **`Error`** strings are rewritten during **`sanitize-bare-bundles.mjs`** (invoked from **`bare-os-bare-libs`** build) so **`verify-bundle-throws`** passes with no per-file exemptions. Re-run **`npm run build -w bare-os-bare-libs`** after manifest/catalog changes. |