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

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, 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. 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:

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, 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.
• The feature gate ratchet is a CI script at 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 to include additional domains, the CI ratchet at 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}