# 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<string>): 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<string>): 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<string>): axes where this severity is allowed as a primary state
- `forbiddenAxes` (list<string>): 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<string>): 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<string>): enums, badge mappers, presenters, or views currently using overloaded semantics
- `surfaceTypes` (list<string>): 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<string>): 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`