@taskforcehq/taskforce 0.3.302 → 0.3.304

package/dist/core/PlanEntitlementService.js

@@ -35,7 +35,13 @@ export class PlanEntitlementService {
     // ─── Normalizers ─────────────────────────────────────────────────────────
     normalizeEntitlementState(value) {
         const normalized = String(value || '').trim().toLowerCase();
-        if (normalized === 'active' || normalized === 'trialing' || normalized === 'grace' || normalized === 'suspended' || normalized === 'canceled') {
+        if (normalized === 'pending_plan_selection'
+            || normalized === 'checkout_pending'
+            || normalized === 'active'
+            || normalized === 'trialing'
+            || normalized === 'grace'
+            || normalized === 'suspended'
+            || normalized === 'canceled') {
             return normalized;
         }
         return 'canceled';
@@ -112,6 +118,77 @@ export class PlanEntitlementService {
     isEntitlementStateAllowed(state) {
         return state === 'active' || state === 'trialing' || state === 'grace';
     }
+    isIsoTimestampExpired(value) {
+        const timestamp = String(value || '').trim();
+        if (!timestamp)
+            return false;
+        const expiresAt = Date.parse(timestamp);
+        if (!Number.isFinite(expiresAt))
+            return false;
+        return expiresAt <= Date.now();
+    }
+    readAccountEntitlementRow(accountId) {
+        return this.db.prepare(`
+            SELECT account_id, plan_version_id, entitlement_state, effective_at, effective_until
+            FROM account_entitlements
+            WHERE tenant_id = ? AND account_id = ?
+            LIMIT 1
+        `).get(this.tenantId, accountId);
+    }
+    normalizeExpiredCheckoutPendingRow(accountId) {
+        const row = this.readAccountEntitlementRow(accountId);
+        if (!row?.account_id || !row.plan_version_id) {
+            return row;
+        }
+        const currentState = this.normalizeEntitlementState(row.entitlement_state);
+        if (currentState !== 'checkout_pending' || !this.isIsoTimestampExpired(row.effective_until || null)) {
+            return row;
+        }
+        const now = new Date().toISOString();
+        this.db.prepare(`
+            UPDATE account_entitlements
+            SET entitlement_state = ?, effective_until = NULL, updated_by = ?, updated_at = ?
+            WHERE tenant_id = ? AND account_id = ?
+        `).run('pending_plan_selection', 'checkout-expired', now, this.tenantId, accountId);
+        this.createUserBillingRecord(accountId, {
+            entitlementState: 'pending_plan_selection',
+            planId: null,
+            effectiveUntil: null
+        });
+        return this.readAccountEntitlementRow(accountId);
+    }
+    isBillingConfirmedTransitionSource(source) {
+        return source === 'checkout-confirm' || source === 'stripe-webhook';
+    }
+    resolveCanonicalTransitionSource(updatedBy) {
+        if (updatedBy === 'registration'
+            || updatedBy === 'checkout-start'
+            || updatedBy === 'checkout-confirm'
+            || updatedBy === 'stripe-webhook'
+            || updatedBy === 'backfill'
+            || updatedBy === 'legacy-plan-mode') {
+            return updatedBy;
+        }
+        return 'system';
+    }
+    resolvePendingPlanVersionId(planVersionIdRaw) {
+        const planVersionId = String(planVersionIdRaw || '').trim();
+        if (planVersionId) {
+            return this.getPlanVersionSnapshot(planVersionId).planVersionId;
+        }
+        return this.getDefaultPlanVersionByMode('personal', { allowFallback: true }).planVersionId;
+    }
+    buildBlockedAccessStatus(input) {
+        return {
+            gate: input.gate,
+            hasEntitlement: Boolean(input.entitlement),
+            canAccessApp: false,
+            canAccessPlans: true,
+            planSelectionRequired: input.planSelectionRequired === true,
+            message: input.message,
+            entitlement: input.entitlement
+        };
+    }
     // ─── Plan defaults repair ─────────────────────────────────────────────────
     repairPlanDefaultVersionIfNeeded(planIdRaw) {
         const planId = String(planIdRaw || '').trim().toLowerCase();
@@ -152,42 +229,6 @@ export class PlanEntitlementService {
             this.repairPlanDefaultVersionIfNeeded(planId);
         }
     }
-    repairSignupMonetizationSettingsIfNeeded() {
-        const current = this.deps.readGlobalConfig();
-        const currentAuth = current.auth && typeof current.auth === 'object'
-            ? current.auth
-            : {};
-        const strategy = currentAuth.signupMonetizationStrategy === 'plan_selection_required'
-            ? 'plan_selection_required'
-            : currentAuth.signupMonetizationStrategy === 'auto_assign_default'
-                ? 'auto_assign_default'
-                : null;
-        const hasStrategy = strategy === 'auto_assign_default' || strategy === 'plan_selection_required';
-        const hasDefaultVersionId = typeof currentAuth.defaultSignupPlanVersionId === 'string'
-            && currentAuth.defaultSignupPlanVersionId.trim().length > 0;
-        if (strategy === 'plan_selection_required') {
-            return;
-        }
-        if (strategy === 'auto_assign_default' && hasDefaultVersionId) {
-            return;
-        }
-        const fallbackVersion = this.tryGetDefaultPlanVersionByMode('personal', { allowFallback: true });
-        if (!fallbackVersion) {
-            return;
-        }
-        this.deps.writeGlobalConfig({
-            ...current,
-            auth: {
-                ...currentAuth,
-                signupMonetizationStrategy: hasStrategy
-                    ? strategy
-                    : 'auto_assign_default',
-                defaultSignupPlanVersionId: strategy === 'auto_assign_default' && hasDefaultVersionId
-                    ? currentAuth.defaultSignupPlanVersionId
-                    : fallbackVersion.planVersionId
-            }
-        });
-    }
     normalizeLegacyPlanDataIfNeeded() {
         this.migrateLegacySeatLimitFeatureConfigToVersionSeatLimit();
         this.normalizeLegacyBillingMirrorRows();
@@ -301,16 +342,16 @@ export class PlanEntitlementService {
             if (!accountId)
                 continue;
             const rawBillingState = String(row.entitlement_state || '').trim().toLowerCase();
-            if (rawBillingState === 'pending_plan_selection')
-                continue;
             const mirroredPlanId = String(row.tier || '').trim().toLowerCase();
             const planVersion = this.tryGetDefaultPlanVersionByPlanId(mirroredPlanId)
                 || defaultPersonalVersion;
-            this.upsertCanonicalEntitlementRecord({
+            this.transitionCanonicalCommercialState({
                 accountId,
                 planVersionId: planVersion.planVersionId,
                 state: this.resolveCanonicalEntitlementStateFromBilling(row.entitlement_state),
                 effectiveAt: row.billing_created_at ? String(row.billing_created_at) : undefined,
+                billingMirrorPlanId: rawBillingState === 'pending_plan_selection' ? null : planVersion.planId,
+                source: 'backfill',
                 updatedBy: 'backfill',
                 createdAt: row.billing_created_at ? String(row.billing_created_at) : undefined,
                 updatedAt: row.billing_updated_at ? String(row.billing_updated_at) : undefined
@@ -351,7 +392,39 @@ export class PlanEntitlementService {
     resolveCanonicalEntitlementStateFromBilling(raw) {
         return this.normalizeEntitlementState(raw);
     }
-    upsertCanonicalEntitlementRecord(input) {
+    transitionCanonicalCommercialState(input) {
+        const accountId = String(input.accountId || '').trim();
+        if (!accountId) {
+            throw new TaskforceRuleError('accountId is required', 400, 'ACCOUNT_ID_REQUIRED');
+        }
+        const nextState = this.normalizeEntitlementState(input.state);
+        const existing = this.tryGetAccountEntitlement(accountId);
+        const planVersionId = nextState === 'pending_plan_selection'
+            ? this.resolvePendingPlanVersionId(input.planVersionId || existing?.planVersionId || null)
+            : String(input.planVersionId || existing?.planVersionId || '').trim();
+        if (!planVersionId) {
+            throw new TaskforceRuleError('planVersionId is required', 400, 'PLAN_VERSION_ID_REQUIRED');
+        }
+        const planVersion = this.getPlanVersionSnapshot(planVersionId);
+        if (existing && !this.isValidEntitlementTransition(existing.state, nextState)) {
+            throw new TaskforceRuleError('Invalid entitlement state transition', 409, 'INVALID_STATE_TRANSITION');
+        }
+        const planHasActivePricing = this.planHasAnyActivePricing(planVersion.planId);
+        const planVersionHasActiveFreePricing = this.planVersionHasActiveFreePricing(planVersion.planVersionId);
+        if ((nextState === 'active' || nextState === 'grace')
+            && planHasActivePricing
+            && !planVersionHasActiveFreePricing
+            && !this.isBillingConfirmedTransitionSource(input.source)
+            && input.source !== 'admin'
+            && input.source !== 'backfill'
+            && input.source !== 'legacy-plan-mode') {
+            throw new TaskforceRuleError('Paid active access can only be activated from billing-confirmed transitions.', 409, 'PAID_ACCESS_REQUIRES_BILLING_CONFIRMATION', {
+                accountId,
+                planVersionId,
+                state: nextState,
+                source: input.source
+            });
+        }
         const now = new Date().toISOString();
         const createdAt = input.createdAt || now;
         const updatedAt = input.updatedAt || now;
@@ -365,7 +438,21 @@ export class PlanEntitlementService {
                 effective_until = excluded.effective_until,
                 updated_by = excluded.updated_by,
                 updated_at = excluded.updated_at
-        `).run(input.accountId, this.tenantId, input.planVersionId, input.state, input.effectiveAt || now, input.effectiveUntil || null, input.updatedBy, createdAt, updatedAt);
+        `).run(accountId, this.tenantId, planVersion.planVersionId, nextState, input.effectiveAt || now, input.effectiveUntil || null, input.updatedBy, createdAt, updatedAt);
+        this.createUserBillingRecord(accountId, {
+            entitlementState: nextState,
+            planId: input.billingMirrorPlanId !== undefined
+                ? input.billingMirrorPlanId
+                : (nextState === 'pending_plan_selection' ? null : planVersion.planId),
+            effectiveUntil: input.effectiveUntil || null
+        });
+        return this.getAccountEntitlement(accountId);
+    }
+    upsertCanonicalEntitlementRecord(input) {
+        this.transitionCanonicalCommercialState({
+            ...input,
+            source: this.resolveCanonicalTransitionSource(input.updatedBy)
+        });
     }
     isFeatureEnabledForPlanMode(feature) {
         return Boolean(feature && feature.access !== 'disabled');
@@ -463,6 +550,26 @@ export class PlanEntitlementService {
         `).get(this.tenantId, planId);
         return Number(row?.count || 0) > 0;
     }
+    planVersionHasActiveFreePricing(planVersionIdRaw) {
+        const planVersionId = String(planVersionIdRaw || '').trim();
+        if (!planVersionId)
+            return false;
+        const row = this.db.prepare(`
+            SELECT COUNT(*) AS count
+            FROM billing_price_mappings
+            WHERE tenant_id = ?
+              AND plan_version_id = ?
+              AND active = 1
+              AND pricing_type = 'free'
+        `).get(this.tenantId, planVersionId);
+        return Number(row?.count || 0) > 0;
+    }
+    planVersionIsTrialEligible(planVersionIdRaw) {
+        const planVersionId = String(planVersionIdRaw || '').trim();
+        if (!planVersionId)
+            return false;
+        return this.getPlanVersionSnapshot(planVersionId).trialDays > 0;
+    }
     tryGetDefaultPlanVersionByPlanId(planIdRaw) {
         const planId = String(planIdRaw || '').trim().toLowerCase();
         if (!planId)
@@ -522,51 +629,169 @@ export class PlanEntitlementService {
             throw error;
         }
     }
-    resolveRegistrationPlanAssignment(selectedPlanVersionIdRaw) {
-        const selectedPlanVersionId = String(selectedPlanVersionIdRaw || '').trim();
-        if (selectedPlanVersionId) {
-            const row = this.db.prepare(`
-                SELECT v.plan_version_id, v.plan_id, COALESCE(p.status, 'active') AS plan_status
-                FROM plan_versions v
-                JOIN plan_catalog p ON p.tenant_id = v.tenant_id AND p.plan_id = v.plan_id
-                WHERE v.tenant_id = ? AND v.plan_version_id = ?
-                LIMIT 1
-            `).get(this.tenantId, selectedPlanVersionId);
-            if (!row?.plan_version_id || !row.plan_id) {
-                throw new TaskforceRuleError(`Selected signup plan version "${selectedPlanVersionId}" was not found.`, 400, 'SIGNUP_PLAN_VERSION_NOT_FOUND', { planVersionId: selectedPlanVersionId });
+    tryGetImplicitFreeOnboardingPlanVersion() {
+        const rows = this.db.prepare(`
+            SELECT DISTINCT v.plan_version_id
+            FROM plan_versions v
+            JOIN plan_catalog p
+              ON p.tenant_id = v.tenant_id
+             AND p.plan_id = v.plan_id
+            JOIN billing_price_mappings bpm
+              ON bpm.tenant_id = v.tenant_id
+             AND bpm.plan_version_id = v.plan_version_id
+            WHERE v.tenant_id = ?
+              AND COALESCE(p.status, 'active') = 'active'
+              AND bpm.active = 1
+              AND bpm.pricing_type = 'free'
+            ORDER BY v.is_default DESC, p.updated_at DESC, p.created_at DESC, v.version_number DESC, v.created_at DESC
+        `).all(this.tenantId);
+        for (const row of rows) {
+            const planVersionId = String(row.plan_version_id || '').trim();
+            if (!planVersionId)
+                continue;
+            const version = this.getPlanVersionSnapshot(planVersionId);
+            if (!this.isTeamPlanVersion(version)) {
+                return version;
             }
-            if (String(row.plan_status || '').trim().toLowerCase() !== 'active') {
-                throw new TaskforceRuleError(`Selected signup plan version "${selectedPlanVersionId}" belongs to a disabled plan.`, 400, 'SIGNUP_PLAN_NOT_ENABLED', {
-                    planVersionId: selectedPlanVersionId,
+        }
+        return null;
+    }
+    getOnboardingPolicy() {
+        const billing = this.deps.readGlobalConfig().billing || {};
+        const policy = billing.onboardingPolicy && typeof billing.onboardingPolicy === 'object'
+            ? billing.onboardingPolicy
+            : null;
+        if (policy?.mode === 'require_plan_selection'
+            || policy?.mode === 'auto_grant_free'
+            || policy?.mode === 'auto_start_trial') {
+            return {
+                mode: policy.mode,
+                planVersionId: typeof policy.planVersionId === 'string'
+                    ? (policy.planVersionId.trim() || null)
+                    : null
+            };
+        }
+        const implicitFreeVersion = this.tryGetImplicitFreeOnboardingPlanVersion();
+        if (implicitFreeVersion) {
+            return {
+                mode: 'auto_grant_free',
+                planVersionId: implicitFreeVersion.planVersionId
+            };
+        }
+        return {
+            mode: 'require_plan_selection',
+            planVersionId: null
+        };
+    }
+    validateOnboardingPolicy(input) {
+        const current = this.getOnboardingPolicy();
+        const mode = input?.mode === 'auto_grant_free' || input?.mode === 'auto_start_trial'
+            ? input.mode
+            : input?.mode === 'require_plan_selection'
+                ? 'require_plan_selection'
+                : current.mode;
+        const planVersionId = input?.planVersionId !== undefined
+            ? (typeof input.planVersionId === 'string' ? input.planVersionId.trim() || null : null)
+            : current.planVersionId;
+        if (mode === 'require_plan_selection') {
+            return { valid: true };
+        }
+        if (!planVersionId) {
+            return {
+                valid: false,
+                code: 'ONBOARDING_PLAN_VERSION_REQUIRED',
+                message: 'An onboarding plan version is required for the selected onboarding mode.'
+            };
+        }
+        const row = this.db.prepare(`
+            SELECT v.plan_version_id, v.plan_id, COALESCE(p.status, 'active') AS plan_status
+            FROM plan_versions v
+            JOIN plan_catalog p ON p.tenant_id = v.tenant_id AND p.plan_id = v.plan_id
+            WHERE v.tenant_id = ? AND v.plan_version_id = ?
+            LIMIT 1
+        `).get(this.tenantId, planVersionId);
+        if (!row?.plan_version_id || !row.plan_id) {
+            return {
+                valid: false,
+                code: 'ONBOARDING_PLAN_VERSION_NOT_FOUND',
+                message: `Configured onboarding plan version "${planVersionId}" was not found.`,
+                details: { planVersionId }
+            };
+        }
+        if (String(row.plan_status || '').trim().toLowerCase() !== 'active') {
+            return {
+                valid: false,
+                code: 'ONBOARDING_PLAN_NOT_ENABLED',
+                message: `Configured onboarding plan version "${planVersionId}" belongs to a disabled plan.`,
+                details: {
+                    planVersionId,
                     planId: String(row.plan_id)
-                });
-            }
+                }
+            };
+        }
+        if (mode === 'auto_grant_free' && !this.planVersionHasActiveFreePricing(planVersionId)) {
+            return {
+                valid: false,
+                code: 'ONBOARDING_PLAN_MUST_BE_FREE',
+                message: `Configured onboarding plan version "${planVersionId}" does not have active free pricing.`,
+                details: {
+                    planVersionId,
+                    planId: String(row.plan_id)
+                }
+            };
+        }
+        if (mode === 'auto_start_trial' && !this.planVersionIsTrialEligible(planVersionId)) {
+            return {
+                valid: false,
+                code: 'ONBOARDING_PLAN_TRIAL_REQUIRED',
+                message: `Configured onboarding plan version "${planVersionId}" is not trial eligible.`,
+                details: {
+                    planVersionId,
+                    planId: String(row.plan_id)
+                }
+            };
+        }
+        return { valid: true };
+    }
+    resolveRegistrationOnboardingOutcome(selectedPlanVersionIdRaw) {
+        const selectedPlanVersionId = String(selectedPlanVersionIdRaw || '').trim();
+        if (selectedPlanVersionId) {
+            const planVersion = this.getPlanVersionSnapshot(selectedPlanVersionId);
+            const commercialState = this.planVersionHasActiveFreePricing(planVersion.planVersionId)
+                ? 'active'
+                : 'checkout_pending';
             return {
                 requiresPlanSelection: false,
-                planVersionId: String(row.plan_version_id),
-                planId: String(row.plan_id)
+                checkoutPending: commercialState === 'checkout_pending',
+                commercialState,
+                planVersionId: planVersion.planVersionId,
+                planId: planVersion.planId
             };
         }
-        const signupSettings = this.getSignupMonetizationSettings();
-        if (signupSettings.strategy === 'plan_selection_required') {
+        const onboardingPolicy = this.getOnboardingPolicy();
+        const validation = this.validateOnboardingPolicy(onboardingPolicy);
+        if (!validation.valid) {
+            throw new TaskforceRuleError(validation.message || 'Onboarding policy is misconfigured.', 500, validation.code || 'ONBOARDING_POLICY_INVALID', validation.details);
+        }
+        if (onboardingPolicy.mode === 'require_plan_selection') {
             return {
                 requiresPlanSelection: true,
+                checkoutPending: false,
+                commercialState: 'pending_plan_selection',
                 planVersionId: null,
                 planId: null
             };
         }
-        const validation = this.validateSignupMonetizationSettings(signupSettings);
-        if (!validation.valid) {
-            throw new TaskforceRuleError(validation.message || 'Signup monetization is misconfigured.', 500, validation.code || 'SIGNUP_MONETIZATION_MISCONFIGURED', validation.details);
-        }
-        const configuredVersion = signupSettings.strategy === 'auto_assign_default' && signupSettings.defaultSignupPlanVersionId
-            ? this.getPlanVersionSnapshot(signupSettings.defaultSignupPlanVersionId)
+        const configuredVersion = onboardingPolicy.planVersionId
+            ? this.getPlanVersionSnapshot(onboardingPolicy.planVersionId)
             : null;
         if (!configuredVersion) {
-            throw new TaskforceRuleError('Default signup plan version is required when signup strategy is auto-assign default.', 500, 'SIGNUP_PLAN_VERSION_REQUIRED');
+            throw new TaskforceRuleError('Configured onboarding plan version is required.', 500, 'ONBOARDING_PLAN_VERSION_REQUIRED');
         }
         return {
             requiresPlanSelection: false,
+            checkoutPending: false,
+            commercialState: onboardingPolicy.mode === 'auto_start_trial' ? 'trialing' : 'active',
             planVersionId: configuredVersion.planVersionId,
             planId: configuredVersion.planId
         };
@@ -578,14 +803,22 @@ export class PlanEntitlementService {
         const planId = typeof options?.planId === 'string'
             ? options.planId.trim().toLowerCase()
             : '';
+        const shouldUpdateEffectiveUntil = options ? Object.prototype.hasOwnProperty.call(options, 'effectiveUntil') : false;
+        const effectiveUntil = shouldUpdateEffectiveUntil
+            ? (typeof options?.effectiveUntil === 'string' ? options.effectiveUntil : null)
+            : null;
         this.db.prepare(`
-            INSERT INTO user_billing (user_id, tenant_id, entitlement_state, tier, created_at, updated_at)
-            VALUES (?, ?, ?, ?, ?, ?)
+            INSERT INTO user_billing (user_id, tenant_id, entitlement_state, tier, effective_until, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
             ON CONFLICT (user_id) DO UPDATE SET
                 entitlement_state = excluded.entitlement_state,
                 tier = excluded.tier,
+                effective_until = CASE
+                    WHEN ? THEN excluded.effective_until
+                    ELSE user_billing.effective_until
+                END,
                 updated_at = excluded.updated_at
-        `).run(userId, this.tenantId, entitlementState, planId, now, now);
+        `).run(userId, this.tenantId, entitlementState, planId, effectiveUntil, now, now, shouldUpdateEffectiveUntil ? 1 : 0);
     }
     getUserEntitlement(userId) {
         const account = this.getAccountEntitlement(userId);
@@ -616,88 +849,55 @@ export class PlanEntitlementService {
         if (!normalizedAccountId) {
             throw new TaskforceRuleError('accountId is required', 400, 'ACCOUNT_ID_REQUIRED');
         }
-        const signupSettings = this.getSignupMonetizationSettings();
-        const validation = this.validateSignupMonetizationSettings(signupSettings);
+        const onboardingPolicy = this.getOnboardingPolicy();
+        const validation = this.validateOnboardingPolicy(onboardingPolicy);
         const entitlement = this.tryGetAccountEntitlement(normalizedAccountId);
-        if (entitlement && this.isEntitlementStateAllowed(entitlement.state)) {
+        if (!entitlement) {
+            return !validation.valid
+                ? this.buildBlockedAccessStatus({
+                    gate: 'misconfigured',
+                    message: validation.message || 'Onboarding policy is misconfigured.',
+                    entitlement: null
+                })
+                : this.buildBlockedAccessStatus({
+                    gate: 'missing_entitlement',
+                    message: 'No entitlement is linked to this account.',
+                    entitlement: null
+                });
+        }
+        if (this.isEntitlementStateAllowed(entitlement.state)) {
             return {
                 gate: 'ok',
                 hasEntitlement: true,
                 canAccessApp: true,
                 canAccessPlans: true,
-                signupMonetizationStrategy: signupSettings.strategy,
                 planSelectionRequired: false,
                 message: null,
                 entitlement
             };
         }
-        if (entitlement) {
-            return {
-                gate: 'missing_entitlement',
-                hasEntitlement: true,
-                canAccessApp: false,
-                canAccessPlans: true,
-                signupMonetizationStrategy: signupSettings.strategy,
-                planSelectionRequired: false,
-                message: entitlement.state === 'suspended'
-                    ? 'Your subscription is suspended. Update billing to continue.'
-                    : 'Your plan is inactive. Choose a plan to continue.',
-                entitlement
-            };
-        }
-        if (signupSettings.strategy === 'plan_selection_required') {
-            const billingRow = this.db.prepare(`
-                SELECT entitlement_state
-                FROM user_billing
-                WHERE tenant_id = ? AND user_id = ?
-                LIMIT 1
-            `).get(this.tenantId, normalizedAccountId);
-            const billingState = String(billingRow?.entitlement_state || '').trim().toLowerCase();
-            if (billingState === 'pending_plan_selection') {
-                return {
-                    gate: 'plan_selection_required',
-                    hasEntitlement: false,
-                    canAccessApp: false,
-                    canAccessPlans: true,
-                    signupMonetizationStrategy: signupSettings.strategy,
-                    planSelectionRequired: true,
-                    message: 'Choose a plan to continue.',
-                    entitlement: null
-                };
-            }
-            return {
+        if (entitlement.state === 'pending_plan_selection') {
+            return this.buildBlockedAccessStatus({
                 gate: 'plan_selection_required',
-                hasEntitlement: false,
-                canAccessApp: false,
-                canAccessPlans: true,
-                signupMonetizationStrategy: signupSettings.strategy,
-                planSelectionRequired: true,
                 message: 'Choose a plan to continue.',
-                entitlement: null
-            };
+                entitlement,
+                planSelectionRequired: true
+            });
         }
-        if (!validation.valid) {
-            return {
-                gate: 'misconfigured',
-                hasEntitlement: false,
-                canAccessApp: false,
-                canAccessPlans: true,
-                signupMonetizationStrategy: signupSettings.strategy,
-                planSelectionRequired: false,
-                message: validation.message || 'Signup monetization is misconfigured.',
-                entitlement: null
-            };
+        if (entitlement.state === 'checkout_pending') {
+            return this.buildBlockedAccessStatus({
+                gate: 'checkout_pending',
+                message: 'Complete checkout to continue.',
+                entitlement
+            });
         }
-        return {
+        return this.buildBlockedAccessStatus({
             gate: 'missing_entitlement',
-            hasEntitlement: false,
-            canAccessApp: false,
-            canAccessPlans: true,
-            signupMonetizationStrategy: signupSettings.strategy,
-            planSelectionRequired: false,
-            message: 'No entitlement is linked to this account.',
-            entitlement: null
-        };
+            message: entitlement.state === 'suspended'
+                ? 'Your subscription is suspended. Update billing to continue.'
+                : 'Your plan is inactive. Choose a plan to continue.',
+            entitlement
+        });
     }
     getEffectivePlanVersion(accountId) {
         const normalizedAccountId = String(accountId || '').trim();
@@ -749,12 +949,7 @@ export class PlanEntitlementService {
         if (!normalizedAccountId) {
             throw new TaskforceRuleError('accountId is required', 400, 'ACCOUNT_ID_REQUIRED');
         }
-        const row = this.db.prepare(`
-            SELECT account_id, plan_version_id, entitlement_state, effective_at, effective_until
-            FROM account_entitlements
-            WHERE tenant_id = ? AND account_id = ?
-            LIMIT 1
-        `).get(this.tenantId, normalizedAccountId);
+        const row = this.normalizeExpiredCheckoutPendingRow(normalizedAccountId);
         if (!row?.account_id || !row.plan_version_id) {
             throw new TaskforceRuleError('Entitlement not found', 404, 'ENTITLEMENT_NOT_FOUND');
         }
@@ -847,25 +1042,15 @@ export class PlanEntitlementService {
         }
         const normalizedMode = String(mode || '').trim().toLowerCase() === 'team' ? 'team' : 'personal';
         const targetVersion = this.getDefaultPlanVersionByMode(normalizedMode);
-        const now = new Date().toISOString();
-        this.db.prepare(`
-            INSERT INTO user_billing (user_id, tenant_id, entitlement_state, tier, created_at, updated_at)
-            VALUES (?, ?, ?, ?, ?, ?)
-            ON CONFLICT (user_id) DO UPDATE SET
-                entitlement_state = excluded.entitlement_state,
-                tier = excluded.tier,
-                updated_at = excluded.updated_at
-        `).run(normalizedUserId, this.tenantId, 'active', targetVersion.planId, now, now);
-        const planVersionId = targetVersion.planVersionId;
         const entitlementState = 'active';
-        this.upsertCanonicalEntitlementRecord({
+        this.transitionCanonicalCommercialState({
             accountId: normalizedUserId,
-            planVersionId,
+            planVersionId: targetVersion.planVersionId,
             state: entitlementState,
-            effectiveAt: now,
+            effectiveAt: new Date().toISOString(),
+            billingMirrorPlanId: targetVersion.planId,
+            source: 'legacy-plan-mode',
             updatedBy: 'legacy-plan-mode',
-            createdAt: now,
-            updatedAt: now
         });
         return normalizedMode;
     }
@@ -882,76 +1067,18 @@ export class PlanEntitlementService {
             entitlementState: 'active'
         };
     }
-    // ─── Signup monetization settings ─────────────────────────────────────────
-    getSignupMonetizationSettings() {
-        const auth = this.deps.readGlobalConfig().auth || {};
-        return {
-            strategy: auth.signupMonetizationStrategy === 'plan_selection_required'
-                ? 'plan_selection_required'
-                : 'auto_assign_default',
-            defaultSignupPlanVersionId: typeof auth.defaultSignupPlanVersionId === 'string'
-                ? (auth.defaultSignupPlanVersionId.trim() || null)
-                : null
-        };
-    }
-    validateSignupMonetizationSettings(input) {
-        const current = this.getSignupMonetizationSettings();
-        const strategy = input?.strategy === 'plan_selection_required'
-            ? 'plan_selection_required'
-            : input?.strategy === 'auto_assign_default'
-                ? 'auto_assign_default'
-                : current.strategy;
-        const defaultSignupPlanVersionId = input?.defaultSignupPlanVersionId !== undefined
-            ? (typeof input.defaultSignupPlanVersionId === 'string' ? input.defaultSignupPlanVersionId.trim() || null : null)
-            : current.defaultSignupPlanVersionId;
-        if (strategy === 'plan_selection_required') {
-            return { valid: true };
-        }
-        if (!defaultSignupPlanVersionId) {
-            return {
-                valid: false,
-                code: 'SIGNUP_PLAN_VERSION_REQUIRED',
-                message: 'Default signup plan version is required when signup strategy is auto-assign default.'
-            };
-        }
-        const row = this.db.prepare(`
-            SELECT v.plan_version_id, v.plan_id, COALESCE(p.status, 'active') AS plan_status
-            FROM plan_versions v
-            JOIN plan_catalog p ON p.tenant_id = v.tenant_id AND p.plan_id = v.plan_id
-            WHERE v.tenant_id = ? AND v.plan_version_id = ?
-            LIMIT 1
-        `).get(this.tenantId, defaultSignupPlanVersionId);
-        if (!row?.plan_version_id || !row.plan_id) {
-            return {
-                valid: false,
-                code: 'SIGNUP_PLAN_VERSION_NOT_FOUND',
-                message: `Configured default signup plan version "${defaultSignupPlanVersionId}" was not found.`,
-                details: { defaultSignupPlanVersionId }
-            };
-        }
-        if (String(row.plan_status || '').trim().toLowerCase() !== 'active') {
-            return {
-                valid: false,
-                code: 'SIGNUP_PLAN_NOT_ENABLED',
-                message: `Configured default signup plan version "${defaultSignupPlanVersionId}" belongs to a disabled plan.`,
-                details: {
-                    defaultSignupPlanVersionId,
-                    planId: String(row.plan_id)
-                }
-            };
-        }
-        return { valid: true };
-    }
     // ─── Plan catalog admin ───────────────────────────────────────────────────
     isValidEntitlementTransition(fromState, toState) {
         if (fromState === toState)
             return true;
         const allowed = {
+            pending_plan_selection: ['checkout_pending', 'trialing', 'active', 'canceled'],
+            checkout_pending: ['pending_plan_selection', 'active', 'trialing', 'canceled'],
             trialing: ['active', 'grace', 'canceled'],
             active: ['grace', 'suspended', 'canceled'],
             grace: ['active', 'suspended', 'canceled'],
             suspended: ['active', 'canceled'],
-            canceled: ['trialing', 'active']
+            canceled: ['pending_plan_selection', 'checkout_pending', 'trialing', 'active']
         };
         return allowed[fromState].includes(toState);
     }
@@ -1358,12 +1485,13 @@ export class PlanEntitlementService {
         const effectiveAt = input.effectiveAt === undefined ? (before?.effectiveAt || null) : (input.effectiveAt ? String(input.effectiveAt) : null);
         const effectiveUntil = input.effectiveUntil === undefined ? (before?.effectiveUntil || null) : (input.effectiveUntil ? String(input.effectiveUntil) : null);
         const now = new Date().toISOString();
-        this.upsertCanonicalEntitlementRecord({
+        this.transitionCanonicalCommercialState({
             accountId,
             planVersionId: nextPlanVersionId,
             state: nextState,
             effectiveAt,
             effectiveUntil,
+            source: 'admin',
             updatedBy: String(input.actorUserId || 'system').trim() || 'system',
             createdAt: before?.effectiveAt || now,
             updatedAt: now