103 lines
8.4 KiB
Markdown
103 lines
8.4 KiB
Markdown
# Research: Platform Core Vocabulary Hardening
|
|
|
|
## Decision: Keep the maintained platform glossary inside `App\Support\Governance`
|
|
|
|
### Rationale
|
|
|
|
The codebase already has a real governance vocabulary seam through `GovernanceDomainKey`, `GovernanceSubjectClass`, `GovernanceSubjectType`, and `GovernanceSubjectTaxonomyRegistry`. Spec 204 needs one maintained code-side location for canonical platform nouns, ownership boundaries, and forbidden false-universal aliases. Extending the existing governance namespace keeps the glossary close to the actual platform vocabulary primitives instead of scattering meaning across docs, config comments, and presenter code.
|
|
|
|
### Alternatives considered
|
|
|
|
- Add glossary prose only in the spec artifacts: rejected because implementation code and regression tests would still lack a maintained source of truth.
|
|
- Put the glossary entirely in config: rejected because canonical vocabulary and ownership boundaries are platform semantics, not environment configuration.
|
|
- Create a new top-level vocabulary framework: rejected because current governance seams already cover the necessary ownership model.
|
|
|
|
## Decision: Resolve one canonical operation vocabulary from stored values through explicit legacy aliases
|
|
|
|
### Rationale
|
|
|
|
`OperationRunType` and `OperationCatalog` already anchor operation meaning across monitoring, notifications, audit prose, widgets, and Filament detail surfaces. The real gap is that historical stored values mix domain-aware dotted names and older underscore names. The narrowest safe hardening is to add canonical operation codes plus explicit alias resolution so old persisted values remain readable while the platform only treats one code as canonical for future-facing semantics.
|
|
|
|
### Alternatives considered
|
|
|
|
- Rewrite all historical `operation_runs.type` values immediately: rejected because it adds migration and compatibility risk without improving operator understanding faster.
|
|
- Keep all current values equally canonical: rejected because mixed-era names would remain a permanent source of ambiguity.
|
|
- Introduce a second operation registry beside `OperationCatalog`: rejected because current consumers already centralize on the existing catalog.
|
|
|
|
## Decision: Reuse `OperationCatalog` as the central operation registry rather than creating a parallel vocabulary service
|
|
|
|
### Rationale
|
|
|
|
Exploration showed that `OperationCatalog` is already the shared read path for labels, durations, artifact families, and operator explanation support. Spec 204 should strengthen that seam with canonicalization and domain grouping instead of duplicating registry logic elsewhere. This keeps all operation-facing UI surfaces on one consistent resolution path and minimizes the amount of code that has to know about alias compatibility.
|
|
|
|
### Alternatives considered
|
|
|
|
- Add a new platform vocabulary service that wraps `OperationCatalog`: rejected because it would create an unnecessary second layer for the same meaning.
|
|
- Resolve canonical labels ad hoc in each page or widget: rejected because that would scatter compatibility logic and make regressions likely.
|
|
|
|
## Decision: Keep domain-owned reason codes intact and derive platform reason families at the translation boundary
|
|
|
|
### Rationale
|
|
|
|
The codebase already has stable domain-owned reason families such as `ProviderReasonCodes`, `RbacReason`, `BaselineCompareReasonCode`, and execution-denial reasoning. `ReasonTranslator` and `ReasonResolutionEnvelope` are already the platform-owned boundary where those codes become operator-facing explanations. Spec 204 should extend that boundary with explicit ownership metadata and platform reason-family classification so platform surfaces can speak clearly without renaming every domain enum into an artificial universal namespace.
|
|
|
|
### Alternatives considered
|
|
|
|
- Rename all existing reason enums into one platform-wide code family: rejected because it would blur ownership and create large churn for little gain.
|
|
- Leave ownership implicit and only tweak labels: rejected because ambiguity about which layer owns a reason is part of the current problem.
|
|
- Add a second explanation system beside `ReasonTranslator`: rejected because the current translation seam already owns operator-safe explanation rendering.
|
|
|
|
## Decision: Treat `policy_type` as valid only in explicitly Intune-owned or adapter-owned contexts
|
|
|
|
### Rationale
|
|
|
|
Search results showed that many `policy_type` uses are still correct because they belong to Intune policy models, backup items, inventory records, and Graph-facing adapter logic. The misleading cases are platform-near compare, snapshot, review, and monitoring contracts that use `policy_type` as if it were the product's universal noun. The hardening should therefore preserve Intune-native usage where ownership is truly Intune-specific and replace only the false-universal platform-facing usage with governed-subject descriptors.
|
|
|
|
### Alternatives considered
|
|
|
|
- Ban `policy_type` everywhere: rejected because that would erase legitimate Intune-domain meaning and distort adapter boundaries.
|
|
- Leave platform-near `policy_type` untouched: rejected because it keeps leaking one domain's nouns into product-core semantics.
|
|
|
|
## Decision: Prefer wrapper-first hardening for platform-near JSON and presenter contracts
|
|
|
|
### Rationale
|
|
|
|
Baseline compare, baseline snapshots, operation run context, and evidence rendering already persist JSON and derived presentation payloads. The narrowest implementation is to harden projections, presenters, and platform-owned context wrappers so they expose `domain_key`, `subject_class`, `subject_type_key`, and `subject_type_label` first while preserving compatibility with any existing legacy keys as secondary detail. This avoids unnecessary schema churn and keeps the change proportional.
|
|
|
|
### Alternatives considered
|
|
|
|
- Add new tables for platform-neutral subject descriptors: rejected because the existing persisted truths are already sufficient.
|
|
- Rewrite all existing JSON shapes in one release: rejected because it increases migration and rollback complexity without being necessary for operator clarity.
|
|
|
|
## Decision: Add explicit ownership descriptors around existing registries rather than building a universal plugin system
|
|
|
|
### Rationale
|
|
|
|
The codebase already contains several registry-like seams with different ownership layers: governance taxonomy, operation catalog, provider reason codes, compare explanations, and Intune policy-type config. Spec 204 needs those ownership layers to be explicit so future changes do not treat all registries as equivalent platform vocabulary sources. A small ownership descriptor model is enough to encode which registries are canonical platform vocabulary, which are domain-owned, and which are compatibility-only.
|
|
|
|
### Alternatives considered
|
|
|
|
- Build a universal runtime registry framework: rejected because it adds infrastructure without solving a concrete current-release problem.
|
|
- Rely on naming conventions only: rejected because that keeps the rules implicit and hard to enforce with tests.
|
|
|
|
## Decision: Make compatibility explicit and temporary through regression guards
|
|
|
|
### Rationale
|
|
|
|
Spec 204 is intentionally transitional. Historical operation codes and legacy platform-near payload keys still have to render correctly, but they should no longer be treated as equally canonical. The safest way to enforce that boundary is to codify canonical resolution in tests for monitoring, reason translation, baseline compare, and snapshot presentation so new work cannot quietly reintroduce raw mixed vocabulary.
|
|
|
|
### Alternatives considered
|
|
|
|
- Leave compatibility informal and rely on code review: rejected because the current ambiguity already slipped through existing review.
|
|
- Remove all legacy aliases immediately: rejected because current persisted truth and current filters still depend on them.
|
|
|
|
## Decision: Keep the scope narrow and implementation-first
|
|
|
|
### Rationale
|
|
|
|
Most of the architecture required by this feature already exists from Specs 202 and 203. The correct plan is therefore a hardening pass over those seams, not a new platform-core subsystem. That keeps the feature proportional to the actual problem: clearer boundaries, clearer nouns, and safer future evolution.
|
|
|
|
### Alternatives considered
|
|
|
|
- Expand the spec into a broad multi-domain abstraction initiative: rejected because the repo does not yet need a generic framework beyond the seams already shipping.
|
|
- Defer until another provider exists: rejected because the current mixed vocabulary is already harming platform clarity today. |