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.