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.