The Difference Between tinydocs-bus Contract Ownership and Host Enforcement

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, 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, 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, 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 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, 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 demonstrates how the host uses contract constants while applying pre-flight validation:

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 shows how the host remaps module errors to add policy context:

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 and 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 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.

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, and mapping raw module errors into DocumentCallError types with added security context in 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, 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.

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