Raven Scott
0d7b27bea8
Expose /proc/bare_os/metrics.prom (kernel counter OpenMetrics) and /proc/bare_os/protomux.json (alias registry snapshot). Extend VFS routing, readdir, pseudo watch, and bare_os_proc_index to schema 8; restore flat /proc entries for syscalls and process_table with sort order matching tests. Add ctx.bareOsAuditLogAppendBatch and bump BARE_OS_CTX_API_VERSION to 1.30.0 with d.ts and compatibility-matrix updates. Harden swarm peer ban backoff with jitter on the exponential window. Refresh conformance matrix, environment appendix, booter package doc, and handbook chapters for proc paths, param expansion V3, vault at rest, and baretop snapshot keys. Align baretop-snapshot with bareOsReadBareTopSnapshot.
/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.