Files

T

Raven Scott ebee9576c8 feat(booter): POSIX/P2P kernel roadmap — sockets, disk.os, VFS, docs

- Bump bareOsCtxApiVersion to 1.46.0 and POSIX profile 1.0.10; sync
  syscalls example, process table, compatibility matrix, CHANGELOGs.
- Socket FD bridge: passive SOCK_DGRAM bind/connect/send path, poll
  readiness; bareOsPosixPoll monotonic timeouts via bare-hrtime.
- disk.os: replication_operator_sketch schema 2; cap-gated
  replication_operator_intent + audit; enrich protomux proc JSON.
- VFS: route /.bare/** to personal drive; optional
  BARE_OS_PERSONAL_VAULT_INDEX_CACHE_MS readdir TTL cache.
- Boot policy: p2pAdmission (peerAllowlistHex, hyperswarmBootstrap) in
  schema + kernel init merge into ctx.env when unset.
- Coreutils/booter getconf: expand _SC_* coverage; shell wait -n under
  BARE_OS_SHELL_POSIX_MODE; seeder multisig verify → security_posture.
- Tests: vfs /.bare routing; test.bare-smoke + test:bare; bench schema 2.
- Docs: syscall-socket-contract, handbook/env/kernel-extensions,
  holepunch drift pretest note, vault threat model multisig section.
- Drop hyperbee from bare-os-booter package.json dependencies (if that
  change is part of this commit).

2026-04-05 01:46:17 -04:00

4.9 KiB

Raw Blame History

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

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

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

Edit packages/bare-os-booter/lib/bare-module-manifest.json or bundle sources under packages/bare-os-bare-libs/ as needed.
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).
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.
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.

4.9 KiB Raw Blame History Unescape Escape