# The Difference Between tinydocs-bus Contract Ownership and Host Enforcement

> Understand tinydocs-bus contract ownership and host enforcement in OpenHuman. Learn how the bus defines protocols and the host validates inputs, applies timeouts, and remaps errors.

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

---

**Contract ownership resides in the `tinydocs-bus` crate that defines the shared wire protocol and constants, while host enforcement is the OpenHuman core's responsibility to validate inputs, apply timeouts, and remap errors before they reach the module.**

The `tinyhumansai/openhuman` repository implements a strict architectural separation between protocol definition and policy enforcement for its document processing capabilities. Understanding the distinction between **tinydocs-bus contract ownership and host enforcement** is critical for developers extending the system's `.docx` generation and PDF extraction features. This design ensures that while the module and host share a common vocabulary, the host maintains exclusive control over security constraints and resource limits.

## Contract Ownership in the tinydocs-bus Crate

### The Shared Wire Protocol Definition

The `tinydocs-bus` crate serves as the canonical source of truth for the wire protocol used by the `tinydocs` module. Located at [`vendor/tinydocs-bus/crates/tinydocs-bus/src/lib.rs`](https://github.com/tinyhumansai/openhuman/blob/main/vendor/tinydocs-bus/crates/tinydocs-bus/src/lib.rs), this component owns the exact **enum and constant names** that both the host (OpenHuman core) and the external `tinydocs` module must agree upon. The crate defines method identifiers like `methods::GENERATE_DOCX`, bus names such as `BUS_NAME`, and object paths including `OBJECT_PATH`.

### Compile-Time Safety Guarantees

Because the contract exists as a separate crate referenced in [`src/openhuman/tools/impl/document/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tools/impl/document/mod.rs), any modification to field names or method signatures causes an immediate **compile-time mismatch**. This design guarantees that the host and module speak the same vocabulary without runtime negotiation. The OpenHuman host imports these definitions to ensure version alignment across distributed components.

## Host Enforcement in OpenHuman

### Pre-Invocation Validation

The host explicitly does not trust the module to obey policy. In [`src/openhuman/modules/documents.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/modules/documents.rs), the OpenHuman core **validates incoming arguments** before they reach the module implementation. This includes trimming PDFs, checking size limits, and sanitizing inputs to prevent malformed data from triggering module execution.

### Timeout and Resource Limit Management

Enforcement includes hard deadlines that the contract itself does not specify. The PDF extraction deadline defined in [`src/openhuman/agent/artifacts/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/artifacts/ops.rs) establishes a hard upper bound on how long the `tinydocs` module may spend processing a document. These timeouts, along with sandboxing and resource limits, remain invisible to the module but are strictly imposed by the host.

### Error Translation and Security Context

When the module returns errors, the host maps raw `tinydocs_bus::Error` variants into host-specific `DocumentCallError` types. According to the source code in [`src/openhuman/modules/documents.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/modules/documents.rs), this translation layer adds **security-related context** and host-level diagnostics, converting generic module failures into actionable error states that preserve system integrity.

## Implementation Examples

### Host-Side Contract Consumption

The following pattern from [`src/openhuman/tools/impl/document/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tools/impl/document/mod.rs) demonstrates how the host uses contract constants while applying pre-flight validation:

```rust
use tinydocs_bus::names::{methods, BUS_NAME, OBJECT_PATH};

fn call_generate_docx(payload: DocumentSpec) -> Result<DocumentResult, DocumentCallError> {
    // Host-side validation before sending to the module
    let validated = host_validate(payload)?;
    // Send the request using the contract-defined method name
    bus.call(methods::GENERATE_DOCX, validated)
        .map_err(|e| map_tinydocs_error(e))
}

```

### Error Mapping Enforcement

This implementation from [`src/openhuman/modules/documents.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/modules/documents.rs) shows how the host remaps module errors to add policy context:

```rust
match module_error.as_str() {
    "ai.tinyhumans.tinydocs.Error.InvalidInput" => {
        DocumentCallError::InvalidInput(message)
    }
    "ai.tinyhumans.tinydocs.Error.GenerationFailed" => {
        DocumentCallError::GenerationFailed(message)
    }
    // Fallback for unmapped errors
    _ => DocumentCallError::ModuleFailed(module_error.to_string()),
}

```

## Summary

- **Contract ownership** belongs to the `tinydocs-bus` crate, which defines shared constants, method names, and enums that ensure compile-time agreement between host and module.
- **Host enforcement** is implemented in [`src/openhuman/modules/documents.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/modules/documents.rs) and [`src/openhuman/agent/artifacts/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/artifacts/ops.rs), where the OpenHuman core validates inputs, applies deadlines, and manages resource constraints.
- The separation prevents runtime protocol mismatches while allowing the host to impose security policies, timeouts, and error translations transparently.
- File paths including [`src/openhuman/tools/impl/document/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tools/impl/document/mod.rs) demonstrate the integration point where the host imports and utilizes the contract crate.

## Frequently Asked Questions

### What is the tinydocs-bus crate responsible for?

The `tinydocs-bus` crate owns the wire protocol definition, containing the canonical enum variants, method constants like `methods::GENERATE_DOCX`, and data structures that both the OpenHuman host and the `tinydocs` module use to communicate. It ensures both sides speak the same language through compile-time verification when imported in [`src/openhuman/tools/impl/document/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tools/impl/document/mod.rs).

### How does the host enforce policy beyond the contract?

The host enforces policy by validating arguments before module invocation (trimming PDFs, checking size limits), applying hard timeouts such as the PDF extraction deadline in [`src/openhuman/agent/artifacts/ops.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/agent/artifacts/ops.rs), and mapping raw module errors into `DocumentCallError` types with added security context in [`src/openhuman/modules/documents.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/modules/documents.rs).

### Why separate contract ownership from host enforcement?

Separating these concerns allows the `tinydocs` module to focus on document processing logic while the OpenHuman core handles security, resource management, and error handling. This architecture prevents the module from bypassing timeouts or validation rules, as the host intercepts and enforces all interactions regardless of the contract's contents.

### Where is the contract enforced at compile time?

Compile-time enforcement occurs through Rust's crate system in [`src/openhuman/tools/impl/document/mod.rs`](https://github.com/tinyhumansai/openhuman/blob/main/src/openhuman/tools/impl/document/mod.rs), where the host imports `tinydocs_bus`. If the contract crate changes method names or field structures, the host code fails to compile, guaranteeing version alignment between the distributed components.