Raven Scott
433cb2176d
Migrate booter and seeder host file/path access to bare-fs/bare-path via package imports while keeping Node defaults for dev/CI; extend CI to reject bare fs/path imports on Pear surfaces. Wire bareOsPearUpdaterDelegate through pear-runtime-updater-style dynamic import, expand process table and signal routing, add system RO alias mount and optional Hyperbee bin hint, protomux proc metrics, cron dom/dow OR rule, boot-perf detail with optional bare-hrtime, /lib/bare warm cache with metrics_live warmReadCache, vault threat-model and users-manual crypto pointers, Pear inspect emit, gated shell break/continue, kernel-ext-graph output and example schema, POSIX compliance matrix + verifier in pretest. Harden ACL sidecar evaluation toward POSIX-like mask semantics; tighten test/expr/ printf edge cases and man JSON; add blind-bootstrap/DHT registry protocol test and troubleshooting notes; refresh handbook, KERNEL_CONTRACT, environment appendix, and reference hub links.
/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:bundleslists IIFE paths that assign intoglobalThis.__bare_os_stdlib__;bundleStatscounts attempted bundles;bundleDiagnosticslists each bundle’s byte size (same data asdocs/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*.jsleft from older tiered builds are pruned on each successful build. Regenerate withnpm run build -w bare-os-bare-libs(updatesdocs/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
- Seeded bundles win for keys they actually populate — they are part of the trusted image, same class as
/bin. - Host imports run only for keys still missing after bundle evaluation, keeping local checkout workflows fast.
- 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 to0/falseto forbid hostimport()fallback (drive-only resolution).- Related Pear
ctx.baretoggles 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
- Edit
packages/bare-os-booter/lib/bare-module-manifest.jsonor bundle sources underpackages/bare-os-bare-libs/as needed. - Run
npm run build -w bare-os-bare-libs— output lands inkernel/lib/bare/(and CI expectspackages/bare-os-seeder/kernel/to matchkernel/byte-for-byte afterward). - Re-run the seeder so peers replicate the updated system drive.
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 flags TODO / NOT_IMPLEMENTED substrings in bundles unless listed in docs/audit/bundle-marker-allowlist.json (shrink over time).
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.