Agent Mesh — aggregate roots¶

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.

Aggregate	Service	Root entity	Events	Tables
ExecutionAttempt	AgentRuntimeService	ExecutionAttempt	AttemptStarted, AttemptPhaseChanged, AttemptCheckpointed, AttemptDecisionRequested, AttemptCancellationObserved, AttemptOutcomeReported, SubAgentDelegated	ExecutionAttempts, Checkpoints, CallRecords, DecisionRequests, SubAgentDelegations
LoadedRelease	AgentRuntimeService	LoadedRelease	ReleaseLoaded, ReleaseLoadRejected	LoadedReleases
WorkflowDefinitionVersion	WorkflowEngineService	WorkflowDefinitionVersion	WorkflowDefinitionLoaded	WorkflowDefinitions, StepDefinitions, EdgeDefinitions
WorkflowRun	WorkflowEngineService	WorkflowRun	WorkflowRunStarted, StepReady, StepRunStateChanged, TimerFired, CompensationStarted, WorkflowRunCompleted, WorkflowRunFailed, WorkflowRunCancelled	WorkflowRuns, StepRuns, Timers, CompensationEntries

ExecutionAttempt (AgentRuntimeService)¶

One try of one step under one lease; the unit the runtime owns end to end. Holds the fencing token, the immutable snapshot reference, the loop phase, checkpoints, every call record, decision requests and the single reported outcome.

Field	Type	Required	Description
`attemptId`	`guid`	yes	Issued by Run Control with the lease.
`runId`	`guid`	yes
`stepId`	`guid`	yes
`tenantId`	`string`	yes
`projectId`	`string`	yes
`environmentId`	`string`	no
`leaseId`	`guid`	yes
`fencingToken`	`long`	yes	Monotonic token from the lease; every outbound call and the outcome carry it.
`snapshotId`	`guid`	yes	Resolved execution snapshot (resolved-execution-snapshot-v1).
`releaseId`	`string`	yes
`agentId`	`string`	yes
`modelProfileId`	`string`	yes
`state`	`enum:AttemptState`	yes
`phase`	`enum:AttemptPhase`	yes
`correctionCount`	`int`	yes
`maxCorrections`	`int`	yes	From the workflow step or the agent contract (agent-task-contract-v1).
`lastCheckpointId`	`guid`	no
`contextSnapshotRef`	`string`	no	context-snapshot-v1 reference produced by Knowledge (BC-09).
`outcomeHash`	`hash`	no	Hash of the reported outcome (attempt-outcome-v1); the report is idempotent on it.
`cancellationObservedAt`	`datetime`	no
`startedAt`	`datetime`	yes
`endedAt`	`datetime`	no
`version`	`long`	yes

Invariants

An attempt exists only for a lease issued by Run Control; its fencing token accompanies every outbound call and the outcome report.
Every call of class shared-write or above goes through the Tools and MCP executor with the policy decision id; the runtime never opens a connection to an external system itself.
A checkpoint is written before every gated call and after every observed outcome; resumption happens only from a checkpoint whose adapter and checkpoint-format versions are compatible, otherwise Run Control starts a new attempt.
correctionCount never exceeds maxCorrections; exhaustion ends the attempt as Failed with class validation, never as a silent success.
Exactly one outcome is reported per attempt; a repeated report with the same outcomeHash is acknowledged, a different one is rejected.
After cancellation is observed no further model or tool call is made; a call already in flight settles as Uncertain when its effect cannot be confirmed.

States (AttemptState)

stateDiagram-v2
    Claimed --> Running : ReleaseLoadedAndContextBuilt
    Running --> WaitingForTool : ToolCallIssued
    WaitingForTool --> Running : ToolResultObserved
    Running --> WaitingForDecision : DecisionRequested
    WaitingForDecision --> Running : DecisionReceived
    Running --> Paused : ControlPlaneUnreachable
    Paused --> Running : LeaseRenewed
    Running --> Succeeded : OutputVerified
    Running --> Failed : CorrectionsExhaustedOrTerminalError
    Running --> TimedOut : AttemptBudgetExceeded
    WaitingForDecision --> Failed : DecisionRejectedOrExpired
    Running --> Cancelled : CancellationObserved
    WaitingForTool --> Cancelled : CancellationObserved
    WaitingForDecision --> Cancelled : CancellationObserved
    WaitingForTool --> Uncertain : EffectUnconfirmed

Hold "Alt" / "Option" to enable pan & zoom

Entities: Checkpoint, CallRecord, DecisionRequest, SubAgentDelegation · Value objects: AttemptLimits

LoadedRelease (AgentRuntimeService)¶

Runtime read model of a Published release verified against its manifest hashes and the adapter compatibility of this worker; never a write path to publication.

Field	Type	Required	Description
`releaseId`	`string`	yes
`tenantId`	`string`	yes
`manifestHash`	`hash`	yes
`adapterVersion`	`string`	yes	Runtime adapter and checkpoint format the release was verified against.
`contentRefs`	`json`	yes	Artifact references of agent instructions, skill contents, tool descriptors, workflow definition, policy revision, model profile.
`state`	`enum:LoadState`	yes
`verifiedAt`	`datetime`	yes
`inFlightPolicy`	`string`	no	finish

Invariants

A release is usable only in state Verified; a hash mismatch or an incompatible adapter rejects it with an explicit reason.
Revocation applies the in-flight policy to running attempts of that release and never deletes the manifest the attempts already loaded.

WorkflowDefinitionVersion (WorkflowEngineService)¶

Immutable, validated graph of a Published workflow asset — steps, edges, conditions, timers, compensation map, input and output schemas — cached in the runtime for execution.

Field	Type	Required	Description
`definitionId`	`string`	yes
`version`	`string`	yes
`releaseId`	`string`	yes	Asset release of the workflow (BC-04).
`tenantId`	`string`	yes
`graphHash`	`hash`	yes
`stepCount`	`int`	yes
`inputSchemaRef`	`string`	yes
`outputSchemaRef`	`string`	yes
`maxLoopIterations`	`int`	yes
`loadedAt`	`datetime`	yes

Invariants

The graph is acyclic except for explicitly declared loops with a bounded iteration count.
Every Agent, Tool and Human step declares its action class (D21) and its failure policy; publication is refused otherwise (validated by the engine at validate time and at load).
A Condition step reads only recorded step outputs and run variables; it never calls a model.
A definition version is immutable once loaded; a changed graph has a new release id.

Entities: StepDefinition, EdgeDefinition · Value objects: —

WorkflowRun (WorkflowEngineService)¶

The engine's state of one run — cursor over the graph, step runs, variables, timers and compensation plan — projected from Run Control's accepted run and attempt outcomes.

Field	Type	Required	Description
`runId`	`guid`	yes	Same id as the Run in Run Control.
`tenantId`	`string`	yes
`projectId`	`string`	yes
`definitionReleaseId`	`string`	yes
`graphHash`	`hash`	yes
`state`	`enum:WorkflowRunState`	yes
`variablesRef`	`string`	yes	Artifact reference of the run variables (JSON).
`activeStepRuns`	`int`	yes
`lastOutcomeSequence`	`long`	yes	Last Run Control attempt outcome applied; makes Advance idempotent.
`version`	`long`	yes

Invariants

The engine never changes a run's authoritative state; it emits StepReady for Run Control to dispatch and WorkflowRunCompleted, WorkflowRunFailed or WorkflowRunCancelled for Run Control to record.
Advance is idempotent on the outcome sequence; an outcome applied twice changes nothing.
One StepRun per step is active unless the step is inside a Fanout; a Join waits for every branch or the declared quorum.
Timers are durable reminders; a fired timer that finds its step already advanced is a no-op.
Compensation runs the declared compensation steps of succeeded steps in reverse completion order; a failed compensation ends the run Failed with an operator follow-up, never silently.

States (WorkflowRunState)

stateDiagram-v2
    Pending --> Running : RunAcceptedAndBudgetReserved
    Running --> WaitingForTimer : TimerStepReached
    WaitingForTimer --> Running : TimerFired
    Running --> WaitingForHuman : HumanStepReached
    WaitingForHuman --> Running : DecisionApplied
    Running --> Compensating : StepFailedWithCompensatePolicy
    Compensating --> Failed : CompensationCompletedOrFailed
    Running --> Completed : TerminalStepsSucceeded
    Running --> Failed : StepFailedWithFailPolicy
    Running --> Cancelled : RunCancelled
    WaitingForTimer --> Cancelled : RunCancelled
    WaitingForHuman --> Cancelled : RunCancelled

Hold "Alt" / "Option" to enable pan & zoom

Entities: StepRun, TimerEntry, CompensationEntry · Value objects: —