TenantAtlas/specs/164-run-detail-hardening/data-model.md

Data Model: Operation Run Detail Hierarchy, Deduplication, and Decision Guidance Hardening

Overview

This feature does not add or change persisted domain entities. It introduces a stricter derived page model for the canonical operation-run detail surface using existing OperationRun, artifact-truth, operator-explanation, summary-count, and lifecycle data.

The core design task is to transform an existing run record into a decision-first presentation contract without changing:

• OperationRun persistence
• route identity
• RBAC semantics
• status and outcome lifecycle ownership
• type-specific payload availability

Existing Persistent Entity

OperationRun

• Purpose: Canonical workspace-owned execution record for operational work tracked in Monitoring.
• Persistent fields used by this feature:
  • id
  • workspace_id
  • tenant_id
  • type
  • status
  • outcome
  • initiator_name
  • summary_counts
  • failure_summary
  • context
  • created_at
  • started_at
  • completed_at
• Existing relationships used by this feature:
  • workspace
  • tenant
  • user

Derived View Models

1. RunDetailPageModel

Top-level page payload consumed by the enterprise-detail layout and viewer wrapper.

Field	Type	Source	Notes
header	object	Existing SummaryHeaderData	Run identity, badges, key facts, existing page-level actions
decisionZone	object	New derived payload	First-class operator summary immediately after header
supportingGroups	list	Existing supporting-card inputs regrouped	Replaces or restructures the current dense Current state card
mainSections	list	Existing section builder output	Used for supporting detail and type-specific detail after the decision zone
technicalSections	list	Existing technical-detail output	Diagnostics-last content such as context JSON
attentionBanners	list	Existing viewer wrapper helpers	Context mismatch, blocked prerequisite, stale or reconciled lifecycle attention

2. DecisionZoneModel

The primary operator reading block. It must answer: what happened, is the result trustworthy enough to use, and what should happen next.

Field	Type	Source	Required	Notes
executionState	badge or labeled fact	status plus centralized badge rendering	Yes	Lifecycle state, not result quality
outcome	badge or labeled fact	outcome plus centralized badge rendering	Yes	Execution result, not artifact usability
artifactTruth	object	ArtifactTruthPresenter::forOperationRun() when available	Conditional	Required when the run has artifact-relevant operator meaning
resultMeaning	string	operator explanation headline or evaluation label	Conditional	Human-readable interpretation of what the result means
resultTrust	string or badge	operator explanation trust level	Conditional	Confidence or reliability meaning stays distinct from outcome
primaryNextStep	object	Derived precedence chain	Yes	Exactly one primary next step
compactCounts	object or null	SummaryCountsNormalizer output	Optional	Only when counts add decision value and do not duplicate diagnostics
attentionNote	string or null	lifecycle or caveat helper	Optional	Short exceptional-state caveat if needed in-zone

PrimaryNextStepModel

Field	Type	Source	Notes
text	string	Derived from prioritized guidance sources	Canonical operator action statement
source	enum-like string	operator_explanation, artifact_truth, ops_ux, blocked_reason, lifecycle_attention	Debugging and testability only
secondaryGuidance	list	Non-primary guidance sources	Must not render as equal-priority duplicates

Proposed precedence for primaryNextStep

1. Operator explanation next action when present
2. Artifact-truth next step when it is more specific than generic run guidance
3. Blocked-execution guidance when outcome is blocked
4. Lifecycle guidance when stale or reconciled state requires explicit attention
5. Generic OperationUxPresenter::surfaceGuidance()
6. Fallback No action needed only when the result is explicitly trustworthy and no follow-up is indicated

3. SupportingGroupModel

Semantically grouped supporting context that sits below or beside the decision zone but above diagnostics.

Group	Purpose	Typical fields
guidance	Secondary operator context that supports the primary next step	coverage statement, contextual caveat, related follow-up links
lifecycle	Freshness, reconciliation, tenant lifecycle, and contextual caveats	freshness, lifecycle truth, reconciled at, reconciled by
timing	Operational timestamps and elapsed timing	created, started, completed, elapsed
metadata	Secondary facts that do not drive the first decision	target scope, initiator, viewer-context notes

Rules:

• The same semantic fact must not appear in multiple supporting groups unless the representation serves a genuinely different purpose.
• Supporting groups must not restate the same primary next step as the decision zone.
• Supporting groups may explain why the primary next step exists, but not compete with it.

4. CountPresentationModel

Field	Type	Purpose
summaryLine	string or null	Compact operator-facing count hint
primaryFacts	list	Single main count presentation if counts materially help first-pass understanding
diagnosticFacts	list	Optional deeper breakdown when the detailed count grid serves investigation

Rules:

• primaryFacts and diagnosticFacts must not be identical renderings of the same normalized counts.
• If the detailed count grid remains in main content, the compact summary line must be materially different and lighter-weight.
• If counts are low-signal for the run, both may be omitted.

5. TypeSpecificDetailModel

Represents operation-type-specific content that follows the canonical decision summary.

Operation Type	Existing section examples	Ordering rule
baseline_compare	compare facts, evidence gap details, compare evidence	After decision zone and supporting groups
baseline_capture	capture evidence	After decision zone and supporting groups
verification-capable runs	verification report	After decision zone and supporting groups
any run with failures	failures section	After decision zone and supporting groups
reconciled runs	lifecycle reconciliation payload	After decision zone and supporting groups

Rules:

• Type-specific sections may deepen or explain the decision, but they must not replace the canonical summary.
• Raw JSON remains valid only as diagnostics or deep detail.

6. DiagnosticSectionModel

Lower-priority technical or investigative information.

Section	Source	Default posture
failures	failure_summary	Visible after decision and supporting context
reconciliation	context.reconciliation	Visible only when relevant; diagnostic
context	redacted context payload	Collapsed by default
raw evidence payloads	baseline compare or capture payload arrays	Secondary or collapsible

Rules:

• Diagnostic sections must remain available for support and investigation.
• Diagnostic sections must never be required to answer the primary operator questions.

Render Ordering Contract

The surface must obey this order:

1. Attention banners that indicate exceptional context without duplicating neutral page facts
2. Header identity and route-level actions
3. Primary decision zone
4. Supporting semantic groups
5. Type-specific supporting detail
6. Diagnostic and raw context sections

Validation Rules

• Exactly one primary next-step statement is rendered at top-level priority.
• No identical normalized count block appears more than once in the main content hierarchy.
• Outcome, Artifact truth, and Result trust remain independently visible when the run supplies those semantics.
• Diagnostic JSON or raw technical context cannot appear before the decision zone.
• Type-specific detail cannot render above the canonical decision zone.

State Notes

There are no new persisted state transitions in this feature.

The relevant page-state modes that must remain representable are:

• completed and trustworthy
• completed with follow-up required
• failed
• blocked
• stale
• reconciled
• artifact unavailable or limited confidence
• type-specific diagnostic-heavy runs