How DomainSet Runtime Axis Composes with Compile-Time Cargo Feature Gates in OpenHuman

OpenHuman implements a two-dimensional gating model where Cargo feature gates compile out entire domain families at build time, while the DomainSet runtime axis selects which compiled families are active for each Core instance.

OpenHuman splits the decision of what code executes across two orthogonal layers. The DomainSet runtime axis composes with compile-time Cargo feature gates to give developers and embedders fine-grained control over binary size, dependency trees, and runtime capabilities. This architecture ensures heavy dependencies—such as cryptographic libraries for web3 or media codecs—can be excluded from builds while still allowing runtime flexibility for the features that remain.

The Two-Dimensional Gating Model

OpenHuman organizes functionality into domain families—logical groups like web3, media, voice, and agent. The system uses two distinct mechanisms to control these families:

Layer	Controls	Implementation
Compile-time Cargo features	Whether domain family code is included in the binary	#[cfg(feature = "...")] attributes in Cargo.toml and source files
Runtime DomainSet axis	Which compiled families are active for a specific Core instance	DomainSet struct in src/core/runtime/builder.rs with bit-flag logic

Compile-time gates happen first. When a feature like web3 is disabled, the compiler removes the openhuman::web3 module and its transitive dependencies—ethers-core, bitcoin, curve25519-dalek, and associated controllers—from the binary entirely.

Compile-Time Gates Prune the Code Graph

Cargo feature gates in OpenHuman are defined in Cargo.toml under [features] and orchestrated through scripts/ci/product-features.txt for shipped products. When a feature is off, the corresponding code never reaches the linker.

The DomainGroup enum in src/core/all.rs ⟨line 229⟩ defines the runtime identifiers for these families:

pub enum DomainGroup {
    Agent,
    Memory,
    Web3,
    Voice,
    Media,
    // ... additional families
}

Even when a feature is disabled at compile time, the DomainGroup variant typically remains in the enum to preserve type safety. However, the actual implementations—controllers, stores, and tools—are excluded via conditional compilation attributes like #[cfg(feature = "web3")].

Runtime DomainSet Controls Activation

The DomainSet struct defined in src/core/runtime/builder.rs ⟨line 176⟩ provides runtime filtering:

pub struct DomainSet {
    /// Bit-flags for each DomainGroup (Agent, Memory, Web3, …)
    bits: u128,
}

This compact representation uses a 128-bit integer to store enablement flags for up to 128 distinct domain families. The struct provides three primary presets via its implementation block ⟨line 229⟩:

• DomainSet::full() — Enables all domain families present in the binary. This is the default for desktop products.
• DomainSet::harness() — Activates a minimal set: Agent, Memory, Threads, Config, and Security. Heavy families like Web3, Voice, and Media remain disabled.
• DomainSet::none() — Disables all domain families, leaving only transport layers (RPC, sockets).

The harness preset constructs its mask through bitwise operations:

DomainSet::new()
    .allow(DomainGroup::Agent)
    .allow(DomainGroup::Memory)
    .allow(DomainGroup::Threads)
    .allow(DomainGroup::Config)
    .allow(DomainGroup::Security)

How the Layers Interact

The composition follows a strict ordering: compile-time filtering occurs before runtime selection.

When the Core initializes via CoreBuilder, it accepts a DomainSet parameter. Throughout the codebase, registration logic checks both the compile-time feature gate and the runtime DomainSet configuration.

In src/core/runtime/context.rs ⟨line 572⟩, store initialization follows this pattern:

1. Check #[cfg(feature = "memory")] at compile time
2. At runtime, verify domains.allows(DomainGroup::Memory) before instantiating the store

Similarly, tool registration in src/openhuman/tools/ops.rs ⟨line 1148⟩ maps tool names to DomainGroup variants and filters them against the active DomainSet. Tools belonging to disabled groups are dropped from the available set.

Because runtime checks occur only on compiled-in code, disabling a Cargo feature at build time makes the corresponding DomainGroup variant inert—the runtime check becomes a no-op for that family. Conversely, a compiled-in feature can be deactivated for specific launches by passing a restrictive DomainSet to CoreBuilder::domains().

Validation Through Testing

The interaction between compile-time gates and runtime domains is enforced by test suites in src/core/all_tests.rs and src/openhuman/tools/ops_tests.rs.

Assertions verify that DomainSet::harness() correctly excludes heavy families:

assert!(!DomainSet::harness().allows(DomainGroup::Web3));
assert!(!DomainSet::harness().allows(DomainGroup::Voice));

These tests prevent drift between the DomainGroup enum definitions, the preset bit masks in builder.rs, and the actual registration code throughout the system.

Practical Deployment Patterns

Scenario	Configuration	Result
Full desktop application	Default features + DomainSet::full()	All capabilities available; largest binary
Headless CLI tool	Default features + DomainSet::harness()	Lightweight runtime without web3/media overhead
Embedded sandbox	--no-default-features + DomainSet::none()	Minimal binary with only transport layers
Custom hardware build	--features agent,memory + DomainSet::full()	Trimmed binary with only specific families

Summary

• Cargo feature gates eliminate code and dependencies at compile time; disabled features occupy zero bytes in the final binary.
• DomainSet provides runtime flexibility through bit-mask checks in src/core/runtime/builder.rs, allowing the same binary to serve different use cases.
• Composition is hierarchical: compile-time gates determine what can run; runtime DomainSet determines what does run.
• Preset constructors like harness() offer battle-tested configurations for common deployment scenarios.
• Dual validation via #[cfg] attributes and domains.allows() checks ensures safe feature management across the codebase.

Frequently Asked Questions

What happens if I disable a Cargo feature but try to enable it via DomainSet at runtime?

The DomainGroup variant may still exist in the enum, but all associated code—controllers, stores, and tools—has been compiled out. The runtime check domains.allows(DomainGroup::Web3) will return true if set, but attempts to access web3 functionality will result in stub behavior or method-not-found errors because the implementation code was removed by the preprocessor.

How does DomainSet::harness() improve performance compared to DomainSet::full()?

DomainSet::harness() disables initialization of heavy subsystems like cryptographic engines for Web3, media codecs, and voice processing pipelines. This reduces memory footprint, startup latency, and attack surface for headless deployments while preserving core agent functionality defined in src/core/all.rs.

Can I create custom DomainSet presets beyond full(), harness(), and none()?

Yes. The DomainSet struct implements Clone and provides the allow() and deny() methods for programmatic construction. You can chain these methods to create custom bit masks targeting specific domain combinations, then pass the instance to CoreBuilder::domains() in src/core/runtime/builder.rs.

Where does the runtime check actually prevent domain execution?

Critical gating occurs in src/core/runtime/context.rs for store initialization and src/openhuman/tools/ops.rs for tool registration. Both locations check domains.allows(DomainGroup::X) before instantiating domain-specific resources, ensuring disabled families consume no runtime resources beyond their bit flag in the DomainSet mask.

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