105 lines
9.8 KiB
Markdown
105 lines
9.8 KiB
Markdown
# Glossary (canonical)
|
||
|
||
Short definitions for terms used across the user manual, handbook, developer guide, and reference. For **developer-oriented** FAQs and implementation tips, see [developer-guide/10-glossary-and-faq.md](../developer-guide/10-glossary-and-faq.md). For **exact** version strings and matrices, see [docs/reference/compatibility-matrix.md](reference/compatibility-matrix.md).
|
||
|
||
---
|
||
|
||
## A–Z
|
||
|
||
**AsyncFunction** — `Object.getPrototypeOf(async function () {}).constructor`; used by the booter to evaluate in-image JavaScript with parameters such as `ctx` and `argv`. See [developer-guide/01-two-runtimes-host-vs-image.md](../developer-guide/01-two-runtimes-host-vs-image.md).
|
||
|
||
**Bare** — JavaScript runtime in the Holepunch ecosystem; Bare OS targets Bare semantics for code that runs **in** the image. The **host** may use Node.js during development.
|
||
|
||
**Booter** — The `bare-os-booter` application: joins Hyperswarm, replicates Hyperdrives, builds the guest **VFS** and **`ctx`**, runs **`/boot/init.js`**, shell, initd, cron, and selected host delegates. After successful boot, eligible nodes can mirror block `0` and captured seed RPC snapshots for cold joiners. Package reference: [package-bare-os-booter.md](reference/package-bare-os-booter.md).
|
||
|
||
**`agent`** — In-guest ReAct coding agent (`/bin/agent`). Default backend is **QVAC** (local); **REST** (OpenAI-compatible) is optional. Full guest admin by default (denylist). Config and workspace live under **`~/.agent/`**. Discord **`/agent`** is the same session. See **`man agent`** and [users-manual ch.4](../users-manual/04-shell-path-and-scripts.md).
|
||
|
||
**`bareOsCtxApiVersion`** — Semver for the guest-visible **`ctx`** contract; defined in `packages/bare-os-booter/lib/bare-os-ctx-api.js`. History: [packages/bare-os-booter/CHANGELOG.md](../packages/bare-os-booter/CHANGELOG.md).
|
||
|
||
**`BARE_OS_KERNEL_FEATURE_BITS_DOC`** — Integer that versions kernel feature-bit **documentation** and governance; keep aligned with [developer-guide/adr/001-kernel-feature-bits-governance.md](../developer-guide/adr/001-kernel-feature-bits-governance.md). Source: `packages/bare-os-protocol/lib/kernel-feature-bits.js`.
|
||
|
||
**Booter boot steps** — Canonical milestones: **`vfs`** → **`ctx`** → **`repl`** → **`initd`** → **`kernel_invoke`** (see [architecture/KERNEL_CONTRACT.md](architecture/KERNEL_CONTRACT.md) and `packages/bare-os-booter/lib/bare-os-boot-phases.js`).
|
||
|
||
**`bare-holesail`** — Initd unit wrapping upstream **holesail** (Holepunch-style TCP/UDP tunnels; upstream package is AGPL-3.0). **Managed** mode persists connections under **`BARE_OS_HOLESAIL_STATE`** (default `**~/.holesail/state.json**`): each **server** row keeps a stable **`seed`** (64-hex or z32 ctor material) and a shareable **`key`** (**`hs://…`** after `**ready()**`). Stock auto-rows `**bare-www-<port>`** and **`bare-ssh-<port>`** use the same file. Handbook: [Chapter 4](../handbook/04-the-booter-runtime.md).
|
||
|
||
**`bare-os-www`** — Initd static HTTP server for **`~/.www`** on **`127.0.0.1`** (default port **8088**); pairs with managed **Holesail** for **`bare-www-<port>`** in `**~/.holesail/state.json`**. Handbook: [Chapter 4 — bare-os-www](../handbook/04-the-booter-runtime.md#bare-os-www-static-http-for-www).
|
||
|
||
**`bare-openssh`** — SSH-2 server (**`bare-ssh2`**) on the loopback **sshd** port (default **2222**); managed Holesail can add `**bare-ssh-<port>`** to the **same** **`state.json`** as **`bare-www-*`** (**`BARE_OS_SSH_HOLESAIL`**). Handbook: [Chapter 4](../handbook/04-the-booter-runtime.md).
|
||
|
||
**Capability words** — Structured feature masks on **`bare_os.capabilities`** RPC and under **`/proc/bare_os_features`**. Described in [compatibility-matrix.md](reference/compatibility-matrix.md) and [kernel-capabilities-index.md](reference/kernel-capabilities-index.md).
|
||
|
||
**Corestore** — Storage backend for Hypercores/Hyperdrives on the host; default locations often under **`~/.bare-os/`**. Env vars: [environment-and-posix-appendix.md](reference/environment-and-posix-appendix.md).
|
||
|
||
**Coreutils** — `bare-os-coreutils`: sources and build for **`/bin`** utilities and merged **`man.json`**. See [package-bare-os-coreutils-and-ci.md](reference/package-bare-os-coreutils-and-ci.md).
|
||
|
||
**QVAC** — QuantumVerse Automatic Computer: in-process local LLM for **`/bin/agent`** via **`ctx.bareOsQvac*`** (`@qvac/sdk` + llamacpp). Default agent backend. Disable with **`BARE_OS_SKIP_QVAC=1`** / **`--skip-qvac`**.
|
||
|
||
**`ctx`** — Context object passed to **`start(ctx)`** (`/boot/init.js`) and **`run(ctx, argv)`** (user scripts and `/bin` tools). Full map: [developer-guide/02-the-context-object.md](../developer-guide/02-the-context-object.md).
|
||
|
||
**`ctx.bare`** — Frozen map of curated modules exposed to in-image code per manifest and optional **`/lib/bare`** bundles. See [developer-guide/12-bare-modules-and-pear-ecosystem.md](../developer-guide/12-bare-modules-and-pear-ecosystem.md).
|
||
|
||
**`ctx.pear`** — Frozen map of Pear development packages (`pear-build`, `pear-bundle`, `bare-bundle-compile`, …) exposed when **`BARE_OS_BARE_MODULES`** is enabled. Used by **`/bin/pear`**.
|
||
|
||
**App Store (`/bin/appstore`)** — Guest command to install packages from **`pear://`** links into **`~/.appstore/`** (or **`/mnt/appstore`**) and **launch** entry scripts in the shell. See [guides/guest-pear-and-appstore-workflow.md](guides/guest-pear-and-appstore-workflow.md).
|
||
|
||
**`/bin/pear`** — Guest Pear dev CLI: **`init`**, **`stage`**, **`release`**, **`seed`**. Publishes apps to HDMS and **`pear://`** links without host Pear CLI. Same guide as App Store.
|
||
|
||
**Guest** — Pre-login session identity; typically **`BARE_OS_IDENTITY=guest`**. Contrast with logged-in user and vault flows in [handbook/05-identity-vault-and-hdms.md](../handbook/05-identity-vault-and-hdms.md).
|
||
|
||
**HDMS** — Hyperdrive mount subsystem: optional extra drives under **`/mnt`**. Handbook: [Chapter 5](../handbook/05-identity-vault-and-hdms.md).
|
||
|
||
**Holepunch** — Ecosystem (Bare, Hyperdrive, Hyperswarm, Pear, etc.) that Bare OS integrates with.
|
||
|
||
**Hyperdrive** — Merkle-addressed, replicated filesystem abstraction; Bare OS uses a **system** drive (image) and a **personal** drive (mutable per node).
|
||
|
||
**Hyperswarm** — DHT-based peer discovery; Bare OS uses a topic derived from **`bare-os-v1`**. Protocol: [package-bare-os-protocol.md](reference/package-bare-os-protocol.md).
|
||
|
||
**In-image** — Code whose source lives on a drive and is executed via **AsyncFunction** (not ESM **`import`** in the usual sense). See [developer-guide/05-modules-and-imports.md](../developer-guide/05-modules-and-imports.md).
|
||
|
||
**Kernel (guest)** — **`/boot/init.js`**: **`async function start(ctx)`**; session entry after the booter constructs **`ctx`**. Distinct from the **host** booter process.
|
||
|
||
**MBR (Bare OS)** — 512-byte bootstrap block on the system image with magic **`BIOS`** and Hyperdrive discovery key material (not a PC BIOS partition table). Seeder is canonical; eligible booted peers may mirror the same block `0` for availability. Layout: [handbook/03-protocol-and-disk.md](../handbook/03-protocol-and-disk.md).
|
||
|
||
**Pear** — Packaging and distribution layer for Bare apps; seeder and booter ship as Pear projects. Host: [PEAR-RUN.md](./PEAR-RUN.md). Guest authoring/install: [guides/guest-pear-and-appstore-workflow.md](guides/guest-pear-and-appstore-workflow.md).
|
||
|
||
**Personal drive** — Writable Hyperdrive for **`$HOME`**, **`/.bare/`**, vault snapshots, logs, and user files. Routed by the VFS alongside the read-only system tree.
|
||
|
||
**Protomux** — Multiplexed protocol framing; channel name **`bare-os-v1`** pairs with the swarm topic. Reference: [package-bare-os-protocol.md](reference/package-bare-os-protocol.md).
|
||
|
||
**Seeder** — The `bare-os-seeder` application: stages **`kernel/`** into the system Hyperdrive, publishes the canonical MBR, and joins the swarm. Reference: [package-bare-os-seeder.md](reference/package-bare-os-seeder.md).
|
||
|
||
**Stock image** — The default tree from this repository’s **`kernel/`**, built **`/bin`**, and **`man.json`**, without private forks—used as the compatibility baseline.
|
||
|
||
**System drive** — Replicated OS image: **`/bin`**, **`/boot`**, **`/etc`**, etc. Treated as shared and replaceable from the swarm’s perspective.
|
||
|
||
**Tier-1 `/bin**` — Command names shipped as `**/bin/***` on the system drive; the authoritative list is **`COREUTILS_COMMANDS`** in **`packages/bare-os-coreutils/lib/commands.mjs`**. Root **`pretest`** runs **`scripts/verify-man-coverage.mjs`** so every Tier-1 name has a matching **`man.json`** page.
|
||
|
||
**SwarmDisk** — Booter-side disk implementation that reads the OS image from replicated storage.
|
||
|
||
**VFS** — Virtual file system: path classes, mounts, synthetic **`/proc`**, **`/run`**, **`/sys`**. Policy sketch: [vfs-path-classes.md](reference/vfs-path-classes.md).
|
||
|
||
**VFS path classes** — Rules for which paths map to system vs personal drive or synthetic trees. Reference: [vfs-path-classes.md](reference/vfs-path-classes.md).
|
||
|
||
---
|
||
|
||
## Shell and theme (guest)
|
||
|
||
**`~/.barerc`** — Personal shell init file: **`export`**, **`alias`**, **`theme <preset>`**; parsed by **`loadBarerc`**. Builtin **`barerc reload`** reapplies without logout.
|
||
|
||
**`BARE_OS_THEME`** — Active color preset; **`/bin/theme`**, **`~/.barerc`**, and **`ctx.bareOsApplyTheme()`** refresh **`BARE_OS_COLOR_*`** and usually **`LS_COLORS`**.
|
||
|
||
**`LS_COLORS`** — GNU-style colon-separated map for **`ls --color`**; optional file via **`BARE_OS_DIRCOLORS`** and **`dircolors`**.
|
||
|
||
**`BARE_OS_COLOR_DEPTH`** — **`truecolor`** (default), **`256`**, or **`16`** / **`ansi`** — affects truecolor sequences for the fish REPL when downgraded.
|
||
|
||
---
|
||
|
||
## See also
|
||
|
||
- [docs/faq.md](faq.md)
|
||
- [docs/troubleshooting.md](troubleshooting.md)
|
||
- [User manual](../users-manual/README.md)
|
||
- [Handbook](../handbook/README.md)
|
||
- [Developer guide](../developer-guide/README.md)
|
||
- [Reference hub](reference/README.md)
|