TenantAtlas/specs/157-reason-code-translation/data-model.md

Data Model: Operator Reason Code Translation and Humanization Contract

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

Entities

ReasonCodeArtifact

Represents one source family that owns stable internal reason identifiers.

Fields:

• key (string): stable artifact identifier such as provider_reason_codes or execution_denial_reason_code
• structure (enum): string_constants, enum_without_message, enum_with_message, localized_helper, mixed
• domain (string): source domain such as provider, operations, tenants, rbac, baseline, verification
• ownsStableCodes (bool): whether the artifact is the source of truth for machine-readable codes
• supportsNativeBehavior (bool): whether the artifact can already expose methods such as message()
• adoptionPriority (enum): P0, P1, P2

Validation rules:

• Each adopted reason must belong to exactly one source artifact.
• string_constants artifacts require an adapter or registry-backed translation path.
• enum_without_message artifacts require shared translation behavior before adoption.

ReasonTranslationEntry

Represents one mapping from a stable internal code to operator-facing explanation semantics.

Fields:

• artifactKey (string): owning ReasonCodeArtifact
• internalCode (string): stable machine-readable reason code
• operatorLabel (string): primary human-readable label
• shortExplanation (string): concise operator-facing explanation
• actionability (enum): retryable_transient, permanent_configuration, prerequisite_missing, non_actionable
• diagnosticVisibility (enum): always_available, secondary_only
• nextStepPolicy (enum): required, optional, none
• taxonomyTerms (list): canonical outcome-taxonomy terms this translation relies on
• legacyInputs (list): raw or heuristic inputs that may normalize into this entry

Validation rules:

• operatorLabel must not be the raw internal code.
• nextStepPolicy = required when the actionability class implies a useful remediation path.
• non_actionable entries must explicitly communicate that no operator action is required.

ReasonResolutionEnvelope

Represents the shared operator-facing contract returned by the translation layer.

Fields:

• internalCode (string): stable machine-readable code preserved for diagnostics
• operatorLabel (string): primary translated label
• shortExplanation (string): concise explanation for default-visible surfaces
• actionability (enum): retryable_transient, permanent_configuration, prerequisite_missing, non_actionable
• nextSteps (list): zero or more remediation options
• showNoActionNeeded (bool): whether the envelope should explicitly say no action is required
• diagnosticCodeLabel (optional string): secondary detail label for raw-code display

Validation rules:

• Every adopted primary reason surface resolves through exactly one envelope.
• The envelope must preserve internalCode unchanged.
• An envelope may contain no nextSteps only when nextStepPolicy is none or the surface cannot safely expose the next step.

NextStepOption

Represents one operator-facing remediation path associated with a translated reason.

Fields:

• label (string): action-oriented guidance such as Grant admin consent or Review provider connection
• kind (enum): link, instruction, diagnostic_only
• destination (optional string): logical destination or URL when the step is link-based
• authorizationRequired (bool): whether the destination requires entitlement checks before display or execution
• scope (enum): tenant, workspace, system, none

Validation rules:

• destination is required when kind = link.
• Unauthorized next-step options must not be surfaced on primary views.
• diagnostic_only next steps cannot become the only primary guidance for actionable states.

TranslationFallbackRule

Represents the bounded fallback behavior used when a source reason lacks a domain-owned translation entry.

Fields:

• sourcePattern (string): input code or normalized pattern being matched
• normalizedCode (string): internal code chosen after bounded normalization
• fallbackLabel (string): understandable operator-facing fallback label
• fallbackExplanation (string): concise fallback explanation
• allowedSurfaces (list): where fallback behavior is acceptable

Validation rules:

• Fallback labels must remain understandable and must not expose raw internal code as the only primary message.
• Fallback behavior cannot become the preferred long-term path for adopted reason families.

AdoptionTarget

Represents one bounded surface family included in the first implementation slice.

Fields:

• key (string): stable target identifier
• family (enum): operations, providers, tenants, rbac, baseline, verification, restore, onboarding, system_console
• sourceArtifacts (list): ReasonCodeArtifact keys adopted by this target
• surfaceTypes (list): examples such as notification, run_detail, banner, summary_line, table, helper_copy
• priority (enum): P0, P1, P2
• rolloutStage (int): ordered rollout stage

Validation rules:

• The first slice must include operations, providers, tenant-operability governance, and adopted system-console RBAC or onboarding surfaces.
• Each target must identify both shared-code seams and user-visible surfaces.

RegressionGuardCase

Represents one reusable test or guard invariant enforcing the contract.

Fields:

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

Validation rules:

• The first slice must include guards for raw-code primary exposure, fallback overuse, missing next-step guidance for actionable states, and cross-scope leak risks.

Relationships

• ReasonCodeArtifact 1-to-many ReasonTranslationEntry
• ReasonTranslationEntry 1-to-1 ReasonResolutionEnvelope in adopted paths
• ReasonResolutionEnvelope 1-to-many NextStepOption
• TranslationFallbackRule supports many ReasonCodeArtifact families when no direct entry exists
• AdoptionTarget consumes many ReasonCodeArtifact and ReasonTranslationEntry combinations
• RegressionGuardCase validates many AdoptionTarget and ReasonResolutionEnvelope combinations

Initial First-Slice Adoption Set

Operations and notifications

• Source artifacts: ExecutionDenialReasonCode, normalized failure reasons, OperationUxPresenter, OperationRunCompleted, SummaryCountsNormalizer
• Primary needs: translated label, concise explanation, actionability guidance, diagnostic raw-code preservation

Provider blocking and guidance

• Source artifacts: ProviderReasonCodes, ProviderNextStepsRegistry, provider-connection blocking flows
• Primary needs: stable provider code translation, next-step guidance, bounded fallback for unknown provider errors

Tenant operability and RBAC governance

• Source artifacts: TenantOperabilityReasonCode, RbacReason
• Primary needs: move from raw enum values to translated operator-facing envelopes without changing existing domain semantics

Out-of-slice but adjacent families

• BaselineReasonCodes and BaselineCompareReasonCode
• onboarding lifecycle raw string reasons
• verification check reason payloads
• restore item-level reason payloads

These remain explicit downstream adoption candidates once the shared contract is proven on the first slice.