TenantAtlas/specs/132-guid-context-resolver/data-model.md

# Data Model: GUID Context Resolver & Human-Readable Reference Presentation

## Overview

This feature adds no new database tables. It introduces an application-layer reference model that normalizes how user-visible references are described, resolved, and rendered across Filament resources and related-context sections.

## Entities

### 1. ReferenceDescriptor

Represents the structured input passed into the shared resolver layer.

| Field | Type | Required | Notes |
|------|------|----------|------|
| `referenceClass` | string | Yes | Explicit class such as `policy`, `policy_version`, `baseline_snapshot`, `operation_run`, `group`, `role_definition`, or `unsupported`. |
| `rawIdentifier` | string | Yes | Canonical raw ID, GUID, key, or source token preserved as evidence. |
| `workspaceId` | int\|null | No | Required when the target is workspace-owned or when workspace-scoped authorization is needed. |
| `tenantId` | int\|null | No | Required when the target is tenant-owned or provider-backed in tenant scope. |
| `sourceType` | string\|null | No | Calling surface or domain source, such as `finding`, `baseline_snapshot`, or `assignment_target`. |
| `sourceSurface` | string\|null | No | Rendering context such as `detail_section`, `detail_header`, or `list_row`. |
| `fallbackLabel` | string\|null | No | Safe operator-facing label derived from source payload when authoritative lookup is unavailable. |
| `linkedModelId` | int\|null | No | Optional internal record ID when the caller already knows the local model. |
| `linkedModelType` | string\|null | No | Optional model class or logical model name paired with `linkedModelId`. |
| `context` | array<string, mixed> | No | Safe source metadata used for best-effort enrichment and target construction. |

Validation rules:
- `referenceClass` must be from the supported registry or explicitly marked `unsupported`.
- `rawIdentifier` must be non-empty even when `linkedModelId` is present so technical detail is preserved.
- `context` must contain only safe, serializable values; no secrets or raw provider payload dumps.

### 2. ResolvedReference

Represents the normalized output from a resolver.

| Field | Type | Required | Notes |
|------|------|----------|------|
| `referenceClass` | string | Yes | Echoes the resolved class. |
| `rawIdentifier` | string | Yes | Original raw identifier preserved for technical detail. |
| `primaryLabel` | string | Yes | Human-readable display name or best-known fallback label. |
| `secondaryLabel` | string\|null | No | Type or context hint such as `Policy version`, `Group`, or `Workspace baseline`. |
| `state` | string | Yes | One of `resolved`, `partially_resolved`, `unresolved`, `deleted_or_missing`, `inaccessible`, or `external_limited_context`. |
| `stateLabel` | string\|null | No | Shared operator-facing vocabulary for the current state. |
| `linkTarget` | ReferenceLinkTarget\|null | No | Present only when the target is meaningful and access is allowed. |
| `technicalDetail` | ReferenceTechnicalDetail | Yes | Structured secondary detail for advanced operators. |
| `meta` | array<string, mixed> | No | Extra safe metadata such as badge hints or source provenance. |

Rules:
- `primaryLabel` must never default to the raw ID when a better fallback label exists.
- `linkTarget` must be absent when the reference is inaccessible, unsupported, or not meaningful to navigate.
- `state` must be explicit; null-based implicit semantics are not allowed.

### 3. ReferenceLinkTarget

Represents an optional canonical destination.

| Field | Type | Required | Notes |
|------|------|----------|------|
| `targetKind` | string | Yes | Logical target such as `policy`, `policy_version`, `baseline_snapshot`, or `operation_run`. |
| `url` | string | Yes | Canonical resolved URL when the target is actionable. |
| `contextBadge` | string\|null | No | Optional context hint such as `Tenant context`. |
| `actionLabel` | string | Yes | Operator-facing action label such as `View policy` or `View run`. |

Rules:
- `url` must come from canonical helpers such as resource `getUrl()` or `OperationRunLinks`, not hand-built route strings.
- `actionLabel` must follow shared UI naming vocabulary.

### 4. ReferenceTechnicalDetail

Represents controlled technical detail.

| Field | Type | Required | Notes |
|------|------|----------|------|
| `displayId` | string\|null | No | Shortened or copyable technical identifier for UI display. |
| `fullId` | string | Yes | Raw identifier preserved in full form. |
| `sourceHint` | string\|null | No | Optional text like `Captured from snapshot evidence`. |
| `copyable` | bool | Yes | Whether UI may expose copy-to-clipboard affordance. |
| `defaultCollapsed` | bool | Yes | Whether technical detail should remain visually secondary by default. |

### 5. ReferencePresentationVariant

Represents the intended rendering density.

| Field | Type | Required | Notes |
|------|------|----------|------|
| `variant` | string | Yes | `compact` or `detail`. |
| `showStateBadge` | bool | Yes | Indicates whether state badge is rendered inline. |
| `showTechnicalDetail` | bool | Yes | Whether the variant exposes secondary technical text inline or in disclosure form. |

## Relationships

- `ReferenceDescriptor` is passed to `ReferenceResolverRegistry`.
- `ReferenceResolverRegistry` selects one resolver based on `referenceClass`.
- The chosen resolver returns a `ResolvedReference`.
- `ResolvedReference` may contain a `ReferenceLinkTarget` and `ReferenceTechnicalDetail`.
- Shared Filament renderers consume `ResolvedReference` plus `ReferencePresentationVariant`.
- Existing `RelatedNavigationResolver` and current related-context sections are expected to adapt from `RelatedContextEntry` arrays to the richer `ResolvedReference` contract.

## Reference State Semantics

| State | Meaning | UI Expectation |
|------|---------|----------------|
| `resolved` | Authoritative label and optional canonical target are known. | Label-first; actionable only when permitted. |
| `partially_resolved` | Useful label or type is known, but some context or navigation is missing. | Label-first with explicit partial context; technical ID secondary. |
| `unresolved` | Only raw identifier and perhaps source hints are known. | Visible degraded state; no false confidence. |
| `deleted_or_missing` | Reference once mapped to a record that no longer exists locally. | Distinct missing/deleted message; raw ID preserved secondarily. |
| `inaccessible` | Resolver knows a target exists but current policy does not allow navigation or safe disclosure. | Non-clickable; disclosure limited by policy. |
| `external_limited_context` | Reference belongs to an external/provider object with only limited local enrichment. | Best-effort label/type plus raw ID as secondary evidence. |

## Current Domain Sources Expected to Feed the Model

| Source Model / Surface | Likely Reference Classes Produced |
|------|------|
| `Finding` | `baseline_snapshot`, `operation_run`, `policy_version`, `policy`, `baseline_profile`, assignment or principal targets from evidence |
| `PolicyVersion` | `policy`, `baseline_snapshot`, `baseline_profile`, `operation_run` |
| `BaselineSnapshot` | `baseline_profile`, `policy_version`, `operation_run`, role or assignment evidence references |
| `BackupSet` | `operation_run`, `policy`, `policy_version`, assignment-related target references |
| `OperationRun` | `backup_set`, `restore_run`, `baseline_profile`, `baseline_snapshot`, `policy`, target tenant or provider-linked context |
| Assignment-like views | `group`, `user`, `service_principal`, `role_definition`, `policy`, `policy_version` |

## Migration Impact

- No database migration required.
- Existing related-context or label helpers may be refactored to produce structured reference outputs instead of final UI strings.