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

# Feature Specification: GUID Context Resolver & Human-Readable Reference Presentation

**Feature Branch**: `132-guid-context-resolver`  
**Created**: 2026-03-10  
**Status**: Draft  
**Input**: User description: "Spec 132 — GUID Context Resolver & Human-Readable Reference Presentation"

## Spec Scope Fields *(mandatory)*

- **Scope**: canonical-view
- **Primary Routes**:
  - Workspace admin governance, findings, snapshot, assignment, and operations pages under `/admin/...`
  - Tenant-context governance and related detail pages under `/admin/t/{tenant}/...`
  - Canonical workspace destinations reached from tenant-context sources, where originating tenant meaning must remain visible through filters, badges, or source-context metadata
  - Assignment-like surfaces already present in the product, including the baseline tenant assignments relation manager and assignment evidence sections on policy-version, finding, and baseline-snapshot views
  - Shared related-context sections and reference-heavy list/detail surfaces that currently expose important IDs as primary text
- **Data Ownership**:
  - Existing workspace-owned governance, operations, backup, and monitoring records remain the source of truth
  - Existing tenant-scoped records and provider-linked identifiers remain unchanged; this feature standardizes how references to them are resolved and presented
  - No new persistent domain model is introduced solely for this feature; the change is a shared presentation and resolution capability layered on top of existing records and source identifiers
- **RBAC**:
  - Workspace membership remains the primary boundary for reference visibility across admin resources
  - Tenant-scope entitlement remains required before showing tenant-context reference detail or navigation
  - Capability checks remain required before rendering actionable navigation to protected related resources
  - Reference presentation must preserve deny-as-not-found behavior for non-members and out-of-scope tenant access

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: When a user enters a canonical workspace-level destination from a tenant-context source, the destination remains authoritative while preserving the originating tenant meaning through visible tenant filters, context badges, or source context metadata where relevant.
- **Explicit entitlement checks preventing cross-tenant leakage**: Reference resolution and rendering must enforce existing workspace membership and tenant-scope entitlements before exposing protected labels, canonical destinations, or context details. Non-members and users outside permitted tenant scope must not receive related-object labels, existence hints beyond allowed degraded states, or actionable links.

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Read referenced objects without decoding IDs (Priority: P1)

As an enterprise operator, I want important referenced objects to display as names and context first so I can understand findings, snapshots, runs, and assignments without manually decoding GUIDs.

**Why this priority**: Reference-heavy screens lose most of their operational value when core objects appear only as opaque identifiers.

**Independent Test**: Can be fully tested by opening a finding, snapshot, or run that includes supported references and verifying that the interface shows human-readable labels, type hints, and secondary technical IDs instead of GUID-first output.

**Acceptance Scenarios**:

1. **Given** a supported reference that resolves to a known internal or provider-backed object, **When** an authorized operator opens an in-scope screen, **Then** the reference displays a human-readable label first, contextual type second, and the technical ID only as secondary detail.
2. **Given** a screen with several different supported reference classes, **When** the operator reviews that screen, **Then** equivalent references follow the same information hierarchy instead of page-specific formatting.

---

### User Story 2 - Understand degraded references safely (Priority: P1)

As an enterprise operator, I want unresolved, deleted, partially known, or inaccessible references to degrade clearly so I can tell what the system knows and what follow-up is needed.

**Why this priority**: Governance and troubleshooting flows break when every failure mode collapses into the same vague “Unknown” text.

**Independent Test**: Can be fully tested by rendering supported references in resolved, partially resolved, missing, and inaccessible states and confirming that each state remains visible, distinct, and non-misleading.

**Acceptance Scenarios**:

1. **Given** a reference whose raw identifier is present but whose target cannot be fully matched, **When** the operator views the record, **Then** the interface keeps the reference visible and marks it as unresolved, partial, missing, or inaccessible using shared vocabulary.
2. **Given** a reference to a protected in-product resource, **When** the current user lacks destination access, **Then** the UI does not present that reference as clickable and does not reveal unauthorized detail beyond the allowed degraded state.

---

### User Story 3 - Navigate from references when allowed (Priority: P2)

As an authorized operator, I want resolved references to link to the correct canonical destination when that destination is meaningful and permitted so I can move from context to action quickly.

**Why this priority**: Once a reference is understandable, the next operator need is fast drill-down to the authoritative related record.

**Independent Test**: Can be fully tested by opening supported references on in-scope screens and verifying that only permitted destinations render as actionable links and that those links use canonical targets.

**Acceptance Scenarios**:

1. **Given** a resolved reference with a valid canonical destination and an entitled user, **When** the reference is rendered, **Then** the destination is clearly actionable and opens the canonical target for that object.
2. **Given** a resolved reference without a meaningful destination or without access, **When** the reference is rendered, **Then** it remains informative but non-clickable.

---

### User Story 4 - Extend the same pattern to future surfaces (Priority: P3)

As a product team member, I want new reference-heavy surfaces to reuse the same reference semantics so the product stops solving ID presentation differently on every page.

**Why this priority**: The platform value comes from consistent reuse, not one-off cleanup on a few screens.

**Independent Test**: Can be fully tested by adding a new supported reference class or a new target surface without rewriting every existing page’s formatting logic.

**Acceptance Scenarios**:

1. **Given** a newly supported reference class, **When** it is added to the shared reference presentation capability, **Then** existing rendering patterns can present it without page-specific reinvention.

### Edge Cases

- A reference may be syntactically valid but point to a record that has been deleted since capture.
- A reference may expose only a fallback label, a broad type, or source metadata, but no canonical target.
- A reference may be known to exist conceptually while the current user is not authorized to open the target record.
- Multiple different reference classes may appear in the same dense list or detail section and must remain readable without excessive visual noise.
- A surface may encounter a supported reference class with insufficient enrichment and must still avoid falling back to GUID-first output when partial context is available.
- A screen may receive an unsupported reference class and must keep the reference visible without breaking the page.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature is a read-oriented presentation and shared semantics improvement. It introduces no new Microsoft Graph calls, no new write/change workflows, and no new long-running or scheduled work. Existing governance, monitoring, backup, assignment, and tenant-linked records remain authoritative. The feature only standardizes how known references are enriched, classified, and rendered on user-facing surfaces.

**Constitution alignment (OPS-UX):** This feature may display existing operation runs as resolved references, but it does not create, mutate, or observe `OperationRun` lifecycle behavior and does not alter toast, progress, or terminal-notification contracts.

**Constitution alignment (RBAC-UX):** This feature affects workspace-admin `/admin` surfaces and tenant-context `/admin/t/{tenant}/...` surfaces that render or link to related records. Cross-plane access remains deny-as-not-found. Non-members and users outside entitled workspace or tenant scope must receive 404 semantics. Members within the correct scope who lack target-resource capability must receive 403 semantics when opening protected destinations. Reference presentation must remain capability-aware and must not use raw capability strings or role-name checks in feature code. At least one positive and one negative authorization test must protect reference visibility and linkability behavior.

**Constitution alignment (OPS-EX-AUTH-001):** Not applicable. No authentication-handshake behavior is introduced.

**Constitution alignment (BADGE-001):** If this feature introduces or standardizes reference-state badges, those states must use centralized semantics and shared vocabulary through the existing badge system, using shared badge-domain mapping and shared badge rendering rather than page-local label/color logic.

**Constitution alignment (UI-NAMING-001):** Operator-facing reference copy must use domain vocabulary such as “Policy,” “Policy version,” “Baseline snapshot,” “Operation run,” “Group,” “User,” and “Role definition” rather than implementation-first ID language. Actions and helper copy must preserve the same object naming across list rows, related-context sections, link labels, and empty or degraded states.

**Constitution alignment (Filament Action Surfaces):** This feature modifies multiple Filament resources and detail pages by standardizing inspect affordances, related-context rows, and view actions for resolved references. The Action Surface Contract remains satisfied because this feature adds read-oriented reference display and navigation only; it introduces no destructive actions.

**Constitution alignment (UX-001 — Layout & Information Architecture):** Modified Filament detail pages must present references in structured read-only sections or rows rather than raw field dumps. View pages remain infolist-first or equivalent read-only presentations. List and table screens continue to support search, sort, and filters for their core dimensions while reference-heavy values adopt the same label-first hierarchy. If a dense table cannot support the detailed reference variant without harming readability, it may use a compact variant that preserves the same meaning order.

### Functional Requirements

- **FR-132-01 Label-first presentation**: For supported reference classes, user-facing screens must not present raw GUIDs, raw IDs, or foreign keys as the primary visible value when a more human-readable label or fallback label is available.
- **FR-132-02 Shared reference capability**: The product must provide one shared reference-resolution and presentation capability that can be reused across multiple surfaces instead of page-specific formatting logic.
- **FR-132-03 Explicit reference classes**: Supported references must be classified into explicit reference classes rather than treated as generic strings.
- **FR-132-04 Initial class coverage**: Initial supported reference classes must cover, where surfaced today, policies, policy versions, baseline profiles, baseline snapshots, operation runs, backup-related artifacts, role definitions, principals, groups, service-principal-style references, and tenant-linked external object references relevant to current domains.
- **FR-132-05 Normalized reference output**: The shared capability must return a normalized presentation result that includes reference class, raw identifier, primary label, secondary context or type label, explicit resolution state, and optional canonical destination.
- **FR-132-06 Consistent hierarchy**: Resolved references must render with the same information order across surfaces: primary label, type or context, state, then technical ID.
- **FR-132-07 Secondary technical detail**: Technical identifiers must remain available for advanced troubleshooting, copying, or support workflows, but only as visually secondary detail.
- **FR-132-08 Distinct degraded states**: The UI must distinguish at minimum between resolved, partially resolved, unresolved, deleted or missing, inaccessible, and external-only limited-context references where those states are materially different.
- **FR-132-09 Safe degradation**: When a reference cannot be fully resolved, the interface must preserve the reference visibly, avoid false confidence, and show the best safe context available.
- **FR-132-10 Partial resolution support**: The product must support partially resolved references that have some useful context, such as fallback label, broad object type, or retained source metadata, even when a full destination or authoritative record is unavailable.
- **FR-132-11 Role-aware linkability**: References may render as actionable only when they have a meaningful canonical destination and the current user is permitted to open it.
- **FR-132-12 No ambiguous clickability**: References without a permitted or meaningful destination must not appear clickable.
- **FR-132-13 Canonical destinations**: When a supported reference links internally, it must use the canonical destination for that resource instead of page-specific ad hoc routes.
- **FR-132-14 No unauthorized disclosure**: Reference presentation must not broaden existence leakage, protected labels, or related-object detail beyond what existing authorization policy permits.
- **FR-132-15 Cross-surface reuse**: The same resolution and presentation semantics must be reusable across baseline snapshots, findings, operation runs, related-context sections, assignments, and equivalent governance artifacts.
- **FR-132-16 Centralized logic**: Pages must not reimplement bespoke “if GUID then format” branches for supported reference classes.
- **FR-132-17 Unsupported-class fallback**: If a reference class is unsupported or no enrichment is available, the page must still render the reference in a safe degraded form instead of failing or hiding it entirely.
- **FR-132-18 Dense-view variants**: The product may use compact and detailed reference variants, but both variants must preserve the same hierarchy and state semantics.
- **FR-132-19 Shared vocabulary**: Reference types and reference states must use a shared display vocabulary across all in-scope screens.
- **FR-132-20 Related-context readability**: Screens that expose many references must remain readable because each rendered reference is self-describing without requiring the operator to leave the page first.
- **FR-132-21 Best-effort enrichment**: The shared capability must support best-effort enrichment from available source context, fallback label, workspace or tenant context, and already-known relations.
- **FR-132-22 Incremental rollout compatibility**: During rollout, the target surfaces named in this spec must fully adopt the new pattern even if out-of-scope screens such as dashboard summary widgets or later inventory/reporting views temporarily still use older formatting.
- **FR-132-22 Incremental rollout compatibility**: During rollout, the target surfaces named in this spec must fully adopt the new pattern even if out-of-scope screens such as dashboard summary widgets or later inventory/reporting views temporarily still use older formatting. This includes tenant-context entry into canonical workspace destinations where originating tenant filters, context badges, or source-context metadata remain visible.
- **FR-132-23 Future extensibility**: Adding a newly supported reference class must not require rewriting all existing page templates or all existing reference renderers.
- **FR-132-24 Baseline snapshot adoption**: Baseline snapshot views and snapshot-related sections must use the shared reference presentation pattern for referenced policies, profiles, runs, and related governance objects in scope.
- **FR-132-25 Findings adoption**: Findings must render referenced policies, snapshots, runs, assignments, principals, and similar related entities using contextual references rather than raw IDs as primary text.
- **FR-132-26 Operation-run adoption**: Operation-run surfaces must render important target and related-object references in the shared human-readable format.
- **FR-132-27 Assignment-like adoption**: The baseline tenant assignments relation manager plus assignment-evidence and assignment-diff views that surface principals, groups, roles, or policy relationships must use the shared reference presentation pattern.
- **FR-132-28 Evidence preservation**: Even in degraded states, raw identifiers must remain available as supporting evidence when operationally useful.

### Non-Goals

- Full cross-resource navigation redesign
- New audit-log features
- Universal raw-payload transformation
- New persistent domain models created solely for reference resolution
- Global search redesign
- External directory synchronization redesign
- A full evidence-viewer redesign
- Changes to capture or snapshot semantics
- Guaranteed full resolution for every arbitrary external identifier

### Assumptions

- Existing records and source payloads already contain enough relationship hints to materially improve how important references are presented on the initial target surfaces.
- Some provider-backed references will remain partially known, and that is acceptable if the degraded state is explicit.
- Operators still need access to technical IDs for support and troubleshooting, but not as the dominant visual language.
- In-scope surfaces can adopt a compact reference variant where dense layouts would otherwise become noisy.

### Dependencies

- Existing workspace and tenant authorization rules
- Existing canonical destinations for supported internal resources
- Existing governance, monitoring, backup, assignment, and provider-linked domain relationships
- Existing display names, fallback labels, or type hints already stored or derivable from source context

## UI Action Matrix *(mandatory when Filament is changed)*

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Findings | Workspace admin list and detail surfaces | None new beyond existing page actions | Reference-heavy columns and related-context rows must use shared label-first rendering | View related record, View run when permitted | None | Existing empty state remains; no new mutation CTA required | View related record, View snapshot or policy when most relevant | N/A | No | Read-only presentation upgrade only; no destructive actions |
| Baseline snapshots | Workspace admin list and detail surfaces | None new beyond existing view actions | Snapshot rows and detail related-context entries use shared reference presentation | View profile, View run when permitted | None | Existing empty state remains | View profile, View policy version when relevant | N/A | No | Snapshot readability is a primary target surface |
| Operation runs | Canonical workspace operations list and detail surfaces | None new beyond existing view actions | Run target and related-object references render label-first | View target record, View related artifact when permitted | None | Existing empty state remains | View related record, View source context when relevant | N/A | No | Links must stay canonical and capability-aware |
| Assignment-like views | Workspace admin and tenant-context assignment or relationship surfaces | None new beyond existing view actions | Principal, group, role, and target references use shared compact rendering in tables and detailed rendering on view pages | View principal or target, View role when permitted | None | Existing empty state remains | View target record, View related policy when relevant | N/A | No | Initial concrete targets are `BaselineTenantAssignmentsRelationManager` plus assignment-evidence sections on policy-version, finding, and baseline-snapshot views; no new mutations, only reference clarity and consistent linking |
| Related-context sections across governance artifacts | View pages under `/admin/...` and `/admin/t/{tenant}/...` | None | Structured related-context rows become the primary inspect affordance for secondary objects | At most the two most relevant permitted related links | None | N/A | Existing page header actions remain authoritative | N/A | No | Exemption: row-action cap may be enforced through section ordering rather than visible button count in some view-only layouts |

### Key Entities *(include if feature involves data)*

- **Reference Descriptor**: The structured description of a user-visible reference, including its class, raw identifier, available context, and any safe fallback label or source metadata.
- **Resolved Reference**: The normalized presentation result for a reference, including its primary label, contextual type, explicit state, technical identifier, and optional canonical destination.
- **Reference State**: The explicit condition of a reference, such as resolved, partially resolved, unresolved, missing, inaccessible, or limited-context external.
- **Reference Presentation Variant**: The compact or detailed rendering pattern that preserves the same meaning order while adapting to list-density or detail-page needs.
- **Canonical Destination**: The authoritative in-product destination for a resolved internal reference when the current user is allowed to navigate to it.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-132-01 Readability improvement on target surfaces**: In acceptance testing for the in-scope target surfaces, supported references are displayed label-first rather than GUID-first in 100% of covered cases.
- **SC-132-02 Distinct degraded states**: In regression tests for degraded-reference scenarios, 100% of covered resolved, partial, unresolved, missing, and inaccessible cases render visibly distinct states instead of collapsing into the same generic label.
- **SC-132-03 Secondary-ID compliance**: In target-surface review, technical IDs remain available as secondary detail for 100% of covered supported reference classes without becoming the primary displayed value.
- **SC-132-04 Canonical-link correctness**: In authorization-aware navigation tests, 100% of covered actionable references open canonical destinations only when the user is permitted to access them.
- **SC-132-05 Reuse across surfaces**: At least the baseline snapshot, findings, operation-run, baseline tenant assignments relation manager, and assignment-evidence target surfaces use the same shared reference semantics without page-specific ad hoc formatting rules for supported classes.
- **SC-132-06 Future extensibility**: In implementation review and regression coverage, adding a new supported reference class requires changes only to the shared reference capability and the intended target surface mappings, not wholesale rewrites of existing page templates.