TenantAtlas/specs/204-platform-core-vocabulary-hardening/data-model.md

Data Model: Platform Core Vocabulary Hardening

Overview

This feature introduces no new top-level persisted entity and no new mandatory database table. It formalizes a small set of internal platform contracts that clarify ownership, canonical naming, alias handling, and platform-facing subject descriptors across the existing governance, operation, and reason-translation seams.

Existing Persisted Truth Reused Without Change

Operation truth

• operation_runs.type
• operation_runs.context
• current run summary, monitoring, notification, and audit projections

These remain the persisted record of what ran. Spec 204 changes how platform code resolves and presents operation meaning, not the existence of those records.

Governance and baseline truth

• baseline_profiles.scope_jsonb
• baseline_snapshots
• baseline_snapshot_items
• current findings and evidence payloads
• canonical Baseline Scope V2 from Spec 202

These remain the reference truth for platform-near compare and snapshot surfaces.

Domain-owned provider and policy truth

• Intune policy records and policy versions
• backup and inventory items with Intune-native metadata
• Graph-facing provider payloads and config-backed Intune policy-type catalogs

These remain intentionally domain-owned and may continue to use Intune-native terminology such as policy_type where that ownership is explicit.

New Internal Contracts

VocabularyBoundaryClassification

Type: internal enum
Purpose: give contributors one explicit three-way classification for touched concepts

Value	Meaning
platform_core	Core product vocabulary owned by the platform itself
cross_domain_governance	Governance vocabulary shared across domains and workflows
intune_specific	Vocabulary that remains intentionally specific to the Intune domain

PlatformVocabularyTerm

Type: internal governance record
Purpose: define one canonical platform noun or phrase and its ownership boundary

Field	Type	Notes
term_key	string	Stable internal identifier for the term
canonical_label	string	Preferred operator-safe platform label
canonical_description	string	Maintained description of what the term means in platform context
boundary_classification	string	platform_core, cross_domain_governance, or intune_specific
owner_layer	string	platform_core, domain_owned, provider_owned, or compatibility_alias
allowed_contexts	array	Surfaces or layers where the term is valid
legacy_aliases	array	Historical names still recognized for compatibility
alias_retirement_path	string or null	Documented path for retiring any legacy alias once rollout stabilizes
forbidden_platform_aliases	array	Names that must not be used as universal platform vocabulary

RegistryOwnershipDescriptor

Type: internal governance record
Purpose: describe whether a registry or catalog is canonical platform vocabulary, domain-owned vocabulary, or compatibility-only

Field	Type	Notes
registry_key	string	Stable internal identifier
boundary_classification	string	platform_core, cross_domain_governance, or intune_specific
owner_layer	string	platform_core, domain_owned, provider_owned, or compatibility_only
source_class_or_file	string	Class or config path that owns the registry
canonical_nouns	array	Terms this registry defines authoritatively
allowed_consumers	array	Surfaces allowed to consume the registry as-is
compatibility_notes	string or null	Transitional notes where legacy or domain-specific terms remain exposed

CanonicalOperationType

Type: internal operation catalog record
Purpose: describe one canonical platform operation code

Field	Type	Notes
canonical_code	string	Preferred platform operation code
domain_key	string or null	Optional domain grouping when the operation belongs to a specific subject family
artifact_family	string	Existing operation artifact grouping
display_label	string	Preferred operator-facing label
supports_operator_explanation	boolean	Mirrors existing catalog behavior
expected_duration_seconds	integer or null	Existing duration hint

OperationTypeAlias

Type: internal compatibility record
Purpose: map one stored or historical operation type value onto one canonical operation type

Field	Type	Notes
raw_value	string	Stored or historical operation type value
canonical_code	string	Target canonical operation code
alias_status	string	canonical, legacy_alias, or deprecated_alias
write_allowed	boolean	Whether new writes may still emit this raw value
deprecation_note	string or null	Optional explanation for reviewers or maintainers
retirement_path	string or null	Required rollout note describing how and when the alias stops being writable or supported

OperationTypeResolution

Type: internal derived value object
Purpose: represent resolved operation meaning for monitoring, filters, notifications, audit prose, and run detail surfaces

Field	Type	Notes
raw_value	string	Original stored value
canonical	CanonicalOperationType	Resolved canonical operation record
aliases_considered	array<OperationTypeAlias>	Alias records considered during normalization
alias_status	string	Current alias state
was_legacy_alias	boolean	Convenience flag for diagnostics and test assertions

PlatformReasonFamily

Type: internal enum
Purpose: classify translated reasons into one platform-owned family without changing domain-owned reason codes

Value	Meaning
authorization	Access or RBAC boundary prevented the action or view
prerequisite	Required tenant, workspace, or configuration precondition is missing
compatibility	The requested workflow or subject family is not supported together
coverage	Evidence or scope coverage is insufficient to make a trustworthy claim
availability	The referenced object, source, or provider data is absent or unavailable
execution	Runtime execution failed or degraded

ReasonOwnershipDescriptor

Type: internal derived record
Purpose: identify which layer owns the underlying reason code

Field	Type	Notes
owner_layer	string	platform_core, domain_owned, or provider_owned
owner_namespace	string	Stable namespace such as provider.intune, governance.baseline_compare, access.rbac, or execution.runtime
reason_code	string	Original reason code value
platform_reason_family	string	PlatformReasonFamily value

TranslatedReasonEnvelopeV2

Type: internal extension of the existing ReasonResolutionEnvelope
Purpose: provide one operator-safe explanation object with explicit ownership and family metadata

Field	Type	Notes
reason_owner	ReasonOwnershipDescriptor	New ownership metadata
operator_label	string	Existing translated label
explanation	string	Existing translated explanation
actionability	string	Existing actionability field
next_steps	array	Existing or derived remediation hints
diagnostic_label	string or null	Existing technical summary
trust_impact	string or null	Existing trust impact summary
absence_pattern	string or null	Existing absence classification where relevant

PlatformSubjectDescriptor

Type: internal derived value object
Purpose: normalize platform-near subject meaning without assuming universal Intune policy nouns

Field	Type	Notes
domain_key	string	Canonical governance domain
subject_class	string	Canonical subject class
subject_type_key	string	Domain-owned subject family key
subject_type_label	string	Operator-facing subject family label
platform_noun	string	Preferred platform noun for the object
display_label	string	Subject label used on touched UI surfaces
legacy_policy_type	string or null	Optional legacy Intune discriminator retained only for compatibility or diagnostics
owner_layer	string	Usually platform_core for the descriptor itself even when the underlying subject is Intune-owned

SubjectDescriptorNormalizationResult

Type: internal derived record
Purpose: report how a platform-near raw payload was normalized into a PlatformSubjectDescriptor

Field	Type	Notes
descriptor	PlatformSubjectDescriptor	Required normalized descriptor
source_surface	string	Run detail, snapshot rendering, compare summary, evidence rendering, or similar
used_legacy_alias	boolean	Whether normalization had to fall back to policy_type or another legacy discriminator
warnings	array	Non-fatal compatibility warnings for diagnostics

Relationships

• One PlatformVocabularyTerm may describe many RegistryOwnershipDescriptor or PlatformSubjectDescriptor contracts.
• One CanonicalOperationType may have many OperationTypeAlias records.
• One OperationTypeResolution is produced from exactly one raw operation type value and one resolved CanonicalOperationType.
• One ReasonOwnershipDescriptor classifies one underlying reason code and feeds one TranslatedReasonEnvelopeV2.
• One SubjectDescriptorNormalizationResult produces exactly one PlatformSubjectDescriptor for one touched platform-near payload.
• One registry or catalog should have exactly one RegistryOwnershipDescriptor to keep ownership explicit.

Validation Rules

Platform glossary and registry ownership

1. Every canonical platform term must have exactly one owner_layer.
2. Every canonical platform term must have exactly one explicit boundary_classification.
3. A term marked compatibility_alias cannot be the primary label on new platform surfaces.
4. A registry marked domain_owned or provider_owned cannot be treated as a universal platform glossary without an explicit wrapper or translation step.
5. Any term with one or more legacy_aliases must also define an alias_retirement_path.

Operation vocabulary

1. Every stored operation type value consumed by touched platform surfaces must resolve to exactly one canonical operation code.
2. New writes on touched flows must not introduce a raw value marked deprecated_alias.
3. Monitoring, filters, notifications, and audit prose must render canonical labels through OperationTypeResolution rather than raw strings.

Reason ownership

1. Every translated operator reason must carry explicit reason_owner metadata.
2. A platform_reason_family must be derived without renaming the original domain-owned code.
3. Platform surfaces may summarize by family, but diagnostics must preserve the original owner namespace and code.

Platform subject descriptors

1. Every touched platform-near compare, snapshot, or review payload must provide a PlatformSubjectDescriptor or enough source data to derive one.
2. legacy_policy_type may be carried only as secondary compatibility data.
3. New or updated platform-facing summary labels must prefer platform_noun, subject_type_label, or display_label over raw policy_type.

Transition Rules

Operation type transition

1. Existing stored raw values remain readable.
2. Canonical resolution happens at read and presentation time for touched surfaces.
3. New or updated platform flows touched by this spec must emit canonical operation codes on new writes.
4. Legacy aliases remain documented and test-covered as read-only compatibility paths for historical data and untouched flows until intentionally retired.

Reason translation transition

1. Existing domain reason codes remain unchanged.
2. Ownership and family metadata are added at translation time.
3. Existing operator-safe explanation fields remain the primary rendering contract.

Platform-near subject transition

1. Existing persisted baseline and evidence truths remain intact.
2. Wrapper or presenter normalization adds PlatformSubjectDescriptor semantics first.
3. Legacy policy_type remains available only for compatibility, diagnostics, or Intune-owned surfaces.