TenantAtlas/specs/132-guid-context-resolver/research.md

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

## Decision 1: Extend the existing shared navigation layer instead of replacing it

- 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 3: Keep render-time resolution DB-only and best-effort

- 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 4: Use two shared presentation variants with one semantic payload

- 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 5: Authorization controls linkability first, label disclosure second

- 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 6: Upgrade narrow label helpers into structured resolver collaborators

- 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 7: Leverage the repo’s existing registry-and-DTO pattern

- 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.