TenantAtlas/specs/274-billing-subscription-truth/data-model.md

Data Model: Billing & Subscription Truth Layer v1

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

Overview

This slice adds one new workspace-owned source of truth: a current subscription record. Existing plan profiles, entitlement overrides, and manual commercial lifecycle fallback remain in their current storage. The new record feeds the existing commercial lifecycle resolver when present.

Persisted Truth

1. Workspace Subscription Aggregate

Persistence: New workspace_subscriptions table
Ownership: Workspace-owned
Scope: One current record per workspace

Field	Type	Nullable	Validation	Notes
id	bigint	no	primary key	Internal record id
workspace_id	bigint	no	foreign key, unique	Enforces one current subscription record per workspace
state	string	no	must be one of trial, active, past_due, cancel_at_period_end, ended	Current subscription posture
billing_reference	string	yes	trimmed, max 191 chars	Optional contract, subscription, or invoice reference label
trial_ends_at	datetime	yes	required when state=trial	Current trial end date
current_period_starts_at	datetime	yes	required when state is active, past_due, or cancel_at_period_end	Current commercial period start
current_period_ends_at	datetime	yes	required when state is active, past_due, cancel_at_period_end, or ended	Current commercial period end or ended-on boundary
status_reason	text	no	required on every explicit mutation path	Operator-visible explanation
created_at	datetime	no	standard timestamps	Creation time
updated_at	datetime	no	standard timestamps	Latest mutation time

Write rules:

• Mutation happens from the system plane only.
• workspace_id is immutable once the row exists.
• The record is updated in place in v1; no historical row chain is created.
• Audit history captures before and after values and actor attribution.

Relationships:

• workspace_subscriptions.workspace_id references workspaces.id.
• Workspace gains a singular subscription relationship.

Existing Persisted Truth Reused

2. Workspace Entitlement Substrate

Persistence: Existing workspace_settings rows plus code-owned plan catalog
Owner: WorkspaceEntitlementResolver

This slice does not remodel:

• plan profile selection
• first-slice entitlement overrides
• first-slice entitlement usage summaries

These remain the substrate that lifecycle may restrict after subscription mapping.

3. Manual Lifecycle Fallback

Persistence: Existing workspace_settings rows from Spec 251
Owner: WorkspaceCommercialLifecycleResolver

Manual lifecycle state remains valid only as fallback when a workspace does not yet have a current subscription record.

Code-Owned Truth

4. Subscription State Catalog Entry

Persistence: none, code-owned
Ownership: product runtime configuration

Field	Type	Required	Notes
id	string	yes	Stable internal identifier
label	string	yes	Operator-facing label
description	string	yes	Short explanation for system and settings summaries
derived_lifecycle_state	string	yes	One of the existing Spec 251 lifecycle states
needs_review_when_past_date	bool	yes	Whether the record should surface explicit review-required wording when its key date is in the past

Behavior matrix:

Subscription state	Derived lifecycle state	Key date surfaced	Notes
trial	trial	trial_ends_at	Current trial posture
active	active_paid	current_period_ends_at	Current paid period
past_due	grace	current_period_ends_at	Commercial grace posture
cancel_at_period_end	active_paid	current_period_ends_at	Still active, but cancellation is pending
ended	suspended_read_only	current_period_ends_at	Commercial access has ended

Derived Truth

5. Workspace Subscription Summary

Persistence: none, derived at runtime
Owner: WorkspaceSubscriptionResolver

Field	Type	Required	Notes
workspace_id	int	yes	Workspace being evaluated
subscription_present	bool	yes	Whether a current record exists
state	string	no	Current subscription state when present
label	string	no	Operator-facing state label
billing_reference	string	no	Optional reference
status_reason	string	no	Operator-visible explanation
key_date_label	string	no	Trial ends or Current period ends
key_date	datetime	no	Current relevant date
needs_review	bool	yes	True when a date-sensitive state is past its visible date
source	string	yes	One of workspace_subscription, workspace_setting, or default_active_paid
fallback_status	bool	yes	True when the summary is not backed by a current subscription record
derived_lifecycle_state	string	yes	Existing lifecycle state consumed downstream

6. Effective Commercial Lifecycle Decision

Persistence: none, derived at runtime
Owner: existing WorkspaceCommercialLifecycleResolver

The lifecycle decision remains the shared gate shape from Spec 251, but its source changes:

• If a subscription record exists, the lifecycle source becomes workspace_subscription.
• If no subscription record exists, the current workspace_setting or default_active_paid source remains.

Ordering rules:

1. Resolve the underlying entitlement substrate.
2. Resolve the lifecycle source from subscription truth when present, otherwise from fallback manual lifecycle truth.
3. If the substrate already blocks the action, keep the substrate block.
4. If the substrate allows the action, apply the lifecycle outcome from the resolved lifecycle state.

Supporting Derived View Models

7. System Workspace Subscription View Model

Consumer: ViewWorkspace

Contains:

• current subscription summary
• derived lifecycle summary
• fallback indicator when no subscription exists
• last-change attribution
• mutation affordance metadata for Update subscription truth

8. Workspace Settings Subscription Summary View Model

Consumer: WorkspaceSettings

Contains:

• current commercial posture
• whether it is subscription-backed or fallback-backed
• next relevant date
• concise explanation only

State Transitions

There is no multi-row ledger in v1. State changes are explicit updates to the current workspace subscription record plus audit entries.

From	To	Trigger	Consequence
no record	any valid state	platform operator creates current subscription truth	workspace becomes subscription-backed
trial	active	platform operator transition	derived lifecycle moves from trial to active_paid
active	past_due	platform operator transition	derived lifecycle moves to grace
active	cancel_at_period_end	platform operator transition	derived lifecycle stays active_paid, but period end becomes important context
past_due	ended	platform operator transition	derived lifecycle moves to suspended_read_only
any state	any other valid state	platform operator update	current subscription truth changes in place and is auditable

Boundaries Explicitly Preserved

• No invoice, payment, or provider-sync persistence exists in this slice.
• No multi-record historical subscription ledger exists in this slice.
• No direct subscription gate shape exists on onboarding or review-pack surfaces; lifecycle remains the only gate.
• Existing view and download access to already-generated review packs, evidence, and review history stays governed by the current lifecycle and RBAC rules.