# /lib/bare (system image)

Self-contained **`ctx.bare` support** on the **system** Hyperdrive: Holepunch **Bare** packages bundled as IIFE scripts the booter can execute without a traditional Node module graph on the drive.

**Documentation:** [Developer guide ch.12](../../../developer-guide/12-bare-modules-and-pear-ecosystem.md) · [bare-os-bare-libs package README](../../../packages/bare-os-bare-libs/README.md).

---

## On this page

- [What gets staged](#what-gets-staged)
- [Boot order: drive bundles vs host imports](#boot-order-drive-bundles-vs-host-imports)
- [Environment toggles](#environment-toggles)
- [Trust model](#trust-model)
- [Regenerating bundles](#regenerating-bundles)
- [When builds fail (stubs)](#when-builds-fail-stubs)

---

## What gets staged

- **`bare-module-manifest.json`** — Copy of the booter manifest (same keys and packages as host resolution). Tells the runtime which logical module names exist.
- **`manifest.json`** — Drive loader index: **`bundles`** lists IIFE paths that assign into **`globalThis.__bare_os_stdlib__`**; **`bundleStats`** counts attempted bundles; **`bundleDiagnostics`** lists each bundle’s byte size (same data as **`docs/audit/bundle-health.json`**).
- **`bundles/*.js`** — One esbuild IIFE per catalog entry. The bare-libs build is **fail-fast** (esbuild errors abort; no stub placeholders). Stale **`*.js`** left from older tiered builds are **pruned** on each successful build. Regenerate with **`npm run build -w bare-os-bare-libs`** (updates **`docs/audit/bundle-health.json`**).

At boot the booter runs **drive bundles first**, then (unless **`BARE_OS_BARE_HOST_IMPORTS=0`**) fills any missing keys via host **`import()`** so development iterations can patch a single package without re-seeding the entire drive.

---

## Boot order: drive bundles vs host imports

1. **Seeded bundles** win for keys they actually populate — they are part of the trusted image, same class as **`/bin`**.
2. **Host imports** run only for keys still missing after bundle evaluation, keeping local checkout workflows fast.
3. Disabling host imports (**`BARE_OS_BARE_HOST_IMPORTS=0`**) approximates production Pear behavior where only the drive contents exist.

---

## Environment toggles

The authoritative list is in the [environment appendix](../../../docs/reference/environment-and-posix-appendix.md). Names that operators mention most often alongside **`/lib/bare`**:

- **`BARE_OS_BARE_HOST_IMPORTS`** — Set to **`0`** / **`false`** to forbid host **`import()`** fallback (drive-only resolution).
- Related Pear **`ctx.bare`** toggles and HTTP allow lists are documented in **[PEAR-RUN.md](../../../docs/PEAR-RUN.md)** and the booter package reference.

---

## Trust model

**Trusted image only:** executing these bundles is equivalent to running seeded **`/bin`** utilities. Do not copy arbitrary third-party IIFEs into **`kernel/lib/bare/bundles/`** without reviewing them the same way you would review a new setuid binary on a Unix system.

---

## Regenerating bundles

1. Edit **`packages/bare-os-booter/lib/bare-module-manifest.json`** or bundle sources under **`packages/bare-os-bare-libs/`** as needed.
2. Run **`npm run build -w bare-os-bare-libs`** — output lands in **`kernel/lib/bare/`** (and CI expects **`packages/bare-os-seeder/kernel/`** to match **`kernel/`** byte-for-byte afterward).
3. Mirror **`kernel/`** into **`packages/bare-os-seeder/kernel/`** (same tree) so **`scripts/verify-kernel-seeder-parity.mjs`** passes — typically `rsync -a --delete kernel/ packages/bare-os-seeder/kernel/` from the repo root after init/bundle changes.
4. Re-run the seeder so peers replicate the updated system drive.

**Order with coreutils:** from repo root, prefer **`npm run build -w bare-os-coreutils && npm run build -w bare-os-bare-libs && npm run bundle:kernel`** before parity check (matches root **`pretest`**).

---

## When builds fail

Esbuild prints the failing **`ctxKey`** and package. Fix **`bare-module-manifest.json`**, adjust **`build.mjs`** (plugins, platform), or mark the entry **`optional`** / **`bundle: false`** when host-only resolution is intended. **`npm run smoke:bare-manifest`** guards required imports listed in the manifest smoke list.

**CI:** **`scripts/verify-bundle-health.mjs`** checks **`docs/audit/bundle-health.json`** against on-disk sizes; **`scripts/verify-bundle-markers.mjs`** and **`scripts/verify-bundle-throws.mjs`** gate incomplete-looking substrings / **`Error`** messages. **`scripts/sanitize-bare-bundles.mjs`** (run from this build) normalizes known upstream HTTP helpers, stream-base-class messages, and ICO encode paths so **`docs/audit/bundle-marker-allowlist.json`** and **`docs/audit/bundle-throw-allowlist.json`** stay **empty**.

---

_Note:_ This file is copied to **`kernel/lib/bare/README.md`** (and the vendored seeder tree) by **`bare-os-bare-libs`** build. Links are written for the **`kernel/lib/bare/`** path; **`verify-doc-links`** skips this template path because its on-disk location differs.