TenantAtlas/specs/136-admin-canonical-tenant/data-model.md

Data Model: Spec 136 Admin Panel Canonical Tenant Resolution Full Rollout

Overview

This feature introduces no new database tables or persisted business objects. Its data model is request-time and behavioral: it formalizes how surface classification, panel mode, canonical admin tenant context, session-backed filter state, and sensitive actions combine into one deterministic tenant outcome.

Entity: Surface Inventory Entry

Purpose: Represents one admin-visible or admin-reachable surface in the rollout manifest.

Fields:

• surface_name
• class_name
• surface_kind enum: resource, page, widget, shared_helper, guarded_file
• classification enum: type_a, type_b, type_c
• visibility_mode enum: admin_visible, shared_code_path, tenant_panel_only_but_reviewed
• has_persisted_tenant_filters boolean
• has_global_search boolean
• has_sensitive_actions boolean
• guard_required boolean

Relationships:

• may reference one resource, page, or widget class
• may depend on one or more support-layer resolver or filter-state helpers

Validation rules:

• Every rollout surface must have exactly one classification.
• Type A and Type B surfaces must be guard-covered unless explicitly documented as an exception.
• Type C surfaces must not acquire hidden tenant enforcement in read or write paths.

Entity: Canonical Admin Tenant Context

Purpose: Represents the single tenant context used by workspace-admin tenant-sensitive flows.

Source fields:

• workspace_id
• panel_id
• route_tenant_id nullable
• filament_tenant_id nullable
• remembered_tenant_id nullable
• resolved_tenant_id nullable
• resolution_source enum: route, filament, remembered, none
• is_entitled boolean

Relationships:

• belongs to one current workspace
• may resolve to one entitled tenant
• drives header context, queries, filter defaults, widgets, links, and sensitive actions for Type A and Type B admin surfaces

Validation rules:

• resolved_tenant_id must be null when no entitled tenant exists.
• The same resolved tenant must drive every tenant-sensitive element of the same admin surface.
• When the panel is admin, raw panel-native tenant reads are not valid substitutes for this entity.

Entity: Panel Resolver Contract

Purpose: Encodes which resolver is allowed in a given panel mode.

Fields:

• panel_id
• allowed_source enum: operate_hub_shell, filament_tenant, none
• fallback_behavior enum: remembered_allowed, no_fallback, safe_none
• applies_to enum: admin, tenant, shared_surface

Validation rules:

• Admin panel uses operate_hub_shell.
• Tenant panel uses filament_tenant.
• Shared surfaces must branch by current panel rather than blending both rules.

Entity: Persisted Tenant Filter Session State

Purpose: Represents session-backed filter state whose validity depends on the current canonical admin tenant.

Fields:

• filters_session_key
• tenant_sensitive_filters array
• previous_resolved_tenant_id nullable
• current_resolved_tenant_id nullable
• resolution_action enum: apply, reseed, clear
• has_invalid_values boolean

Relationships:

• belongs to one table or page surface
• depends on one Canonical Admin Tenant Context

Validation rules:

• Tenant-sensitive filter values must be cleared or reseeded when resolved tenant changes.
• If current_resolved_tenant_id is null, tenant-specific filter state must not remain active.
• Workspace-wide Type B surfaces may preserve non-tenant filters while clearing or reseeding tenant-specific ones.

Entity: Sensitive Action Scope Contract

Purpose: Represents the tenant parity requirement between visible surface context and a sensitive action target.

Fields:

• surface_name
• action_name
• visible_tenant_id nullable
• query_tenant_id nullable
• action_tenant_id nullable
• authorization_outcome enum: ok, not_found, forbidden
• confirmation_required boolean

Relationships:

• belongs to one rollout surface
• depends on one resolved tenant context and one authorization decision

Validation rules:

• action_tenant_id must equal visible_tenant_id for Type A surfaces.
• Out-of-scope or missing tenant access must remain not_found when membership is not established.
• Existing destructive-like actions must still require confirmation and server-side authorization.

Entity: Search and Record Resolution Contract

Purpose: Represents list, detail, deep-link, and global-search parity for tenant-sensitive resources.

Fields:

• surface_name
• access_path enum: list, detail, direct_url, deep_link, global_search
• panel_mode enum: admin, tenant
• resolved_tenant_id nullable
• record_tenant_id nullable
• parity_outcome enum: aligned, disabled, not_found, forbidden

Validation rules:

• Detail and direct access must never be broader than list scope.
• Global search must either match list/detail parity or be disabled.
• Admin no-context behavior must be explicit and deterministic per surface class.

Entity: Guard Coverage Entry

Purpose: Documents whether a file is enforced by the admin tenant resolver guard or allowed as an exception.

Fields:

• relative_path
• surface_name
• guard_status enum: guarded, exception
• exception_reason nullable
• review_owner

Validation rules:

• Exceptions must be explicit and stable.
• Admin-only files are not valid exceptions for raw Filament::getTenant() or Tenant::current() reads.
• Guard output must clearly distinguish true violations from approved tenant-panel-native usage.

State Transitions

Canonical admin tenant state

1. none

• No entitled route, Filament, or remembered tenant is available.
• Outcome: safe no-tenant-selected behavior by surface type.

2. remembered

• Only remembered tenant is valid and entitled.
• Outcome: remembered tenant becomes the canonical admin tenant for the full request.

3. filament

• A Filament tenant is valid and entitled.
• Outcome: Filament tenant becomes the canonical admin tenant for the full request.

4. route

• A route tenant parameter is present and entitled for a tenant-panel or shared route.
• Outcome: route tenant governs the request where panel-native semantics apply.

Persisted filter synchronization state

1. unchanged

• Previous and current resolved tenant IDs match.
• Outcome: persisted tenant filter values may remain.

2. tenant_switched

• Previous and current resolved tenant IDs differ.
• Outcome: tenant-sensitive filter values are cleared or reseeded.

3. tenant_removed

• Current resolved tenant ID becomes null.
• Outcome: tenant-sensitive filter values are cleared.

Invariants

• One workspace-admin surface uses one tenant source for every tenant-sensitive element.
• Shared resources must branch by panel mode instead of mixing admin and tenant rules inside one execution path.
• Persisted tenant filter state is never trusted without synchronization.
• Search, list, detail, and deep-link behavior cannot exceed the same tenant boundary.
• Existing destructive or governance-sensitive actions keep their confirmations and authorization while gaining tenant-target parity.