Skip to content

Aggregate Roots

Archived 2026-10-09

This June-2026 catalog page was superseded by the generated page at planes/agent-runtime/aggregate-roots.md, which is rendered from the architecture model. It is kept for provenance; its content was the seed for the model.

Historical — archived

This page is kept for provenance. Its dates, targets and technology statements are not current direction. See the linked replacement page.

Reviewed 2026-10-09

Target; AgentDefinition/AgentVersion/SkillDefinition/SkillVersion are owned by Control plane publication; this plane owns attempt execution records and checkpoint references (ownership map).

Target Architecture — Final-State Design

The Agent Mesh domain is modeled as twelve aggregate roots, each owned by a single service and each carrying the cross-cutting metadata schema (tenantId, traceId, correlationId, timestamps). Aggregates persist via NHibernate on Azure SQL / PostgreSQL; hot state lives in Redis and large payloads in Blob. Domain events travel in the canonical envelope.

Aggregate Map

flowchart TB
    AD["AgentDefinition"] --> AV["AgentVersion"]
    SD["SkillDefinition"] --> SV["SkillVersion"]
    AT["AgentTask"] --> AE["AgentExecution"]
    AE --> SE["SkillExecution"]
    AE --> TI["ToolInvocation"]
    AE --> MI["ModelInvocation"]
    AE --> VR["ValidationResult"]
    VR --> CA["CorrectionAttempt"]
    AHS["AgentHealthStatus"]
Hold "Alt" / "Option" to enable pan & zoom

1. AgentDefinition

Purpose — Stable identity of an agent role; root of the agent's version history.

  • Fields — agentId, tenantId, cluster, displayName, description, status (Active/Deprecated), currentVersion, createdAt, updatedAt.
  • Entities — AgentVersion (history, but versioned independently as its own aggregate for immutability; referenced here).
  • Value Objects — PermissionScope (default scope), ClusterRef.
  • Invariants — agentId is unique per tenant and follows ConnectSoft.Agent.{Name}; currentVersion must reference a registered AgentVersion.
  • Domain Events — AgentRegistered, AgentDeprecated.
  • Repository — AgentDefinitionRepository.
  • Persistence — Azure SQL / PostgreSQL (NHibernate); indexed by agentId, tenantId.

2. AgentVersion

Purpose — Immutable, semver-tagged snapshot of an agent's configuration.

  • Fields — agentId, version, tenantId, status, promptStrategy, correctionLimit, publishedAt.
  • Entities — none (leaf snapshot).
  • Value Objects — SkillBinding (skillId + version range), ModelPolicyRef, PermissionScope, ToolPermission.
  • Invariants — immutable once published; every SkillBinding must resolve to a registered SkillVersion; PermissionScope must be authorized by Governance.
  • Domain Events — AgentRegistered (version), AgentVersionRetired.
  • Repository — AgentVersionRepository.
  • Persistence — Azure SQL / PostgreSQL (NHibernate); indexed by agentId + version.

3. SkillDefinition

Purpose — Stable identity of a reusable capability.

  • Fields — skillId, tenantId, category, displayName, description, status, currentVersion, createdAt.
  • Entities — none.
  • Value Objects — SkillCategory, ClusterAffinity.
  • Invariants — skillId unique per tenant, follows ConnectSoft.Skill.{Name}; currentVersion references a registered SkillVersion.
  • Domain Events — SkillRegistered, SkillDeprecated.
  • Repository — SkillDefinitionRepository.
  • Persistence — Azure SQL / PostgreSQL (NHibernate); indexed by skillId.

4. SkillVersion

Purpose — Immutable contract for a skill version (input/output, tools, validation).

  • Fields — skillId, version, tenantId, status, publishedAt.
  • Entities — none.
  • Value Objects — InputContract, OutputContract, ToolRequirement, ModelExpectation, ValidationRuleSet.
  • Invariants — immutable once published; input/output contracts are schema-valid; tool requirements must be grantable.
  • Domain Events — SkillRegistered (version).
  • Repository — SkillVersionRepository.
  • Persistence — Azure SQL / PostgreSQL (NHibernate); indexed by skillId + version.

5. AgentTask

Purpose — The unit of assigned work; root of task lifecycle.

  • Fields — taskId, tenantId, projectId, moduleId, traceId, correlationId, agentRole, requestedSkill, status, createdAt, updatedAt, deadline.
  • Entities — none (executions are a separate aggregate, referenced).
  • Value Objects — TaskInputs, ContextRequest, TaskConstraints (modelPolicyId, maxCorrectionAttempts).
  • Invariants — idempotent on taskId; status transitions follow the lifecycle; cannot complete without a passed ValidationResult.
  • Domain Events — AgentTaskAssigned, AgentTaskCompleted, AgentTaskFailed.
  • Repository — AgentTaskRepository.
  • Persistence — Azure SQL / PostgreSQL (NHibernate); indexed by taskId, traceId, tenantId.

6. AgentExecution

Purpose — A single attempt to fulfil a task; the traceability hub for skill/model/tool calls.

  • Fields — executionId, taskId, tenantId, agentId, agentVersion, contextPackageId, status, tokensUsed, startedAt, completedAt.
  • Entities — SkillExecution references; ModelInvocation/ToolInvocation references.
  • Value Objects — ExecutionOutcome, ArtifactReference[].
  • Invariants — exactly one active execution per task at a time; must reference a contextPackageId; terminal status is Completed or Failed.
  • Domain Events — AgentExecutionStarted, (contributes to) AgentTaskCompleted / AgentTaskFailed.
  • Repository — AgentExecutionRepository.
  • Persistence — Azure SQL / PostgreSQL (NHibernate); hot status in Redis; indexed by executionId, taskId, traceId.

7. SkillExecution

Purpose — A record of one skill version run inside an execution.

  • Fields — skillExecutionId, executionId, skillId, skillVersion, tenantId, status, startedAt, completedAt.
  • Entities — none.
  • Value Objects — SkillInputs, SkillOutputs, ArtifactReference[].
  • Invariants — inputs validate against the bound SkillVersion.InputContract; outputs validate against OutputContract before completion.
  • Domain Events — SkillExecutionStarted, SkillExecutionCompleted.
  • Repository — SkillExecutionRepository.
  • Persistence — Azure SQL / PostgreSQL (NHibernate); large payloads in Blob; indexed by executionId, skillId.

8. ToolInvocation

Purpose — A record of one MCP tool call.

  • Fields — toolInvocationId, executionId, tenantId, toolName, status, latencyMs, invokedAt.
  • Entities — none.
  • Value Objects — ToolArguments, ToolResultRef, PermissionScopeUsed.
  • Invariants — tool must be within the acting agent version's PermissionScope; non-idempotent tools execute at most once per stepId.
  • Domain Events — ToolInvoked.
  • Repository — ToolInvocationRepository.
  • Persistence — Azure SQL / PostgreSQL (NHibernate); large results in Blob; indexed by executionId, toolName.

9. ModelInvocation

Purpose — A record of one model provider call.

  • Fields — modelInvocationId, executionId, tenantId, provider, model, promptTokens, completionTokens, costEstimate, latencyMs, invokedAt.
  • Entities — none.
  • Value Objects — ModelPolicyRef, ProviderRef, PromptRef, ResponseRef.
  • Invariants — provider selection complies with the task's modelPolicyId and tenant routing; prompt/response payloads are classified before storage.
  • Domain Events — ModelInvoked.
  • Repository — ModelInvocationRepository.
  • Persistence — Azure SQL / PostgreSQL (NHibernate); prompt/response bodies in Blob; indexed by executionId, provider.

10. ValidationResult

Purpose — The outcome of validating an execution's outputs.

  • Fields — validationResultId, executionId, tenantId, passed, evaluatedAt.
  • Entities — RuleEvaluation (per-rule outcome).
  • Value Objects — ValidationRuleResult (rule, passed, message), RuleSetRef.
  • Invariants — passed is true only if all required rules (schema, naming, dependency, policy) pass; a failed result must record actionable messages for correction.
  • Domain Events — ValidationFailed (when not passed), ValidationPassed.
  • Repository — ValidationResultRepository.
  • Persistence — Azure SQL / PostgreSQL (NHibernate); indexed by executionId.

11. CorrectionAttempt

Purpose — A record of one feedback-driven correction of a failed validation.

  • Fields — correctionAttemptId, executionId, validationResultId, tenantId, attemptNumber, status, attemptedAt.
  • Entities — none.
  • Value Objects — CorrectionFeedback, ResultingArtifactRef[].
  • Invariants — attemptNumber is monotonic and <= maxCorrectionAttempts; each attempt references the ValidationResult it addresses.
  • Domain Events — CorrectionAttempted.
  • Repository — CorrectionAttemptRepository.
  • Persistence — Azure SQL / PostgreSQL (NHibernate); indexed by executionId, attemptNumber.

12. AgentHealthStatus

Purpose — The pooled health of an agent, owned by the AgentPoolManager.

  • Fields — agentId, tenantId, health (Healthy/Degraded/Unhealthy), warmInstances, busyInstances, maxConcurrency, lastProbedAt.
  • Entities — PoolInstance (per-instance status).
  • Value Objects — HealthSignal, ConcurrencyLimits.
  • Invariants — busyInstances <= maxConcurrency; a transition only emits an event when the discrete health level changes.
  • Domain Events — AgentHealthChanged.
  • Repository — AgentHealthStatusRepository.
  • Persistence — Redis (hot status) with relational history for audit; indexed by agentId, tenantId.