Observability — 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
AlertRule	AlertRuleService	AlertRule	AlertRuleChanged	AlertRules
AlertInstance	AlertRuleService	AlertInstance	AlertFired, AlertResolved	AlertInstances
RunProjection	DashboardService	RunProjection	RunProjectionUpdated	RunProjections, TimelineEntries, ProjectionCheckpoints
OverviewProjection	DashboardService	OverviewProjection	OperationsDigestProduced	OverviewProjections
HumanFeedback	FeedbackService	HumanFeedback	FeedbackRecorded	HumanFeedback
Dataset	FeedbackService	Dataset	DatasetPublished	Datasets, DatasetTasks
LearningProposal	FeedbackService	LearningProposal	LearningProposalRaised, LearningProposalDecided	LearningProposals
EvaluationSuite	QualityScoreService	EvaluationSuite	EvaluationSuiteActivated	EvaluationSuites
EvaluationRun	QualityScoreService	EvaluationRun	EvaluationStarted, EvaluationCompleted, EvaluationFailed, DriftDetected	EvaluationRuns, EvaluationResults
SloDefinition	SloService	SloDefinition	SloDefined, SloBreached, SloRecovered	SloDefinitions, SloMeasurements
ServiceHealth	SloService	ServiceHealth	ServiceHealthChanged	ServiceHealth

AlertRule (AlertRuleService)

A rule with a source condition, severity, deduplication key template, routing targets and suppression windows.

Field	Type	Required	Description
ruleId	guid	yes
tenantId	string	yes
name	string	yes
sourceKind	enum:AlertSourceKind	yes
condition	json	yes	Event filter or metric threshold with duration
severity	enum:AlertSeverity	yes
dedupKeyTemplate	string	yes
routes	json	yes	studio-notification
suppression	json	no
active	bool	yes

Invariants

• Platform rules (health, chain validity, uncertain effects) are always active and cannot be deleted per tenant; tenants add their own.
• Routes to external channels go through connectors (BC-17) with the external class and the tenant's connection; never raw webhooks.

AlertInstance (AlertRuleService)

One fired alert with its deduplication key, severity, source reference, acknowledgement and resolution.

Field	Type	Required	Description
alertId	guid	yes
tenantId	string	yes
ruleId	guid	yes
dedupKey	string	yes
severity	enum:AlertSeverity	yes
sourceRef	string	yes	SLO id, host id, invocation id, finding id or metric query.
state	enum:AlertState	yes
firedAt	datetime	yes
acknowledgedBy	string	no
resolvedAt	datetime	no
notifications	json	yes	Deliveries made per route with receipts.

Invariants

• The same dedupKey while an instance is Fired or Acknowledged does not fire again; it increments the occurrence count.
• Resolution is automatic on the source's recovery event or manual with a reason.

States (AlertState)

stateDiagram-v2
    Fired --> Acknowledged : Acknowledge
    Fired --> Resolved : SourceRecovered
    Acknowledged --> Resolved : SourceRecoveredOrManual
    Fired --> Suppressed : SuppressionWindow

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

RunProjection (DashboardService)

The joined view of one run — state and steps from Run Control, attempt phases and checkpoints from the runtime, model receipts, tool receipts, context snapshots, approvals, usage states and the trace id — kept current from events.

Field	Type	Required	Description
runId	guid	yes
tenantId	string	yes
projectId	string	yes
workflowId	string	yes
state	string	yes	Run Control vocabulary (ADR-0014).
steps	int	yes
attempts	int	yes
modelCalls	int	yes
toolCalls	int	yes
approvalsWaiting	int	yes
uncertainEffects	int	yes
tokens	long	yes
costUsdByStatus	json	yes	estimated, reserved, observed, reconciled, uncertain (FUX-08)
durationMs	long	no
traceId	string	yes
lastEventSequence	long	yes
updatedAt	datetime	yes

Invariants

• Projections are derived from events and the run journal; a discrepancy is resolved by rebuilding from Run Control, never by editing the projection.
• Usage amounts carry their status; uncertain amounts are never folded into totals.
• Content never enters a projection; entries hold hashes, receipt and artifact references.

Entities: TimelineEntry · Value objects: —

OverviewProjection (DashboardService)

Rolling aggregates per tenant, project, agent, workflow, tool and model for a window — task success, agent success, cost per task, latency per task, tokens per task, tool failure rate, model fallback rate, human intervention rate, sandbox failures, context retrieval quality, evaluation score.

Field	Type	Required	Description
overviewId	guid	yes
tenantId	string	yes
kind	enum:ProjectionKind	yes
subjectId	string	yes	Project, agent, workflow, tool or model id.
window	string	yes	1h
metrics	json	yes
computedAt	datetime	yes

Invariants

• Aggregates are recomputed from projections on a schedule; they are never written by hand.

HumanFeedback (FeedbackService)

Feedback from a requester, reviewer or operator on a run, attempt, artifact or memory, with the subject reference and an optional corrected artifact.

Field	Type	Required	Description
feedbackId	guid	yes
tenantId	string	yes
projectId	string	yes
subjectKind	string	yes	run
subjectRef	string	yes
kind	enum:FeedbackKind	yes
rating	int	no
commentRef	string	no	Artifact reference of the text.
correctedArtifactRef	string	no
givenBy	string	yes
givenAt	datetime	yes

Invariants

• Feedback references its subject by id and keeps text as artifacts; it never alters the subject.

Dataset (FeedbackService)

A versioned evaluation dataset of historical tasks (inputs, expected outcomes, scoring rules) with snapshots stored as artifacts; built from completed runs, feedback and curated additions.

Field	Type	Required	Description
datasetId	guid	yes
tenantId	string	yes
name	string	yes
target	string	yes	Evaluation target kind the dataset serves.
version	int	yes
taskCount	int	yes
snapshotRef	string	yes	Artifact reference of the snapshot.
classification	string	yes
publishedAt	datetime	no

Invariants

• Tasks derived from tenant runs stay tenant-scoped (D32); sharing across tenants needs anonymisation and consent.
• A snapshot is immutable; suites pin a snapshot version.

LearningProposal (FeedbackService)

A reviewable suggestion to change an asset or a strategy, with the evidence (feedback, drift, evaluations, reinforced memory) and the target asset; accepted proposals become release candidates in BC-04.

Field	Type	Required	Description
proposalId	guid	yes
tenantId	string	yes
kind	enum:ProposalKind	yes
targetAssetId	string	yes
targetVersion	string	yes
summaryRef	string	yes	Artifact reference of the proposal text and diff.
evidenceRefs	list:string	yes
expectedEffect	json	no	Metric, from, to, confidence
state	enum:ProposalState	yes
reviewedBy	string	no
resultingReleaseId	string	no
raisedAt	datetime	yes

Invariants

• A proposal never changes an asset; acceptance opens a Draft release that goes through evaluation and publication like any change.
• Proposals cite evidence; a proposal without evidence is not raised.

States (ProposalState)

stateDiagram-v2
    Proposed --> InReview : MaintainerPicksUp
    InReview --> Accepted : ReleaseCandidateOpened
    InReview --> Rejected : Rejected
    Proposed --> Superseded : NewerProposal

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

EvaluationSuite (QualityScoreService)

Runtime read model of a Published evaluation-suite asset — target kind, dataset reference, metrics with thresholds per model profile, baseline rule (no regression on task success, no rise in tool-error rate) and cost and latency budgets.

Field	Type	Required	Description
suiteId	string	yes
version	string	yes
releaseId	string	yes
tenantId	string	yes
target	enum:EvaluationTarget	yes
datasetId	guid	yes	Dataset of historical tasks (FeedbackService).
metrics	json	yes	Metric ids with thresholds, for example tool-selection ≥ 0.97, valid-arguments ≥ 0.99, structured-output ≥ 0.995, multi-turn ≥ 0.95, instruction-compliance ≥ 0.95, patch-compile ≥ 0.90
baselineRule	json	yes	Compared release must not lower task success or raise tool-error rate (D32)
budgets	json	yes	max cost and duration per run
active	bool	yes

Invariants

• Thresholds are set per profile by Platform admin through the suite asset (D32) and never by the evaluated asset's author.
• A suite pins its dataset version; a changed dataset is a new suite version.

EvaluationRun (QualityScoreService)

One execution of a suite against one target release (and optionally a baseline release) over a dataset snapshot — per-metric results, cost, latency, verdict, waiver and the evidence record artifact.

Field	Type	Required	Description
evaluationId	guid	yes
tenantId	string	yes
suiteId	string	yes
suiteVersion	string	yes
targetReleaseId	string	yes
baselineReleaseId	string	no
datasetSnapshotRef	string	yes
state	enum:EvaluationState	yes
results	json	yes	Per-metric values for target and baseline.
verdict	enum:Verdict	no
waiverApprovalId	guid	no
costUsd	decimal	no
durationMs	long	no
evidenceRef	string	no	Evaluation record artifact read by Asset Publication (ADR-0021).
startedAt	datetime	yes
completedAt	datetime	no

Invariants

• Evaluations run as Factory runs under a dedicated project with sandbox-class tools only; their model calls carry receipts and are attributed to the evaluation.
• A verdict is Passed only when every threshold is met and the baseline rule holds; a waiver needs an approval of class publication bound to the evaluation id and is recorded as evidence.
• The evidence record is immutable and references the dataset snapshot, the releases and every receipt.

States (EvaluationState)

stateDiagram-v2
    Queued --> Running : Started
    Running --> Scoring : TasksCompleted
    Scoring --> Completed : VerdictComputed
    Running --> Failed : InfrastructureFailure
    Queued --> Cancelled : Cancel
    Running --> Cancelled : Cancel

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

SloDefinition (SloService)

One objective for one subject (platform, tenant, workflow, agent, generated product) with target, window and error-budget policy.

Field	Type	Required	Description
sloId	guid	yes
tenantId	string	yes
subjectKind	string	yes	platform
subjectId	string	yes
kind	enum:ObjectiveKind	yes
target	decimal	yes	For example 0.995 availability, 2 s p95, 0.9 success.
window	string	yes	30d rolling or calendar month
burnAlertThresholds	json	yes	Fast and slow burn thresholds.
source	string	yes	metric name or projection
active	bool	yes

Invariants

• Platform objectives are the NFR baseline (D30) and cannot be loosened per tenant; tenant and product objectives may be stricter.
• A measurement is computed from projections or metrics, never entered; error budget consumption is monotonic within the window.

Entities: SloMeasurement · Value objects: —

ServiceHealth (SloService)

The health rollup of one host (and its modules) from liveness, readiness and dependency probes collected by the HealthChecks aggregator.

Field	Type	Required	Description
hostId	string	yes
tenantId	string	yes	Platform tenant for shared hosts.
state	enum:HealthState	yes
dependencies	json	yes	Per-dependency state.
replicasReady	int	yes
observedAt	datetime	yes

Invariants

• Health is observed, never declared; a host without a fresh probe is Unknown.