snxraven/bare-operating-system
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Further MD Fixes

Browse Source
This commit is contained in:
Raven Scott
2026-04-25 23:04:56 -04:00
parent b07bc38708
commit b9d3a8b17f
143 changed files with 1861 additions and 1861 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/README.md
+77 -77
View File
@@ -11,17 +11,17 @@ Small **monorepo-level** helpers used by npm scripts and maintainers.
Root **`pretest`** already enforces this sequence; follow the same order when changing the guest image or stdlib bundles:
1. **`npm run build -w bare-os-coreutils`** — emit `/bin` sources into **`kernel/bin`** (and man pages).
2. **`npm run build -w bare-os-bare-libs**` — esbuild Holepunch `**bare-***` IIFEs into `**kernel/lib/bare/**`, refresh `**docs/audit/bundle-health.json`**.
3. **`npm run bundle:kernel**` (part of `**pretest**`) — concatenate `**kernel/lib/boot/*.js**` + `**kernel/lib/init/fragments/*.js**` + `**kernel/lib/init/init-main.js**` → `**kernel/init.js`**.
4. **`node scripts/verify-kernel-seeder-parity.mjs**` — `**kernel/**` must match `**packages/bare-os-seeder/kernel/`** byte-for-byte (rsync or seeder copy after edits).
2. **`npm run build -w bare-os-bare-libs**` — esbuild Holepunch **`bare-*`** IIFEs into **`kernel/lib/bare/`**, refresh **`docs/audit/bundle-health.json`**.
3. **`npm run bundle:kernel**` (part of **`pretest`**) — concatenate **`kernel/lib/boot/*.js`** + **`kernel/lib/init/fragments/*.js`** + **`kernel/lib/init/init-main.js`** → **`kernel/init.js`**.
4. **`node scripts/verify-kernel-seeder-parity.mjs**` — **`kernel/`** must match **`packages/bare-os-seeder/kernel/`** byte-for-byte (rsync or seeder copy after edits).
**Shortcut:** **`npm run maintainer:sync-kernel-seeder**` runs `**rsync -a --delete**` then `**verify-kernel-seeder-parity**`. `**npm run maintainer:sync-kernel-seeder:bundle**` rebundles `**/boot/init.js**` first. See `**sync-kernel-to-seeder.mjs`**.
**Shortcut:** **`npm run maintainer:sync-kernel-seeder**` runs `**rsync -a --delete**` then **`verify-kernel-seeder-parity`**. `**npm run maintainer:sync-kernel-seeder:bundle**` rebundles **`/boot/init.js`** first. See **`sync-kernel-to-seeder.mjs`**.
If **`verify-kernel-seeder-parity**` fails after bare-libs or init changes, sync the seeder tree before committing (see `**kernel/lib/bare/README.md**` / `**packages/bare-os-bare-libs/README.kernel-lib-bare.md`**).
If **`verify-kernel-seeder-parity`** fails after bare-libs or init changes, sync the seeder tree before committing (see **`kernel/lib/bare/README.md`** / **`packages/bare-os-bare-libs/README.kernel-lib-bare.md`**).
### POSIX verifier “pretest matrix” (dashboard + compliance)
Root **`pretest**` already runs the POSIX scripts below (see root `**package.json**` for the exact order). Together they keep the **declared POSIX profile**, **compliance matrix JSON**, and **generated dashboard** aligned with protocol constants and `**kernel/etc/bare-os/syscalls.example.json`**.
Root **`pretest`** already runs the POSIX scripts below (see root **`package.json`** for the exact order). Together they keep the **declared POSIX profile**, **compliance matrix JSON**, and **generated dashboard** aligned with protocol constants and **`kernel/etc/bare-os/syscalls.example.json`**.
```mermaid
flowchart LR
@@ -32,10 +32,10 @@ flowchart LR
- **`gen-posix-dashboard.mjs`** — writes or refreshes **[`docs/reference/posix-dashboard.md`](../docs/reference/posix-dashboard.md)** from repo sources.
- **`verify-posix-dashboard.mjs`** — fails when the dashboard is stale relative to generators.
- **`verify-posix-compliance-matrix.mjs**` — `**docs/reference/posix-compliance-matrix.json**` `**profileId**` vs protocol `**BARE_OS_POSIX_PROFILE_ID**`; `**syscalls.example.json**` `**ctxApiVersion**` vs `**BARE_OS_CTX_API_VERSION`**; syscall proc JSON **schema** parity.
- **`verify-posix-profile-triplet.mjs**` — declared profile doc, protocol exports, and matrix `**profileVersion`** stay in sync.
- **`verify-posix-compliance-matrix.mjs`** — **`docs/reference/posix-compliance-matrix.json`** **`profileId`** vs protocol **`BARE_OS_POSIX_PROFILE_ID`**; **`syscalls.example.json`** **`ctxApiVersion`** vs **`BARE_OS_CTX_API_VERSION`**; syscall proc JSON **schema** parity.
- **`verify-posix-profile-triplet.mjs`** — declared profile doc, protocol exports, and matrix **`profileVersion`** stay in sync.
**Seeder host logging:** **`packages/bare-os-seeder**` uses `**lib/host-logger.mjs**`. Set `**BARE_OS_SEED_LOG_LEVEL**` (`**debug**`, `**info**`, `**warn**`, `**error**`) and optional `**BARE_OS_SEED_LOG_FORMAT=ndjson**` (or `**json`**) for one JSON object per line on stdout—useful in CI and log shippers. See [handbook ch.7](../handbook/07-operations-and-development.md).
**Seeder host logging:** **`packages/bare-os-seeder`** uses **`lib/host-logger.mjs`**. Set **`BARE_OS_SEED_LOG_LEVEL`** (**`debug`**, **`info`**, **`warn`**, **`error`**) and optional **`BARE_OS_SEED_LOG_FORMAT=ndjson`** (or **`json`**) for one JSON object per line on stdout—useful in CI and log shippers. See [handbook ch.7](../handbook/07-operations-and-development.md).
---
@@ -49,7 +49,7 @@ Verifiers and generators are listed in the order they typically appear in root *
**Usage:** `node scripts/ensure-pear-node-modules.mjs packages/<app>`
Recreates `packages/<app>/node_modules` by symlinking **each top-level package** from the **repo root** `node_modules` (matching npm’s flat hoist). Pear’s dev bundle often does not resolve a single nested `node_modules` tree correctly; this makes `pear run --dev .` reliable after `npm ci` at the root. Dependencies declared as **`file:**` with a path **outside** that package (e.g. `**bare-ssh2**` vendored under `**bare-os-openssh**`) are then **copied** into local `**node_modules/<name>`** so `pear stage` / Bare can resolve them in released bundles. The booter also concretizes the **`holesail`** dependency closure (instead of leaving it as hoisted symlinks) because released Pear bundles have dropped that tree when staged only via symlinks.
Recreates `packages/<app>/node_modules` by symlinking **each top-level package** from the **repo root** `node_modules` (matching npm’s flat hoist). Pear’s dev bundle often does not resolve a single nested `node_modules` tree correctly; this makes `pear run --dev .` reliable after `npm ci` at the root. Dependencies declared as **`file:`** with a path **outside** that package (e.g. **`bare-ssh2`** vendored under **`bare-os-openssh`**) are then **copied** into local **`node_modules/<name>`** so `pear stage` / Bare can resolve them in released bundles. The booter also concretizes the **`holesail`** dependency closure (instead of leaving it as hoisted symlinks) because released Pear bundles have dropped that tree when staged only via symlinks.
Invoked automatically by:
@@ -60,43 +60,43 @@ Invoked automatically by:
**Usage:** `node scripts/vendor-bare-node-shims.mjs` (also **`npm run vendor:bare-node-shims -w bare-os-openssh`**)
Copies **`bare-net**` and the `**bare-node-***` packages `**bare-ssh2**` needs from the root `**node_modules**` into `**packages/bare-os-openssh/vendor/bare-node-shims/**` (no nested `**node_modules**`), rewrites **intra-vendor** deps to `**file:../<pkg>**`, and writes `**README.md**`. **Commit** that directory so clones include `**bare-node-net**` etc. even when the npm registry is unreachable. `**bare-os-booter**` depends on those paths via `**file:**`; run `**npm install**` at the root after changing versions so `**package-lock.json`** stays consistent.
Copies **`bare-net`** and the **`bare-node-*`** packages **`bare-ssh2`** needs from the root **`node_modules`** into **`packages/bare-os-openssh/vendor/bare-node-shims/`** (no nested **`node_modules`**), rewrites **intra-vendor** deps to **`file:../<pkg>`**, and writes **`README.md`**. **Commit** that directory so clones include **`bare-node-net`** etc. even when the npm registry is unreachable. **`bare-os-booter`** depends on those paths via **`file:`**; run `**npm install**` at the root after changing versions so **`package-lock.json`** stays consistent.
## `sync-kernel-to-seeder.mjs`
**Usage:** `npm run maintainer:sync-kernel-seeder` · `npm run maintainer:sync-kernel-seeder:bundle`
Runs **`rsync -a --delete kernel/ packages/bare-os-seeder/kernel/**` then `**verify-kernel-seeder-parity.mjs**`. `**--bundle**` regenerates `**kernel/init.js**` first. Requires `**rsync**` on `**PATH`**.
Runs **`rsync -a --delete kernel/ packages/bare-os-seeder/kernel/**` then **`verify-kernel-seeder-parity.mjs`**. **`--bundle`** regenerates **`kernel/init.js`** first. Requires **`rsync`** on **`PATH`**.
## `verify-kernel-seeder-parity.mjs`
**Usage:** `node scripts/verify-kernel-seeder-parity.mjs`
Exits **0** only when **`kernel/**` and `**packages/bare-os-seeder/kernel/**` contain the **same recursive file set** with **byte-identical** contents (full mirror parity, not a spot check on `**init.js**` alone). Requires `**init.js**`, `**lib/init/init-main.js**`, `**lib/init/fragments/*.js**`, `**lib/boot/*.js**`, `**lib/bare/manifest.json**`, `**lib/bare/bare-module-manifest.json**`, and asserts `**kernel/init.js**` matches the bundle recipe via `**scripts/lib/kernel-init-bundle.mjs**`. Every `**kernel/bin/***` must include `**BARE_OS_BIN_API**`. Invoked from the root `**pretest**` hook after `**npm run build -w bare-os-coreutils`**. **Sync:** `rsync -a --delete kernel/ packages/bare-os-seeder/kernel/` (after **`bundle:kernel**` when `**init.js`** is generated).
Exits **0** only when **`kernel/`** and **`packages/bare-os-seeder/kernel/`** contain the **same recursive file set** with **byte-identical** contents (full mirror parity, not a spot check on **`init.js`** alone). Requires **`init.js`**, **`lib/init/init-main.js`**, **`lib/init/fragments/*.js`**, **`lib/boot/*.js`**, **`lib/bare/manifest.json`**, **`lib/bare/bare-module-manifest.json`**, and asserts **`kernel/init.js`** matches the bundle recipe via **`scripts/lib/kernel-init-bundle.mjs`**. Every **`kernel/bin/*`** must include **`BARE_OS_BIN_API`**. Invoked from the root **`pretest`** hook after `**npm run build -w bare-os-coreutils`**. **Sync:** `rsync -a --delete kernel/ packages/bare-os-seeder/kernel/` (after **`bundle:kernel`** when **`init.js`** is generated).
## `verify-init-bundle-recipe.mjs`
**Usage:** `node scripts/verify-init-bundle-recipe.mjs` (also **`npm run verify:init-bundle`**)
Fails when **`kernel/init.js**` does not match the bundle recipe (sorted `**kernel/lib/boot/*.js**` + `**kernel/lib/init/fragments/*.js**` + `**kernel/lib/init/init-main.js**`). Shared logic lives in `**scripts/lib/kernel-init-bundle.mjs**`. Also invoked from `**npm run release-checklist`**.
Fails when **`kernel/init.js`** does not match the bundle recipe (sorted **`kernel/lib/boot/*.js`** + **`kernel/lib/init/fragments/*.js`** + **`kernel/lib/init/init-main.js`**). Shared logic lives in **`scripts/lib/kernel-init-bundle.mjs`**. Also invoked from `**npm run release-checklist`**.
## `verify-banned-terminology.mjs`
**Usage:** `node scripts/verify-banned-terminology.mjs`
Fails when banned governance tokens (**`Wave N**`, `**wave N**`, `**tranche**`, `**mega-phase**`, `**multi-stage` / `multi stage**`) appear in tracked `**md` / `js` / `mjs` / `json`** files (excluding `node_modules`, **`kernel/lib/bare/`** vendored trees, `share/man/man.json`, and this script). Root **`pretest`**.
Fails when banned governance tokens (**`Wave N**`, `**wave N**`, **`tranche`**, **`mega-phase`**, `**multi-stage` / `multi stage**`) appear in tracked `**md` / `js` / `mjs` / `json`** files (excluding `node_modules`, **`kernel/lib/bare/`** vendored trees, `share/man/man.json`, and this script). Root **`pretest`**.
## `bundle-kernel-init.mjs`
**Usage:** `node scripts/bundle-kernel-init.mjs` (also **`npm run bundle:kernel`**)
Concatenates sorted `kernel/lib/boot/*.js` + sorted `kernel/lib/init/fragments/*.js` + `kernel/lib/init/init-main.js` → **`kernel/init.js**`. Run after editing boot or init fragments; root `**pretest`** invokes it automatically.
Concatenates sorted `kernel/lib/boot/*.js` + sorted `kernel/lib/init/fragments/*.js` + `kernel/lib/init/init-main.js` → **`kernel/init.js`**. Run after editing boot or init fragments; root **`pretest`** invokes it automatically.
## `verify-feature-roadmap-canonical.mjs`
**Usage:** `node scripts/verify-feature-roadmap-canonical.mjs`
Ensures [docs/data/feature-roadmap-canonical.json](../docs/data/feature-roadmap-canonical.json) aligns with the batch B table in **`feature-roadmap.md**`. Root `**pretest`**.
Ensures [docs/data/feature-roadmap-canonical.json](../docs/data/feature-roadmap-canonical.json) aligns with the batch B table in **`feature-roadmap.md`**. Root **`pretest`**.
## `verify-no-new-giant-phase-identifiers.mjs`
@@ -120,43 +120,43 @@ Developer-only smoke path for local mirror plus synthetic peer checks; extend wi
**Usage:** `node scripts/benchmark-boot-sketch.mjs`
Appends one NDJSON trend row (`schema: 1`) to **`BARE_OS_BENCHMARK_TREND_NDJSON**` or `**$TMPDIR/bare-os-benchmark-trend.ndjson`**.
Appends one NDJSON trend row (`schema: 1`) to **`BARE_OS_BENCHMARK_TREND_NDJSON`** or **`$TMPDIR/bare-os-benchmark-trend.ndjson`**.
## `verify-naming-alias-matrix.mjs`
**Usage:** `node scripts/verify-naming-alias-matrix.mjs`
Ensures [docs/reference/naming-alias-matrix.md](../docs/reference/naming-alias-matrix.md) lists canonical **`ctx**` boot-hook names and boot-policy key aliases. Root `**pretest`**.
Ensures [docs/reference/naming-alias-matrix.md](../docs/reference/naming-alias-matrix.md) lists canonical **`ctx`** boot-hook names and boot-policy key aliases. Root **`pretest`**.
## `verify-booter-boot-steps-alignment.mjs`
**Usage:** `node scripts/verify-booter-boot-steps-alignment.mjs`
Ensures every **`emitBooterBootPhase('…')**` in `**packages/bare-os-booter/index.js**` matches `**BARE_OS_BOOTER_BOOT_STEPS**` in `**packages/bare-os-booter/lib/bare-os-boot-phases.js**` (no drift). Root `**pretest`**.
Ensures every **`emitBooterBootPhase('…')**` in **`packages/bare-os-booter/index.js`** matches **`BARE_OS_BOOTER_BOOT_STEPS`** in **`packages/bare-os-booter/lib/bare-os-boot-phases.js`** (no drift). Root **`pretest`**.
## `verify-runtime-no-incomplete-markers.mjs`
**Usage:** `node scripts/verify-runtime-no-incomplete-markers.mjs`
Fails on incomplete-runtime markers (**`TODO**`, `**FIXME**`, `**HACK**`, `**XXX**`, or `**throw new Error(\"Not implemented\")**`) in hand-authored `**kernel/init.js**`, `**kernel/lib/init/**`, `**kernel/lib/boot/**`, `**kernel/bin/*.js**`, and `**packages/bare-os-booter/`** (excludes vendored bundles and tests). Optional path prefixes in **[`docs/audit/runtime-marker-excludes.json`](../docs/audit/runtime-marker-excludes.json)** are skipped. Root **`pretest`**.
Fails on incomplete-runtime markers (**`TODO`**, **`FIXME`**, **`HACK`**, **`XXX`**, or `**throw new Error(\"Not implemented\")**`) in hand-authored **`kernel/init.js`**, **`kernel/lib/init/`**, **`kernel/lib/boot/`**, **`kernel/bin/*.js`**, and **`packages/bare-os-booter/`** (excludes vendored bundles and tests). Optional path prefixes in **[`docs/audit/runtime-marker-excludes.json`](../docs/audit/runtime-marker-excludes.json)** are skipped. Root **`pretest`**.
## `verify-bare-imports.mjs`
**Usage:** `node scripts/verify-bare-imports.mjs`
Forbids **`node:**` in static `**from**`, dynamic `**import()**`, and `**require()**` for `**kernel/init.js**`, `**kernel/lib/init/**`, `**kernel/lib/boot/**` (excluding `**bundles/**` subtree via walk rules), `**packages/bare-os-booter/index.js**`, `**packages/bare-os-booter/lib/**/*.js**` (skips `***.node.js**` shims), `**packages/bare-os-protocol/lib/**/*.js**`, and `**kernel/lib/bare/bundles/*.js**`. Does not scan `**scripts/**` (Node tooling may use `**node:fs**`). Root `**pretest`**.
Forbids **`node:`** in static **`from`**, dynamic `**import()**`, and `**require()**` for **`kernel/init.js`**, **`kernel/lib/init/`**, **`kernel/lib/boot/`** (excluding **`bundles/`** subtree via walk rules), **`packages/bare-os-booter/index.js`**, **`packages/bare-os-booter/lib/**`/*.js`** (skips **`*.node.js`** shims), **`packages/bare-os-protocol/lib/**`/*.js`**, and **`kernel/lib/bare/bundles/*.js`**. Does not scan **`scripts/`** (Node tooling may use **`node:fs`**). Root **`pretest`**.
## `gen-ctx-client-helper.mjs`
**Usage:** `node scripts/gen-ctx-client-helper.mjs`
Writes **[`docs/reference/ctx-client-helper.generated.ts`](../docs/reference/ctx-client-helper.generated.ts)** with **`BARE_OS_CTX_API_CLIENT_VERSION**`, DTS path hints, and schema pointers. Root `**pretest`**.
Writes **[`docs/reference/ctx-client-helper.generated.ts`](../docs/reference/ctx-client-helper.generated.ts)** with **`BARE_OS_CTX_API_CLIENT_VERSION`**, DTS path hints, and schema pointers. Root **`pretest`**.
## `sanitize-bare-bundles.mjs`
**Usage:** imported from **`packages/bare-os-bare-libs/build.mjs`** (not run standalone in CI).
Post-processes esbuild IIFE output so **`verify-bundle-markers**` / `**verify-bundle-throws**` stay green and `**bareDev.js**` uses `**bare-***` instead of `**node:`** requires.
Post-processes esbuild IIFE output so **`verify-bundle-markers`** / **`verify-bundle-throws`** stay green and **`bareDev.js`** uses **`bare-*`** instead of **`node:`** requires.
## `verify-extension-manifest-schema.mjs`
@@ -168,19 +168,19 @@ Validates [docs/schemas/kernel-extension-manifest.schema.json](../docs/schemas/k
**Usage:** `node scripts/verify-boot-policy-extension-signer-pins.mjs`
Ensures **`boot.policy**` documents `**extensionSignerPinsV2**`…`**V5**` and `**kernel/lib/init/init-main.js**` still assigns `**BARE_OS_BOOT_POLICY_EXTENSION_SIGNER_PINS_V*_JSON**`. Root `**pretest`**.
Ensures **`boot.policy`** documents **`extensionSignerPinsV2`**…**`V5`** and **`kernel/lib/init/init-main.js`** still assigns **`BARE_OS_BOOT_POLICY_EXTENSION_SIGNER_PINS_V*_JSON`**. Root **`pretest`**.
## `verify-ctx-api-feature-bits.mjs`
**Usage:** `node scripts/verify-ctx-api-feature-bits.mjs`
Checks that **`packages/bare-os-booter/lib/bare-os-ctx-api.js**` documents a `**BARE_OS_CTX_API_VERSION**` that matches the contract surface (semver discipline) and that stock kernel feature words (`**BARE_OS_KERNEL_FEATURES_STOCK_WORD_***`) in `**bare-os-protocol**` stay referenced from the booter (including `**kernelCapabilityWords**` / `**ctx**` maps for wire v2). Invoked from the root `**pretest`** hook.
Checks that **`packages/bare-os-booter/lib/bare-os-ctx-api.js`** documents a **`BARE_OS_CTX_API_VERSION`** that matches the contract surface (semver discipline) and that stock kernel feature words (**`BARE_OS_KERNEL_FEATURES_STOCK_WORD_*`**) in **`bare-os-protocol`** stay referenced from the booter (including **`kernelCapabilityWords`** / **`ctx`** maps for wire v2). Invoked from the root **`pretest`** hook.
## `verify-ctx-client-helper-sync.mjs`
**Usage:** `node scripts/verify-ctx-client-helper-sync.mjs`
Ensures **[`docs/reference/ctx-client-helper.generated.ts`](../docs/reference/ctx-client-helper.generated.ts)** mentions the current **`BARE_OS_CTX_API_VERSION**` after `**gen-ctx-client-helper.mjs**`. Root `**pretest`**.
Ensures **[`docs/reference/ctx-client-helper.generated.ts`](../docs/reference/ctx-client-helper.generated.ts)** mentions the current **`BARE_OS_CTX_API_VERSION`** after **`gen-ctx-client-helper.mjs`**. Root **`pretest`**.
## `verify-personal-drive-path-policy.mjs`
@@ -192,49 +192,49 @@ Checks that canonical personal-drive path strings stay documented across the POS
**Usage:** `node scripts/verify-kernel-capabilities-contract.mjs`
Static checks for capability wire **v2** (**`kernelCapabilityWords**`): stock mask constants in `**kernel-feature-bits.js**`, seed `**capabilities**` in `**channel.js**`, booter `**index.js**` strict checks, boot policy schema keys, kernel `**init.js**` enforcement, and `**seed-rpc-methods.js**` wiring. Root `**pretest`**.
Static checks for capability wire **v2** (**`kernelCapabilityWords`**): stock mask constants in **`kernel-feature-bits.js`**, seed **`capabilities`** in **`channel.js`**, booter **`index.js`** strict checks, boot policy schema keys, kernel **`init.js`** enforcement, and **`seed-rpc-methods.js`** wiring. Root **`pretest`**.
## `verify-kernel-capabilities-word-6.mjs`
**Usage:** `node scripts/verify-kernel-capabilities-word-6.mjs`
Asserts **[`docs/reference/feature-roadmap.md`](../docs/reference/feature-roadmap.md)** contains **`## Capability word 6 checklist (100-item mega kernel)**` with at least **100** numbered table rows. Root `**pretest`**.
Asserts **[`docs/reference/feature-roadmap.md`](../docs/reference/feature-roadmap.md)** contains **`## Capability word 6 checklist (100-item mega kernel)**` with at least **100** numbered table rows. Root **`pretest`**.
## `verify-kernel-capabilities-word-7.mjs`
**Usage:** `node scripts/verify-kernel-capabilities-word-7.mjs`
Asserts **`feature-roadmap.md**` contains `**## Capability word 7 checklist (100-item mega kernel)**` with at least **100** numbered table rows. Root `**pretest`**.
Asserts **`feature-roadmap.md`** contains `**## Capability word 7 checklist (100-item mega kernel)**` with at least **100** numbered table rows. Root **`pretest`**.
## `verify-kernel-capabilities-word-8.mjs`
**Usage:** `node scripts/verify-kernel-capabilities-word-8.mjs`
Asserts **`feature-roadmap.md**` contains `**## Capability word 8 checklist (100-item mega kernel)**` with at least **100** numbered table rows. Root `**pretest`**.
Asserts **`feature-roadmap.md`** contains `**## Capability word 8 checklist (100-item mega kernel)**` with at least **100** numbered table rows. Root **`pretest`**.
## `verify-kernel-capabilities-word-9.mjs`
**Usage:** `node scripts/verify-kernel-capabilities-word-9.mjs`
Asserts **`feature-roadmap.md**` contains `**## Capability word 9 checklist (100-item mega kernel)**` with at least **100** numbered table rows. Root `**pretest`**.
Asserts **`feature-roadmap.md`** contains `**## Capability word 9 checklist (100-item mega kernel)**` with at least **100** numbered table rows. Root **`pretest`**.
## `verify-kernel-capabilities-word-10.mjs`
**Usage:** `node scripts/verify-kernel-capabilities-word-10.mjs`
Asserts **`feature-roadmap.md**` contains `**## Capability word 10 checklist (100-item mega kernel)**` with at least **100** numbered table rows. Root `**pretest`**.
Asserts **`feature-roadmap.md`** contains `**## Capability word 10 checklist (100-item mega kernel)**` with at least **100** numbered table rows. Root **`pretest`**.
## `verify-kernel-capabilities-word-11.mjs`
**Usage:** `node scripts/verify-kernel-capabilities-word-11.mjs`
Asserts **`feature-roadmap.md**` contains `**## Capability word 11 checklist (100-item mega kernel)**` with at least **100** numbered table rows. Root `**pretest`**.
Asserts **`feature-roadmap.md`** contains `**## Capability word 11 checklist (100-item mega kernel)**` with at least **100** numbered table rows. Root **`pretest`**.
## `gen-posix-dashboard.mjs`
**Usage:** `node scripts/gen-posix-dashboard.mjs`
Writes [docs/reference/posix-dashboard.md](../docs/reference/posix-dashboard.md) from **`posix-compliance-matrix.json**`. Root `**pretest`**.
Writes [docs/reference/posix-dashboard.md](../docs/reference/posix-dashboard.md) from **`posix-compliance-matrix.json`**. Root **`pretest`**.
## `verify-posix-dashboard.mjs`
@@ -246,133 +246,133 @@ Fails when the dashboard is stale relative to the matrix. Root **`pretest`**.
**Usage:** `node scripts/verify-posix-compliance-matrix.mjs`
Ensures [docs/reference/posix-compliance-matrix.json](../docs/reference/posix-compliance-matrix.json) **`profileId**` matches `**BARE_OS_POSIX_PROFILE_ID**` in the protocol package, and `**kernel/etc/bare-os/syscalls.example.json**` `**ctxApiVersion**` matches `**BARE_OS_CTX_API_VERSION**`. Root `**pretest`**.
Ensures [docs/reference/posix-compliance-matrix.json](../docs/reference/posix-compliance-matrix.json) **`profileId`** matches **`BARE_OS_POSIX_PROFILE_ID`** in the protocol package, and **`kernel/etc/bare-os/syscalls.example.json`** **`ctxApiVersion`** matches **`BARE_OS_CTX_API_VERSION`**. Root **`pretest`**.
## `verify-pear-no-static-node-import.mjs`
**Usage:** `node scripts/verify-pear-no-static-node-import.mjs`
Fails on **`from 'node:…'**` static imports, on `**require('node:…')**` / `**import('node:…')**` in those same trees, and on bare `**from 'fs'**` / `**from 'path'**` / `**from 'fs/promises'**` under `**packages/bare-os-booter/index.js**`, `**packages/bare-os-booter/lib/**/*.js**`, `**packages/bare-os-seeder/index.js**`, and `**packages/bare-os-seeder/lib/**/*.js**` (excluding `**bare-os-boot-manifest-sig.node.js**` from the walk). Use package `**imports**` aliases `**#host-fs**`, `**#host-path**`, `**#host-fs-promises**` (seeder) instead. Root `**pretest`**.
Fails on **`from 'node:…'**` static imports, on `**require('node:…')**` / `**import('node:…')**` in those same trees, and on bare `**from 'fs'**` / `**from 'path'**` / `**from 'fs/promises'**` under **`packages/bare-os-booter/index.js`**, **`packages/bare-os-booter/lib/**`/*.js`**, **`packages/bare-os-seeder/index.js`**, and **`packages/bare-os-seeder/lib/**`/*.js`** (excluding **`bare-os-boot-manifest-sig.node.js`** from the walk). Use package **`imports`** aliases `**#host-fs**`, `**#host-path**`, `**#host-fs-promises**` (seeder) instead. Root **`pretest`**.
## `verify-ctx-dts.mjs`
**Usage:** `node scripts/verify-ctx-dts.mjs`
Ensures **`bare-os-ctx.d.ts**` lists documented `**ctx**` fields (including `**bareOsAdvertisedKernelCapabilityWords**` / `**bareOsSeedKernelCapabilityWords**`, Bare runtime semver, protocol/Pear runtime semver, subprocess snapshot, profile reload, delegate fairness, IPC audit, Pear / bundlebee / diagnostics / hrpc / structured-clone / wave9–11 stubs, …) that exist in `**packages/bare-os-booter/index.js**`. Root `**pretest`**.
Ensures **`bare-os-ctx.d.ts`** lists documented **`ctx`** fields (including **`bareOsAdvertisedKernelCapabilityWords`** / **`bareOsSeedKernelCapabilityWords`**, Bare runtime semver, protocol/Pear runtime semver, subprocess snapshot, profile reload, delegate fairness, IPC audit, Pear / bundlebee / diagnostics / hrpc / structured-clone / wave9–11 stubs, …) that exist in **`packages/bare-os-booter/index.js`**. Root **`pretest`**.
## `verify-doc-links.mjs`
**Usage:** `node scripts/verify-doc-links.mjs`
Scans **`docs/**`, `**handbook/**`, `**developer-guide/**`, `**users-manual/**`, `**packages/**`, `**kernel/**`, `**scripts/*.md**`, plus root `**README.md**` / `**DOCUMENTATION.md**`, for relative `**.md**` links and fails when the target file is missing. Root `**pretest`**.
Scans **`docs/`**, **`handbook/`**, **`developer-guide/`**, **`users-manual/`**, **`packages/`**, **`kernel/`**, **`scripts/*.md`**, plus root **`README.md`** / **`DOCUMENTATION.md`**, for relative **`.md`** links and fails when the target file is missing. Root **`pretest`**.
## `validate-mermaid-syntax.mjs`
**Usage:** `BARE_OS_VALIDATE_MERMAID=1 node scripts/validate-mermaid-syntax.mjs` · workflow **[`.github/workflows/docs-mermaid-smoke.yml`](../.github/workflows/docs-mermaid-smoke.yml)** (**`workflow_dispatch**` + weekly `**cron`**)
**Usage:** `BARE_OS_VALIDATE_MERMAID=1 node scripts/validate-mermaid-syntax.mjs` · workflow **[`.github/workflows/docs-mermaid-smoke.yml`](../.github/workflows/docs-mermaid-smoke.yml)** (**`workflow_dispatch`** + weekly **`cron`**)
Renders every **```mermaid** fenced block (under **`docs/**`, `**handbook/**`, `**developer-guide/**`, `**users-manual/**`, `**packages/**`, `**scripts/**`, plus root `**README.md**` / `**DOCUMENTATION.md**`) via a one-off `**@mermaid-js/mermaid-cli**` install in a temp directory. **Not** part of root `**pretest**`. Locally **skips** unless `**BARE_OS_VALIDATE_MERMAID=1**`; GitHub Actions sets `**GITHUB_ACTIONS=true`** so scheduled / manual runs validate diagrams without slowing every clone.
Renders every **```mermaid** fenced block (under **`docs/`**, **`handbook/`**, **`developer-guide/`**, **`users-manual/`**, **`packages/`**, **`scripts/`**, plus root **`README.md`** / **`DOCUMENTATION.md`**) via a one-off `**@mermaid-js/mermaid-cli**` install in a temp directory. **Not** part of root **`pretest`**. Locally **skips** unless **`BARE_OS_VALIDATE_MERMAID=1`**; GitHub Actions sets **`GITHUB_ACTIONS=true`** so scheduled / manual runs validate diagrams without slowing every clone.
## `verify-man-coverage.mjs`
**Usage:** `node scripts/verify-man-coverage.mjs`
Asserts every Tier-1 name in **`packages/bare-os-coreutils/lib/commands.mjs**` has a matching `**name**` entry in `**kernel/share/man/man.json**`. Root `**pretest`**.
Asserts every Tier-1 name in **`packages/bare-os-coreutils/lib/commands.mjs`** has a matching **`name`** entry in **`kernel/share/man/man.json`**. Root **`pretest`**.
## `verify-doc-tier1-count.mjs`
**Usage:** `node scripts/verify-doc-tier1-count.mjs`
Ensures a fixed set of markdown files (root **`README.md**`, `**kernel/README.md**`, environment appendix, placeholder baseline, `**packages/bare-os-coreutils/README.md**`) document the live `**COREUTILS_COMMANDS.length**` and do not reintroduce obsolete `**~113**` / `**~115**` / `**146**` tier-1 approximations. Root `**pretest**` (after `**verify-man-coverage`**).
Ensures a fixed set of markdown files (root **`README.md`**, **`kernel/README.md`**, environment appendix, placeholder baseline, **`packages/bare-os-coreutils/README.md`**) document the live **`COREUTILS_COMMANDS.length`** and do not reintroduce obsolete **`~113`** / **`~115`** / **`146`** tier-1 approximations. Root **`pretest`** (after **`verify-man-coverage`**).
## `verify-compat-matrix.mjs`
**Usage:** `node scripts/verify-compat-matrix.mjs`
Checks **[`docs/reference/compatibility-matrix.md`](../docs/reference/compatibility-matrix.md)** lists the current **`BARE_OS_CTX_API_VERSION**`, `**BARE_OS_KERNEL_FEATURE_BITS_DOC**`, `**BARE_OS_LIFECYCLE_SCHEMA_VERSION**`, and mentions `**bits5**` … `**bits10**`. Root `**pretest`**.
Checks **[`docs/reference/compatibility-matrix.md`](../docs/reference/compatibility-matrix.md)** lists the current **`BARE_OS_CTX_API_VERSION`**, **`BARE_OS_KERNEL_FEATURE_BITS_DOC`**, **`BARE_OS_LIFECYCLE_SCHEMA_VERSION`**, and mentions **`bits5`** … **`bits10`**. Root **`pretest`**.
## `verify-doc-contracts.mjs`
**Usage:** `node scripts/verify-doc-contracts.mjs`
Ensures **`BARE_OS_CTX_API_VERSION**` and `**BARE_OS_POSIX_PROFILE_VERSION**` appear in the compatibility matrix and declared POSIX profile doc, and that `**/proc/bare_os/syscalls.json**` `**schemaVersion**` matches `**kernel/etc/bare-os/syscalls.example.json`** and **[`docs/schemas/bare-os-syscalls.schema.json`](../docs/schemas/bare-os-syscalls.schema.json)**. Root **`pretest**` (after `**verify-compat-matrix`**).
Ensures **`BARE_OS_CTX_API_VERSION`** and **`BARE_OS_POSIX_PROFILE_VERSION`** appear in the compatibility matrix and declared POSIX profile doc, and that **`/proc/bare_os/syscalls.json`** **`schemaVersion`** matches **`kernel/etc/bare-os/syscalls.example.json`** and **[`docs/schemas/bare-os-syscalls.schema.json`](../docs/schemas/bare-os-syscalls.schema.json)**. Root **`pretest`** (after **`verify-compat-matrix`**).
## `verify-bundle-health.mjs`
**Usage:** `node scripts/verify-bundle-health.mjs`
Asserts **[`docs/audit/bundle-health.json`](../docs/audit/bundle-health.json)** (regenerated by **`npm run build -w bare-os-bare-libs**`) matches `**kernel/lib/bare/manifest.json**` and on-disk `**kernel/lib/bare/bundles/*.js**` byte sizes. Detects orphan bundle files. Root `**pretest`**.
Asserts **[`docs/audit/bundle-health.json`](../docs/audit/bundle-health.json)** (regenerated by **`npm run build -w bare-os-bare-libs**`) matches **`kernel/lib/bare/manifest.json`** and on-disk **`kernel/lib/bare/bundles/*.js`** byte sizes. Detects orphan bundle files. Root **`pretest`**.
## `verify-bundle-markers.mjs`
**Usage:** `node scripts/verify-bundle-markers.mjs`
Scans vendored **`kernel/lib/bare/bundles/*.js**` for `**TODO` / `FIXME` / `XXX` / `NOT_IMPLEMENTED` / `###TODO###`** unless the basename is listed in **[`docs/audit/bundle-marker-allowlist.json`](../docs/audit/bundle-marker-allowlist.json)**. Complements **`verify-runtime-no-incomplete-markers.mjs**` (hand-authored sources only). Root `**pretest`**.
Scans vendored **`kernel/lib/bare/bundles/*.js`** for `**TODO` / `FIXME` / `XXX` / `NOT_IMPLEMENTED` / `###TODO###`** unless the basename is listed in **[`docs/audit/bundle-marker-allowlist.json`](../docs/audit/bundle-marker-allowlist.json)**. Complements **`verify-runtime-no-incomplete-markers.mjs`** (hand-authored sources only). Root **`pretest`**.
## `sync-holepunch-clones.mjs`
**Usage:** `node scripts/sync-holepunch-clones.mjs` — chained by **`npm run audit:holepunch-clones**` with `**report-holepunch-lockfile-drift.mjs`** (repo root).
**Usage:** `node scripts/sync-holepunch-clones.mjs` — chained by **`npm run audit:holepunch-clones**` with **`report-holepunch-lockfile-drift.mjs`** (repo root).
Writes **[`docs/audit/holepunch-clone-sync-report.json`](../docs/audit/holepunch-clone-sync-report.json)** (**schema 3**) for every distinct **`package**` name in `**packages/bare-os-booter/lib/bare-module-manifest.json**` (also honors legacy `**name**` / `**packageName**` if present). After `**sync:bare-manifest**` or hand-edits to that JSON, run `**npm run verify:manifest-data**` so `**bare-module-manifest.data.mjs**` stays aligned before `**pear stage**`. Scoped npm names (`**@scope/pkg**`) are mapped to the `**pkg**` directory expected under `**holepunchto_repos**`. Each row records `**cloneExists**`, `**gitHead**`, `**originMainHead**`, `**originMainResolvable**`, `**commitsBehindOriginMain**`, `**commitsAheadOfOriginMain**` (run `**git fetch origin main**` in clones so `**origin/main**` is meaningful), and `**packageJsonVersion**`. The report also includes `**goldenPathRows**` from `**goldenPathRepos`** in **[`docs/audit/holepunch-drift-repos.json`](../docs/audit/holepunch-drift-repos.json)** (maintainer review only) and **`goldenPathGaps**` when a golden-path basename has no resolvable clone or `**origin/main`**. The same run appends one NDJSON line per manifest row to **[`docs/audit/holepunch-clone-sync-summary.ndjson`](../docs/audit/holepunch-clone-sync-summary.ndjson)** (**schema 2** lines). Set **`BARE_OS_HOLEPUNCH_CLONES_ROOT**` when your checkout is not `**$HOME/dev/pearcli/holepunch-repos/holepunchto_repos`**. Operator-maintained; not in default CI.
Writes **[`docs/audit/holepunch-clone-sync-report.json`](../docs/audit/holepunch-clone-sync-report.json)** (**schema 3**) for every distinct **`package`** name in **`packages/bare-os-booter/lib/bare-module-manifest.json`** (also honors legacy **`name`** / **`packageName`** if present). After **`sync:bare-manifest`** or hand-edits to that JSON, run `**npm run verify:manifest-data**` so **`bare-module-manifest.data.mjs`** stays aligned before `**pear stage**`. Scoped npm names (`**@scope/pkg**`) are mapped to the **`pkg`** directory expected under **`holepunchto_repos`**. Each row records **`cloneExists`**, **`gitHead`**, **`originMainHead`**, **`originMainResolvable`**, **`commitsBehindOriginMain`**, **`commitsAheadOfOriginMain`** (run `**git fetch origin main**` in clones so **`origin/main`** is meaningful), and **`packageJsonVersion`**. The report also includes **`goldenPathRows`** from **`goldenPathRepos`** in **[`docs/audit/holepunch-drift-repos.json`](../docs/audit/holepunch-drift-repos.json)** (maintainer review only) and **`goldenPathGaps`** when a golden-path basename has no resolvable clone or **`origin/main`**. The same run appends one NDJSON line per manifest row to **[`docs/audit/holepunch-clone-sync-summary.ndjson`](../docs/audit/holepunch-clone-sync-summary.ndjson)** (**schema 2** lines). Set **`BARE_OS_HOLEPUNCH_CLONES_ROOT`** when your checkout is not **`$HOME/dev/pearcli/holepunch-repos/holepunchto_repos`**. Operator-maintained; not in default CI.
## `report-holepunch-lockfile-drift.mjs`
**Usage:** `npm run audit:holepunch-clones` (includes this step) or `node scripts/report-holepunch-lockfile-drift.mjs`
Compares hoisted **`package-lock.json**` versions (`**node_modules/<pkg>**`) against `**lockfilePackages`** in **[`docs/audit/holepunch-drift-repos.json`](../docs/audit/holepunch-drift-repos.json)** and local clone **`package.json`** versions. Writes **[`docs/audit/holepunch-lockfile-drift.json`](../docs/audit/holepunch-lockfile-drift.json)** and **`holepunch-lockfile-drift-summary.ndjson`**, plus a maintainer-readable Markdown table **[`docs/audit/holepunch-lockfile-drift-dashboard.md`](../docs/audit/holepunch-lockfile-drift-dashboard.md)**. Informational only (not a failing CI gate).
Compares hoisted **`package-lock.json`** versions (**`node_modules/<pkg>`**) against **`lockfilePackages`** in **[`docs/audit/holepunch-drift-repos.json`](../docs/audit/holepunch-drift-repos.json)** and local clone **`package.json`** versions. Writes **[`docs/audit/holepunch-lockfile-drift.json`](../docs/audit/holepunch-lockfile-drift.json)** and **`holepunch-lockfile-drift-summary.ndjson`**, plus a maintainer-readable Markdown table **[`docs/audit/holepunch-lockfile-drift-dashboard.md`](../docs/audit/holepunch-lockfile-drift-dashboard.md)**. Informational only (not a failing CI gate).
## `audit-placeholder-baseline.mjs`
**Usage:** `npm run audit:placeholder-baseline` (regenerate JSON) · `npm run audit:placeholder-baseline:check` (root **`pretest`**)
Emits **[`docs/audit/placeholder-baseline-scan.json`](../docs/audit/placeholder-baseline-scan.json)** — TODO/stub-phrase sweep over first-party kernel, booter, protocol, and coreutils **`src**` trees (excludes vendored bundles). `**--check`** compares a fresh scan to the committed JSON plus optional **[`docs/audit/placeholder-baseline-allowlist.json`](../docs/audit/placeholder-baseline-allowlist.json)** and fails **`pretest`** on new disallowed hits.
Emits **[`docs/audit/placeholder-baseline-scan.json`](../docs/audit/placeholder-baseline-scan.json)** — TODO/stub-phrase sweep over first-party kernel, booter, protocol, and coreutils **`src`** trees (excludes vendored bundles). **`--check`** compares a fresh scan to the committed JSON plus optional **[`docs/audit/placeholder-baseline-allowlist.json`](../docs/audit/placeholder-baseline-allowlist.json)** and fails **`pretest`** on new disallowed hits.
## `verify-posix-profile-triplet.mjs`
**Usage:** root **`pretest`**
Fails when **`BARE_OS_POSIX_PROFILE_VERSION**` / `**BARE_OS_POSIX_PROFILE_ID**` diverge between `**bare-os-posix-profile.js`**, **[`POSIX_DECLARED_PROFILE.md`](../docs/architecture/POSIX_DECLARED_PROFILE.md)**, and **`posix-compliance-matrix.json**`, or when the matrix `**note`** omits the profile version string.
Fails when **`BARE_OS_POSIX_PROFILE_VERSION`** / **`BARE_OS_POSIX_PROFILE_ID`** diverge between **`bare-os-posix-profile.js`**, **[`POSIX_DECLARED_PROFILE.md`](../docs/architecture/POSIX_DECLARED_PROFILE.md)**, and **`posix-compliance-matrix.json`**, or when the matrix **`note`** omits the profile version string.
## `verify-holepunch-clone-drift.mjs`
**Usage:** `node scripts/verify-holepunch-clone-drift.mjs` (root **`pretest`**)
Runs on every **`pretest**`. For each repo basename listed in `**repos`** inside **[`docs/audit/holepunch-drift-repos.json`](../docs/audit/holepunch-drift-repos.json)**, checks that **`origin/main**` is an ancestor of `**HEAD**` (clone not behind remote). With an empty `**repos**` array, the script is a no-op unless `**BARE_OS_HOLEPUNCH_DRIFT_TIER1=1**`, in which case it checks `**tier1Repos[]**` (hypercore, hyperdrive, hyperswarm, protomux, pear, pear-runtime, bare-fs, bare-process) instead. The same file carries `**suggestedCriticalRepos**` and optional `**goldenPathRepos**` (wire stack + runtime hints); copy `**suggestedCriticalRepos**` into `**repos**` when you maintain local clones and want CI to enforce freshness. `**goldenPathRepos**` is informational only (surfaced in `**holepunch-clone-sync-report.json**`). Set `**BARE_OS_HOLEPUNCH_DRIFT_CHECK=0**` to skip the script entirely (e.g. offline sandboxes). `**sync-holepunch-clones.mjs**` echoes `**suggestedCriticalRepos**` into `**holepunch-clone-sync-report.json`** for review.
Runs on every **`pretest`**. For each repo basename listed in **`repos`** inside **[`docs/audit/holepunch-drift-repos.json`](../docs/audit/holepunch-drift-repos.json)**, checks that **`origin/main`** is an ancestor of **`HEAD`** (clone not behind remote). With an empty **`repos`** array, the script is a no-op unless **`BARE_OS_HOLEPUNCH_DRIFT_TIER1=1`**, in which case it checks `**tier1Repos[]**` (hypercore, hyperdrive, hyperswarm, protomux, pear, pear-runtime, bare-fs, bare-process) instead. The same file carries **`suggestedCriticalRepos`** and optional **`goldenPathRepos`** (wire stack + runtime hints); copy **`suggestedCriticalRepos`** into **`repos`** when you maintain local clones and want CI to enforce freshness. **`goldenPathRepos`** is informational only (surfaced in **`holepunch-clone-sync-report.json`**). Set **`BARE_OS_HOLEPUNCH_DRIFT_CHECK=0`** to skip the script entirely (e.g. offline sandboxes). **`sync-holepunch-clones.mjs`** echoes **`suggestedCriticalRepos`** into **`holepunch-clone-sync-report.json`** for review.
## `verify-holepunch-clone-freshness.mjs`
**Usage:** `node scripts/verify-holepunch-clone-freshness.mjs` (chained in root **`pretest`** after drift)
Reads **[`docs/audit/holepunch-freshness-gate.json`](../docs/audit/holepunch-freshness-gate.json)**. Default **`enabled: false**` — the script logs and exits **0** so offline CI never needs local clones. When `**enabled**` is `**true**`, listed repos under `**BARE_OS_HOLEPUNCH_CLONES_ROOT**` (default `**~/dev/pearcli/holepunch-repos/holepunchto_repos**`) that exceed `**maxCommitsBehind**` vs `**origin/main**` cause a **warning**; set `**BARE_OS_HOLEPUNCH_FRESHNESS_STRICT=1**` to **fail** `**pretest**`. Requires `**git fetch origin main`** in each clone for meaningful counts.
Reads **[`docs/audit/holepunch-freshness-gate.json`](../docs/audit/holepunch-freshness-gate.json)**. Default **`enabled: false**` — the script logs and exits **0** so offline CI never needs local clones. When **`enabled`** is **`true`**, listed repos under **`BARE_OS_HOLEPUNCH_CLONES_ROOT`** (default **`~/dev/pearcli/holepunch-repos/holepunchto_repos`**) that exceed **`maxCommitsBehind`** vs **`origin/main`** cause a **warning**; set **`BARE_OS_HOLEPUNCH_FRESHNESS_STRICT=1`** to **fail** **`pretest`**. Requires `**git fetch origin main`** in each clone for meaningful counts.
## `gen-bare-holepunch-catalog.mjs`
**Usage:** `node scripts/gen-bare-holepunch-catalog.mjs` (also **`npm run gen:bare-catalog**` / `**npm run gen:bare-catalog:check`** from the repo root)
Scans a local Holepunch mirror ( **`HOLEPUNCH_MIRROR**` or default under the repo) for `**holepunchto/bare-***` repos, merges npm `**latest`** metadata and **[`scripts/bare-catalog-overrides.json`](bare-catalog-overrides.json)**, and writes **[`docs/bare-holepunch-catalog.json`](../docs/bare-holepunch-catalog.json)**. Follow with **`npm run sync:bare-manifest**` and `**npm install`** so **[`packages/bare-os-booter/lib/bare-module-manifest.json`](../packages/bare-os-booter/lib/bare-module-manifest.json)** and booter **`optionalDependencies**` stay aligned. CI `**gen:bare-catalog:check`** ensures the committed catalog does not drift.
Scans a local Holepunch mirror ( **`HOLEPUNCH_MIRROR`** or default under the repo) for **`holepunchto/bare-*`** repos, merges npm **`latest`** metadata and **[`scripts/bare-catalog-overrides.json`](bare-catalog-overrides.json)**, and writes **[`docs/bare-holepunch-catalog.json`](../docs/bare-holepunch-catalog.json)**. Follow with **`npm run sync:bare-manifest**` and `**npm install`** so **[`packages/bare-os-booter/lib/bare-module-manifest.json`](../packages/bare-os-booter/lib/bare-module-manifest.json)** and booter **`optionalDependencies`** stay aligned. CI **`gen:bare-catalog:check`** ensures the committed catalog does not drift.
## `verify-bundle-throws.mjs`
**Usage:** `node scripts/verify-bundle-throws.mjs`
Scans vendored **`kernel/lib/bare/bundles/*.js**` for `**new Error("…")**` string arguments whose message matches incomplete-implementation phrases (`**not implemented**`, `**not yet implemented**`, `**abstract method … not implemented**`), regardless of whether the call is `**throw**`, `**cb(…)**`, or `**emit("error", …)**`. Known-upstream stream and ICO messages are rewritten in `**scripts/sanitize-bare-bundles.mjs**` during `**bare-os-bare-libs`** build; **[`docs/audit/bundle-throw-allowlist.json`](../docs/audit/bundle-throw-allowlist.json)** is **empty** by policy. Root **`pretest`**.
Scans vendored **`kernel/lib/bare/bundles/*.js`** for `**new Error("…")**` string arguments whose message matches incomplete-implementation phrases (`**not implemented**`, `**not yet implemented**`, `**abstract method … not implemented**`), regardless of whether the call is **`throw`**, `**cb(…)**`, or `**emit("error", …)**`. Known-upstream stream and ICO messages are rewritten in **`scripts/sanitize-bare-bundles.mjs`** during **`bare-os-bare-libs`** build; **[`docs/audit/bundle-throw-allowlist.json`](../docs/audit/bundle-throw-allowlist.json)** is **empty** by policy. Root **`pretest`**.
## `verify-kernel-program-doc.mjs`
**Usage:** `node scripts/verify-kernel-program-doc.mjs`
Ensures **[`developer-guide/kernel-program.md`](../developer-guide/kernel-program.md)** exists and references the **100-item** program, **`kernel_program**` proc path, and `**operatorSketches**`. Root `**pretest`**.
Ensures **[`developer-guide/kernel-program.md`](../developer-guide/kernel-program.md)** exists and references the **100-item** program, **`kernel_program`** proc path, and **`operatorSketches`**. Root **`pretest`**.
## `verify-kernel-program-proc-schema.mjs`
**Usage:** `node scripts/verify-kernel-program-proc-schema.mjs`
Asserts **`buildKernelProgramProcJson**` returns `**schema**` / `**programVersion**` matching `**KERNEL_PROGRAM_PROC_SCHEMA**` / `**KERNEL_PROGRAM_PROC_VERSION**` and that an `**operatorSketches**` object is present. Root `**pretest`**.
Asserts **`buildKernelProgramProcJson`** returns **`schema`** / **`programVersion`** matching **`KERNEL_PROGRAM_PROC_SCHEMA`** / **`KERNEL_PROGRAM_PROC_VERSION`** and that an **`operatorSketches`** object is present. Root **`pretest`**.
## `verify-kernel-program-roadmap-table.mjs`
**Usage:** `node scripts/verify-kernel-program-roadmap-table.mjs`
Asserts **[`docs/reference/feature-roadmap.md`](../docs/reference/feature-roadmap.md)** contains **`## Kernel program backlog — batch B (100 items)**` with at least **100** numbered table rows. Root `**pretest`**.
Asserts **[`docs/reference/feature-roadmap.md`](../docs/reference/feature-roadmap.md)** contains **`## Kernel program backlog — batch B (100 items)**` with at least **100** numbered table rows. Root **`pretest`**.
## `fuzz-boot-policy-json.mjs`
@@ -390,23 +390,23 @@ Compares **`bootMs`** fields from two benchmark JSON files; exits **1** when reg
**Usage:** `node scripts/kernel-microbench.mjs [--list] [--suite boot|vfs|crypto|syscall] [--all]`
Host-side microbench driver used as a **regression-shaped** workload (not a literal cold-boot timer). The **`boot**` suite prints JSON with `**bootMs**` suitable for `**kernel-program-release-gate.mjs**`. The `**vfs**` suite adds `**warmReplicationPathClassify**` (synthetic `**/bin**` / `**/lib/bare**` path classification) and `**warmReadCacheInvalidateSynthetic**` (JS `**Map`** clear/refill churn — informal warm-cache invalidation comparison). Example baseline fixture: [`fixtures/kernel-microbench-release-gate-baseline.example.json`](fixtures/kernel-microbench-release-gate-baseline.example.json).
Host-side microbench driver used as a **regression-shaped** workload (not a literal cold-boot timer). The **`boot`** suite prints JSON with **`bootMs`** suitable for **`kernel-program-release-gate.mjs`**. The **`vfs`** suite adds **`warmReplicationPathClassify`** (synthetic **`/bin`** / **`/lib/bare`** path classification) and **`warmReadCacheInvalidateSynthetic`** (JS **`Map`** clear/refill churn — informal warm-cache invalidation comparison). Example baseline fixture: [`fixtures/kernel-microbench-release-gate-baseline.example.json`](fixtures/kernel-microbench-release-gate-baseline.example.json).
## `kernel-vfs-simulated-host-bench.mjs` / `kernel-net-deterministic-bench.mjs` / `kernel-bare-crypto-microbench.mjs`
Single-purpose host benchmarks: deterministic VFS-shaped CPU loop (**`kernel-vfs-simulated-host-bench.mjs**` output `**schema: 2**`: warm `**/lib/bare**` path classification), socket-bridge readiness sketch for DGRAM/TCP (`**kernel-net-deterministic-bench.mjs**`, `**schema: 2**`), and SHA-256 regression loop via Node `**crypto**`. Also surfaced under `**kernel-microbench.mjs**` suites `**vfs**` / `**crypto`**.
Single-purpose host benchmarks: deterministic VFS-shaped CPU loop (**`kernel-vfs-simulated-host-bench.mjs`** output `**schema: 2**`: warm **`/lib/bare`** path classification), socket-bridge readiness sketch for DGRAM/TCP (**`kernel-net-deterministic-bench.mjs`**, `**schema: 2**`), and SHA-256 regression loop via Node **`crypto`**. Also surfaced under **`kernel-microbench.mjs`** suites **`vfs`** / **`crypto`**.
## `kernel-program-benchmark-harness.mjs`
**Usage:** `node scripts/kernel-program-benchmark-harness.mjs [--list|--help|--sample-boot-ms N]`
Synthetic **`bootMs**` JSON for `**kernel-program-release-gate.mjs**` fixtures when you need a deterministic sample without running `**kernel-microbench.mjs**`. The `**--list**` suite names (e.g. `**kernel_crypto_synthetic_benchmark**`) label **host-side regression harnesses** and **deterministic samples**—not incomplete kernel implementations. `**packages/bare-os-booter/test.js**` uses **in-memory VFS fakes** and **HTTP test doubles** for `**curl`/`wget`**; those are **test-only** substitutes, not guest image behavior.
Synthetic **`bootMs`** JSON for **`kernel-program-release-gate.mjs`** fixtures when you need a deterministic sample without running **`kernel-microbench.mjs`**. The **`--list`** suite names (e.g. **`kernel_crypto_synthetic_benchmark`**) label **host-side regression harnesses** and **deterministic samples**—not incomplete kernel implementations. **`packages/bare-os-booter/test.js`** uses **in-memory VFS fakes** and **HTTP test doubles** for `**curl`/`wget`**; those are **test-only** substitutes, not guest image behavior.
## `validate-example-schemas.mjs`
**Usage:** `node scripts/validate-example-schemas.mjs`
Validates representative JSON under **`kernel/etc/bare-os/**` (e.g. `**boot.policy.example.json**`, boot-trace and telemetry samples, `**otel-jsonl.example.json`**) against **[`docs/schemas/`](../docs/schemas/)** using **Ajv** draft 2020-12. Invoked from the root **`pretest**` hook after `**verify-ctx-api-feature-bits.mjs`**.
Validates representative JSON under **`kernel/etc/bare-os/`** (e.g. **`boot.policy.example.json`**, boot-trace and telemetry samples, **`otel-jsonl.example.json`**) against **[`docs/schemas/`](../docs/schemas/)** using **Ajv** draft 2020-12. Invoked from the root **`pretest`** hook after **`verify-ctx-api-feature-bits.mjs`**.
## `stage-release.sh`
@@ -414,30 +414,30 @@ Maintainer helper for release/staging workflows (see script header for intended
## Root `npm run test:bare`
Runs **`bare-os-protocol**` tests, `**bare-os-booter**` `**test:bare**` (`**brittle-bare**` identity slice), and `**bare-os-seeder**` `**node --test**` helpers. Full workspace coverage remains `**npm test**` (includes `**brittle-node`** booter harness + coreutils).
Runs **`bare-os-protocol`** tests, **`bare-os-booter`** **`test:bare`** (**`brittle-bare`** identity slice), and **`bare-os-seeder`** `**node --test**` helpers. Full workspace coverage remains `**npm test**` (includes **`brittle-node`** booter harness + coreutils).
## Maintainer: `pretest` generator runbook
Root **`npm run pretest**` is the canonical doc/code gate. Run it before pushing when you touch booter `**ctx`**, POSIX artifacts, bundles, or the kernel image. Order (mirrors [`package.json`](../package.json) **`pretest`**):
Root **`npm run pretest**` is the canonical doc/code gate. Run it before pushing when you touch booter **`ctx`**, POSIX artifacts, bundles, or the kernel image. Order (mirrors [`package.json`](../package.json) **`pretest`**):
1. **`npm run build -w bare-os-coreutils**` — Refreshes staged `**kernel/bin**` and `**kernel/share/man/man.json**` from `**packages/bare-os-coreutils`** (`ensure-man-pages` + `build.mjs`).
2. **`npm run build -w bare-os-bare-libs**` — Rebuilds `**kernel/lib/bare/bundles/*.js**` and related audit JSON; invokes `**sanitize-bare-bundles`** as configured in that workspace.
3. **`npm run bundle:kernel**` — `**scripts/bundle-kernel-init.mjs**` → `**kernel/init.js**` from `**kernel/lib/boot/*.js**` + `**kernel/lib/init/init-main.js`**.
4. **`scripts/gen-kernel-extensions-index.mjs**` — Regenerates `**docs/reference/kernel-extensions-generated-toc.md`**.
5. **`scripts/verify-kernel-seeder-parity.mjs**` — `**kernel/**` must match `**packages/bare-os-seeder/kernel/`** (rsync after kernel edits).
1. **`npm run build -w bare-os-coreutils**` — Refreshes staged **`kernel/bin`** and **`kernel/share/man/man.json`** from **`packages/bare-os-coreutils`** (`ensure-man-pages` + `build.mjs`).
2. **`npm run build -w bare-os-bare-libs**` — Rebuilds **`kernel/lib/bare/bundles/*.js`** and related audit JSON; invokes **`sanitize-bare-bundles`** as configured in that workspace.
3. **`npm run bundle:kernel**` — **`scripts/bundle-kernel-init.mjs`** → **`kernel/init.js`** from **`kernel/lib/boot/*.js`** + **`kernel/lib/init/init-main.js`**.
4. **`scripts/gen-kernel-extensions-index.mjs`** — Regenerates **`docs/reference/kernel-extensions-generated-toc.md`**.
5. **`scripts/verify-kernel-seeder-parity.mjs`** — **`kernel/`** must match **`packages/bare-os-seeder/kernel/`** (rsync after kernel edits).
6. **Policy / terminology / roadmap verifiers** — Banned tokens, naming matrix, feature-roadmap canonical JSON, giant-phase guard, runtime incomplete-marker scan, bare imports, boot-step alignment.
7. **`scripts/gen-ctx-client-helper.mjs**` — Regenerates the TS helper when `**BARE_OS_CTX_API_VERSION**` changes (`**packages/bare-os-booter/lib/bare-os-ctx-api.js`**).
8. **Extension manifest + boot policy + capability contract verifiers** — **`verify-extension-manifest-schema**`, signer pins, `**verify-ctx-api-feature-bits**`, `**verify-kernel-capabilities-contract.mjs**`, capability-word **6–11** table depth scripts, `**verify-ctx-dts.mjs`**.
9. **`scripts/validate-example-schemas.mjs**` — Ajv check for `**kernel/etc/bare-os/*.example.json**` vs `**docs/schemas/`**.
7. **`scripts/gen-ctx-client-helper.mjs`** — Regenerates the TS helper when **`BARE_OS_CTX_API_VERSION`** changes (**`packages/bare-os-booter/lib/bare-os-ctx-api.js`**).
8. **Extension manifest + boot policy + capability contract verifiers** — **`verify-extension-manifest-schema`**, signer pins, **`verify-ctx-api-feature-bits`**, **`verify-kernel-capabilities-contract.mjs`**, capability-word **6–11** table depth scripts, **`verify-ctx-dts.mjs`**.
9. **`scripts/validate-example-schemas.mjs`** — Ajv check for **`kernel/etc/bare-os/*.example.json`** vs **`docs/schemas/`**.
10. **Doc link + man coverage + compatibility matrix + doc contracts**.
11. **Bundle health / markers / throws** — Upstream bundle hygiene gates.
12. **Kernel program doc / proc schema / roadmap table verifiers**.
13. **`scripts/verify-pear-no-static-node-import.mjs`**.
14. **`scripts/gen-posix-dashboard.mjs**` + `**verify-posix-dashboard.mjs**` + `**verify-posix-profile-triplet.mjs**` + `**verify-posix-compliance-matrix.mjs`**.
15. **`scripts/verify-holepunch-clone-drift.mjs**` — No-op when `**holepunch-drift-repos.json**` `**repos[]`** is empty; optional release gate when populated.
16. **`scripts/verify-holepunch-clone-freshness.mjs**` — Optional lag gate from `**holepunch-freshness-gate.json**` (`**enabled: false**` by default); strict mode via `**BARE_OS_HOLEPUNCH_FRESHNESS_STRICT=1`**.
14. **`scripts/gen-posix-dashboard.mjs`** + **`verify-posix-dashboard.mjs`** + **`verify-posix-profile-triplet.mjs`** + **`verify-posix-compliance-matrix.mjs`**.
15. **`scripts/verify-holepunch-clone-drift.mjs`** — No-op when **`holepunch-drift-repos.json`** `**repos[]`** is empty; optional release gate when populated.
16. **`scripts/verify-holepunch-clone-freshness.mjs`** — Optional lag gate from **`holepunch-freshness-gate.json`** (`**enabled: false**` by default); strict mode via **`BARE_OS_HOLEPUNCH_FRESHNESS_STRICT=1`**.
17. **`npm run smoke:bare-manifest`** — Manifest import smoke.
18. **`npm run smoke:agent-web-fetch:bare`** (optional) — Runs [`scripts/smoke-agent-web-fetch-bare.mjs`](smoke-agent-web-fetch-bare.mjs) under the **Bare** runtime: exercises **`lib/agent-web-fetch.js**` timeout/abort contract and a live `**https://example.com`** fetch when network is available.
18. **`npm run smoke:agent-web-fetch:bare`** (optional) — Runs [`scripts/smoke-agent-web-fetch-bare.mjs`](smoke-agent-web-fetch-bare.mjs) under the **Bare** runtime: exercises **`lib/agent-web-fetch.js`** timeout/abort contract and a live **`https://example.com`** fetch when network is available.
19. **`npm run sample:agent-workspace`** — Runs [`print-agent-workspace-sample.mjs`](print-agent-workspace-sample.mjs): prints a concatenated **agent workspace** system prompt sample from [`packages/bare-os-coreutils/share/agent-workspace/`](../packages/bare-os-coreutils/share/agent-workspace/) (host Node; no booter).
**Commit expectation:** check in every regenerated artifact **`pretest` produces** (kernel init bundle, seeder mirror, generated markdown/JSON, dashboard) in the same change set as the source edit.