TenantAtlas/specs/131-cross-resource-navigation/data-model.md

# Data Model: Cross-Resource Navigation & Drill-Down Cohesion

**Feature**: 131-cross-resource-navigation | **Date**: 2026-03-10

## Overview

This feature introduces no new database tables. It adds a shared navigation read model and relation-mapping layer over existing workspace-owned and tenant-owned records.

The design relies on existing persisted entities plus a small set of computed presentation concepts:

1. a navigation matrix defining allowed operator journeys,
2. related-context sections on key detail pages,
3. list-level drill-down actions,
4. canonical destination context for operations and other authoritative pages,
5. explicit unavailable-state handling for missing or unauthorized relations.

## Existing Persistent Entities

### Policy

| Attribute | Type | Notes |
|-----------|------|-------|
| `id` | int | Primary internal policy identity |
| `tenant_id` | int | Tenant ownership boundary |
| `workspace_id` | int | Workspace ownership boundary |
| `display_name` | string nullable | Primary human-readable label for navigation |
| `policy_type` | string | Policy-type hint used in labels and filtered destinations |

**Relationships**:
- has many `PolicyVersion`
- may be referenced by findings, backup items, and operation runs through context or foreign keys

**Usage rules**:
- Parent policy is the default upstream destination from a policy version.
- Policy links must remain tenant-entitlement checked.

### PolicyVersion

| Attribute | Type | Notes |
|-----------|------|-------|
| `id` | int | Primary version identity |
| `policy_id` | int nullable | Parent policy relationship |
| `tenant_id` | int | Tenant ownership boundary |
| `workspace_id` | int | Workspace ownership boundary |
| `version_number` | int or string | Displayed as user-facing version context |
| `captured_at` | timestamp | Useful for evidence-related context |

**Relationships**:
- belongs to `Policy`
- may be referenced from baseline snapshot items or backup items

**Usage rules**:
- Policy version detail must expose parent policy and related snapshot evidence where resolvable.
- When the parent policy cannot be opened, the page must still preserve readable version context.

### BaselineProfile

| Attribute | Type | Notes |
|-----------|------|-------|
| `id` | int | Primary workspace-owned baseline profile identity |
| `workspace_id` | int | Workspace ownership boundary |
| `name` | string | Primary label |
| `status` | string | Badge-backed profile state |
| `capture_mode` | string | Useful supporting context on related pages |

**Relationships**:
- has many `BaselineSnapshot`
- may be indirectly referenced by findings and operation runs

**Usage rules**:
- Baseline profile is the primary upstream destination from a baseline snapshot.
- Baseline profile links are workspace-authorized, not tenant-authorized.

### BaselineSnapshot

| Attribute | Type | Notes |
|-----------|------|-------|
| `id` | int | Primary snapshot identity |
| `workspace_id` | int | Workspace ownership boundary |
| `baseline_profile_id` | int | Owning baseline profile |
| `captured_at` | timestamp | Primary temporal context |
| `summary_jsonb` | jsonb | Existing summary and fidelity metadata |

**Relationships**:
- belongs to `BaselineProfile`
- may reference policy versions and source operation runs through existing summary or evidence metadata
- may be linked to related findings

**Usage rules**:
- Snapshot detail must expose owning profile, source run, and related findings where meaningful and authorized.
- Snapshot remains workspace-owned even when it refers to tenant evidence.

### Finding

| Attribute | Type | Notes |
|-----------|------|-------|
| `id` | int | Primary finding identity |
| `tenant_id` | int | Tenant ownership boundary |
| `workspace_id` | int | Workspace ownership boundary |
| `finding_type` | string | Used for operator context and prioritization |
| `subject_display_name` | string nullable | Existing human-readable subject label |
| `baseline_operation_run_id` | int nullable | Existing related operations link |
| `current_operation_run_id` | int nullable | Existing related operations link |
| `evidence_jsonb` | jsonb | Existing source-evidence context |

**Relationships**:
- may point to baseline snapshots, policy versions, policies, inventory items, and runs through evidence metadata and explicit IDs

**Usage rules**:
- Findings are high-priority drill-down surfaces and must not degrade into raw IDs when source evidence is resolvable.
- Findings remain tenant-authorized even when they link to workspace-owned baseline records.

### BackupSet

| Attribute | Type | Notes |
|-----------|------|-------|
| `id` | int | Primary backup set identity |
| `tenant_id` | int | Tenant ownership boundary |
| `workspace_id` | int | Workspace ownership boundary |
| `name` | string | Primary operator label |
| `status` | string | Existing badge-backed lifecycle state |
| `item_count` | int | Supporting list context |

**Relationships**:
- has many backup items
- may be referenced by operation-run context and restore flows

**Usage rules**:
- Backup set pages should expose related operation runs or resulting artifacts when available.
- Backup-related navigation must stay consistent with canonical operations routing.

### OperationRun

| Attribute | Type | Notes |
|-----------|------|-------|
| `id` | int | Canonical run identity |
| `workspace_id` | int | Workspace ownership boundary |
| `tenant_id` | int nullable | Nullable for some workspace-level operations |
| `type` | string | Operation type driving related destinations |
| `status` | string | Existing run status badge |
| `outcome` | string nullable | Existing outcome badge |
| `context` | json/jsonb | Existing target-resource and workflow metadata |

**Relationships**:
- may point to policies, backup sets, restore runs, baseline compare destinations, and other domain records via context

**Usage rules**:
- `OperationRun` is the canonical operational drill-down target.
- Related domain links should be generated from run context only when target authorization can be proven.

## New Computed Read Models

### NavigationMatrixRule

| Field | Type | Description |
|------|------|-------------|
| `source_type` | string | Resource or page type that owns the navigation surface |
| `source_surface` | string enum | `detail_section`, `detail_header`, `list_row`, `canonical_list` |
| `relation_key` | string | Stable semantic relation identifier, e.g. `source_run`, `parent_policy` |
| `target_type` | string | Destination resource or page type |
| `target_mode` | string enum | `direct_record`, `filtered_list`, `canonical_page` |
| `label` | string | Shared operator-facing action or entry label |
| `priority` | int | Lower number = higher visibility priority |
| `requires_capability_check` | bool | Whether actionability depends on explicit authorization |
| `missing_state_policy` | string enum | `hide`, `show_unavailable`, `show_reference_only` |

**Rules**:
- Every in-scope relationship in the spec’s navigation matrix maps to one rule.
- Rules choose only one canonical destination for the same operator task.

### RelatedContextSection

| Field | Type | Description |
|------|------|-------------|
| `title` | string | Usually `Related context` or a narrow equivalent |
| `entries` | list<RelatedContextEntry> | Ordered related records for the current page |
| `primary_entry_key` | string nullable | Optional marker for the most likely next step |
| `empty_message` | string nullable | Optional empty-state copy when no related entries are available |

**Rules**:
- Detail pages should render one structured section rather than scattering relation fields.
- Entries are ordered by operator relevance, not by storage order.

### RelatedContextEntry

| Field | Type | Description |
|------|------|-------------|
| `key` | string | Stable identifier such as `source_run` or `baseline_profile` |
| `label` | string | User-facing relation label |
| `value` | string | Human-readable related object label |
| `secondary_value` | string nullable | Optional technical ID or context hint |
| `target_url` | string nullable | Drill-down destination when actionable |
| `target_kind` | string | Resource or canonical page type |
| `availability` | string enum | `available`, `missing`, `unauthorized`, `unresolved` |
| `unavailable_reason` | string nullable | User-safe explanation when not actionable |
| `context_badge` | string nullable | Optional workspace, tenant, or type hint |

**Rules**:
- `value` should favor human-readable labels over raw IDs.
- Technical identifiers may appear only as secondary supporting context.

### DrillDownAction

| Field | Type | Description |
|------|------|-------------|
| `label` | string | Shared operator-facing action label |
| `url` | string | Target destination |
| `placement` | string enum | `row_action`, `header_action`, `inline_entry`, `grouped_action` |
| `priority` | int | Governs whether it appears inline or only in grouped context |
| `target_kind` | string | Destination type |
| `visible` | bool | Whether action should be rendered at all |
| `disabled_reason` | string nullable | Optional tooltip or unavailable-state explanation |

**Rules**:
- No more than the highest-priority actions should remain visibly inline on list rows.
- Actions to canonical operations pages must resolve through the canonical helper layer.

### CanonicalNavigationContext

| Field | Type | Description |
|------|------|-------------|
| `workspace_id` | int | Active workspace scope |
| `tenant_id` | int nullable | Originating tenant context if preserved |
| `source_surface` | string | Resource or page that launched the navigation |
| `canonical_route_name` | string | Authoritative destination route name |
| `filter_payload` | array | Context-preserving query or filter state |
| `back_link_label` | string nullable | Explicit return path label |

**Rules**:
- Canonical route identity must remain stable even when tenant context is preserved.
- This model is especially important for operations and monitoring surfaces.

### UnavailableRelationState

| Field | Type | Description |
|------|------|-------------|
| `relation_key` | string | Relation that could not be resolved |
| `reference_value` | string nullable | Technical identifier or fallback reference |
| `reason` | string enum | `missing`, `deleted`, `unauthorized`, `unresolved` |
| `message` | string | User-facing explanation |
| `show_reference` | bool | Whether the secondary reference is safe to display |

**Rules**:
- Unauthorized states must not disclose more than existing access rules allow.
- Missing and unresolved states must preserve surrounding page usability and layout.

## Validation Rules

| Rule | Result |
|------|--------|
| Every in-scope relationship resolves through one explicit navigation-matrix rule | Required |
| Canonical run destinations always use the tenantless operations route family | Required |
| Non-members receive 404 semantics for target resources | Required |
| In-scope members lacking capability may see disabled or unavailable context, but target execution still fails with 403 | Required |
| Related-context entries show human-readable labels first and technical IDs second | Required |
| List-level drill-down actions remain limited to the highest-priority operator journeys | Required |
| Missing or unresolved relations render clear unavailable states without broken links | Required |

## Schema Impact

No schema migration is expected for this feature.