TenantAtlas/specs/251-commercial-entitlements-billing-state/research.md

# Research: Commercial Entitlements and Billing-State Maturity

**Date**: 2026-04-28  
**Branch**: `251-commercial-entitlements-billing-state`

## Decision 1: Persist lifecycle truth inside the existing `entitlements` settings domain

- **Decision**: Store the workspace commercial lifecycle overlay through explicit `WorkspaceSetting` keys in the existing `entitlements` domain, conceptually `commercial_lifecycle_state` plus `commercial_lifecycle_reason`.
- **Rationale**: Spec 247 already proved that workspace-owned commercial truth belongs in the existing workspace settings infrastructure. Reusing that path keeps audit behavior, validation, and source-of-truth ownership consistent without inventing a billing/account model or a second persistence family.
- **Alternatives considered**:
  - New `subscriptions`, `billing_states`, or `customer_accounts` tables: rejected because the spec explicitly forbids broad billing/account scope.
  - A separate `commercial` settings domain: rejected because the new state is an overlay on the already-real entitlement substrate, not a second independent settings family.

## Decision 2: Add one bounded lifecycle overlay service above `WorkspaceEntitlementResolver`

- **Decision**: Introduce one bounded `WorkspaceCommercialLifecycleResolver` in `App\Services\Entitlements` that composes `WorkspaceEntitlementResolver` instead of replacing it.
- **Rationale**: The underlying entitlement resolver remains canonical for plan-profile defaults, override values, and per-key allow/block truth. The new feature needs one additional workspace-wide layer that can answer lifecycle state, lifecycle rationale, and action-family outcomes across onboarding, review-pack starts, and preserved read-only history access.
- **Alternatives considered**:
  - Extend `WorkspaceEntitlementResolver` until it also owns lifecycle posture: rejected because that would blur substrate truth with the new overlay and make future review of state ordering harder.
  - Local page/service conditionals in onboarding, review-pack resources, and system detail: rejected because they would drift immediately.

## Decision 3: Keep system-plane mutation on the existing workspace detail page only

- **Decision**: Make `/system/directory/workspaces/{workspace}` the only mutation surface for lifecycle state changes, with inspection plus a confirmation-protected `Change commercial state` action.
- **Rationale**: The spec requires platform-managed lifecycle mutation. The existing system workspace detail page already exposes commercial truth read-only and is the narrowest platform context that can show state, rationale, and audit attribution without creating a second control plane.
- **Alternatives considered**:
  - Add lifecycle mutation to `/admin/settings/workspace`: rejected because the slice must not become a self-service workspace-admin commercial control surface.
  - Create a dedicated system commercial page/resource: rejected because the existing workspace detail page already anchors the platform/support workflow.

## Decision 4: Preserve explicit business-state versus authorization semantics

- **Decision**: Keep non-member and wrong-plane access as 404, keep established-scope capability denial as 403, and treat lifecycle blocking or warnings as business-state results for otherwise authorized actors.
- **Rationale**: This is the main operator value of the slice. The commercial lifecycle overlay must explain why an action is blocked without pretending the actor lacks scope or permission.
- **Alternatives considered**:
  - Hide blocked actions entirely: rejected because it would erase the commercial explanation the feature exists to provide.
  - Return 403 for lifecycle blocks: rejected because it would conflate business state with authorization.

## Decision 5: Review-pack lifecycle blocking must happen before `ReviewPack` or `OperationRun` creation

- **Decision**: Reuse `ReviewPackService` as the hard enforcement boundary and block lifecycle-restricted starts before any `ReviewPack` or `OperationRun` write occurs.
- **Rationale**: Current review-pack start surfaces already converge on `ReviewPackService`. Blocking at the service boundary prevents UI-surface bypass and preserves the shared OperationRun start UX for allowed actions.
- **Alternatives considered**:
  - UI-only disabling on each widget/resource/page action: rejected because it would not protect direct action execution.
  - A new review-pack lifecycle queue/framework: rejected because the slice changes eligibility only, not run orchestration.

## Decision 6: Reuse the existing blocked-decision transport if it can carry lifecycle metadata cleanly

- **Decision**: Prefer reusing `WorkspaceEntitlementBlockedException` and extending its decision payload for lifecycle blocks, rather than introducing a second parallel business-state exception family.
- **Rationale**: Review-pack widgets/resources already catch `WorkspaceEntitlementBlockedException` and project its `block_reason` into user-visible feedback. Reusing that transport keeps the change narrow unless implementation proves the class name or payload shape is too substrate-specific.
- **Alternatives considered**:
  - New `WorkspaceCommercialLifecycleBlockedException`: rejected for now because it would widen changes across all review-pack action surfaces without proving extra value.
  - Plain string returns without a shared decision payload: rejected because the UI surfaces already consume structured block context.

## Decision 7: Preserve suspended read-only access by leaving existing history/evidence/download routes outside the new gate

- **Decision**: Keep `CustomerReviewWorkspace`, `ViewTenantReview`, `ViewReviewPack`, `ViewEvidenceSnapshot`, and current review-pack download access outside the new lifecycle start gate, while allowing them to show a calm read-only explanation when helpful.
- **Rationale**: The feature promise is not "suspend everything." It is "block future starts while preserving safe existing history." Existing view/download routes already encode current RBAC and redaction semantics and are the narrowest place to preserve that truth.
- **Alternatives considered**:
  - Broad product-wide suspension of all mutable controls: rejected because the spec explicitly forbids a broad suspension engine.
  - No plan for preserved read access: rejected because suspension would otherwise appear as total lockout and break the evidence/history requirement.

## Decision 8: Keep the four-state vocabulary, but justify it narrowly

- **Decision**: Keep exactly four lifecycle states: `trial`, `grace`, `active_paid`, and `suspended_read_only`.
- **Rationale**: The spec requires these named postures, and platform operators need to set and audit them explicitly from one system surface. `grace` and `suspended_read_only` have immediate distinct action-family consequences. `trial` remains in scope because the platform/support workflow and audit trail need to distinguish temporary non-paid posture from steady active paid posture now, even though both allow the two in-scope gated behavior families.
- **Alternatives considered**:
  - Collapse to three states by removing `trial`: rejected because it would erase a required current-release commercial posture and force later renaming/migration when trial lifecycle work grows.
  - Persist only booleans like `is_suspended` and `is_in_grace`: rejected because that would not yield one clear operator-facing commercial state.

## Decision 9: Prove the slice with focused unit and feature lanes only

- **Decision**: Use one unit family for lifecycle resolution and focused feature tests for system mutation, onboarding gating, review-pack no-run blocking, and suspended read-only consumption.
- **Rationale**: The primary risk is correctness of decision ordering and bounded surface behavior, not browser layout or heavy orchestration.
- **Alternatives considered**:
  - Browser tests: rejected because no browser-only interaction risk is introduced in the planning slice.
  - Heavy-governance suite expansion: rejected because the scope is feature-local and uses existing surfaces.

## Decision 10: Leave panels, assets, and global search unchanged

- **Decision**: Do not add new panels, provider registration changes, global-search resources, or Filament assets as part of this slice.
- **Rationale**: The feature is a business-state overlay inside existing admin and system surfaces. Infrastructure changes would widen scope without helping the current release.
- **Alternatives considered**:
  - New commercial panel: rejected because `/system` detail already anchors the platform workflow.
  - Asset-backed custom commercial UI: rejected because current Filament components and the existing Blade detail view are sufficient.