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

> Discover how OpenHuman's DomainSet runtime axis works with compile-time Cargo feature gates to selectively activate domain families for each Core instance at build time.

- Repository: [Tiny Humans/openhuman](https://github.com/tinyhumansai/openhuman)
- Tags: internals
- Published: 2026-08-27

---

**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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/Cargo.toml) under `[features]` and orchestrated through [`scripts/ci/product-features.txt`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/all.rs) ⟨[line 229](https://github.com/tinyhumansai/openhuman/blob/main/src/core/all.rs#L229)⟩ defines the runtime identifiers for these families:

```rust
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`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/runtime/builder.rs) ⟨[line 176](https://github.com/tinyhumansai/openhuman/blob/main/src/core/runtime/builder.rs#L176)⟩ provides runtime filtering:

```rust
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](https://github.com/tinyhumansai/openhuman/blob/main/src/core/runtime/builder.rs#L229)⟩:

- **`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:

```rust
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`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/runtime/context.rs) ⟨[line 572](https://github.com/tinyhumansai/openhuman/blob/main/src/core/runtime/context.rs#L572)⟩, 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`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tools/ops.rs) ⟨[line 1148](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tools/ops.rs#L1148)⟩ 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`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/all_tests.rs) and [`src/openhuman/tools/ops_tests.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tools/ops_tests.rs).

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

```rust
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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/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`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/runtime/builder.rs).

### Where does the runtime check actually prevent domain execution?

Critical gating occurs in [`src/core/runtime/context.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/core/runtime/context.rs) for store initialization and [`src/openhuman/tools/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/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.