TenantAtlas/specs/147-tenant-selector-remembered-context-enforcement/data-model.md

# Data Model: Tenant Selector and Remembered Context Enforcement

## Overview

This feature does not introduce a new persistence model. It formalizes how existing workspace, tenant, route, and remembered-context concepts interact at the shell and routing layers.

## Entities

### 1. Workspace Context

**Represents**: The primary operating boundary for the current admin session.

**Key fields**:
- `workspace_id`
- `workspace.slug`
- `workspace.archived_at`

**Relationships**:
- Owns many tenants
- Owns many canonical workspace records such as operation runs
- Owns one session-scoped remembered tenant preference map entry per user session

**Validation rules**:
- Must exist
- Must not be archived for active selection
- Actor must be a workspace member or the request resolves as deny-as-not-found

### 2. Tenant

**Represents**: A workspace-owned tenant record that may be active, onboarding, draft, or archived.

**Key fields**:
- `id`
- `workspace_id`
- `external_id`
- `status`
- `deleted_at`
- operator-facing identity fields such as `name`, `domain`, `environment`

**Relationships**:
- Belongs to one workspace
- May be a route subject on tenant-bound pages
- May be referenced by canonical workspace records such as operation runs
- May be persisted as remembered active-lane context only when selector-eligible

**Validation rules**:
- For standard active selector use, tenant must belong to current workspace, remain entitled to the actor, exist, and satisfy active-lane eligibility
- For tenant-bound route validity, tenant must satisfy workspace and entitlement checks; selector eligibility is not required

### 3. Remembered Tenant Context

**Represents**: A workspace-scoped user/session preference for the last active-lane tenant.

**Key fields**:
- `workspace_last_tenant_ids[workspace_id]` session entry
- optional persisted recency signals through `users.last_tenant_id` or `user_tenant_preferences.last_used_at`

**Relationships**:
- Belongs logically to one workspace context
- References one tenant candidate for active-lane convenience

**Validation rules**:
- Must only be read inside an established workspace context
- Must resolve to an existing tenant in the current workspace
- Must satisfy entitlement-sensitive access checks
- Must satisfy active-lane eligibility checks
- Invalid values must be cleared or ignored deterministically

### 4. Active Selector Option

**Represents**: A tenant that is eligible to appear in the standard active tenant selector.

**Derived from**:
- `TenantOperabilityDecision.canSelectAsContext`

**Required attributes**:
- tenant identity
- lifecycle presentation
- selector-safe label and helper copy

**Validation rules**:
- Must not include `draft`, `onboarding`, or `archived` tenants under the current lifecycle model
- Must not include tenants outside the current workspace
- Must not include tenants the actor cannot access

### 5. Route Subject

**Represents**: The record made authoritative by the current route.

**Variants**:
- tenant-bound route subject: `Tenant`
- canonical workspace record subject: `OperationRun` or other workspace-owned records

**Validation rules**:
- Route subject legitimacy is resolved from route record identity plus policy checks
- Remembered tenant context may influence convenience UI only and must not replace route authority

## Derived Domain Objects

### Tenant Operability Decision

**Represents**: The existing lifecycle-aware rule set produced by `TenantOperabilityService`.

**Relevant flags for this feature**:
- `canSelectAsContext`
- `canViewTenantSurface`
- `canReferenceInWorkspaceMonitoring`

### Shell Context Resolution Result

**Represents**: The runtime decision for what tenant, if any, the shell should treat as active convenience context.

**Possible states**:
- `route_authoritative_tenant`
- `validated_selected_tenant`
- `no_selected_tenant`
- `stale_context_cleared`

## State Transitions

### Remembered Tenant Context Lifecycle

1. `unset`
   - No remembered tenant exists for the current workspace.
2. `remembered_active`
   - An active-lane-eligible tenant is selected and stored for the current workspace.
3. `revalidated_active`
   - A later request reads the remembered tenant and confirms workspace match, entitlement, existence, and selector eligibility.
4. `invalidated_cleared`
   - A later request detects stale or ineligible remembered tenant context and clears or ignores it.
5. `no_selected_tenant`
   - The shell falls back to a legitimate workspace-level no-tenant state.

**Invalidation triggers**:
- workspace switch
- tenant no longer exists
- tenant no longer belongs to current workspace
- tenant no longer satisfies active-lane eligibility
- actor no longer has tenant entitlement where required

### Page Semantics By Category

#### Workspace-level page
- Accepts `remembered_active`, `invalidated_cleared`, or `no_selected_tenant`
- Selected tenant may become a filter only

#### Tenant-bound page
- Route tenant is authoritative
- Selected tenant may match, differ, or be absent

#### Canonical workspace record viewer
- Route record is authoritative
- Referenced tenant may differ from selected tenant without invalidating the page

## Invariants

- Workspace is always the primary context boundary.
- Remembered tenant context never broadens authorization.
- Standard selector membership never implies universal tenant discoverability.
- Route legitimacy always outranks selected tenant context.
- No-selected-tenant is a valid workspace shell state.