TenantAtlas/specs/156-operator-outcome-taxonomy/data-model.md

Data Model: Operator Outcome Taxonomy and Cross-Domain State Separation

This feature defines a shared semantic model rather than introducing a new business-domain table. The model below captures the entities that the implementation and guard coverage must agree on.

Entities

SemanticAxis

Represents one independent meaning dimension that operator-facing state is allowed to communicate.

Fields:

• key (string): stable identifier such as execution_outcome, freshness, or product_support_maturity
• label (string): human-readable axis name used in documentation
• definition (string): the exact semantic question this axis answers
• allowedValues (list): canonical operator-facing values allowed on this axis
• defaultPresentationLevel (enum): primary or diagnostic
• nextActionRequired (bool): whether non-green states on this axis must always carry action guidance

Validation rules:

• Each operator-facing primary state belongs to exactly one axis.
• Different axes must not be flattened into one unqualified label.
• Diagnostic-only axes cannot use warning or danger as their default severity.

TaxonomyTerm

Represents one canonical operator-facing term or phrase permitted by the taxonomy.

Fields:

• term (string): canonical label shown to operators
• axisKey (string): owning semantic axis
• replaces (list): overloaded legacy terms or synonyms that must migrate away
• requiresQualifier (bool): whether the term must include a qualifier such as count, cause, or dimension
• notes (string): usage guidance and example contexts

Validation rules:

• A canonical term must have one meaning only.
• A term marked requiresQualifier is invalid when used bare.
• Legacy overloaded terms such as Partial, Blocked, Missing, and Unsupported must map to one or more canonical replacements.

SeverityRule

Represents the shared meaning of severity colors and tones.

Fields:

• severity (enum): danger, warning, info, success, gray, primary
• meaning (string): semantic meaning of the severity across the product
• allowedAxes (list): axes where this severity is allowed as a primary state
• forbiddenAxes (list): axes where this severity must not be used
• operatorExpectation (string): what the operator should infer from seeing the severity

Validation rules:

• danger is reserved for execution failure, governance violation, or material risk.
• warning is reserved for action-recommended or mixed-outcome primary states.
• gray is reserved for neutral, archived, not applicable, or explicitly non-actionable context.
• Diagnostic-only states must not use danger or warning.

PresentationClassification

Represents whether a state belongs in the operator's primary view or in diagnostics.

Fields:

• level (enum): primary or diagnostic
• actionability (enum): action_required, action_recommended, no_action_needed, context_only
• explanationRequired (bool): whether helper text or a next-step reference is mandatory
• supportsRawDetails (bool): whether raw technical detail may be shown as secondary detail

Validation rules:

• Every non-green, non-gray primary state requires explanation or an explicit no-action-needed note.
• Diagnostic classification never replaces the primary state for a surface that already exposes a primary state.

TaxonomyEntry

Represents the complete classification of one raw domain state into taxonomy semantics.

Fields:

• domain (string): source domain such as operation_run_outcome or evidence_completeness
• rawValue (string): existing enum value or normalized source state
• axisKey (string): owning semantic axis
• primaryLabel (string): operator-facing label to render
• severity (enum): resolved severity band
• classificationLevel (enum): primary or diagnostic
• legacyAliases (list): prior labels that must stop being used
• nextActionPolicy (enum): required, optional, none
• diagnosticLabel (optional string): secondary label for detailed views
• notes (string): human explanation of why the mapping exists

Validation rules:

• Every adopted raw state must have exactly one taxonomy entry.
• classificationLevel = diagnostic forbids severity = warning|danger.
• nextActionPolicy = required must be set for non-green, non-gray primary states.

AdoptionTarget

Represents a bounded surface or domain family included in the first implementation slice.

Fields:

• key (string): stable target identifier
• family (enum): operations, baselines, restore, evidence, reviews, inventory_provider, verification
• sourceArtifacts (list): enums, badge mappers, presenters, or views currently using overloaded semantics
• surfaceTypes (list): examples such as table, infolist, notification, widget, helper_copy
• priority (enum): P0, P1, P2
• rolloutStage (int): ordered implementation stage

Validation rules:

• The first slice must include operations, baselines, restore, and at least one additional family.
• Each target must identify both shared-code adoption points and user-visible surfaces.

RegressionGuardCase

Represents one reusable guard or regression test category enforcing the taxonomy.

Fields:

• name (string): guard case identifier
• assertion (string): invariant being enforced
• scope (enum): unit, feature, architecture
• coversAxes (list): axes touched by the case
• failureSignal (string): what should cause CI to fail

Validation rules:

• The first slice must include guards for diagnostic severity misuse, valid-empty misclassification, freshness severity misuse, unqualified partial or blocked labels, and cross-tenant leakage in canonical views.

Relationships

• SemanticAxis 1-to-many TaxonomyTerm
• SemanticAxis 1-to-many SeverityRule by allowed or forbidden usage
• TaxonomyEntry belongs to one SemanticAxis
• TaxonomyEntry belongs to one PresentationClassification
• AdoptionTarget consumes many TaxonomyEntry mappings
• RegressionGuardCase validates many TaxonomyEntry and AdoptionTarget combinations

Initial First-Slice Adoption Set

Operations

• Source artifacts: OperationRunOutcomeBadge, OperationUxPresenter, SummaryCountsNormalizer, operation notifications
• Primary axes involved: execution_outcome, operator_actionability

Baseline snapshot semantics

• Source artifacts: FidelityState, GapSummary, BaselineSnapshotFidelityBadge, BaselineSnapshotGapStatusBadge
• Primary axes involved: evidence_depth, data_coverage, product_support_maturity

Restore semantics

• Source artifacts: RestoreRunStatusBadge, RestoreResultStatusBadge, RestorePreviewDecisionBadge, RestoreCheckSeverityBadge
• Primary axes involved: execution_lifecycle, item_result, operator_actionability

Evidence and review completeness

• Source artifacts: EvidenceCompletenessState, TenantReviewCompletenessState, their badge mappers, canonical review surfaces
• Primary axes involved: data_coverage, data_freshness

Inventory or provider operability

• Source artifacts: InventoryKpiBadges, PolicySnapshotModeBadge, ProviderConnectionStatusBadge, ProviderConnectionHealthBadge, verification status helpers
• Primary axes involved: product_support_maturity, operator_actionability, freshness