snxraven/bare-operating-system
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
d286ce19b5c1790281450602479e6b74a2959158
bare-operating-system/packages/bare-os-seeder/kernel
T
History
Raven Scott d286ce19b5 chore(plan): cancel end-to-end seeder-to-booter smoke harness task 
test(protocol): add deterministic MBR failover-key coverage
docs(protocol): align package-bare-os-protocol version to 0.9.1
test(booter): add MBR corruption and wrong-topic smoke fixtures
test(peer-seed): add strict pre-MBR bare_os.capabilities negotiation check
feat(seeder): validate BARE_OS_SEED_REQUIRE_MBR_LABELS
feat(seeder): validate BARE_OS_SEED_CAPABILITY_ATTESTATION_JSON schema
docs(boot-policy): add requireProtocolPackageMin 0.9.1 example
test(kernel): cover boot.policy denySeedRpcMethods behavior
test(protocol): add app/cap/chat/meshdrop channel compatibility fixture
test(swarm-disk): cover duplicate Protomux channel null-return path
test(protocol): add 11-word kernelCapabilityWords round-trip fixture
docs(schema): add mbr-layout schema and validate seeder examples
test(protocol): add topicKey() golden hash fixture
docs(trust): document block-0 trust assumptions in boot docs
feat(seeder): add discovery.flushed readiness logging
feat(booter): record peer discovery timings in boot-perf.json
feat(integration): add local testnet mode to integration lab smoke
test(booter): add Hyperswarm connection-budget env regression coverage
test(booter): add swarm plus Corestore suspend/resume integration coverage
feat(booter): mirror swarm ban events into host audit logs
feat(booter): add direct-peer boot via BARE_OS_BOOT_JOIN_PEER_HEX
feat(seeder): pass BARE_OS_SEED_MAX_PEERS to Hyperswarm
feat(seeder): log drive.version and discoveryKey at startup
test(booter): add Hyperdrive.checkout read-only boot probe coverage
feat(booter): prefetch /boot/init.js before kernel handoff
feat(booter): add optional /bin warm replication via downloadDiff
feat(seeder): add manifestPaths SHA-256 generation in stage-kernel-tree
test(peer-seed): cover helper-served block-0 after seeder exit
feat(protocol): add Protomux cork batching for initial channel sends
test(boot-graph): compare kernel/init labels with booter graph proc
docs(boot-policy): add v9-v11 schema examples
feat(release): add requireInitJsSha256 fixture generation step
test(vfs): add BARE_OS_VFS_SYSTEM_RO_ALIAS coverage
test(vfs): strengthen system-drive write-deny path coverage
feat(identity): add personal-drive namespace export/import docs and tests
test(booter): add guest-to-login warm cache invalidation regression
test(vfs): add guest deny coverage for /.bare sensitive paths
test(coreutils): add cross-drive mv failure injection coverage
test(vfs): add .bareos_empty round-trip coverage across mkdir/rmdir/cp/git-fs
test(vfs): add /dev/shm quota enforcement coverage
test(proc): add /proc/bare_os/index.json sortedness and schema checks
test(vfs): add warm read cache invalidation on replication growth
docs(ctx): document bareOsInvalidateWarmReadCaches(reason)
test(kernel): add BARE_OS_BOOT_DRY_RUN behavior coverage
docs(posix): add dashboard rows for all COREUTILS_COMMANDS
feat(curl): expand -w variables beyond http_code/url_effective/size_download
feat(wget): mark -N timestamping as explicit unsupported error
feat(curl): plumb mutual TLS cert/key intent to ctx.httpFetch metadata
feat(shuf): add deterministic seed mode via BARE_OS_SHUF_SEED
docs(sort): document -M month-sort as unsupported
feat(grep): add explicit -E and -G mode handling
test(sed): add Open Group Issue 7 golden fixtures
test(awk): add getline VFS regressions for missing/repeat/boundary cases
test(shell): add non-interactive here-doc coverage
test(shell): add trap delivery coverage for synthetic PIDs/job IDs
test(shell): add set -e compound-body behavior coverage
docs(shell): strengthen read builtin opt-in guidance
test(env): add Bare-runtime coverage for -S and --env-file
docs(man): add examples for pathcap-verify pkg-swarm-index corestorectl
test(identity): add account/vault backup-restore smoke coverage
feat(audit): add tamper detection verification for audit chain rows
test(peer-admission): cover strict empty allowlist deny behavior
test(peer-admission): add denylist precedence over allowlist coverage
test(peer-admission): add BARE_OS_PEER_REQUIRE_CAPS_JSON metadata checks
docs(identity): add trusted-key rotation example for path capabilities
feat(schema): tighten extensionSignerPinsV2-V4 hash validation
test(delegate): add allowlist negative cases for curl/wget/git/hrpc/systemctl
test(proc): extend /proc/self/environ redaction key coverage
docs(security): add peer-assisted block-0 mirroring threat-model notes
feat(bench): add boot budget trend output from real booter phases
test(baretop): align fixture coverage with /proc snapshot key set
test(metrics): validate /proc/bare_os/metrics.prom OpenMetrics shape
docs(ops): add structured seeder NDJSON examples
test(replication): add live stall-hint coverage for no_peers/length_unavailable/ok
docs(release): add corestore-snapshot workflow to checklist
docs(ops): add mirror-drive experiment utility to maintainer workflow
test(booter): add monitor progress coverage for replication live sketch
feat(seeder): validate DHT bootstrap address class JSON inputs
docs(network): add HYPERSWARM_BOOTSTRAP testnet operator guidance
chore(root): add deterministic test:integration script
docs(ci): add local CI runbook for no-.github environments
docs(release): add npm run test:bare after npm test
feat(verify): add protocol docs/package version parity checker
feat(verify): enforce feature-roadmap canonical path consistency
feat(lockfile-drift): add tier-1 strict fail option for mismatches
docs(lockfile-drift): add udx-native and blind-peering upgrade workflow notes
docs(cli-parity): add bare-fetch upstream issue tracking row
feat(bundle-health): generate per-tier bundle size regression thresholds
feat(doc-contracts): verify handbook references to current proc schema versions
feat(pretest): add validate-mermaid-syntax gate
feat(probe): add bare-runtime top-25 critical command lane
docs(protocol): update capability-word prose from bits..bits5 to current words
docs(two-drive): document /tmp /var/log and account-prefix routing
docs(security): add concise boot trust model page and links
docs(dev-guide): add P2P lab cookbook section
docs(dev-guide): add how-to for adding seed RPCs
docs(dev-guide): add how-to for adding /proc/bare_os nodes
docs(dev-guide): add /bin utility checklist for man/posix/build/parity/tests
docs(user-manual): add short What BareOS is not section
2026-04-26 22:28:21 -04:00
..
bin
chore(plan): cancel end-to-end seeder-to-booter smoke harness task
2026-04-26 22:28:21 -04:00
etc
chore(plan): cancel end-to-end seeder-to-booter smoke harness task
2026-04-26 22:28:21 -04:00
lib
chore(plan): cancel end-to-end seeder-to-booter smoke harness task
2026-04-26 22:28:21 -04:00
share
chore(plan): cancel end-to-end seeder-to-booter smoke harness task
2026-04-26 22:28:21 -04:00
init.js
Change how login works
2026-04-26 06:19:47 -04:00
README.md
chore(plan): cancel end-to-end seeder-to-booter smoke harness task
2026-04-26 22:28:21 -04:00

README.md

kernel — system image sources

Files in this directory are read from disk by the seeder (or copied into packages/bare-os-seeder/kernel/ for Pear) and written into the system Hyperdrive with no temporary directory on the host.

This README.md file only documents the tree layout in the repository; the seeder does not install it as /README.md on the image (so the guest root directory stays free of repo docs).

Documentation: Concepts — Boot · User manual · Handbook · Kernel image reference · Developer guide.

Staging map (seeder)

  • init.js — /boot/init.js
  • bin/<name> — /bin/<name>
  • etc/... — /etc/...
  • share/man/... — /share/man/...
  • lib/bare/... — /lib/bare/... (optional ctx.bare bundles; see bare-os-bare-libs)
  • Any other file — /<relative path>
  • **README.md (this file)** — (skipped — not copied to /README.md)

Contents

  • init.js — Kernel entry: must define async function start(ctx). Boot order: /etc/os-release → /etc/motd → optional /etc/bare-os/rc.profile.<profile> (profile from BARE_OS_BOOT_PROFILE or first line of /etc/bare-os/profile; the booter mirrors the resolved name in ctx.env.BARE_OS_BOOT_PROFILE_RESOLVED and /run/bare-os/boot_profile) → /etc/bare-os/rc → **/etc/bare-os/rc.d/*** (sorted; digit-prefixed names only; skip dotfiles, *~, README*, *.md; optional BARE_OS_RC_D_SKIP comma list and prefix* patterns) → optional /etc/bare-os/rc.local → /etc/bare-os/kernel.d/* (same rules as rc.d) → banner → when BARE_OS_SKIP_REPL, optional onboot lines from BARE_OS_ONBOOT or /etc/bare-os/onboot → **readLine / execLine** loop. Boot execLine errors in trusted snippets are logged; with BARE_OS_BOOT_STRICT=1 or true, the first throw calls requestBooterExit(1) and stops later boot phases. Custom kernels may call ctx.registerKernelShutdownHook(fn) before initd disposers; use ctx.bareOsRuntimeCaps for limits, pseudo paths, and features ([developer-guide/02-the-context-object.md](../developer-guide/02-the-context-object.md)).
  • bin/ — Tier-1 utilities built by bare-os-coreutils plus sshd / bare-sshd from bare-os-openssh (179 commands in COREUTILS_COMMANDS; sshd is listed for man/help but its concatenated script is emitted by the openssh package build, not coreutils src/). Each file is runtime.js + optional preamble (lib/md5.js for md5sum, lib/sha224.js for sha224sum, lib/*-engine.js for sed/awk, jq-engine.js, lib/man-render.js, lib/edit-*.js for edit/nano, lscolors for ls/dircolors, …) + **async function run(ctx, argv)** (no ESM import in src/). /bin/nano duplicates /bin/edit for familiarity; the shell’s default **nano → edit** alias uses the edit command name after expansion. dir/vdir invoke ls via ctx.runBinCommand.
  • lib/bare/ — Optional IIFE bundles + manifest.json for ctx.bare drive merge, built by bare-os-bare-libs. Same trust model as bin/ (trusted seeded image).
  • share/man/man.json — Merged manual database for /bin/man (built by bare-os-coreutils; see handbook ch.10).
  • etc/os-release — Static OS metadata (NAME, VERSION, …).
  • etc/motd — Optional message printed after os-release (distributors can customize).
  • etc/bare-os/banner or /etc/issue — If present on the system drive, the default kernel prints one of these instead of the built-in session hint (unless BARE_OS_SKIP_REPL shortens the banner). Set BARE_OS_BOOT_TRACE=1 or true for [boot] phase: Nms lines on stderr, json for {"phase":"…","ms":n} per phase, or ndjson for machine-readable lines with sessionId. Recovery: BARE_OS_BOOT_MINIMAL, granular BARE_OS_BOOT_SKIP, optional BARE_OS_KERNEL_SELFTEST (TAP via BARE_OS_SELFTEST_FORMAT=tap; includes /proc/bare_os_resources / /proc/bare_os_features checks), readiness via ctx.bareOsPublishBootReady → /run/bare-os/ready and /run/bare-os/boot.json (phases from the stock kernel plus booterPhases from the booter — see developer guide ch.2).
  • etc/bare-os/rc — Optional boot snippet: one execLine per non-comment line (trusted).
  • etc/bare-os/rc.d/ — Optional extra snippets (basename must start with a digit), same line rules, run after rc in filename order. Human-oriented notes live in .README (a dotfile so legacy init.js never executes it).

Editing workflow

Do not edit kernel/init.js by hand. It is generated from kernel/lib/boot/*.js (sorted), kernel/lib/init/fragments/*.js (sorted), and kernel/lib/init/init-main.js via npm run bundle:kernel (scripts/bundle-kernel-init.mjs). CI and npm run verify:init-bundle fail when the file drifts. Edit the fragments under lib/boot/, lib/init/fragments/, and lib/init/ only, then bundle and rsync to packages/bare-os-seeder/kernel/ for Pear parity. See lib/init/STRUCTURE.md.

  1. Change sources under kernel/ or packages/bare-os-coreutils/src/.
  2. Run npm run build -w bare-os-coreutils to refresh kernel/bin/*.
  3. Run npm run build -w bare-os-bare-libs when packages/bare-os-booter/lib/bare-module-manifest.json or bundle entries change.
  4. Run seeder again to re-stage the drive (or use a fresh Corestore for a clean image).

Host boot perf: when BARE_OS_BOOT_PERF_DETAIL=1, the stock booter logs bare_stdlib_merge_ns after maybeMergeBareFromDrive (monotonic hrtime delta in nanoseconds) alongside guest boot-perf.json stages.

Pear bundles use the vendored tree under packages/bare-os-seeder/kernel/; keep it in sync by running the same builds before pear stage. Use npm run maintainer:kernel-image from the repo root for coreutils + bare-libs + init bundle + extensions index + parity verify (then rsync -a --delete kernel/ packages/bare-os-seeder/kernel/ if the verifier reports drift). npm test runs scripts/verify-kernel-seeder-parity.mjs, scripts/verify-ctx-api-feature-bits.mjs, and scripts/validate-example-schemas.mjs (after bare-os-coreutils and bare-os-bare-libs builds) so the two trees match byte-for-byte, ctx semver / feature words stay wired, example JSON matches docs/schemas/, and every kernel/bin/* file contains the BARE_OS_BIN_API pragma (coreutils runtime.js and hand-written stubs such as systemctl / journalctl).

Optional system image examples: etc/bare-os/boot.allow.example (copy to boot.allow when using host BARE_OS_BOOT_ALLOWLIST=1), etc/bare-os/boot.policy.example.json (install as boot.policy.json when using BARE_OS_BOOT_POLICY=1; v2 fields maxExecLineDepth, denyEnvKeys, requireProcNodes; v3 requireKernelCapabilitiesExtendedSeedingPlatform, requireKernelCapabilitiesRlimitsDelegatesShell, allowedPearIpcChannels, denyVfsPrefixes, maxInitdRestartsPerUnit; v4 requireKernelCapabilitiesOfflineNetExtensions, denyExecLineBuiltins, allowedCtxMethods; v9 requireKernelCapabilitiesBareModuleCryptoStaging, requirePearRuntimeRange, denyBareModuleSpecifierPatterns, requireBareCryptoMin, denyKernelSyscalls, requirePearIpcMin, extensionSignerPinsV2, offlineLkgManifestMaxAgeSec, bootPhasesRequireProcIndexMinSchema; v10 requireKernelCapabilitiesPearInspectLoggerTls, requireBareBootMin, bootPhasesRequireLifecycleMinSchema, extensionSignerPinsV3, …; JSON Schema: [docs/schemas/boot.policy.schema.json](../docs/schemas/boot.policy.schema.json)), etc/bare-os/kernel.extensions.registry.example.json (shape for /proc/bare_os/extensions.json schema 7), etc/bare-os/boot-trace-line.example.json and etc/bare-os/telemetry-ndjson.example.json (shape checks for CI), etc/bare-os/rc.profile.full (sample full profile referenced from profile), etc/bare-os/crontab.example (system-wide cron lines merged ahead of user ~/.crontab), etc/bare-os/timers/*.timer.example (copy to ~/.config/bare-os/timers/*.timer for OnCalendar=, EveryMs=, or OnInactiveSec= jobs). kernel.ext.d scripts register into /proc/bare_os/extensions.json when the booter provides ctx.bareOsRegisterKernelExtensionRecord.

See also

Reference in New Issue View Git Blame Copy Permalink