# Feature Specification: Tenant Lifecycle, Operability, and Context Semantics Foundation

**Feature Branch**: `143-tenant-lifecycle-operability-context-semantics`  
**Created**: 2026-03-14  
**Status**: Draft  
**Input**: User description: "Structural review of tenant lifecycle inconsistencies across onboarding, tenant context selection, operation viewing, action availability, status rendering, and authorization semantics."

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace + tenant-bound + canonical workspace record viewers
- **Primary Routes**:
  - `/admin`
  - `/admin/choose-workspace`
  - `/admin/choose-tenant`
  - `/admin/tenants`
  - `/admin/tenants/{tenant}`
  - `/admin/onboarding`
  - `/admin/onboarding/{onboardingDraft}`
  - `/admin/operations`
  - `/admin/operations/{run}`
- **Data Ownership**:
  - Workspaces remain the primary operating boundary.
  - Tenants remain workspace-owned records.
  - Onboarding drafts and sessions remain workspace-scoped workflow records that may link to a tenant.
  - Operation runs remain canonical workspace-owned records that may reference a tenant.
  - This feature does not introduce cross-workspace sharing or change underlying ownership boundaries.
- **RBAC**:
  - Authorization planes involved: tenant/admin `/admin` and tenant-context behavior within the admin plane.
  - Workspace non-members and users without tenant entitlement for a tenant-bound record receive deny-as-not-found semantics.
  - Workspace members lacking the required capability for an otherwise visible action receive forbidden semantics.
  - Authorization decisions must come from workspace membership, tenant entitlement, capability policy checks, and page semantics, not from remembered tenant context.

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: Workspace-scoped indexes may prefilter to the currently selected tenant as a convenience, but the filter is optional state and must never determine whether a canonical workspace-owned record is legitimate.
- **Explicit entitlement checks preventing cross-tenant leakage**: Canonical record viewers must verify workspace ownership of the record, tenant reference ownership where applicable, and actor entitlement to the workspace and referenced tenant before rendering any tenant-linked details.

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Trust Canonical Record Views (Priority: P1)

As a workspace operator, I need deep links to canonical workspace records such as operation runs to remain valid even when my remembered tenant context points at another tenant, so that I can investigate work reliably without false not-found errors.

**Why this priority**: Broken run viewers undermine operator trust fastest because they make valid records appear missing and block investigation during real incidents.

**Independent Test**: Can be fully tested by opening a valid operation run while a different tenant is selected and confirming the page still renders the run, authorizes correctly, and explains any tenant-context mismatch without breaking navigation.

**Acceptance Scenarios**:

1. **Given** a user is authorized for a workspace operation run linked to tenant A, **When** the user opens the run while tenant B is selected in the header, **Then** the run viewer remains accessible and the mismatch is handled as context information rather than record invalidity.
2. **Given** a user is not entitled to the workspace or linked tenant of a canonical record, **When** the user opens the deep link, **Then** the system responds with deny-as-not-found behavior and does not leak tenant identity.

---

### User Story 2 - Select Only Operable Tenants (Priority: P2)

As a workspace operator, I need the standard tenant selector and choose-tenant flow to show only normal operating tenants, so that selecting a tenant never puts me into an invalid or misleading operating context.

**Why this priority**: Tenant selection is a top-level navigation action. If the selector offers ineligible tenants, every downstream page becomes harder to reason about.

**Independent Test**: Can be fully tested by preparing tenants in `draft`, `onboarding`, `active`, and `archived` states and verifying that only `active` tenants appear as selectable normal context while non-active tenants remain visible in the correct management or onboarding surfaces.

**Acceptance Scenarios**:

1. **Given** a workspace contains tenants in all canonical lifecycle states, **When** the user opens the normal tenant selector, **Then** only `active` tenants are available for selection.
2. **Given** a workspace contains onboarding and archived tenants, **When** the user visits onboarding or administrative management surfaces, **Then** those tenants remain visible with lifecycle-appropriate affordances instead of disappearing from the product.

---

### User Story 3 - Understand Lifecycle and Actions Clearly (Priority: P3)

As a workspace operator, I need tenant statuses and lifecycle actions to be labeled consistently with actual domain behavior, so that I can tell whether a tenant is operable, resumable, archivable, or audit-only without interpreting hidden rules.

**Why this priority**: Clear status and action language prevents operator error and creates a stable base for future governance, audit, and customer-facing read-only features.

**Independent Test**: Can be fully tested by reviewing in-scope tenant surfaces and confirming that every valid lifecycle renders explicitly, that archive-like actions are labeled as archive, and that ineligible actions are not shown for the current lifecycle.

**Acceptance Scenarios**:

1. **Given** a tenant is in `onboarding`, **When** the user views management surfaces, **Then** the tenant is labeled as onboarding, may expose resume-onboarding behavior if authorized, and is not presented as a normal active tenant context.
2. **Given** a tenant is in `archived`, **When** the user views tenant management surfaces, **Then** the tenant is clearly labeled archived, excluded from normal active selection, and limited to audit or restore-oriented actions when authorized.

### Edge Cases

- What happens when a remembered tenant was previously `active` but has since become `archived` or `onboarding`? The remembered context must be cleared or ignored for active-context behavior without breaking workspace-scoped pages.
- How does the system handle a canonical workspace record that references an archived tenant? The record remains viewable if authorization allows it, and the tenant reference is shown with archived semantics instead of causing a false not-found.
- What happens when a canonical workspace record has no tenant reference at all? The record remains valid within its workspace scope and must not depend on tenant context.
- How does the system handle a tenant lifecycle transition while an operator is already on a tenant-bound page? The page remains governed by route record legitimacy, but actions and status presentation must refresh to the new lifecycle semantics.
- What happens when onboarding workflow data exists for a tenant that is no longer eligible for onboarding resume? The tenant remains viewable in management surfaces, but resume affordances are suppressed unless operability rules explicitly allow them.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature does not introduce new Microsoft Graph calls, new outbound write behavior, or new queued work. It defines the semantic rules that this implementation slice and any later follow-up implementation specs must apply when lifecycle-driven actions, onboarding continuation, or canonical record viewing touch audit, authorization, or run observability.

**Constitution alignment (OPS-UX):** This feature does not create a new `OperationRun` type. It does define that operation-run viewers are canonical workspace record viewers whose legitimacy must be based on the run, workspace, and entitlement checks rather than remembered tenant context. This implementation slice and any later follow-up implementation that reuses an `OperationRun` must preserve the existing three-surface feedback contract and service-owned status transitions.

**Constitution alignment (RBAC-UX):** This feature changes authorization semantics in the admin plane by separating selector preference from authorization truth. It requires deny-as-not-found behavior for users lacking workspace membership or tenant entitlement, forbidden behavior for users who are members but lack the required capability, server-side enforcement through central policies or authorization services, canonical capability registry usage instead of raw strings, non-member-safe global search behavior, and confirmation on destructive actions introduced by follow-up specs. Validation must include at least one positive and one negative authorization scenario for canonical viewers and tenant-bound surfaces.

**Constitution alignment (OPS-EX-AUTH-001):** This feature does not alter authentication handshakes or allow synchronous login-path behavior to substitute for Monitoring or Operations semantics.

**Constitution alignment (BADGE-001):** This feature requires tenant lifecycle badges to be centrally defined and exhaustive so that `draft`, `onboarding`, `active`, and `archived` never fall through to ad hoc `Unknown` rendering.

**Constitution alignment (UI-NAMING-001):** This feature standardizes operator vocabulary for lifecycle actions and views. Target objects are tenant records and canonical workspace records. Primary verbs are `Archive`, `Restore`, `Resume onboarding`, and `View`. Source disambiguation is only added when needed to distinguish workspace-level record viewers from tenant context. The same lifecycle language must be preserved across table actions, modals, notifications, run viewers, and audit prose.

**Constitution alignment (Filament Action Surfaces):** This feature changes behavior expectations for Filament tenant-management and operations surfaces. The matrix below defines the exact action inventories for the surfaces changed in this implementation slice. Later follow-up specs may extend the same rules to additional screens, but the surfaces listed below are fully in scope now.

**Constitution alignment (UX-001 — Layout & Information Architecture):** This feature defines information architecture semantics rather than a full layout redesign. The current implementation slice must preserve UX-001 on each affected Filament page while applying the lifecycle, operability, and context rules defined here.

### Functional Requirements

- **FR-001**: The system MUST treat `draft`, `onboarding`, `active`, and `archived` as the only canonical tenant lifecycle states within this feature scope.
- **FR-002**: The system MUST define tenant lifecycle as a domain concept separate from tenant operability and separate from tenant context visibility.
- **FR-003**: The system MUST establish a central operability model that decides whether a tenant is viewable, selectable as tenant context, operable for a given action, archivable, restorable, resumable for onboarding, and referenceable in workspace monitoring.
- **FR-004**: The standard tenant selector and choose-tenant flow MUST allow only `active` tenants to become the normal remembered tenant context.
- **FR-005**: `draft` and `onboarding` tenants MUST remain visible in onboarding and administrative management surfaces where the operator needs to create, resume, inspect, or govern onboarding work.
- **FR-006**: `archived` tenants MUST be excluded from normal tenant selection and shown only in administrative, audit, recovery, or other explicitly allowed surfaces.
- **FR-007**: The remembered tenant context MUST be treated as convenience state rather than an authorization primitive or truth source for route legitimacy.
- **FR-008**: When a remembered tenant is no longer eligible for normal active context, the system MUST clear or ignore that remembered value for active-context behavior without breaking workspace-scoped routes.
- **FR-009**: Canonical workspace-level record viewers, including operation runs, MUST resolve access based on the record, workspace relationship, actor entitlement, and referenced tenant entitlement where applicable, and MUST NOT require the referenced tenant to match the currently remembered tenant.
- **FR-010**: Tenant-bound pages MUST resolve legitimacy from the route tenant, workspace relationship, entitlement checks, and page semantics rather than from current header selection.
- **FR-011**: Lifecycle-related actions MUST use labels that accurately describe their behavior, including `Archive`, `Restore`, and `Resume onboarding`, and MUST NOT use misleading labels such as `Deactivate` for archive behavior.
- **FR-012**: The system MUST provide centralized lifecycle presentation so every valid lifecycle renders with explicit label and consistent badge semantics across in-scope surfaces.
- **FR-013**: Authorization for workspace and tenant surfaces MUST distinguish deny-as-not-found for non-members or non-entitled actors from forbidden for members lacking a required capability.
- **FR-014**: Onboarding workflow records and tenant lifecycle records MUST remain distinct but linked, with workflow progression owned by onboarding records and durable lifecycle semantics owned by the tenant record.
- **FR-015**: New or changed code in scope MUST NOT introduce additional ad hoc lifecycle checks where central lifecycle, operability, or presentation rules are required.
- **FR-016**: The product MUST classify affected pages as workspace-scoped pages, tenant-bound pages, onboarding workflow pages, or canonical workspace-level record viewers, and apply lifecycle and context rules according to that page type.
- **FR-017**: Lifecycle transitions and lifecycle-driven action semantics MUST remain auditable and unambiguous so future audit consumers can distinguish onboarding, active, and archived behavior without inference.

## UI Action Matrix *(mandatory when Filament is changed)*

If this feature adds/modifies any Filament Resource / RelationManager / Page, fill out the matrix below.

For each surface, list the exact action labels, whether they are destructive (confirmation? typed confirmation?),
RBAC gating (capability + enforcement helper), and whether the mutation writes an audit log.

| 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 |
|---|---|---|---|---|---|---|---|---|---|---|
| Tenant selector / context chooser | `/admin`, `/admin/choose-tenant` | None beyond selector affordance | Tenant name and lifecycle label | `Select Tenant` for `active` only | None | `View Managed Tenants` when no active tenant is selectable | None | Not applicable | No direct mutation | Current slice defines exact chooser behavior; onboarding and archived tenants are visible only through management routes, not selectable here. |
| Managed tenants index | `/admin/tenants` | `Create Tenant` when already available, plus `Start Onboarding` when the surface already exposes onboarding entry | Linked tenant row inspection via row click | Visible actions are `Resume onboarding` when resumable and one lifecycle action from `Archive` or `Restore` when valid; any additional actions move into `More` | None in this slice | `Create Tenant` and `Start Onboarding` | `Archive`, `Restore`, `Resume onboarding`, and `View related onboarding` when valid | Save and cancel semantics unchanged | Yes for lifecycle mutations | `Archive` and `Restore` are destructive-like and must require confirmation. |
| Tenant detail page | `/admin/tenants/{tenant}` | None added by this slice | Route-record view | None beyond route-record inspection | None | Not applicable | `Archive`, `Restore`, `Resume onboarding`, and `View related onboarding` when valid | Save and cancel semantics unchanged where edit exists | Yes for lifecycle mutations | Route legitimacy comes from the route tenant, not remembered header context. |
| Onboarding workflow pages | `/admin/onboarding`, `/admin/onboarding/{onboardingDraft}` | `Start Onboarding` on index when already available | Linked onboarding draft or linked tenant entry | `Resume onboarding` and `View Tenant` when valid | None | `Start Onboarding` | `View Tenant` when a linked tenant exists and is viewable | Save and cancel semantics unchanged inside onboarding flows | Yes when workflow state mutates | These pages must not masquerade as normal active-tenant context pages. |
| Operations index and run viewer | `/admin/operations`, `/admin/operations/{run}` | None added by this slice | Linked run row inspection | `View Run` | None in this slice | None | None | Not applicable | Existing operation audit rules remain | Exemption: this slice defines viewer legitimacy and mismatch handling, not new run mutations. |

### Key Entities *(include if feature involves data)*

- **Workspace**: The primary operating boundary that owns tenants, onboarding workflow records, and canonical operation records.
- **Tenant**: A durable workspace-owned record with canonical lifecycle state and lifecycle-driven operability semantics.
- **Onboarding Workflow Record**: A workspace-scoped draft or session that governs onboarding progression, resumability, and setup progress for a linked tenant.
- **Operation Run**: A canonical workspace-owned record that may reference a tenant but remains authoritative on its own route.
- **Remembered Tenant Context**: Operator preference state used for convenience filtering and navigation, but not as an authorization source or route-legitimacy requirement.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: In validation scenarios across in-scope tenant and operation surfaces, 100% of canonical lifecycle states render an explicit lifecycle label with no fallback `Unknown` state for valid values.
- **SC-002**: In validation scenarios for canonical workspace record viewers, 100% of authorized deep links remain accessible when the remembered tenant context differs from the record's referenced tenant.
- **SC-003**: In validation scenarios for tenant selection, 0 `draft`, `onboarding`, or `archived` tenants appear as selectable choices in the normal active tenant selector.
- **SC-004**: In validation scenarios for tenant management actions, 100% of lifecycle-changing actions use operator-facing labels that match the underlying lifecycle outcome.
- **SC-005**: In validation scenarios for authorization boundaries, 100% of non-member or non-entitled access attempts resolve as deny-as-not-found, while 100% of member-without-capability attempts resolve as forbidden.
- **SC-006**: Follow-up implementation specs derived from this foundation can classify every affected route into one of the four page categories without introducing a fifth ad hoc category for tenant-context behavior.

## Summary

Tenant lifecycle behavior is currently underspecified and interpreted differently across onboarding, tenant context selection, operation viewing, action availability, and status rendering. This feature establishes an explicit product model that separates tenant lifecycle, tenant operability, and tenant context semantics so that onboarding tenants remain real records without leaking into normal active-tenant workflows, and it applies that model immediately to the current highest-risk admin surfaces.

The central product decision is that a tenant in `onboarding` is a real tenant record, but it is not a normal operable tenant context. That distinction creates a clean boundary between onboarding workflow, tenant management, workspace-level monitoring, and everyday tenant-context operations.

## Goals

- Define a single conceptual model for tenant lifecycle that all product layers can share.
- Define a separate operability model so raw lifecycle is not used as a shortcut for every decision.
- Define explicit tenant-context and selector visibility semantics for workspace pages, tenant-bound pages, onboarding pages, and canonical record viewers.
- Ensure canonical workspace-level records such as operation runs are not invalidated by remembered tenant context.
- Provide a stable foundation for future governance features such as alerts, audit log, baselines, findings, and customer-facing read-only views.
- Deliver the first implementation slice on canonical operation viewers, tenant selection flows, lifecycle presentation, and tenant-safe global search so the model is proven on live admin surfaces.

## Non-Goals

- This feature does not implement a full state machine for every onboarding step.
- This feature does not redesign the onboarding wizard end to end.
- This feature does not introduce new tenant lifecycle states beyond `draft`, `onboarding`, `active`, and `archived`.
- This feature does not remove the tenant record from onboarding flows.
- This feature does not refactor every affected page immediately; it defines the target model and implements it on the current high-risk surfaces called out in the user stories.

## Assumptions

- Workspaces remain the primary ownership and authorization boundary.
- Tenants remain workspace-owned records rather than transient onboarding-only placeholders.
- Existing canonical operation records already have legitimate workspace identity and may optionally reference a tenant.
- This feature's implementation work will centralize lifecycle semantics, operability rules, lifecycle presentation, lifecycle audit coverage, and tenant-safe global-search behavior rather than duplicating them per screen.

## Risks

- Centralizing lifecycle semantics without classifying page types could still leave context behavior inconsistent.
- Future work may regress if lifecycle is again used as a shortcut for every visibility or authorization decision.
- Removing onboarding tenants from normal selectors without strong management discoverability would make records feel lost.
- Partial rollout across surfaces may temporarily increase confusion if follow-up implementation order is not controlled.

## Follow-Up Work

- Extend the same lifecycle and operability semantics to the remaining tenant-bound and workspace-scoped admin surfaces not covered by this initial rollout.
- Apply the same model to future governance surfaces such as alerts, findings, and customer-facing read-only views.
- Expand lifecycle-driven observability and audit analysis once additional tenant lifecycle mutations are introduced.

## Final Direction

The strategic direction is to make tenant lifecycle a domain concern, tenant operability a separate policy concern, and tenant context visibility a separate information architecture and UX concern. Canonical workspace-level records must remain authoritative on their own routes, and onboarding tenants must remain real records without being treated as normal active tenant context.
