@@ -14,7 +14,7 @@ Single place to compare **protocol**, **booter `ctx` API**, **feature-bit docume
## Version artifacts
**`bareOsCtxApiVersion`** (current stock: **`1.47.0`**) — Defined in [`packages/bare-os-booter/lib/bare-os-ctx-api.js`](../../packages/bare-os-booter/lib/bare-os-ctx-api.js). This is the semver string for the documented **`ctx`** contract; bump it when stable guest-visible behavior changes.
**`bareOsCtxApiVersion`** (current stock: **`1.48.0`**) — Defined in [`packages/bare-os-booter/lib/bare-os-ctx-api.js`](../../packages/bare-os-booter/lib/bare-os-ctx-api.js). This is the semver string for the documented **`ctx`** contract; bump it when stable guest-visible behavior changes.
**`BARE_OS_KERNEL_FEATURE_BITS_DOC`** (current stock: **`15`**) — Exported from [`packages/bare-os-protocol/lib/kernel-feature-bits.js`](../../packages/bare-os-protocol/lib/kernel-feature-bits.js). It versions the feature-bit documentation and related governance; keep it aligned with [`developer-guide/adr/001-kernel-feature-bits-governance.md`](../../developer-guide/adr/001-kernel-feature-bits-governance.md).
@@ -38,7 +38,7 @@ Single place to compare **protocol**, **booter `ctx` API**, **feature-bit docume
- **Seeder** must answer **`bare_os.capabilities`** with **`kernelCapabilityWords`** (wire **v2**, **`kernelCapabilityWireVersion`: 2**) when using a current **`bare-os-protocol`** build. **`BARE_OS_SEED_CAP_STRICT`** requires that object and full stock coverage per semantic key.
- **Offline LKG** booters skip the swarm peer wait when **`BARE_OS_OFFLINE_LKG_BOOT=1`** and **`BARE_OS_LKG_SYSTEM_KEY_HEX`** is set; the system drive must already contain **`/boot/init.js`** in Corestore.
- **Pear host** — Couple **`pear-runtime`** / **`pear-runtime-updater`** with this tree’s **`bare-os-protocol`** and **`bareOsCtxApiVersion`** (see [PEAR-RUN.md](../../PEAR-RUN.md)); the stock **`bare-module-manifest.json`** does **not** list **`pear-runtime`** because it is not an npm-resolvable guest bundle—hosts wire it via imports and **`BARE_OS_PEAR_RUNTIME_VERSION`** when needed.
- **Pear host** — Couple **`pear-runtime`** / **`pear-runtime-updater`** with this tree’s **`bare-os-protocol`** and **`bareOsCtxApiVersion`** (see [PEAR-RUN.md](../PEAR-RUN.md)); the stock **`bare-module-manifest.json`** does **not** list **`pear-runtime`** because it is not an npm-resolvable guest bundle—hosts wire it via imports and **`BARE_OS_PEAR_RUNTIME_VERSION`** when needed.
-`BARE_OS_VFS_UNION_PREFIXES` — Booter / VFS — Comma-separated logical path prefixes where **`readFile`** may union system + overlay sources.
-`BARE_OS_VFS_UNION_WRITE_DENY` — Booter / VFS — When **`1`** / **`true`**, block **`writeFile`** / **`unlink`** on paths under union read prefixes (read-only union overlay).
@@ -81,6 +81,7 @@ The list below is one **bullet per variable** in the form **name — component
-`BARE_OS_HYPERBEE_GUEST_INDEX` — Booter / extensions — When **`1`** / **`true`**, **`ctx.bareOsHyperbeeGuestHint()`** documents optional **hyperbee2**-style guest indexes for P2P metadata (host/extension must supply the module; see [ADR-hyperbee-guest-index.md](../architecture/ADR-hyperbee-guest-index.md)).
-`BARE_OS_PEAR_INSPECT` — Booter — When **`1`** / **`true`**, emit **`bare-os:pear-inspect-snapshot`** on the host process after **`ctx`** is wired (non-secret snapshot only).
-`BARE_OS_VFS_BIN_INDEX_BUILD` — Booter — When **`1`** / **`true`**, writes **`/.bare-os/index/bin-manifest.json`** (**schema 2**, **`namesDigest`**) on the personal drive for large images (see **`bare-os-bin-index.js`**); **`bareOsVfsBatchWrite`** on **`bin/*`** rebuilds it when enabled.
-`BARE_OS_VFS_SYSTEM_IMAGE_WRITE` — Booter / VFS — When **`1`** / **`true`**, allow **`vfs.writeFile`** on the **system** Hyperdrive for paths that are normally read-only (**`/bin/*`**, **`/lib/*`**, …) so hosts can mutate the image or run warm-cache tests; default remains guest read-only. ACLs and **`/.bare`** guest rules still apply.
-`BARE_OS_BOOT_MANIFEST` — Stock kernel — Enable digest check of **`/etc/bare-os/boot.manifest.json`**.
-`BARE_OS_BOOT_MANIFEST_SIGN` — Stock kernel + booter — When **`1`**, require valid Ed25519 signature file **`/etc/bare-os/boot.manifest.sig`** (see **`BARE_OS_BOOT_MANIFEST_PUBKEY_HEX`**).
-`BARE_OS_BOOT_MANIFEST_PUBKEY_HEX` — Booter / kernel — 64 hex chars — public key for signed boot manifest verification.
@@ -139,6 +140,7 @@ The list below is one **bullet per variable** in the form **name — component
-`BARE_OS_AUTOPASS_INVITE_URL` — `/proc/bare_os/hdms_hints.json` — Optional operator invite URL hint (guest does not fetch it).
-`BARE_OS_BIN_WORKER_OFFLOAD` — **`runBinCommand`** (Bare) — When **`1`** on **Bare** (not Node), may run **`awk`** / **`sed`** / **`jq`** in a **`bare-worker`** thread; falls back in-process on failure. With **`BARE_OS_BIN_WORKER_ALLOW`** (comma list) for future expansion (**`textproc:*`**, **`mathproc:*`**, **`mediaproc:*`**, **`sysproc:*`**, **`metaproc:*`**, … — see [kernel-extensions.md](kernel-extensions.md)).
-`BARE_OS_BIN_WORKER_CPU_MS_MAX` — Booter — Optional per-invocation CPU-time budget hint (ms) for **`bare-worker`** **`/bin`** offload; surfaced in operator metrics / worker budget snapshots.
-`BARE_OS_BIN_WORKER_WASM_MS_MAX` — Booter — When **> 0** (capped at **3_600_000**), stock **`bare-worker`** offload **`terminate()`**s the thread after that many milliseconds and returns **`{ ok: false, reason: 'wasm_time_budget' }`** to **`runBinCommand`** (falls back to in-process behavior).
-`BARE_OS_EXEC_LINE_BUDGET_MS` — Booter — Reject top-level **`execLine`** when cumulative wall time exceeds budget.
-`BARE_OS_DELEGATE_MAX_PER_MIN` — Host delegates — Global per-minute cap (sliding window) on delegate invocations.
@@ -161,7 +163,8 @@ The list below is one **bullet per variable** in the form **name — component
-`BARE_OS_MIRROR_READ_KEY` — Replication proc / mirror hint — Optional mirror drive key string included in replication snapshot for operators.
-`BARE_OS_PEAR_TRUST_JSON` — `/proc/bare_os/pear_trust.json` — Optional operator JSON merged into trust summary (guest does not verify multisig).
-`BARE_OS_HOST_BUNDLE_EVALUATE` — `ctx.bareOsHostCapability` — When **`1`**, advertise host **`bundleEvaluate`** for optional cross-worker / **`bare-bundle-evaluate`** paths (host-only).
-`BARE_OS_SHELL_PIPEFAIL` — Shell — When **`1`** / **`true`**, a pipeline’s exit status is the first failing stage (bash-like); default is POSIX-like **last stage** status only.
-`BARE_OS_SHELL_PIPEFAIL` — Shell — When **`1`** / **`true`**, or after **`set -o pipefail`**, a pipeline’s exit status is the first failing stage (bash-like); default is POSIX-like **last stage** status only.
-`BARE_OS_SHELL_PIPESTATUS` — Shell — When **`1`** / **`true`**, after each pipeline the space-separated stage exit codes are written to **`BARE_OS_PIPESTATUS`** in **`vfs.env`**.
-`BARE_OS_SHELL_ERREXIT` — Shell — When **`1`** / **`true`**, or after **`set -e`**, stop running further top-level **`;`**-separated commands once a foreground command returns non-zero (subset of POSIX **errexit**; **`if` / `while` / `for`** condition lists are not affected the same way as bash — see handbook ch.9).
-`BARE_OS_VFS_WARM_CACHE_INVALIDATE_ON_APPEND` — Booter — When **`1`** / **`true`**, register **`append`** listeners on the system Hyperdrive metadata and blob Hypercores (when present) to clear **`/bin`** / **`lib/bare`** warm read caches on replication (**offline-first** safety; may increase churn on busy drives).
-`BARE_OS_VFS_WARM_CACHE_PREFIX_INVALIDATE` — Booter — When **`1`** / **`true`**, evict warm-cache entries for **`/bin`**, **`/etc`**, **`/lib`**, **`/usr`**, and configured personal prefixes when replicated core lengths increase (see **`metrics_live.replicationLive.warmPrefixInvalidate`**).
@@ -241,7 +244,7 @@ The list below is one **bullet per variable** in the form **name — component
**Normative declared profile:** [POSIX_DECLARED_PROFILE.md](../architecture/POSIX_DECLARED_PROFILE.md) (version **`BARE_OS_POSIX_PROFILE_VERSION`** in `bare-os-protocol`).
- **Pear working directory** — Some Pear/Bare hosts expose **`process.cwd()`** as an empty string. The booter’s **[`packages/bare-os-booter/lib/paths.js`](../../packages/bare-os-booter/lib/paths.js)** falls back to **`bare-os``os.cwd()`** when resolving **`packageRootDir`** and Corestore path helpers. **`ctx.bare`** manifest selection under **`pear://`** uses embedded **`bare-module-manifest.data.mjs`** (not host FS), so an empty **`process.cwd()`** does not block boot; see [PEAR-RUN.md](../../PEAR-RUN.md) and [Developer guide ch.12](../../developer-guide/12-bare-modules-and-pear-ecosystem.md).
- **Pear working directory** — Some Pear/Bare hosts expose **`process.cwd()`** as an empty string. The booter’s **[`packages/bare-os-booter/lib/paths.js`](../../packages/bare-os-booter/lib/paths.js)** falls back to **`bare-os``os.cwd()`** when resolving **`packageRootDir`** and Corestore path helpers. **`ctx.bare`** manifest selection under **`pear://`** uses embedded **`bare-module-manifest.data.mjs`** (not host FS), so an empty **`process.cwd()`** does not block boot; see [PEAR-RUN.md](../PEAR-RUN.md) and [Developer guide ch.12](../../developer-guide/12-bare-modules-and-pear-ecosystem.md).
- **VFS** — Two-drive unified paths; **`$HOME`** maps to the personal Hyperdrive; writable mounts under **`/mnt`** when HDMS allows. **`mkdir`/`rmdir`**, **`chmod`** (octal + symbolic subset), **`symlink`/`readlink`**, **`stat`/`lstat`**, **`rm`** recursive, **`watch()`** on Hyperdrive paths (optional host **`BARE_OS_VFS_WATCH=0`** to disable). Synthetic **`/proc`**, **`/sys`**, **`/run`**, **`/dev`** for introspection (quotas JSON, boot JSON, initd snapshot, union policy, seed handshake, virtual registry, etc.); **`/dev/shm/<name>`** holds in-memory named segments (**`getconf _POSIX_SHARED_MEMORY_OBJECTS`** is **`1`**). Optional union read overlays (**`BARE_OS_VFS_UNION_PREFIXES`**) with optional write deny (**`BARE_OS_VFS_UNION_WRITE_DENY`**). Empty dirs use **`.bareos_empty`** (same idea as `git-fs-adapter`).
- **Proc budget** — Stock booter **caches****`/proc/bare_os/syscalls.json`** text until **`vfs.bareOsClearWarmReadCaches()`** (shared invalidation with **`/bin`** / **`/lib/bare`** warm read cache, including **`bareOsVfsBatchWrite`** bin/lib puts).
@@ -34,7 +34,7 @@ See also [Kernel subsystem map](../architecture/kernel-subsystems.md) and [ADR 0
### 12.2b Corestore / swarm suspend–resume bridge
- **[`lib/corestore-host-lifecycle.js`](../../packages/bare-os-booter/lib/corestore-host-lifecycle.js)** — Registers one-shot hooks so guest **`ctx.bareOsRegisterSuspendHook`** / **`bareOsRegisterResumeHook`** call host **`corestore`** / **`hyperswarm`** **`suspend()`** / **`resume()`** when those methods exist (mobile sleep, Pear lifecycle). **`bareOsCorestoreSnapshotOperatorHint`** remains a documentation-only sketch (guest does not invoke **`corestore-snapshot`**).
- **[`lib/corestore-host-lifecycle.js`](../../packages/bare-os-booter/lib/corestore-host-lifecycle.js)** — Registers one-shot hooks so guest **`ctx.bareOsRegisterSuspendHook`** / **`bareOsRegisterResumeHook`** call host **`corestore`** / **`hyperswarm`** **`suspend()`** / **`resume()`** when those methods exist (mobile sleep, Pear lifecycle). **Non-goal (stock booter):** automatic **`corestore-snapshot`** / frozen peer images from the guest — operators replicate Hyperdrives via swarm + personal-drive export of keys when needed; **`bareOsCorestoreSnapshotOperatorHint`** in **`/proc`** is an advisory field only (no guest RPC that invokes**`corestore-snapshot`**).
@@ -28,7 +28,7 @@ Enable with **`BARE_OS_POSIX_SOCKET_FD_BRIDGE=1`**. Requires **`ctx.bare`** to e
- **Ancillary control** on **`sendmsg`**: non-empty binary **`control`** / **`controllen`**, or malformed **`cmsgs`**, → **`ENOTSUP`** + **`ancillaryReject`**.
- **`recvmsg`**: **`controllen` 0**; **`msgHdr.name`** filled from UDP **`rinfo`** when present.
- **`BARE_OS_POSIX_SOCKET_SCM_RIGHTS=1`**: **`cmsgs`** and **`msgHdr.cmsgs`** may contain only objects **`{ fds: number[] }`** (logical SCM_RIGHTS). Each fd is duplicated; the syscall result includes **`scmRightsLocalDup: [{ from, to }]`**. Cap via **`BARE_OS_POSIX_SOCKET_SCM_RIGHTS_MAX_FDS`** (default **4**). Idle / listen / bound bridge sockets reject dup. **`shutdown`** refcount-per-alias destroys the underlying slot when the last fd closes. With this env set, the stock bridge implements **logical** fd duplication end-to-end (not host **`SCM_RIGHTS`**); without it, any non-empty ancillary payload remains **`ENOTSUP`** as documented in **`ancillaryControl`**.
- **`BARE_OS_POSIX_SOCKET_SCM_RIGHTS=1`**: **`cmsgs`** and **`msgHdr.cmsgs`** may contain only objects **`{ fds: number[] }`** (logical SCM_RIGHTS). Each fd is duplicated; the syscall result includes **`scmRightsLocalDup: [{ from, to }]`**. Cap via **`BARE_OS_POSIX_SOCKET_SCM_RIGHTS_MAX_FDS`** (default **4**, max **16**). Idle / listen / bound bridge sockets reject dup. **`shutdown`** refcount-per-alias destroys the underlying slot when the last fd closes. With this env set, the stock bridge implements **logical** fd duplication on **`sendmsg`** (same guest address space — not host **`SCM_RIGHTS`** over a real kernel boundary); **`recvmsg`** continues to return **`controllen: 0`** because ancillary data is not queued on datagrams. Without **`BARE_OS_POSIX_SOCKET_SCM_RIGHTS`**, any non-empty ancillary payload remains **`ENOTSUP`** as documented in **`ancillaryControl`**. Parser unit tests: **`packages/bare-os-booter/test.socket-scm-rights.js`**.
## TCP **`shutdown`** / half-close
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Raven Scott