Phase 0 Research: GUID Context Resolver & Human-Readable Reference Presentation

Decision: Build the new reference semantics on top of the current shared related-context/navigation foundation rather than starting from a second unrelated abstraction.
Rationale: The codebase already has RelatedNavigationResolver, CrossResourceNavigationMatrix, RelatedContextEntry, shared related-context Blade rendering, and canonical route helpers. Reusing those extension points reduces migration risk and keeps Spec 131 and Spec 132 aligned.
Alternatives considered:
- Replace the navigation layer entirely with a new reference-only stack: rejected because it would duplicate route, availability, and action-label logic that already exists and is already wired into multiple resources.
- Keep page-level arrays and only restyle the Blade partial: rejected because it would not satisfy the spec’s requirement for explicit reference classes, shared semantics, and distinct degraded states.

Decision 2: Model references through explicit input and output contracts

Decision: Introduce a structured ReferenceDescriptor input contract and a normalized ResolvedReference output contract with explicit state, type, label, technical detail, and optional canonical target.
Rationale: The current RelatedContextEntry payload is useful for immediate rendering but too shallow for the broader semantics required here. A descriptor plus resolved-reference pair makes support for partial resolution, unsupported classes, and future providers predictable and testable.
Alternatives considered:
- Continue passing free-form arrays between resources and partials: rejected because it invites page-specific drift and makes regression testing weak.
- Resolve everything directly inside Blade partials: rejected because presentation should not own resolution logic or authorization decisions.

Decision: Resolve references at render time using existing relations, local model lookups, current workspace or tenant context, stored fallback labels, and existing helper services only; do not make live Microsoft Graph or provider calls.
Rationale: The constitution and current architecture keep monitoring and governance views DB-only at render time. Best-effort local resolution is sufficient for the target surfaces and avoids latency, availability, and authorization leakage problems.
Alternatives considered:
- Make on-demand provider calls to improve labels: rejected because it violates the DB-only rendering expectation, adds latency, and complicates authorization.
- Cache external labels aggressively in new tables: rejected because the spec explicitly avoids introducing new persistent models solely for resolution.

Decision: Provide a compact variant for dense tables and a detailed variant for related-context or infolist sections, both powered by the same resolved-reference payload.
Rationale: Some target surfaces are list-dense and cannot absorb a full detail block without becoming noisy, while detail pages need more explanatory context and degraded-state messaging. One semantic contract with two renderers keeps the hierarchy stable while fitting each surface.
Alternatives considered:
- Force one heavy component everywhere: rejected because it would make list screens noisy and reduce scanability.
- Allow each page to design its own variant independently: rejected because it would recreate the inconsistency the spec is meant to solve.

Decision: Canonical targets become actionable only when current policy allows access; label and state disclosure must degrade to inaccessible or unresolved only to the extent policy allows.
Rationale: The product’s 404-vs-403 semantics and deny-as-not-found rules are already explicit. The reference layer must not accidentally leak object existence or friendly labels just because it has enough data to resolve them internally.
Alternatives considered:
- Hide every unauthorized reference completely: rejected because some surfaces legitimately need to preserve the existence of a reference without allowing navigation.
- Always show the resolved label even when navigation is forbidden: rejected because that can leak protected detail.

Decision: Existing helpers such as EntraGroupLabelResolver should become collaborators that feed structured resolution outputs rather than emitting final UI labels.
Rationale: Current helpers return a single string like Name (…token), which is not enough to separate primary label, type/context, state, and technical detail. They remain useful, but inside a richer resolver contract.
Alternatives considered:
- Leave helpers untouched and parse their formatted strings back into UI parts: rejected because it is brittle and loses state intent.
- Rewrite all provider-backed label logic from scratch: rejected because the current local lookup behavior is already useful and should be preserved.

Decision: Mirror the BaselineSnapshotPresenter and SnapshotTypeRendererRegistry pattern by using immutable value objects, registry dispatch, and fallback behavior for references.
Rationale: The repo already favors registry-driven support layers for normalization and rendering. Following that pattern keeps the reference system familiar, testable, and consistent with current architecture.
Alternatives considered:
- Put the entire resolution switch in one large service class: rejected because explicit per-class resolvers are easier to extend and test.
- Encode resolution rules in configuration only: rejected because authorization-aware destination logic and best-effort lookup behavior require application code.