Object Model

The core domain objects of the Hoziron platform, their real relationships, and the lifecycle contract that governs all of them. Grounded in crates/platform/hoziron-core-types/src/types.rs, crates/platform/hoziron-core-types/src/package/{manifest,contract}.rs, crates/platform/hoziron-core-audit/src/audit/unified_chain.rs, crates/platform/hoziron-core/src/lifecycle/traits.rs, and the module structure under crates/platform/hoziron-core/src/.

Concept Relationships

There is no Trigger class and no Agent --> Trigger relationship — agents do not declare accepted invocation sources. See ../internals/invocation-model.md.

There is also no Approval class — see the "Approval" section below for what this platform has instead of a human-in-the-loop approval queue.

Package Types and the Lifecycle Contract (ADR-044, ADR-056, ADR-060)

Six package types — Skill, Competency, Agent, Workflow, Integration, Contract — share a tiered set of Core-owned lifecycle traits (crates/platform/hoziron-core/src/lifecycle/traits.rs), enforced by the type system rather than by convention:

• Installable (all six types): install is name-keyed — installing a package with a name that already exists preserves its UUID and treats the operation as an upgrade (ADR-029: install is instantiation, one instance per name). uninstall performs complete teardown and is refused if any installed package depends on it, or if it has live runtime state.
• Runnable (Agent, Workflow only): exactly two verbs, activate and suspend (ADR-056). There is no start/stop/resume verb. AgentState is a two-variant enum: Running | Suspended. Install always lands a package Suspended; no entry point auto-activates as a side effect of install. activate is gate-checked every time (dependency/contract check, never cached); suspend is always available and never discards state — sessions, cron registrations, and capability bindings stay live and resumable. For a Workflow, suspend means drain: stop admitting new runs, let in-flight runs complete, then transition to Suspended.
• Connectable (Integration only): connect/disconnect/reconnect/status manage an external process or connection whose state is ephemeral and re-derived from the definition on boot — nothing to persist or resume, unlike Runnable's durable state.
• Install-only provenance (ADR-060): a workflow (and, audited, every other package type) enters the running kernel exclusively through its store-backed install path. There is no side door that mints a live kernel object without a corresponding store row.

Agent

The execution context — an autonomous AI worker invoked via API calls, channel messages, cron schedules, matched conditions, or workflow steps (see ../internals/invocation-model.md).

Key rule: an agent with no equipped competency has empty mcp_servers, which resolves as open-to-all-connected-servers (the backward-compatible default) — but with no required_skills behind it, it is effectively a general-purpose conversational entity with no meaningfully scoped tool access.

Lifecycle (ADR-056)

What an Agent Owns

Permission

The agent-level Permission enum (hoziron-core-types::types::Permission) is deliberately small — six variants, all either agent-interaction or spend-limit grants. It is a distinct system from the RBAC Role/Action model (see ../internals/security-auth.md):

These translate 1:1 into kernel Capability values (crates/platform/hoziron-core/src/permission/mod.rs); several kernel capabilities (OfpDiscover, EconEarn, NetListen, ToolInvoke, LlmQuery, ...) are intentionally suppressed and never exposed as Hoziron permissions. Inheritance rule: a child agent's permissions must be a subset of its parent's.

Competency

The unit of capability. A competency bundles domain knowledge, operational procedures, required skills, declared integration contracts, settings, and metrics into an installable package (COMPETENCY.toml/.md + sibling MANIFEST.toml).

Multi-Competency Composition (ADR-028)

Agents equip multiple competencies with explicit, operator-controlled ordering:

Order matters beyond bookkeeping: the composed system prompt concatenates each competency's prompt in position order, and — because LLM attention is not uniform across a long prompt — a Pre-Invocation Competency Manager (ADR-031, a kernel-adjacent primitive, not an agent-authored feature) fires before every multi-competency invocation whose source is not a scheduled cron wake. It uses a small/fast LLM call to dynamically reorder, reframe, and optionally suppress equipped competencies for the specific incoming action, invisibly to the agent and operator.

Competency → MCP Access (ADR-050, ADR-051, ADR-066)

A competency does not name a concrete integration package. It declares contracts — named tool-surface roles (e.g. claims-core, policy-admin) via a contracts: [] frontmatter field — and any installed integration package that implements that contract satisfies it. This decouples "what an agent needs" from "which vendor package supplies it," so the same competency runs unmodified against Guidewire, Duck Creek, or the demo/e2e reference System of Record, whichever integration package the operator has installed under that contract. An agent's effective mcp_servers allowlist is the union of contracts declared by every currently-equipped competency; equip does not fail if a declared contract's integration is not yet installed or connected (independent lifecycles) — it silently produces zero tools for that entry until the integration connects.

A contract (ADR-066) is itself an installable Contract package (see below) carrying a real JSON Schema per tool. An integration satisfies a contract by declaring [implements.<name>] in its own MANIFEST.toml, with version (which published contract version it satisfies), tool_map (contract tool name → the integration's native tool name, where they differ), and field_map (per-tool contract field name → native field name). This is checked structurally at publish time (validate_contract_payload) and at connect time (a live MCP tools/list response is structurally diffed against the contract's input_schema).

Contract (ADR-051, ADR-066)

A standalone, versioned package (CONTRACT.json payload) defining a tool surface's canonical name and full JSON Schema per tool — the product-level definition of an interface, authored once, checked against by every integration that implements it. Carries no executable behavior; the payload is pure schema data (crates/platform/hoziron-core-types/src/package/contract.rs).

See reference/config/manifest-schemas.md for the full CONTRACT.json and [implements.*] schemas, and reference/api/integrations.md for the GET /contracts binding-list endpoint.

Skill

A tool bundle providing one or more tools (must have at least one, validated at install). A skill is inert without a competency requiring it — crates/platform/hoziron-core/src/skill/.

Tool

An atomic, named action a skill (in-process) or an integration contract (MCP/REST/SOAP, out-of-process IO) provides. Visibility to the model is governed by the two ADR-052 allow-lists; actual permission to execute an outbound call to a carrier system is governed separately, at the mediation seam (see data-flow.md) — visibility and trust are deliberately two different layers.

Workflow

A multi-step pipeline routing work through multiple agents (crates/platform/hoziron-core/src/workflow/). Steps support sequential, fan-out, conditional, and loop execution modes.

Runnable's suspend on a Workflow means drain (admission stops, in-flight runs finish); a WorkflowRun additionally carries RunState::Escalated for a workflow that stranded mid-write when a downstream mediation step failed closed (ADR-047/046) — an escalated run is neither silently dropped nor billed as complete.

Provider / Model

The routing layer models a closed, operator-authored inventory of providers and models (ADR-053) — never an auto-scanned or implicitly-exposed catalog. Each [[provider]] entry names an id (instance) and a driver (kernel-shipped driver class); each nested [[provider.model]] names a concrete model. Exactly one distinction is commercially meaningful: licence-sourced (the carrier licence's locked Anthropic tier models, metered, carrier-immutable) vs. everything else (carrier-managed local or BYO cloud models, ordinary config). A ranked preference list (ADR-054), scoped to the Local or Cloud pool the routing gateway already selected, decides which eligible model actually serves a call — see ../internals/provider-routing.md.

Channel / Invocation Sources / Schedule

InvocationSource (not an agent-declared "trigger" — see ../internals/invocation-model.md):

There is no Event source — no system/lifecycle event mechanism can originate an agent turn.

Session / Memory

Private, per-agent persistence: KV store, semantic memory (vector recall), knowledge graph, and session/conversation history. The kernel's BoundMemoryHandle is structurally bound to one agent_id at construction — no method accepts a foreign agent_id parameter, so cross-agent memory access is a compile-time impossibility at the handle's own surface, not a runtime-checked policy (ADR-039 §3).

Audit Entry

Every authenticated operation is recorded as a UnifiedAuditEntry (crates/platform/hoziron-core-audit/src/audit/unified_chain.rs) — a hash-chained, tamper-evident record, not just a log line:

See ../guides/security/audit-trail.md for retention/export config and ../reference/api/security.md for the GET /security/verify chain-verification endpoint.

Approval

There is no Approval object, no human-in-the-loop approval queue, and no /approvals API or CLI surface. The two mechanisms that stand in for "require sign-off before an action" are: ADR-056's gate-checked activate (a structural precondition check, not a human approval step) and ordinary RBAC-scoped mutating routes (see ../reference/api/approvals.md for the full explanation).

Related:

• system-overview.md — HozironPlatform and the crate tiers that implement this model
• data-flow.md — how these objects interact across a real request
• ../internals/competency-system.md, ../internals/catalog-packages.md, ../internals/provider-routing.md
• docs/decisions/028, 029, 044, 050, 051, 052, 053, 054, 056, 060, 061, 065, 066