# What Is the Kernel Floor in OpenHuman? Understanding the Feature Gate Ratchet

> Learn about the OpenHuman Kernel Floor, its essential domains, and how the feature gate ratchet prevents unwanted growth to maintain a minimal core.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: deep-dive
- Published: 2026-09-01

---

**The OpenHuman Kernel Floor is a minimal runnable core containing only essential domains (threads, config, and security), while the feature gate ratchet is a CI mechanism that strictly prevents this baseline from growing by failing builds when new dependencies are added unintentionally.**

The OpenHuman project from `tinyhumansai/openhuman` implements a modular architecture designed to keep embedded binaries lean. At the heart of this system lies the **Kernel Floor**, a deliberately minimal runtime core that excludes optional subsystems like voice, web3, or flows unless explicitly requested by the developer.

## Defining the OpenHuman Kernel Floor

The Kernel Floor represents the absolute minimal set of functionality required to run the OpenHuman core. According to the source code in [`src/core/runtime/builder.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/runtime/builder.rs), this baseline includes exactly three domains:

- **threads**
- **config**
- **security**

The inline documentation at line 325 explicitly defines this constraint:

> "The kernel floor: threads, config, security — and nothing else."

This design ensures that third-party embeddings can start with the smallest possible binary footprint. Rather than compiling in every available subsystem, developers begin with the Kernel Floor and selectively opt into additional capabilities only when necessary.

## How the Feature Gate Ratchet Prevents Binary Growth

To safeguard the Kernel Floor's minimal footprint, OpenHuman employs a **feature gate ratchet** implemented in [`scripts/check-kernel-floor.sh`](https://github.com/tinyhumansai/openhuman/blob/main/scripts/check-kernel-floor.sh). This CI script enforces a strict "no-growth" policy by tracking three key metrics:

1. Package count
2. Crate names
3. Native builds of the kernel profile

When the CI pipeline runs, the script compares current metrics against the last-recorded baseline. If the script detects a regression—meaning the kernel profile now resolves more packages or includes new dependencies—it fails the build immediately. The error message at line 59 indicates:

> `kernel floor REGRESSED: profile 'kernel' resolves 302 packages …`

Conversely, if a refactoring reduces the dependency count but the baseline isn't updated, the script warns at line 69:

> `kernel floor IMPROVED but was not ratcheted: profile 'kernel'`

This mechanism ensures that any addition to the kernel floor, even indirect transitive dependencies, must be intentional and documented through an updated ratchet baseline.

## Building With the Kernel Floor in Practice

Developers can leverage the Kernel Floor through the `DomainSet::kernel()` constructor when initializing the runtime harness. The following example demonstrates how to start with the minimal core and selectively enable additional domains:

```rust
use openhuman_core::Harness;
use openhuman_core::domain::{DomainSet, DomainGroup};

// Initialize with only the kernel floor (threads, config, security)
let harness = Harness::builder()
    .domains(DomainSet::kernel())                   // minimal baseline
    .domains(DomainSet::with(DomainGroup::Media))   // opt-in specific feature
    .build()
    .await?;

```

For a complete working demonstration, see [`examples/embed_kernel.rs`](https://github.com/tinyhumansai/openhuman/blob/main/examples/embed_kernel.rs), which shows how to embed the OpenHuman core using only the Kernel Floor before adding specific capabilities.

## Summary

- The **Kernel Floor** in OpenHuman provides a minimal runtime containing only threads, config, and security domains as defined in [`src/core/runtime/builder.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/runtime/builder.rs).
- The **feature gate ratchet** is a CI script at [`scripts/check-kernel-floor.sh`](https://github.com/tinyhumansai/openhuman/blob/main/scripts/check-kernel-floor.sh) that monitors package counts and dependencies to prevent binary bloat.
- Any regression in kernel floor size triggers a build failure, enforcing a strict no-growth policy for the baseline.
- Developers use `DomainSet::kernel()` to initialize the minimal core and must explicitly opt into additional features.
- This architecture ensures embedded applications maintain a small footprint across releases.

## Frequently Asked Questions

### What domains are included in the OpenHuman Kernel Floor?

The Kernel Floor includes exactly three essential domains: **threads**, **config**, and **security**. These provide the minimal functionality needed for a runnable core, excluding optional subsystems like voice, web3, or flows that would increase binary size.

### How does the feature gate ratchet detect binary growth?

The ratchet script compares the current kernel profile against a recorded baseline, checking package counts, crate names, and native build configurations. If the script detects an increase in resolved packages or new dependencies at `scripts/check-kernel-floor.sh#L59`, it fails the CI build with a "REGRESSED" error.

### Can I add features to the Kernel Floor temporarily for testing?

While you can locally modify [`src/core/runtime/builder.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/runtime/builder.rs) to include additional domains, the CI ratchet at [`scripts/check-kernel-floor.sh`](https://github.com/tinyhumansai/openhuman/blob/main/scripts/check-kernel-floor.sh) will reject any changes that increase the kernel profile's dependency count unless you explicitly update the baseline metrics to reflect the intentional growth.

### Where can I find an example of embedding the Kernel Floor?

The file [`examples/embed_kernel.rs`](https://github.com/tinyhumansai/openhuman/blob/main/examples/embed_kernel.rs) demonstrates how to embed the OpenHuman core using `DomainSet::kernel()` to start with the minimal baseline, then selectively enable specific domain groups as needed for your application.