System Overview

Hoziron ships as a single unified binary, hoziron-server, that composes several optional HTTP surfaces (API, package registry, MCP, operations console/dashboard) over one shared platform core. A separate, dependency-free hoziron-cli CLI talks to that server over plain HTTP — it has no server-side or kernel dependency at all. Underneath, Hoziron is a compliance-ready enterprise distribution of the open-source OpenFang agent kernel: Hoziron now owns a hard fork of OpenFang (absorbed as the crates/kernel/hoziron-* crates), not a from-scratch runtime and not a vendored subtree it merely wraps.

Crate Tiers and the Kernel Isolation Rule

The workspace is organized into four tiers, each with a distinct trust role:

Kernel Isolation Rule (enforced by construction, not convention): only hoziron-core, hoziron-core-types, hoziron-core-package, and hoziron-core-audit may depend on any crates/kernel/* crate (hoziron-core-package depends on hoziron-skills; hoziron-core-audit depends on hoziron-kernel-types and hoziron-runtime). The CLI, console, API, registry, and MCP crates never import kernel crates directly — every kernel-adjacent operation goes through the HozironPlatform facade in hoziron-core. This is checked two ways:

• No surface crate directly depends on any hoziron-kernel*/hoziron-runtime/hoziron-memory/etc. crate, and no surface crate's source directly uses a kernel symbol — confirmed directly against crates/surfaces/hoziron-api/Cargo.toml, which lists only hoziron-core and hoziron-http. This is a claim about direct dependencies, not the full cargo tree: a surface crate's cargo tree output does show the kernel crates transitively, via hoziron-core — that's expected and fine, since the point of the rule is "no direct import, only through the HozironPlatform facade," not "kernel code never appears anywhere in the dependency graph."
• xtask check runs a structural dependency-graph test (KERNEL ISOLATION VIOLATION) that fails the build if a policy-bearing crate ever enters the kernel's own dependency graph — the inverse direction, protecting the trust gradient described below. Its policy_crates list includes all four crates named above.

bin/hoziron-cli/Cargo.toml confirms the CLI side of the same rule from the other direction: its only internal dependency is hoziron-core (for shared types/config parsing), and every actual operation is a reqwest call against a running server — the CLI ships no kernel, no execution loop, and can talk to a Hoziron instance it did not build.

vendor/openfang/ still exists on disk as an inert leftover from before the fork absorption (ADR-038/040); nothing in the workspace's Cargo.toml path-depends on it any longer. The live kernel is entirely the crates/kernel/hoziron-* crates.

bin/hoziron-demo is not an operator-facing binary — it never ships to a carrier and is absent from the workspace's default-members. It plays the counterparty insurance carrier's System of Record: it generates synthetic inbound claim notices, serves as a slimmed-down outbound SoR Hoziron writes into (via MCP, contract-partitioned by policy-admin/claims-core), and resets to a pristine seed SQLite database on demand. It's what cargo xtask sandbox and the e2e FNOL tests point Hoziron at as the destination system — a test/demo fixture, not a production component.

Hoziron ↔ OpenFang: One-Way Trust Gradient

This is the load-bearing architectural fact, not a historical footnote (ADR-036, ADR-038, ADR-039):

• Hoziron is a compliance-ready enterprise distribution of OpenFang — it forked and absorbed the upstream (now-orphaned) RightNow-AI/openfang project into crates/kernel/hoziron-* rather than either (a) vendoring it as a frozen, periodically-repulled subtree, or (b) rewriting the runtime from scratch. The runtime is treated as inherited floor (137K LOC, a deep pre-existing security model — AES-256-GCM credential vault, Zeroizing secret wipe, hash-chained audit, WASM sandbox), not the product's moat.
• Core is the policy authority. Kernel is the untrusted execution runtime. hoziron-core owns trust policy, PII policy, licence entitlement, routing decisions, competency binding, and the audit-of-record. The kernel owns the agent loop, LLM driver dispatch, tool execution, scheduling, and durable execution state (conversation/session history, memory substrate).
• Constraints flow down; data and events flow up; authority never flows up. The kernel cannot name policy types (TrustPolicy, licence entitlement, PII policy) at all — cargo tree on any kernel crate shows zero hoziron-core* dependency; a Cargo-level dependency cycle makes adding one structurally impossible.
• The crossing is a small number of explicit, owned seams, not a diffuse interface:
  • Dispatch seam — kernel.dispatch(ExecutionRequest). Core resolves the model target, tool allowlist, and effective (already-tokenized) prompt and hands them to the kernel as parameters; the kernel returns an ExecutionResult with response, usage, and mechanical events. No manifest mutation, no shared-state Drop guard.
  • Audit sink — AuditSink, a policy-blind trait the kernel emits MechanicalEvents through (dispatch, token usage, tool call, retry, circuit-breaker trip); core owns the implementation and writes PolicyEvents (PII, routing, entitlement, trust) directly into the same hash chain.
  • Outbound mediation seam — OutboundMediator, injected into the kernel's tool_runner; every outbound tool call (MCP, and — per ADR-047 — direct REST/SOAP carrier writes) is mediated before it leaves the process (see data-flow.md).
  • Inbound ingress authority — per ADR-061, an agent turn may only be originated by hoziron-core through a mediated ingress path; the kernel's raw send_message* is not a callable turn-origin from outside core.
  • Memory binding — BoundMemoryHandle in hoziron-memory structurally binds every memory operation to one agent_id at construction; no method accepts a foreign agent_id.

The practical upshot for anyone reading hoziron-core's source: translation.rs and the platform.rs wiring block are where Hoziron's product concepts (Agent, Competency, Workflow) are translated to and from the kernel's execution primitives — that file is the seam, not a place where kernel types leak into product code.

HozironPlatform — the Central Facade

crates/platform/hoziron-core/src/platform.rs defines HozironPlatform, the single struct every surface (API, console, MCP, registry, CLI-via-HTTP) goes through for every operation — creating agents, equipping competencies, sending messages, running workflows, installing packages. It owns:

hoziron-core's top-level modules (agent/, catalog/resolve/, channel/, competency/, health/, invocation/, memory/, package/, permission/, pii/, provider/, skill/, workflow/, plus platform.rs, translation.rs, config.rs, error.rs) are the implementation of this facade; each internals doc in this knowledge base is grounded in one of them.

High-Level Component Map

Design Principles

1. Single binary, pluggable surfaces. hoziron-server --surfaces api,registry,mcp,dashboard (or a config.toml [surfaces] block) selects which HTTP surfaces run in this process. A DMZ deployment might run --surfaces mcp only; a CDN-origin deployment might run --surfaces registry only (see deployment-topology.md).
2. Kernel isolation is structural, not conventional. No surface crate, and no policy-bearing Core crate, ever appears in the kernel's dependency graph — checked by xtask check on every push.
3. Core is the sole policy authority. Trust policy, PII policy, licence entitlement, and routing decisions live in hoziron-core and are never delegated to the kernel or to agent-authored configuration (ADR-034, ADR-049).
4. One mediated boundary in each direction. Every outbound write leaving the process toward a carrier system crosses CoreOutboundMediator (ADR-042/047); every inbound agent-turn origin crosses a core-mediated ingress path (ADR-061). Neither boundary has a second, unmediated code path by construction.
5. The CLI is a thin, disposable client. hoziron-cli depends on no kernel or server crate; it can be rebuilt, replaced, or run against a remote Hoziron instance without carrying any execution logic.
6. Adopt-and-trim, not rewrite, for the kernel. OpenFang's absorbed crates are trimmed of dead weight (unused adapters, the WASM sandbox, marketplace-only modules) but the execution substrate itself — the agent loop, memory, tool runner — is inherited and hardened, not reimplemented.

Process Model

hoziron-server runs as a single OS process regardless of how many surfaces are enabled:

All agents execute within the same tokio runtime and share the same HozironPlatform instance and local SQLite-backed storage. There is no separate worker pool or per-agent process — this simplifies deployment and debugging at the cost of vertical-only scaling within one instance (see deployment-topology.md for horizontal isolation via multiple instances).

Configuration Hierarchy

Resolution order for any configuration value: CLI flag (if applicable) → environment variable → config.toml field → compiled default. Per project convention, every new file-path resolution must check HOZIRON_HOME before falling back to ~/.hoziron.

Related:

• object-model.md — the domain objects HozironPlatform orchestrates
• data-flow.md — a concrete request lifecycle through the mediation seams
• deployment-topology.md — how hoziron-server and the standalone registry chart deploy
• ../internals/agent-execution.md — the dispatch seam in detail
• docs/decisions/036-hoziron-openfang-boundary.md, 038-openfang-dependency-strategy.md, 039-subsystem-deduplication.md, 040-fork-absorption-trim-sequence.md