Domain Model

This document describes all domain entities in paladin-ai-core and the Medieval Military naming convention that provides Paladin's ubiquitous language.

Medieval Military Naming Convention

Paladin applies Domain-Driven Design's ubiquitous language principle through a consistent Medieval Military theme. Use these terms in all code, documentation, and discussions:

Plain vs. Medieval-Military vocabulary (ADR-0049). Not every token-economy concept in this table gets a Medieval-Military name. Units and measures (TokenUsage, max_tokens, max_context_tokens, TokenBudget) and technical port traits (TokenCounterPort, LlmPort, EmbeddingPort) keep plain industry names — they describe quantities and technical seams, not domain roles. Domain roles, places and events — the rows in the table above — get Medieval-Military names.

Node Pattern

All domain entities use the Node<T> wrapper which adds identifier, timestamps, and metadata to any data payload:

// crates/paladin-core/src/base/node.rs
pub struct Node<T> {
    pub id:         Uuid,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
    pub node:       T,         // The domain payload
}

Domain types are type aliases:

// crates/paladin-core/src/platform/container/paladin.rs
pub type Paladin = Node<PaladinData>;

Core Domain Entities

Paladin (Aggregate Root)

// PaladinData — the domain payload inside Node<PaladinData>
pub struct PaladinData {
    pub name:          String,
    pub system_prompt: String,
    pub model:         String,
    pub temperature:   f32,
    pub max_loops:     u32,
    pub stop_words:    Vec<String>,
    pub status:        PaladinStatus,
}

pub enum PaladinStatus {
    Idle,
    Running,
    Completed,
    Failed,
    Timeout,
}

pub type Paladin = Node<PaladinData>;

Invariants:

• system_prompt must not be empty
• temperature must be in 0.0..=2.0
• max_loops must be >= 1

Garrison (Memory Domain)

// crates/paladin-core/src/platform/container/garrison.rs
pub struct GarrisonEntry {
    pub id:          Uuid,
    pub role:        ConversationRole,   // System | User | Assistant | Tool
    pub content:     String,
    pub timestamp:   DateTime<Utc>,
    pub metadata:    HashMap<String, Value>,
    pub token_count: Option<u32>,
    pub is_summary:  bool,
}

Adapters: InMemoryGarrison, SqliteGarrison (feature sqlite) — see Garrison Memory.

Arsenal (Tool Domain)

// crates/paladin-core/src/platform/container/arsenal/
pub struct ToolDefinition {
    pub name:        String,
    pub description: String,
    pub parameters:  serde_json::Value,  // JSON Schema
}

pub struct ToolCall {
    pub id:        String,
    pub tool_name: String,
    pub arguments: serde_json::Value,
}

pub struct ToolResult {
    pub tool_call_id: String,
    pub content:      String,
    pub is_error:     bool,
}

These types are real, registered and invocable — Arsenal/MCP tool execution ships and works. What no shipped LlmPort adapter exercises is the LLM-initiated path that would populate them from a provider response: generate() never returns a populated function call today, on any of OpenAI, Anthropic, DeepSeek, or the bundled mock. See ADR-0042 for the tracked status.

Citadel (State Persistence)

// crates/paladin-core/src/platform/container/citadel.rs
pub struct CitadelEntry {
    pub paladin_name: String,
    pub state:        PaladinState,
    pub saved_at:     DateTime<Utc>,
}

Herald (Output Formatting)

// crates/paladin-core/src/platform/container/herald.rs
pub trait Herald: Send + Sync {
    fn format(&self, result: &PaladinResult, paladin: &Paladin) -> Result<String, HeraldError>;
}

Implementations: JsonHerald, MarkdownHerald, TableHerald — see Herald Output.

Battlefield (Superstep Shared State)

crates/paladin-core/src/platform/container/battlefield.rs — the typed, schema-declared shared state passed to and returned (as StateDelta) from every node in a WarGraph run, merged each superstep by each field's declared DispatchRule. See WarEngine: Battlefield State & Superstep Execution.

Waypoint (Superstep Checkpoint)

crates/paladin-core/src/platform/container/waypoint.rs — the checkpoint the superstep engine persists after every superstep: a full Battlefield snapshot addressed by (ThreadId, WaypointId), enough to resume a run with zero re-execution of completed work. See WarEngine: Battlefield State & Superstep Execution.

Aegis (Fault-Tolerance Policy)

crates/paladin-core/src/platform/container/aegis.rs — the per-node fault-tolerance policy family (retry, timeout, error handlers, model fallback, node caching), attached as a NodeId-keyed sidecar on a WarGraph rather than as a field on any node spec. See Aegis: Retry, Timeout, Error Handlers, Model Fallback and Node Caching.

TraceRecord (Observability Envelope)

crates/paladin-core/src/platform/container/trace.rs — the envelope every observability sink receives: thread_id, an optional run_id, a per-run monotonic seq, at, and the #[non_exhaustive] TraceEvent itself. See Observability: Traces, Sinks and Persistence.

Base Primitives (crates/paladin-core/src/base/)

Error Types

Each domain has a dedicated error enum using thiserror:

See Design Patterns for the error handling convention.

Bounded Contexts

See Also

• Architecture Overview
• Hexagonal Design
• Crate Map
• Design Patterns — PaladinBuilder and error conventions