TenantAtlas/specs/143-tenant-lifecycle-operability-context-semantics/quickstart.md

Quickstart: Tenant Lifecycle, Operability, and Context Semantics Foundation

Purpose

Use this guide to validate follow-up implementation work derived from Spec 143.

Prerequisites

• Laravel Sail services are running.
• An admin-plane user exists with workspace membership.
• At least one workspace exists with tenants covering these lifecycle states:
  • draft
  • onboarding
  • active
  • archived
• At least one authorized OperationRun exists for a tenant that is not the currently selected tenant.
• At least one resumable TenantOnboardingSession exists for an onboarding tenant.

Validation flow

1. Validate selector eligibility

• Open /admin/choose-tenant.
• Confirm only active tenants are selectable as normal tenant context.
• Confirm draft, onboarding, and archived tenants are not selectable in the standard tenant chooser.

Expected result:

• The chooser represents normal operating context only.
• No invalid tenant selection path is available.

2. Validate management and onboarding visibility

• Open /admin/tenants and inspect lifecycle labels and actions.
• Open /admin/onboarding and any resumable onboarding draft.

Expected result:

• Onboarding and draft tenants remain visible in the correct surfaces.
• Archived tenants remain visible only where administrative or audit semantics justify them.
• Lifecycle-related actions are vocabulary-correct: Archive, Restore, Resume onboarding.

3. Validate canonical operation viewer behavior

• Select tenant B as the remembered tenant context.
• Open /admin/operations/{run} for a run linked to tenant A.

Expected result:

• The run remains visible if workspace membership, tenant entitlement, and capability checks pass.
• The page handles the mismatch explicitly in UX if implemented, but does not return a false 404.

4. Validate tenant-bound route behavior

• Open /admin/tenants/{tenant} for an onboarding tenant that the user is entitled to.
• Repeat for an archived tenant if allowed by the follow-up implementation.

Expected result:

• Route legitimacy comes from the route tenant plus entitlement checks.
• Action availability changes with lifecycle, but route validity does not depend on current header tenant selection.

5. Validate authorization semantics

• Attempt the same tenant and operation-run routes as:
  • a non-member user
  • a workspace member without the required capability

Expected result:

• Non-member or non-entitled access resolves as 404.
• Member without capability resolves as 403 for execution attempts.

6. Validate status presentation

• Inspect tenant lifecycle badges wherever tenant status appears.

Expected result:

• draft, onboarding, active, and archived all render explicit, centralized status presentation.
• No valid lifecycle renders as Unknown.

Suggested focused test targets

• tests/Feature/Auth/TenantChooserSelectionTest.php
• tests/Feature/TenantRBAC/TenantSwitcherScopeTest.php
• tests/Feature/TenantRBAC/ArchivedTenantRouteAccessTest.php
• tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php
• tests/Feature/Operations/TenantlessOperationRunViewerTest.php
• tests/Feature/Spec085/CanonicalMonitoringDoesNotMutateTenantContextTest.php
• tests/Feature/Badges/TenantStatusBadgeTest.php
• tests/Feature/Onboarding/OnboardingDraftAuthorizationTest.php
• tests/Unit/Onboarding/OnboardingLifecycleServiceTest.php

Filament and deployment notes

• Livewire v4.0+ compliance remains required because this feature touches Filament v5 surfaces.
• Filament providers remain registered in bootstrap/providers.php.
• This foundation adds no new assets, so there is no new filament:assets work beyond the project’s existing deploy process.