TenantAtlas/specs/146-central-tenant-status-presentation/spec.md

Feature Specification: Central Tenant Status Presentation

Feature Branch: 146-central-tenant-status-presentation
Created: 2026-03-16
Status: Draft
Input: User description: "Spec 146 — Central Tenant Status Presentation"

Spec Scope Fields (mandatory)

• Scope: workspace + tenant lifecycle presentation + referenced tenant lifecycle presentation on the tenantless operations viewer and its OperationRunResource enterprise-detail summary payload
• Primary Routes: /admin/tenants, /admin/tenants/{tenant}, /admin/choose-tenant, /admin/onboarding, /admin/onboarding/{onboardingDraft}, /admin/operations, /admin/operations/{run}
• Data Ownership: Workspace-owned tenant records remain the source of lifecycle values. Workspace-owned canonical records that reference tenants may display lifecycle, but this feature does not change record ownership, lifecycle transitions, or tenant-workspace relationships.
• RBAC: No new membership rules, capabilities, or authorization planes are introduced. Existing workspace and canonical-view access rules remain in force; this feature only standardizes how already-authorized users see tenant lifecycle.

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: Existing tenant-context and viewer filtering behavior remains unchanged. When a permitted canonical record references a tenant, the viewer may display that tenant's lifecycle using the shared lifecycle contract, but the feature does not broaden record selection or tenant inclusion rules.
• Explicit entitlement checks preventing cross-tenant leakage: Referenced tenant lifecycle may only be shown after the viewer's existing server-side entitlement checks have already allowed access to the canonical record. The feature must not expose lifecycle hints for unauthorized tenants, inaccessible records, or filtered-out tenants.

User Scenarios & Testing (mandatory)

User Story 1 - Read Trusted Lifecycle Badges Everywhere (Priority: P1)

As a workspace operator, I want tenant lifecycle to render with the same label and meaning everywhere it appears so I can trust what a tenant's state means without reinterpreting each page.

Why this priority: This is the core trust problem. If the same valid state renders differently across core surfaces, operators cannot reliably interpret readiness, archived retention, or onboarding context.

Independent Test: Can be fully tested by rendering tenants in each canonical lifecycle state across the tenant index, tenant detail, and choose-tenant surfaces and confirming the same lifecycle label appears without falling back to Unknown.

Acceptance Scenarios:

1. Given a tenant in draft, onboarding, active, or archived, When an operator views the tenant in any in-scope table or detail surface, Then the lifecycle renders with the canonical label for that state and never falls back to Unknown.
2. Given the same tenant appears on multiple in-scope tenant management surfaces, When the lifecycle is shown, Then the label and lifecycle meaning remain consistent even if the surface uses a more concise or more detailed presentation.

---

User Story 2 - Understand Referenced Tenant Context in the Operations Viewer (Priority: P2)

As an operator reviewing an operation run, I want referenced tenant lifecycle to use the same vocabulary as tenant management pages so I can understand whether the tenant was onboarding, active, draft, or archived when the record was created or viewed.

Why this priority: The operations viewer is a high-trust review surface. Referenced tenant lifecycle must explain context clearly without making the record itself appear broken.

Independent Test: Can be fully tested by viewing operation-run records that reference onboarding and archived tenants and confirming the referenced lifecycle uses the same label set as tenant pages.

Acceptance Scenarios:

1. Given an authorized operator opens the tenantless operations viewer for a run that references an onboarding tenant, When tenant lifecycle is shown in the viewer banner or enterprise-detail summary, Then the viewer uses the canonical Onboarding presentation rather than Unknown, Pending, or another alternate label.
2. Given an authorized operator opens the tenantless operations viewer for a run that references an archived tenant, When tenant lifecycle is shown in the viewer banner or enterprise-detail summary, Then the viewer communicates archival lifecycle clearly without implying the referenced tenant is deleted or the canonical record is invalid.

---

User Story 3 - Distinguish Lifecycle from Other Tenant Status Domains (Priority: P3)

As an operator, I want tenant lifecycle to remain separate from provider health, consent, verification, RBAC, and run outcome so I can tell whether a tenant's lifecycle is the issue or whether another domain needs attention.

Why this priority: Lifecycle becomes misleading if it is used as a proxy for unrelated operational states. Clear separation reduces operator error and preserves domain trust.

Independent Test: Can be fully tested by rendering pages that show lifecycle alongside other tenant-adjacent statuses and verifying each status domain remains separately labeled and understandable.

Acceptance Scenarios:

1. Given a surface shows tenant lifecycle together with provider, verification, or RBAC information, When the page is rendered, Then lifecycle remains labeled with the canonical lifecycle vocabulary and does not replace or absorb adjacent status domains.
2. Given an active tenant has failing provider or verification signals, When the page is rendered, Then lifecycle still reads Active and the failure is communicated through its own separate status domain.

Edge Cases

• A lifecycle value outside the canonical model is present because of corrupted or legacy data; the UI may use a reserved invalid-data fallback, but valid canonical states must never use that fallback.
• A surface chooses a concise badge-only presentation while another uses helper text; both must still communicate the same lifecycle meaning.
• A page shows lifecycle next to provider connection, consent, verification, RBAC, onboarding progress, or run outcome; none of those adjacent domains may be renamed to lifecycle-like terms.
• An archived or onboarding tenant appears as a referenced tenant in the tenantless operations viewer; the lifecycle must explain context without making the record appear missing or erroneous.
• A surface omits lifecycle entirely by design; when lifecycle is shown later on that surface, it must consume the central contract rather than invent local wording.

Requirements (mandatory)

Constitution alignment (required): This feature does not introduce Microsoft Graph calls, write/change behavior, queued work, scheduled work, or new operation execution. No contract registry changes, preview flows, confirmation flows, audit-only mutation paths, or OperationRun changes are in scope.

Constitution alignment (OPS-UX): This feature does not create, reuse, or mutate an OperationRun. Monitoring, toast behavior, progress surfaces, terminal notifications, and summary count semantics are unchanged.

Constitution alignment (RBAC-UX): This feature does not introduce new authorization behavior. Existing workspace and canonical-view authorization rules remain unchanged, including deny-as-not-found behavior for inaccessible records. No new capabilities, policy branches, destructive actions, or capability strings are introduced by this spec.

Constitution alignment (OPS-EX-AUTH-001): No authentication handshake or synchronous outbound auth behavior is introduced.

Constitution alignment (BADGE-001): This feature changes status-like presentation and therefore must centralize tenant lifecycle badge semantics in one authoritative contract. All in-scope surfaces must consume that shared contract so valid lifecycle states cannot drift, disappear, or fall back to Unknown. Regression coverage must verify canonical labels for draft, onboarding, active, and archived, plus reserved fallback behavior for truly invalid data only.

Constitution alignment (UI-NAMING-001): Operator-facing lifecycle vocabulary must remain stable across labels, helper text, viewer references, and summary prose. The target object is tenant lifecycle. The operator vocabulary is Draft, Onboarding, Active, and Archived. No implementation-first terms or alternate pseudo-lifecycle names may become the primary operator label for lifecycle.

Constitution alignment (Filament Action Surfaces): In-scope Filament surfaces are modified for presentation consistency only. The Action Surface Contract remains satisfied because this spec does not add new actions, alter destructive behavior, or change existing mutation affordances. The UI Action Matrix below records the affected surfaces and confirms no action semantics change.

Constitution alignment (UX-001 — Layout & Information Architecture): This feature updates lifecycle presentation within existing screens rather than redesigning layouts. Existing Create/Edit/View/Table structures remain intact. Status presentation must comply with BADGE-001 centralization. No UX-001 exemption is required because the spec does not remove or weaken the established layout and information architecture rules.

Functional Requirements

• FR-001: The system MUST define one authoritative tenant lifecycle presentation contract covering the canonical lifecycle values draft, onboarding, active, and archived.
• FR-002: The lifecycle presentation contract MUST provide, at minimum, a machine-readable lifecycle value, a human-readable label, a concise badge or chip semantic, and optional short and detailed explanatory variants derived from the same meaning.
• FR-003: The system MUST render every valid canonical tenant lifecycle value explicitly on in-scope surfaces and MUST NOT render any canonical lifecycle value as Unknown, blank, or a default fallback.
• FR-004: In-scope tenant management surfaces that render lifecycle MUST use the canonical labels Draft, Onboarding, Active, and Archived, with surface-specific density allowed only when the underlying meaning remains unchanged.
• FR-005: The tenantless operations viewer and its OperationRunResource enterprise-detail summary payload MUST use the same lifecycle presentation contract as tenant management surfaces when rendering referenced tenant lifecycle.
• FR-006: The system MUST preserve a clear distinction between tenant lifecycle and adjacent status domains, including provider connection status, app or consent status, RBAC status, verification outcome, onboarding progress, governance posture, and operation-run status.
• FR-007: The system MUST NOT introduce non-canonical lifecycle labels such as Pending, Suspended, Inactive, or Error for tenant lifecycle unless a future domain specification formally adds them.
• FR-008: The system MAY provide a reserved fallback for corrupted or unexpected lifecycle data, but that fallback MUST be visually and semantically reserved for invalid non-canonical data only.
• FR-009: New or changed in-scope code MUST consume the central lifecycle presentation contract rather than defining local lifecycle mapping logic in templates, columns, infolists, widgets, pages, viewers, or helper methods.
• FR-010: The feature MUST make missing coverage for canonical lifecycle states detectable during development and regression testing.
• FR-011: Detailed surfaces MAY show lifecycle helper text, but that helper text MUST reinforce lifecycle meaning without implying provider health, readiness, failure, or authorization outcomes that belong to other domains.
• FR-012: Table, selector, viewer, banner, and summary surfaces that describe tenant lifecycle in prose or badge form MUST align with the same canonical vocabulary and lifecycle meaning.

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 index and tenant detail surfaces	Existing tenant management Filament resources and pages	No change	Existing record links and inspect affordances remain unchanged	No change	No change	No lifecycle-specific CTA change	No change	No change	No change	Presentation-only lifecycle updates; no new actions or destructive behavior
Choose-tenant and onboarding-linked tenant surfaces	Existing tenant selection and onboarding Filament or Livewire surfaces	No change	Existing selection and inspection affordances remain unchanged	No change	No change	No lifecycle-specific CTA change	No change	No change	No change	Lifecycle vocabulary becomes canonical where shown
Operations viewer referenced-tenant surfaces	TenantlessOperationRunViewer and the OperationRunResource enterprise-detail summary payload it renders	No change	Existing viewer navigation remains unchanged	No change	No change	No lifecycle-specific CTA change	No change	No change	No change	Referenced tenant lifecycle aligns with the same contract; no additional canonical viewers are in scope for this feature

Key Entities (include if feature involves data)

• Tenant Lifecycle State: The canonical domain lifecycle assigned to a tenant. For this feature, the relevant values are draft, onboarding, active, and archived.
• Tenant Lifecycle Presentation Contract: The authoritative presentation definition that translates a canonical lifecycle state into its shared operator-facing label, tone, and explanatory variants.
• Referenced Tenant Display Context: Any authorized viewer, summary, card, or detail surface that displays a tenant's lifecycle as context for another record without changing the underlying tenant record.

Assumptions

• Spec 143 remains the source of truth for lifecycle ownership and lifecycle values.
• Spec 145 remains the source of truth for lifecycle-safe action interpretation and visibility semantics.
• This feature is limited to presentation consistency and does not change which tenants are included in selectors, context switching, or canonical viewers.
• Existing authorization, global search, and tenant-context rules remain unchanged except that any already-rendered lifecycle must use the canonical presentation vocabulary.
• The only canonical-view surface in scope for this feature is the tenantless operations viewer, including the OperationRunResource enterprise-detail summary payload it renders. Any additional canonical viewer rollout requires a follow-up spec.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: In the in-scope surfaces covered by regression tests, 100% of canonical lifecycle states draft, onboarding, active, and archived render with explicit canonical labels and 0% render as Unknown.
• SC-002: Operators reviewing the same tenant across at least three in-scope surfaces encounter the same lifecycle label and meaning for that tenant state, with no alternate pseudo-lifecycle labels in the tested paths.
• SC-003: Authorized operators can distinguish tenant lifecycle from adjacent status domains on tested mixed-status surfaces without lifecycle labels changing to reflect provider, consent, RBAC, verification, or run outcome conditions.
• SC-004: Referenced tenant lifecycle in the tested tenantless operations viewer renders intentionally for onboarding and archived tenants without the viewer implying the record is broken, deleted, or missing.