feat: ctx 1.37.0, /bin/link, blind-peer proc gate, and CI/docs follow-ups
- Bump bareOsCtxApiVersion to 1.37.0; sync syscalls.example.json and ctx helper - Add ctx.bareOsReadSnapshotHintsJson mirroring snapshot_hints proc JSON - Gate blind_relay_router / blind_pairing_sketch / relay_geo_hint behind BARE_OS_PROC_BLIND_PEER_RELAY_HINTS; passthrough + env appendix docs - Add POSIX link(1) via coreutils (link.js, man, commands list, kernel bin) - Fix JSDoc in verify-runtime-no-incomplete-markers (avoid */ in glob text) - Align posix-conformance-matrix bareOsSyscallOps with getconf (select, umask) - Add verify-holepunch-clone-drift.mjs (opt-in pretest), holepunch-drift-repos.json, originMainHead in sync-holepunch-clones report - Tests: warm /bin cache clear, blind proc stub, protomux pool schema 2, glob cap - Docs: systemctl man, compatibility matrix boot.policy pins, handbook ch.5 vault/proc note, package-bare-os-booter, kernel-extensions, developer-guide ctx - CHANGELOG and bare-os-ctx.d.ts updates for subprocess bridge and mirror mounts
This commit is contained in:
Raven Scott
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"generatedAt": "2026-04-05T03:03:09.364Z",
|
||||
"generatedAt": "2026-04-05T03:18:48.758Z",
|
||||
"normativeManifest": "packages/bare-os-booter/lib/bare-module-manifest.json",
|
||||
"buildTool": "packages/bare-os-bare-libs/build.mjs",
|
||||
"bundles": [
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"schema": 1,
|
||||
"note": "Repo directory names under BARE_OS_HOLEPUNCH_CLONES_ROOT checked when BARE_OS_HOLEPUNCH_DRIFT_CHECK=1 (see scripts/verify-holepunch-clone-drift.mjs). Leave empty for CI; add names you keep cloned locally for release gates.",
|
||||
"repos": []
|
||||
}
|
||||
@@ -14,7 +14,7 @@ Single place to compare **protocol**, **booter `ctx` API**, **feature-bit docume
|
||||
|
||||
## Version artifacts
|
||||
|
||||
**`bareOsCtxApiVersion`** (current stock: **`1.36.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.37.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).
|
||||
|
||||
@@ -28,6 +28,8 @@ Single place to compare **protocol**, **booter `ctx` API**, **feature-bit docume
|
||||
|
||||
**`/proc/bare_os/syscalls.json`** — Schema **4** extends schema **3** with **`fdModel`** (logical FD table pointers) and **`signalModel`** (synthetic signal vocabulary). Schema **3** added **`opsDetail`**, **`errnoHints`**, and **`posixProfile`**. Example payload: [`kernel/etc/bare-os/syscalls.example.json`](../../kernel/etc/bare-os/syscalls.example.json); JSON Schema: [`docs/schemas/bare-os-syscalls.schema.json`](../schemas/bare-os-syscalls.schema.json).
|
||||
|
||||
**Boot policy pins** — [`kernel/etc/bare-os/boot.policy.example.json`](../../kernel/etc/bare-os/boot.policy.example.json) shows **`extensionSignerPinsV3`**, **`extensionSignerPinsV4`**, and **`kernelExtensionHashPins`** for **`kernel.ext.d`** governance, plus semver gates (**`requireCtxApiMin`**, **`requireBooterSemver`**, **`requireProtocolPackageMin`**, …). Keep this file aligned with [`docs/schemas/boot.policy.schema.json`](../schemas/boot.policy.schema.json) when adding fields.
|
||||
|
||||
---
|
||||
|
||||
## Peer assumptions
|
||||
|
||||
@@ -1,16 +1,16 @@
|
||||
// Auto-generated by scripts/gen-ctx-client-helper.mjs — do not edit by hand.
|
||||
|
||||
/** Canonical `ctx` API semver from `packages/bare-os-booter/lib/bare-os-ctx-api.js`. */
|
||||
export const BARE_OS_CTX_API_CLIENT_VERSION = '1.36.0' as const
|
||||
export const BARE_OS_CTX_API_CLIENT_VERSION = '1.37.0' as const
|
||||
|
||||
/** Relative path to the hand-maintained TypeScript contract (schema source of truth). */
|
||||
export const BARE_OS_CTX_DTS_SOURCE = 'packages/bare-os-booter/lib/bare-os-ctx.d.ts' as const
|
||||
|
||||
/** Approximate count of `bareOs…` members in the DTS (diagnostic only; regenerate on contract edits). */
|
||||
export const BARE_OS_CTX_DTS_BAREOS_MEMBER_APPROX = 146 as const
|
||||
export const BARE_OS_CTX_DTS_BAREOS_MEMBER_APPROX = 147 as const
|
||||
|
||||
/** Byte length of `bare-os-ctx.d.ts` when this file was generated. */
|
||||
export const BARE_OS_CTX_DTS_BYTES = 17869 as const
|
||||
export const BARE_OS_CTX_DTS_BYTES = 18289 as const
|
||||
|
||||
/** Pointers for external client generators (OpenAPI / JSON Schema follow-ups). */
|
||||
export const BARE_OS_CTX_SCHEMA_HINT = {
|
||||
|
||||
@@ -136,6 +136,9 @@ The list below is one **bullet per variable** in the form **name — component
|
||||
- `BARE_OS_SHELL_NOGLOB` — Shell — When **`1`**, pathname expansion is disabled (**`set -f`** sets this; **`set +f`** clears).
|
||||
- `BARE_OS_GLOB_MAX_MATCHES` — Shell — Max matches per glob word (default **4096**).
|
||||
- `BARE_OS_GLOB_IGNORE` — Shell — Colon-separated fnmatch patterns excluded from glob results.
|
||||
- `BARE_OS_PROC_BLIND_PEER_RELAY_HINTS` — Booter / `/proc` — When **`1`** / **`true`** / **`yes`**, **`blind_relay_router`**, **`blind_pairing_sketch`**, and **`relay_geo_hint`** operator JSON under **`/proc/bare_os`** includes env-injected sketches; default is a stub JSON with **`exposed:false`** (no topology fields).
|
||||
- `BARE_OS_BARE_SUBPROCESS_BRIDGE` — Booter / kernel-runner — When **`1`** / **`true`**, enables the documented host **`bare-subprocess`** bridge path for long-running children.
|
||||
- `BARE_OS_BARE_SUBPROCESS_TIMEOUT_MS` — Booter / kernel-runner — When set with **`BARE_OS_BARE_SUBPROCESS_BRIDGE`**, supplies a default **`runBin`** timeout when the caller omits one.
|
||||
- `BARE_OS_DOTGLOB` — Shell — When **`1`**, globbing includes names starting with **`.`** (except **`.bareos_empty`**).
|
||||
- `BARE_OS_SHELL_BRACE_EXPANSION` — Shell — When **`1`**, unquoted **`{a,b}`** brace expansion runs before globbing.
|
||||
- `BARE_OS_GREP_FILTER_MAX` — **`grep -r`** — Max **`--include` / `--exclude` / `--exclude-dir`** glob patterns (default **32**).
|
||||
|
||||
@@ -15,7 +15,7 @@ Bare OS splits **hand-authored kernel code** from **vendored Holepunch runtime b
|
||||
|
||||
**Seeder parity:** [`kernel/`](../../kernel/) and [`packages/bare-os-seeder/kernel/`](../../packages/bare-os-seeder/kernel/) must be byte-identical ([`scripts/verify-kernel-seeder-parity.mjs`](../../scripts/verify-kernel-seeder-parity.mjs)). After editing `kernel/`, sync the seeder tree before commit.
|
||||
|
||||
**`kernel.ext.d` ordering:** The Kahn topological sort in [`kernel/lib/init/init-main.js`](../../kernel/lib/init/init-main.js) must stay aligned with [`packages/bare-os-booter/lib/kernel-extension-resolver.js`](../../packages/bare-os-booter/lib/kernel-extension-resolver.js) (**`topologicalOrderKernelExtensions`**); CI covers this via the Brittle test **`kernel extension topological order matches guest Kahn tie-break`** in **`packages/bare-os-booter/test.js`**.
|
||||
**`kernel.ext.d` ordering:** The Kahn topological sort in [`kernel/lib/init/init-main.js`](../../kernel/lib/init/init-main.js) must stay aligned with [`packages/bare-os-booter/lib/kernel-extension-resolver.js`](../../packages/bare-os-booter/lib/kernel-extension-resolver.js) (**`topologicalOrderKernelExtensions`**); CI covers this via the Brittle test **`kernel extension topological order matches guest Kahn tie-break`** in **`packages/bare-os-booter/test.js`**. Additional harness tests cover **`minCtxApiVersion`** skip paths, **`conflictsWith`** / dependency **cycles** under strict boot policy (no extension scripts run on hard failures).
|
||||
|
||||
## Governance (feature bits doc v14)
|
||||
|
||||
|
||||
@@ -52,7 +52,7 @@ See also [Kernel subsystem map](../architecture/kernel-subsystems.md) and [ADR 0
|
||||
|
||||
- Builds `shellEnv` with **guest** defaults: `USER`/`LOGNAME`=`guest`, `HOME`/`PWD`=`/home/guest`, `UID`/`GID`=`65534`, `BARE_OS_IDENTITY=guest`, `BARE_OS_EXIT_STATUS`=`0`, `BARE_OS_CTX_API_VERSION`, `PATH=/bin`, `SHELL`, `HOSTNAME`, `0`. When the host sets any of the keys listed under “host → session passthrough” in [Environment variables and POSIX appendix](environment-and-posix-appendix.md#14-environment-variables-complete-list), those values are copied into `shellEnv`. Sets **`BARE_OS_BOOT_PROFILE_RESOLVED`** from **`BARE_OS_BOOT_PROFILE`** or the first line of **`/etc/bare-os/profile`**, and **`BARE_OS_SESSION_ID`** (random UUID). Seeds **`/run/bare-os/boot.json`** fields **`imageDigest`**, **`pearChannel`**, **`pearRelease`** from **`BARE_OS_IMAGE_DIGEST`**, **`BARE_OS_PEAR_CHANNEL`** / **`PEAR_CHANNEL`**, **`BARE_OS_PEAR_RELEASE`** when present.
|
||||
- **`createBareOsIpc({ maxFifoBytes, maxChannels?, perChannelMaxBytes?, ipcRpcToken?, enableFanout?, maxJsonRpcLineBytes? })`** ([`bare-os-ipc.js`](../../packages/bare-os-booter/lib/bare-os-ipc.js)) — FIFOs under **`/run/bare-os/ipc/<name>`**; optional per-name byte caps from **`BARE_OS_IPC_CHANNEL_MAX_BYTES`**; optional global channel cap **`BARE_OS_IPC_MAX_CHANNELS`**; JSON-RPC with optional token and line cap; fan-out **`fanoutPublish`/`fanoutSubscribe`**; **`stats`** includes fan-out counts, quota telemetry, and operator backpressure snapshots when caps expose **`features.ipcFanout`**.
|
||||
- **`createVfs(drive, personalDrive, shellEnv, vfsMountRef, vfsOptions)`** → `ctx.vfs` (same `env` object as `ctx.env`). **`vfsOptions`** supply **`procSnapshot`**, dynamic **`/proc/*`** and **`/sys/*`** text (quotas JSON, **`bare_os_features`** with **`bits`**–**`bits5`** when advertised, **`bare_os_net_summary`**, **`bare_os_host_os`**, **`bare_os_sync_window`**, **`bare_os_debug`**, net/disk stubs, session stats), **`bootProfileText`**, **`sessionText`**, **`initdRunText`**, **`bootReadyJsonText`**, mount map for **`/proc/mounts`**, **`bootStartedMs`** for **`/proc/uptime`**, etc. Exposes **`vfs.watch(logicalPath)`** for Hyperdrive-backed paths when **`BARE_OS_VFS_WATCH`** is not **`0`**.
|
||||
- **`createVfs(drive, personalDrive, shellEnv, vfsMountRef, vfsOptions)`** → `ctx.vfs` (same `env` object as `ctx.env`). **`vfsOptions`** supply **`procSnapshot`**, dynamic **`/proc/*`** and **`/sys/*`** text (quotas JSON, **`bare_os_features`** with **`bits`**–**`bits5`** when advertised, **`bare_os_net_summary`**, **`bare_os_host_os`**, **`bare_os_sync_window`**, **`bare_os_debug`**, net/disk stubs, session stats), **`bootProfileText`**, **`sessionText`**, **`initdRunText`**, **`bootReadyJsonText`**, mount map for **`/proc/mounts`**, **`bootStartedMs`** for **`/proc/uptime`**, etc. Exposes **`vfs.watch(logicalPath)`** for Hyperdrive-backed paths when **`BARE_OS_VFS_WATCH`** is not **`0`**. Operator blind-relay sketches (**`blind_relay_router`**, **`blind_pairing_sketch`**, **`relay_geo_hint`**) return a non-exposing stub unless the host sets **`BARE_OS_PROC_BLIND_PEER_RELAY_HINTS`**. **`kernel-runner`**: when **`BARE_OS_BARE_SUBPROCESS_BRIDGE`** is set, **`BARE_OS_BARE_SUBPROCESS_TIMEOUT_MS`** can default **`runBin`** timeouts.
|
||||
- **`applyGuestEnv(ctx)`** then **`ensureGuestHome(ctx)`** — normalizes `ctx.identity` and seeds `/.bare/` (and a guest marker) on the personal drive.
|
||||
- **`createReadLine()`** always resolves stdio first and returns `stdout` (may be `null`) alongside `readLine` so the kernel can write to the **same** stream as the REPL (including `bare-stdio` under Pear).
|
||||
- Builds `ctx`: **`bareOsCtxApiVersion`** (from [`bare-os-ctx-api.js`](../../packages/bare-os-booter/lib/bare-os-ctx-api.js)), **`bareOsRuntimeCaps`** (frozen snapshot from [`bare-os-runtime-caps.js`](../../packages/bare-os-booter/lib/bare-os-runtime-caps.js): pipeline limits, **`quotas`**, pseudo path list, feature flags such as **`vfsWatch`**, **`ipcRpcJson`**, **`initdSocketActivation`**), **`bareOsIpc`**, `disk`, `drive`, `personalDrive`, `vfs`, `env`, `console`, `b4a`, `topic: topicKey()`, `readLine`, **`writeScreen(str)`**, **`bareOsSubscribeBootEvent`** / **`bareOsEmitBootEvent`**, **`bareOsSubscribeHdmsLifecycle`**, **`bareOsAwaitInitdUnits`**, **`bareOsPublishBootReady`**, `execLine` → wraps **`execShellLine`** with optional **audit** (**`BARE_OS_AUDIT`**, **`BARE_OS_AUDIT_JSON`**, redaction), **`execLine` depth cap** (**`BARE_OS_EXEC_MAX_DEPTH`**), then the shell (returns `'ok'` or `'exit'`; updates **`BARE_OS_EXIT_STATUS`** in **`vfs.env`**; bare **`exit`** line sets status then **`requestBooterExit`**), **`runBinCommand(argv)`** → delegates to **`runBinCommand(this, argv)`** from `kernel-runner.js` (for `/bin/time` and similar), plus identity hooks for `/bin` and builtins:
|
||||
|
||||
@@ -24,6 +24,6 @@
|
||||
"syscalls_json_schema": 4,
|
||||
"process_table_schema": 4,
|
||||
"paths": ["/proc/bare_os/syscalls.json", "/proc/bare_os/process_table.json"],
|
||||
"posix_xsh_surface": "open,close,read,write,lseek,pipe,dup,dup2,fcntl,poll in syscalls.json opsDetail + posixXsh.namesCsv; ctx.bareOsSyscall fcntl+posixPoll; ctx.bareOsPosixPoll"
|
||||
"posix_xsh_surface": "open,close,read,write,lseek,pipe,dup,dup2,fcntl,poll,select,umask in syscalls.json opsDetail + posixXsh.namesCsv; ctx.bareOsSyscall fcntl+posixPoll+select+umask; ctx.bareOsPosixPoll"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -29,9 +29,11 @@
|
||||
"readlink",
|
||||
"rename",
|
||||
"rmdir",
|
||||
"select",
|
||||
"stat",
|
||||
"symlink",
|
||||
"truncate",
|
||||
"umask",
|
||||
"umount",
|
||||
"unlink",
|
||||
"utimes",
|
||||
|
||||
Reference in New Issue
Block a user