bare-operating-system/packages/bare-os-seeder/kernel/lib/bare

/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 · bare-os-bare-libs package README.

---

On this page

• What gets staged
• Boot order: drive bundles vs host imports
• Environment toggles
• Trust model
• Regenerating bundles
• 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. 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 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.