# /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`** summarizes esbuild success versus stub-only placeholders (per-entry success/failure counts and paths).
- **`bundles/*.js`** — One file per manifest row. Successful builds are full IIFE bundles; failures are no-op stubs (see the file header comment). Regenerate with **`npm run build -w bare-os-bare-libs`**.

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](../../../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. Re-run the seeder so peers replicate the updated system drive.

---

## When builds fail (stubs)

If **`bundleStats`** shows failures, open the corresponding **`bundles/*.js`** stub: the header usually names the missing dependency or unsupported pattern. Fix the catalog entry, adjust esbuild options in **`packages/bare-os-bare-libs/build.mjs`**, or mark the module optional in the manifest until the ecosystem catches up. **`npm run smoke:bare-manifest`** guards required imports listed in the manifest smoke list.

---

_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.