How OpenHuman's Domain Feature Gate System Manages Compile-Time Gates

OpenHuman isolates major functional families behind domain abstractions controlled by Cargo feature flags at compile time, automatically reflecting those gates in a runtime DomainSet that filters controllers, stores, and tools.

The tinyhumansai/openhuman repository implements a rigorous compile-time gate system that maps each functional domain to a dedicated Cargo feature. This architecture ensures that when a domain is disabled, the compiler completely omits the associated code and dependencies, producing lean binaries while maintaining runtime consistency through a mirrored permission system.

Compile-Time Feature Flags in Cargo.toml

The root Cargo.toml organizes features into two distinct groups to separate development needs from production requirements.

• Contributor features – The default set enabled for development and CI, providing minimal functionality.
• Product features – The exhaustive set defined in scripts/ci/product-features.txt required for the shipped desktop application.

Each major functional family corresponds to a specific Cargo feature. For example, web3, voice, media, and modules each control their respective domains. When you disable a feature using --no-default-features or by omitting it from your build configuration, the Rust compiler excludes all code behind that gate and drops exclusive dependencies. Disabling the web3 feature, for instance, removes the bitcoin, ethers-core, and curve25519-dalek crates entirely from the build.

The DomainGroup Enum as the Canonical Registry

All domains are enumerated as variants in the DomainGroup enum located in src/core/all.rs at lines 91–184.

• Agent, Memory, Web3, Voice, Media, Modules, and Platform are among the defined variants.
• The enum provides an ALL constant containing the complete list of domains.
• An index() implementation at lines 150–164 maps each variant to a numeric slot used by runtime bitsets for efficient permission checks.

This enum serves as the single source of truth for what constitutes a domain within the system, ensuring that both compile-time flags and runtime checks reference identical functional boundaries.

Runtime DomainSet Mirrors Compile-Time Gates

During core construction, src/core/runtime/builder.rs instantiates a DomainSet that bridges compile-time features to runtime behavior. The builder provides preset configurations for common use cases:

let domains = DomainSet::full();    // Enables all domains for product builds
let domains = DomainSet::harness(); // Core-only: agent + memory + threads

Internally, DomainSet::allows(g) checks whether the Cargo feature corresponding to the given DomainGroup variant is active. Every controller registration, store initialization, and tool advertisement invokes domains.allows(g) to determine inclusion. This guarantees that the runtime state cannot diverge from the compiled capabilities.

How Tools and Controllers Are Filtered

The tool registry in src/openhuman/tools/ops.rs (lines 1210–1447) demonstrates runtime gating in practice. When the system classifies a tool to its respective DomainGroup, it queries the DomainSet before registration. If domains.allows(DomainGroup::Web3) returns false, the tool is silently dropped, preventing accidental exposure of uncompiled functionality.

Controllers and stores follow identical patterns, using the same permission checks during the initialization phase to ensure that only enabled domain logic is mounted.

Practical Build Configurations

You control compile-time gates through Cargo commands without modifying source code.

Enable the voice domain explicitly:

cargo build --features voice

Create a minimal build excluding heavy dependencies like Web3:

cargo build --no-default-features --features "agent memory threads"

Check active domains programmatically at runtime:

use openhuman_core::core::all::DomainGroup;

fn list_active_domains(domains: &DomainSet) {
    for g in DomainGroup::ALL {
        if domains.allows(*g) {
            println!("Domain enabled: {:?}", g);
        }
    }
}

Why Compile-Time Gates Matter

Binary size – Disabling domains removes their exclusive crates, keeping the product lean. Removing web3 eliminates cryptographic libraries that can add megabytes to the binary.

Security – Domains depending on native libraries (e.g., voice → cpal audio drivers) can be excluded from builds targeting restricted or sandboxed environments, reducing the attack surface.

Modularity – New domains require only three steps: extend the DomainGroup enum in src/core/all.rs, wire a corresponding feature flag in Cargo.toml, and guard the runtime registration behind domains.allows(DomainGroup::NewDomain).

Summary

• The DomainGroup enum in src/core/all.rs (lines 91–184) provides the canonical list of all functional domains.
• Root Cargo.toml defines feature flags that map one-to-one with DomainGroup variants, splitting contributor and product configurations.
• DomainSet in src/core/runtime/builder.rs constructs runtime permission sets from compile-time features, offering presets like full() and harness().
• The tool registry in src/openhuman/tools/ops.rs (lines 1210–1447) filters tools by domain before registration.
• This architecture enables binary size optimization, security hardening through dependency exclusion, and modular extensibility.

Frequently Asked Questions

What is the difference between DomainGroup and DomainSet?

DomainGroup is a static enum defined in src/core/all.rs that enumerates all possible functional domains as variants (e.g., Web3, Voice). DomainSet is a runtime structure instantiated in src/core/runtime/builder.rs that tracks which of those domains are actually enabled based on the compile-time Cargo features, providing the allows() method for permission checks.

How do I disable the web3 domain to reduce binary size?

Pass --no-default-features to Cargo and specify only the domains you need, excluding web3. For example: cargo build --no-default-features --features "agent memory threads". This removes the bitcoin, ethers-core, and curve25519-dalek dependencies entirely from the compilation.

Where does the runtime check if a domain is enabled?

The runtime checks occur in DomainSet::allows(), which is called during core initialization in src/core/runtime/builder.rs and during tool registration in src/openhuman/tools/ops.rs (lines 1210–1447). This method verifies the Cargo feature status for the requested DomainGroup variant.

Can I add a custom domain to the feature gate system?

Yes. First, add a new variant to the DomainGroup enum in src/core/all.rs. Second, add a corresponding feature flag to the root Cargo.toml. Third, guard any controllers, stores, or tools belonging to this domain with domains.allows(DomainGroup::YourNewDomain) checks during registration.

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