TenantAtlas/specs/274-billing-subscription-truth/research.md

Research: Billing & Subscription Truth Layer v1

Date: 2026-05-04
Branch: 274-billing-subscription-truth

Decision 1: Use a dedicated workspace-owned subscription table, not more workspace-setting keys

• Decision: Persist current subscription truth in a new workspace_subscriptions table with one current row per workspace.
• Rationale: Subscription truth now has its own lifecycle, date fields, audit trail, and future sync seam. Keeping it inside WorkspaceSetting would continue to blur fallback lifecycle truth, plan settings, and current subscription truth into one settings bucket.
• Alternatives considered:
  • More keys under entitlements.*: rejected because the record now has independent lifecycle meaning and no longer behaves like a small plan override.
  • Broad customer-account or billing model: rejected because the current release needs one current subscription record only, not a full billing domain.

Decision 2: Keep WorkspaceCommercialLifecycleResolver as the only runtime gate

• Decision: WorkspaceCommercialLifecycleResolver remains the one gate consulted by onboarding and review-pack surfaces.
• Rationale: Specs 247 and 251 already proved the current gate shape. Introducing direct subscription checks on onboarding or review-pack surfaces would create a second gate and immediate drift.
• Alternatives considered:
  • Direct subscription checks on each surface: rejected because that would duplicate lifecycle logic and blur business-state versus entitlement-state reasoning.
  • Leaving lifecycle fully manual even after adding a subscription record: rejected because it would leave two competing commercial truths alive at once.

Decision 3: Subscription truth becomes the upstream lifecycle source when present

• Decision: When a workspace has a current subscription record, lifecycle state is derived from that record. When no subscription record exists, the current manual lifecycle overlay remains the fallback source.
• Rationale: This keeps current behavior stable for untouched workspaces while letting new subscription-backed workspaces stop relying on manual lifecycle state.
• Alternatives considered:
  • Force every workspace to get a subscription record immediately: rejected because the repo already has live manual lifecycle semantics and the narrow slice should not require a bulk migration workflow.
  • Add subscription truth as read-only evidence without feeding lifecycle: rejected because it would preserve duplicated truths and force operators to reconcile them manually.

Decision 4: Use one current record and audit as history

• Decision: V1 stores one current subscription record per workspace and relies on AuditLog for change history.
• Rationale: The current operator problem is understanding the current posture and driving the current lifecycle gate, not browsing historical subscription revisions in-product.
• Alternatives considered:
  • Multi-row history table or event ledger: rejected because the current slice would become a billing-history feature rather than a source-of-truth follow-through.
  • No history beyond the row itself: rejected because auditability is required for commercial truth changes.

Decision 5: Keep the current mutation surface on the system workspace detail page

• Decision: Reuse ViewWorkspace for subscription mutation and keep WorkspaceSettings read-only.
• Rationale: Specs 247 and 251 already separated admin-plane self-understanding from platform-plane commercial control. This slice should preserve that separation.
• Alternatives considered:
  • Add an admin-plane subscription form: rejected because it would create a second commercial control plane.
  • Add a new system billing page: rejected because the existing workspace detail page is already the commercial-truth drilldown.

Decision 6: No automatic timers, provider sync, or invoice logic in v1

• Decision: Period dates are visible and testable, but the product does not auto-transition subscription state, sync from an external system, or introduce invoices in this slice.
• Rationale: The current need is durable commercial truth and one shared runtime source, not an automation engine.
• Alternatives considered:
  • Webhook or provider sync placeholders: rejected because they would widen the slice into provider-boundary work.
  • Automatic transitions when trial or period end passes: rejected because the repo has no current scheduling or operator-review contract for that behavior.

Final Research Outcome

• Current-release truth requires a dedicated current subscription record.
• Runtime gating remains on the existing lifecycle resolver.
• The implementation should stay on the current system and admin surfaces.
• No provider, invoice, portal, or automation work is needed for this slice.