TenantAtlas/specs/135-canonical-tenant-context-resolution/data-model.md

# Data Model: Spec 135 Canonical Tenant Context Resolution

## Overview

This feature introduces no new database tables or persisted domain objects. Its data model is request-time and behavioral: it formalizes how existing workspace, tenant, filter, and record-access state combine into one canonical tenant-context outcome.

## Entity: Tenant Panel Context

**Purpose**: Represents the panel-native tenant context for tenant-panel flows.

**Source fields**:
- `panel_id`
- `tenant_route_parameter`
- `filament_tenant`
- `tenant_membership_status`

**Relationships**:
- belongs to one current panel
- resolves to one entitled tenant or null

**Validation rules**:
- Only valid on tenant-panel-native surfaces.
- Must not be substituted with admin remembered-tenant fallback semantics.
- Non-members must receive deny-as-not-found behavior.

## Entity: Admin Operational Tenant Context

**Purpose**: Represents the canonical active tenant for workspace-admin flows.

**Source fields**:
- `workspace_id`
- `filament_tenant_id` nullable
- `remembered_tenant_id` nullable
- `resolved_tenant_id` nullable
- `resolution_source` enum: `filament`, `remembered`, `none`
- `is_entitled` boolean

**Relationships**:
- belongs to one current workspace
- may resolve to one tenant in that workspace
- is used by headers, widgets, filters, queries, record links, and search

**Validation rules**:
- `resolved_tenant_id` must be null when no entitled tenant exists.
- If both `filament_tenant_id` and `remembered_tenant_id` exist and disagree, `filament_tenant_id` wins.
- Any resolved tenant must belong to the active workspace and pass tenant entitlement.

## Entity: Tenant Context Conflict

**Purpose**: Captures the request state where more than one tenant source exists for the same admin request.

**Fields**:
- `filament_tenant_id`
- `remembered_tenant_id`
- `workspace_id`
- `winning_source`
- `losing_source`

**Validation rules**:
- Conflict only exists when both source values are present and different.
- Conflict resolution must be deterministic for the entire request.
- Losing source must not leak into filters, widgets, counts, or navigation labels.

## Entity: Tenant-Sensitive Filter State

**Purpose**: Represents persisted or defaulted filter state whose valid values depend on the canonical tenant context.

**Fields**:
- `filter_name`
- `raw_value`
- `canonical_tenant_id` nullable
- `workspace_id`
- `is_valid_for_context` boolean
- `resolution_action` enum: `apply`, `reset`, `ignore`, `replace`

**Relationships**:
- belongs to one request flow
- may constrain one resource list or widget drill-down

**Validation rules**:
- Filter values must be revalidated whenever canonical tenant context changes.
- Filter option lists must never be broader than the underlying list/query scope.
- Invalid persisted tenant-sensitive values must not silently remain active after a tenant switch.

## Entity: Scoped Record Access Path

**Purpose**: Represents any route or UI affordance that can reveal a tenant-sensitive record.

**Fields**:
- `surface_type` enum: `list`, `detail`, `direct_url`, `deep_link`, `global_search`
- `resource_name`
- `workspace_id`
- `canonical_tenant_id` nullable
- `record_tenant_id` nullable
- `authorization_outcome` enum: `ok`, `not_found`, `forbidden`

**Relationships**:
- points to one resource class and optional record
- uses one context resolver appropriate to its panel

**Validation rules**:
- Detail/direct/search access must never be broader than the corresponding list scope.
- Out-of-scope or missing-context access must produce deterministic bounded behavior.
- Membership failures remain `not_found`; capability failures after membership is established remain `forbidden`.

## Entity: Admin Surface Guardrail Exception

**Purpose**: Documents files that are allowed to use panel-native tenant reads without violating the admin guardrail.

**Fields**:
- `file_path`
- `reason`
- `panel_semantics` enum: `tenant_native`, `approved_panel_native_surface`
- `review_owner`

**Validation rules**:
- Every exception must be explicit and stable.
- Admin-only files are not valid exceptions.
- Guardrail output must clearly distinguish violations from approved exceptions.

## State Transitions

### Admin request context state

1. `no_context`
   - No valid Filament tenant and no valid remembered tenant.
   - Outcome: safe empty/not-found bounded behavior.

2. `remembered_only`
   - No valid Filament tenant, valid remembered tenant.
   - Outcome: remembered tenant becomes canonical admin tenant.

3. `filament_only`
   - Valid Filament tenant, no remembered tenant.
   - Outcome: Filament tenant becomes canonical admin tenant.

4. `conflict`
   - Valid Filament tenant and valid remembered tenant differ.
   - Outcome: Filament tenant wins for the full request.

## Invariants

- Tenant-panel-native files use panel-native tenant semantics.
- Workspace-admin files use the canonical admin resolver when resolving an operational tenant.
- Visible tenant context and effective query scope must always match within the same request.
- Persisted tenant-sensitive filter state is never trusted without revalidation.
- Direct record URLs and search results cannot bypass the same tenant boundary as the list surface.