@taskforcehq/taskforce 0.3.304 → 0.3.306

package/dist/core/PlanEntitlementService.js

@@ -1,8 +1,9 @@
 import { TaskforceRuleError } from './types.js';
-import { DOCUMENT_CLOUD_STORAGE_FEATURE_KEY, WORKSPACES_FEATURE_KEY, DOCUMENT_CLOUD_STORAGE_LIMIT_CONFIG_KEY, WORKSPACES_LIMIT_CONFIG_KEY, DEFAULT_PLAN_FEATURE_CATALOG, PLAN_FEATURE_DEPENDENCIES, generateUuidV7, } from './shared.js';
+import { DOCUMENT_CLOUD_STORAGE_FEATURE_KEY, WORKSPACES_FEATURE_KEY, AI_PROFILES_FEATURE_KEY, DOCUMENT_CLOUD_STORAGE_LIMIT_CONFIG_KEY, WORKSPACES_LIMIT_CONFIG_KEY, AI_PROFILES_LIMIT_CONFIG_KEY, DEFAULT_PLAN_FEATURE_CATALOG, PLAN_FEATURE_DEPENDENCIES, generateUuidV7, } from './shared.js';
 const LEGACY_REMOVED_PLAN_FEATURE_KEYS = Object.freeze([
     'documents.workspace_access'
 ]);
+const LEGACY_WORKSPACES_FEATURE_KEY = 'workspace.switching';
 /**
  * Handles all plan catalog, plan version, and account entitlement logic.
  * Extracted from Taskforce.ts to reduce monolith size.
@@ -32,6 +33,45 @@ export class PlanEntitlementService {
             return {};
         }
     }
+    normalizeOptionalCatalogMarketingCopy(raw) {
+        const value = String(raw ?? '').trim();
+        return value || null;
+    }
+    canonicalizePlanFeatureKey(raw) {
+        const featureKey = String(raw || '').trim();
+        return featureKey === LEGACY_WORKSPACES_FEATURE_KEY ? WORKSPACES_FEATURE_KEY : featureKey;
+    }
+    normalizeOptionalCatalogDisplayOrder(raw) {
+        if (raw === null || raw === undefined || raw === '')
+            return null;
+        const numeric = Number(raw);
+        if (!Number.isFinite(numeric))
+            return null;
+        return Math.max(0, Math.floor(numeric));
+    }
+    listPlanFeatureCatalogOverrideMap() {
+        const rows = this.db.prepare(`
+            SELECT feature_key, public_label, public_description, public_display_order
+            FROM plan_feature_catalog_overrides
+            WHERE tenant_id = ?
+        `).all(this.tenantId);
+        const overrides = new Map();
+        for (const row of rows) {
+            const originalFeatureKey = String(row.feature_key || '').trim();
+            const featureKey = this.canonicalizePlanFeatureKey(originalFeatureKey);
+            if (!featureKey)
+                continue;
+            if (featureKey === WORKSPACES_FEATURE_KEY && originalFeatureKey === LEGACY_WORKSPACES_FEATURE_KEY && overrides.has(featureKey)) {
+                continue;
+            }
+            overrides.set(featureKey, {
+                publicLabel: this.normalizeOptionalCatalogMarketingCopy(row.public_label),
+                publicDescription: this.normalizeOptionalCatalogMarketingCopy(row.public_description),
+                publicDisplayOrder: this.normalizeOptionalCatalogDisplayOrder(row.public_display_order)
+            });
+        }
+        return overrides;
+    }
     // ─── Normalizers ─────────────────────────────────────────────────────────
     normalizeEntitlementState(value) {
         const normalized = String(value || '').trim().toLowerCase();
@@ -91,9 +131,10 @@ export class PlanEntitlementService {
         return nextMetadata;
     }
     sanitizePlanFeatureConfig(featureKey, access, config) {
-        if (featureKey === 'collaboration.seat_limit')
+        const normalizedFeatureKey = this.canonicalizePlanFeatureKey(featureKey);
+        if (normalizedFeatureKey === 'collaboration.seat_limit')
             return {};
-        if (featureKey === DOCUMENT_CLOUD_STORAGE_FEATURE_KEY) {
+        if (normalizedFeatureKey === DOCUMENT_CLOUD_STORAGE_FEATURE_KEY) {
             const limit = this.readPositiveIntegerConfig(config[DOCUMENT_CLOUD_STORAGE_LIMIT_CONFIG_KEY], 1);
             if (access === 'limited') {
                 return {
@@ -107,12 +148,21 @@ export class PlanEntitlementService {
             }
             return {};
         }
-        if (featureKey === WORKSPACES_FEATURE_KEY) {
+        if (normalizedFeatureKey === WORKSPACES_FEATURE_KEY) {
             const limit = this.readPositiveIntegerConfig(config[WORKSPACES_LIMIT_CONFIG_KEY], 1);
             return {
                 [WORKSPACES_LIMIT_CONFIG_KEY]: limit ?? 1
             };
         }
+        if (normalizedFeatureKey === AI_PROFILES_FEATURE_KEY) {
+            if (access === 'limited') {
+                const limit = this.readPositiveIntegerConfig(config[AI_PROFILES_LIMIT_CONFIG_KEY], 1);
+                return {
+                    [AI_PROFILES_LIMIT_CONFIG_KEY]: limit ?? 1
+                };
+            }
+            return {};
+        }
         return config && typeof config === 'object' ? { ...config } : {};
     }
     isEntitlementStateAllowed(state) {
@@ -135,21 +185,25 @@ export class PlanEntitlementService {
             LIMIT 1
         `).get(this.tenantId, accountId);
     }
-    normalizeExpiredCheckoutPendingRow(accountId) {
+    normalizeExpiredLifecycleRow(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)) {
+        if (!this.isIsoTimestampExpired(row.effective_until || null)) {
+            return row;
+        }
+        if (currentState !== 'checkout_pending' && currentState !== 'trialing') {
             return row;
         }
+        const updatedBy = currentState === 'trialing' ? 'trial-expired' : 'checkout-expired';
         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);
+        `).run('pending_plan_selection', updatedBy, now, this.tenantId, accountId);
         this.createUserBillingRecord(accountId, {
             entitlementState: 'pending_plan_selection',
             planId: null,
@@ -160,6 +214,20 @@ export class PlanEntitlementService {
     isBillingConfirmedTransitionSource(source) {
         return source === 'checkout-confirm' || source === 'stripe-webhook';
     }
+    countWorkspaceStorageUsageBytes(workspaceIdRaw) {
+        const workspaceId = String(workspaceIdRaw || '').trim();
+        if (!workspaceId)
+            return 0;
+        const row = this.db.prepare(`
+            SELECT COALESCE(SUM(size_bytes), 0) AS total_bytes
+            FROM workspace_assets
+            WHERE tenant_id = ?
+              AND workspace_id = ?
+              AND deleted_at IS NULL
+        `).get(this.tenantId, workspaceId);
+        const total = Number(row?.total_bytes || 0);
+        return Number.isFinite(total) ? Math.max(0, Math.floor(total)) : 0;
+    }
     resolveCanonicalTransitionSource(updatedBy) {
         if (updatedBy === 'registration'
             || updatedBy === 'checkout-start'
@@ -232,8 +300,48 @@ export class PlanEntitlementService {
     normalizeLegacyPlanDataIfNeeded() {
         this.migrateLegacySeatLimitFeatureConfigToVersionSeatLimit();
         this.normalizeLegacyBillingMirrorRows();
+        this.renameLegacyWorkspacesFeatureKey();
         this.removeLegacyPlanFeatureRows();
     }
+    renameLegacyWorkspacesFeatureKey() {
+        const now = new Date().toISOString();
+        const tx = this.db.transaction(() => {
+            this.db.prepare(`
+                DELETE FROM plan_feature_matrix
+                WHERE tenant_id = ?
+                  AND feature_key = ?
+                  AND EXISTS (
+                      SELECT 1
+                      FROM plan_feature_matrix canonical
+                      WHERE canonical.tenant_id = plan_feature_matrix.tenant_id
+                        AND canonical.plan_version_id = plan_feature_matrix.plan_version_id
+                        AND canonical.feature_key = ?
+                  )
+            `).run(this.tenantId, LEGACY_WORKSPACES_FEATURE_KEY, WORKSPACES_FEATURE_KEY);
+            this.db.prepare(`
+                UPDATE plan_feature_matrix
+                SET feature_key = ?, updated_at = ?
+                WHERE tenant_id = ? AND feature_key = ?
+            `).run(WORKSPACES_FEATURE_KEY, now, this.tenantId, LEGACY_WORKSPACES_FEATURE_KEY);
+            this.db.prepare(`
+                DELETE FROM plan_feature_catalog_overrides
+                WHERE tenant_id = ?
+                  AND feature_key = ?
+                  AND EXISTS (
+                      SELECT 1
+                      FROM plan_feature_catalog_overrides canonical
+                      WHERE canonical.tenant_id = plan_feature_catalog_overrides.tenant_id
+                        AND canonical.feature_key = ?
+                  )
+            `).run(this.tenantId, LEGACY_WORKSPACES_FEATURE_KEY, WORKSPACES_FEATURE_KEY);
+            this.db.prepare(`
+                UPDATE plan_feature_catalog_overrides
+                SET feature_key = ?, updated_at = ?
+                WHERE tenant_id = ? AND feature_key = ?
+            `).run(WORKSPACES_FEATURE_KEY, now, this.tenantId, LEGACY_WORKSPACES_FEATURE_KEY);
+        });
+        tx();
+    }
     removeLegacyPlanFeatureRows() {
         const featureKeys = [...LEGACY_REMOVED_PLAN_FEATURE_KEYS];
         if (featureKeys.length < 1)
@@ -524,7 +632,9 @@ export class PlanEntitlementService {
             return { limit: 1, feature: null };
         }
         const entitlement = this.getAccountEntitlement(normalizedUserId);
-        const feature = entitlement.version.features[WORKSPACES_FEATURE_KEY] || null;
+        const feature = entitlement.version.features[WORKSPACES_FEATURE_KEY]
+            || entitlement.version.features[LEGACY_WORKSPACES_FEATURE_KEY]
+            || null;
         if (!feature || feature.access === 'disabled') {
             return { limit: 1, feature };
         }
@@ -534,6 +644,38 @@ export class PlanEntitlementService {
         }
         return { limit: null, feature };
     }
+    resolveAiProfileLimitForWorkspace(workspaceId) {
+        const normalizedWorkspaceId = String(workspaceId || '').trim();
+        if (!normalizedWorkspaceId) {
+            return { limit: null, feature: null };
+        }
+        const accountId = this.deps.getWorkspaceOwnerUserId(normalizedWorkspaceId);
+        if (!accountId) {
+            return { limit: null, feature: null };
+        }
+        let entitlement;
+        try {
+            entitlement = this.getAccountEntitlement(accountId);
+        }
+        catch (error) {
+            if (error instanceof TaskforceRuleError && error.code === 'ENTITLEMENT_NOT_FOUND') {
+                return { limit: null, feature: null };
+            }
+            throw error;
+        }
+        const feature = entitlement.version.features[AI_PROFILES_FEATURE_KEY] || null;
+        if (!feature || feature.access === 'disabled') {
+            return { limit: null, feature };
+        }
+        const configuredLimit = this.readPositiveIntegerConfig(feature.config?.[AI_PROFILES_LIMIT_CONFIG_KEY], 1);
+        if (configuredLimit !== null) {
+            return { limit: configuredLimit, feature };
+        }
+        if (feature.access === 'limited') {
+            return { limit: 1, feature };
+        }
+        return { limit: null, feature };
+    }
     planHasAnyActivePricing(planIdRaw) {
         const planId = String(planIdRaw || '').trim().toLowerCase();
         if (!planId)
@@ -629,32 +771,15 @@ export class PlanEntitlementService {
             throw error;
         }
     }
-    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;
-            }
-        }
-        return null;
+    getOnboardingPlanSnapshot(planIdRaw) {
+        const planId = String(planIdRaw || '').trim().toLowerCase();
+        if (!planId)
+            return null;
+        const plan = this.listPlanCatalog().find((entry) => entry.planId === planId) || null;
+        if (!plan)
+            return null;
+        const defaultVersion = this.listPlanVersions(planId).find((version) => version.isDefault) || null;
+        return { plan, defaultVersion };
     }
     getOnboardingPolicy() {
         const billing = this.deps.readGlobalConfig().billing || {};
@@ -664,23 +789,32 @@ export class PlanEntitlementService {
         if (policy?.mode === 'require_plan_selection'
             || policy?.mode === 'auto_grant_free'
             || policy?.mode === 'auto_start_trial') {
+            const rawPolicy = policy;
+            const explicitPlanId = typeof rawPolicy.planId === 'string'
+                ? (rawPolicy.planId.trim() || null)
+                : null;
+            const legacyPlanVersionId = typeof rawPolicy.planVersionId === 'string'
+                ? (rawPolicy.planVersionId.trim() || null)
+                : null;
+            const resolvedLegacyPlanId = !explicitPlanId && legacyPlanVersionId
+                ? (() => {
+                    const row = this.db.prepare(`
+                        SELECT plan_id
+                        FROM plan_versions
+                        WHERE tenant_id = ? AND plan_version_id = ?
+                        LIMIT 1
+                    `).get(this.tenantId, legacyPlanVersionId);
+                    return typeof row?.plan_id === 'string' ? (row.plan_id.trim() || null) : null;
+                })()
+                : null;
             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
+                planId: explicitPlanId || resolvedLegacyPlanId
             };
         }
         return {
             mode: 'require_plan_selection',
-            planVersionId: null
+            planId: null
         };
     }
     validateOnboardingPolicy(input) {
@@ -690,64 +824,58 @@ export class PlanEntitlementService {
             : 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;
+        const planId = input?.planId !== undefined
+            ? (typeof input.planId === 'string' ? input.planId.trim().toLowerCase() || null : null)
+            : current.planId;
         if (mode === 'require_plan_selection') {
             return { valid: true };
         }
-        if (!planVersionId) {
+        if (!planId) {
             return {
                 valid: false,
-                code: 'ONBOARDING_PLAN_VERSION_REQUIRED',
-                message: 'An onboarding plan version is required for the selected onboarding mode.'
+                code: 'ONBOARDING_PLAN_REQUIRED',
+                message: 'An onboarding plan 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) {
+        const onboardingPlan = this.getOnboardingPlanSnapshot(planId);
+        if (!onboardingPlan?.plan || !onboardingPlan.defaultVersion) {
             return {
                 valid: false,
-                code: 'ONBOARDING_PLAN_VERSION_NOT_FOUND',
-                message: `Configured onboarding plan version "${planVersionId}" was not found.`,
-                details: { planVersionId }
+                code: 'ONBOARDING_PLAN_NOT_FOUND',
+                message: `Configured onboarding plan "${planId}" was not found or has no default version.`,
+                details: { planId }
             };
         }
-        if (String(row.plan_status || '').trim().toLowerCase() !== 'active') {
+        if (onboardingPlan.plan.status !== 'active') {
             return {
                 valid: false,
                 code: 'ONBOARDING_PLAN_NOT_ENABLED',
-                message: `Configured onboarding plan version "${planVersionId}" belongs to a disabled plan.`,
+                message: `Configured onboarding plan "${planId}" is disabled.`,
                 details: {
-                    planVersionId,
-                    planId: String(row.plan_id)
+                    planId: onboardingPlan.plan.planId,
+                    planVersionId: onboardingPlan.defaultVersion.planVersionId
                 }
             };
         }
-        if (mode === 'auto_grant_free' && !this.planVersionHasActiveFreePricing(planVersionId)) {
+        if (mode === 'auto_grant_free' && !this.planVersionHasActiveFreePricing(onboardingPlan.defaultVersion.planVersionId)) {
             return {
                 valid: false,
                 code: 'ONBOARDING_PLAN_MUST_BE_FREE',
-                message: `Configured onboarding plan version "${planVersionId}" does not have active free pricing.`,
+                message: `Configured onboarding plan "${planId}" does not have active free pricing on its default version.`,
                 details: {
-                    planVersionId,
-                    planId: String(row.plan_id)
+                    planId: onboardingPlan.plan.planId,
+                    planVersionId: onboardingPlan.defaultVersion.planVersionId
                 }
             };
         }
-        if (mode === 'auto_start_trial' && !this.planVersionIsTrialEligible(planVersionId)) {
+        if (mode === 'auto_start_trial' && !this.planVersionIsTrialEligible(onboardingPlan.defaultVersion.planVersionId)) {
             return {
                 valid: false,
                 code: 'ONBOARDING_PLAN_TRIAL_REQUIRED',
-                message: `Configured onboarding plan version "${planVersionId}" is not trial eligible.`,
+                message: `Configured onboarding plan "${planId}" is not trial eligible on its default version.`,
                 details: {
-                    planVersionId,
-                    planId: String(row.plan_id)
+                    planId: onboardingPlan.plan.planId,
+                    planVersionId: onboardingPlan.defaultVersion.planVersionId
                 }
             };
         }
@@ -755,7 +883,12 @@ export class PlanEntitlementService {
     }
     resolveRegistrationOnboardingOutcome(selectedPlanVersionIdRaw) {
         const selectedPlanVersionId = String(selectedPlanVersionIdRaw || '').trim();
-        if (selectedPlanVersionId) {
+        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' && selectedPlanVersionId) {
             const planVersion = this.getPlanVersionSnapshot(selectedPlanVersionId);
             const commercialState = this.planVersionHasActiveFreePricing(planVersion.planVersionId)
                 ? 'active'
@@ -768,11 +901,6 @@ export class PlanEntitlementService {
                 planId: planVersion.planId
             };
         }
-        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,
@@ -782,11 +910,11 @@ export class PlanEntitlementService {
                 planId: null
             };
         }
-        const configuredVersion = onboardingPolicy.planVersionId
-            ? this.getPlanVersionSnapshot(onboardingPolicy.planVersionId)
+        const configuredVersion = onboardingPolicy.planId
+            ? this.getOnboardingPlanSnapshot(onboardingPolicy.planId)?.defaultVersion || null
             : null;
         if (!configuredVersion) {
-            throw new TaskforceRuleError('Configured onboarding plan version is required.', 500, 'ONBOARDING_PLAN_VERSION_REQUIRED');
+            throw new TaskforceRuleError('Configured onboarding plan is required.', 500, 'ONBOARDING_PLAN_REQUIRED');
         }
         return {
             requiresPlanSelection: false,
@@ -796,6 +924,26 @@ export class PlanEntitlementService {
             planId: configuredVersion.planId
         };
     }
+    listOnboardingPlanOptions() {
+        return this.listPlanCatalog()
+            .filter((plan) => plan.status === 'active')
+            .map((plan) => {
+            const defaultVersion = this.listPlanVersions(plan.planId).find((version) => version.isDefault) || null;
+            if (!defaultVersion)
+                return null;
+            return {
+                planId: plan.planId,
+                planDisplayName: plan.displayName || plan.planId,
+                defaultPlanVersionId: defaultVersion.planVersionId,
+                defaultVersionNumber: defaultVersion.versionNumber,
+                planStatus: plan.status,
+                supportsAutoGrantFree: this.planVersionHasActiveFreePricing(defaultVersion.planVersionId),
+                supportsAutoStartTrial: this.planVersionIsTrialEligible(defaultVersion.planVersionId)
+            };
+        })
+            .filter((option) => Boolean(option))
+            .sort((a, b) => a.planDisplayName.localeCompare(b.planDisplayName));
+    }
     // ─── Public billing methods ───────────────────────────────────────────────
     createUserBillingRecord(userId, options) {
         const now = new Date().toISOString();
@@ -844,6 +992,108 @@ export class PlanEntitlementService {
             throw error;
         }
     }
+    tryAutoHealLegacyPersonalFreeEntitlement(accountId, entitlement) {
+        if (entitlement.state !== 'canceled')
+            return null;
+        if (this.isTeamPlanVersion(entitlement.version))
+            return null;
+        const defaultPersonalVersion = this.tryGetDefaultPlanVersionByMode('personal');
+        if (!defaultPersonalVersion)
+            return null;
+        if (!this.planVersionHasActiveFreePricing(defaultPersonalVersion.planVersionId))
+            return null;
+        if (String(entitlement.planId || '').trim().toLowerCase() !== defaultPersonalVersion.planId)
+            return null;
+        if (entitlement.planVersionId === defaultPersonalVersion.planVersionId)
+            return null;
+        if (entitlement.version.versionNumber >= defaultPersonalVersion.versionNumber)
+            return null;
+        return this.transitionCanonicalCommercialState({
+            accountId,
+            planVersionId: defaultPersonalVersion.planVersionId,
+            state: 'active',
+            effectiveAt: entitlement.effectiveAt,
+            effectiveUntil: null,
+            billingMirrorPlanId: defaultPersonalVersion.planId,
+            source: 'system',
+            updatedBy: 'legacy-free-auto-heal',
+            createdAt: entitlement.effectiveAt
+        });
+    }
+    tryAutoHealCommercialEntitlementFromBillingMirror(accountId, entitlement) {
+        const currentState = entitlement ? this.normalizeEntitlementState(entitlement.state) : null;
+        if (currentState && this.isEntitlementStateAllowed(currentState))
+            return null;
+        if (currentState && currentState !== 'pending_plan_selection')
+            return null;
+        const billingRow = this.db.prepare(`
+            SELECT stripe_customer_id, stripe_subscription_id, stripe_price_id, stripe_status, entitlement_state, tier, effective_until
+            FROM user_billing
+            WHERE tenant_id = ? AND user_id = ?
+            LIMIT 1
+        `).get(this.tenantId, accountId);
+        const hasStripeLink = Boolean(String(billingRow?.stripe_customer_id || '').trim()
+            || String(billingRow?.stripe_subscription_id || '').trim());
+        if (!hasStripeLink)
+            return null;
+        if (this.isIsoTimestampExpired(billingRow?.effective_until || null))
+            return null;
+        const billingStatus = String(billingRow?.stripe_status || '').trim().toLowerCase();
+        const billingStateFromMirror = this.normalizeEntitlementState(billingRow?.entitlement_state);
+        const derivedBillingState = this.isEntitlementStateAllowed(billingStateFromMirror)
+            ? billingStateFromMirror
+            : (billingStatus === 'trialing' ? 'trialing'
+                : billingStatus === 'active' ? 'active'
+                    : billingStatus === 'past_due' ? 'grace'
+                        : null);
+        if (!derivedBillingState || !this.isEntitlementStateAllowed(derivedBillingState))
+            return null;
+        const stripePriceId = String(billingRow?.stripe_price_id || '').trim();
+        let healedPlanVersionId = '';
+        if (stripePriceId) {
+            const mappingRow = this.db.prepare(`
+                SELECT plan_version_id
+                FROM billing_price_mappings
+                WHERE tenant_id = ? AND stripe_price_id = ? AND active = 1
+                ORDER BY updated_at DESC, created_at DESC
+                LIMIT 1
+            `).get(this.tenantId, stripePriceId);
+            healedPlanVersionId = String(mappingRow?.plan_version_id || '').trim();
+        }
+        if (!healedPlanVersionId) {
+            const billingPlanId = String(billingRow?.tier || '').trim().toLowerCase();
+            if (!billingPlanId)
+                return null;
+            try {
+                healedPlanVersionId = this.getRequiredDefaultPlanVersion(billingPlanId).planVersionId;
+            }
+            catch {
+                return null;
+            }
+        }
+        let healedVersion;
+        try {
+            healedVersion = this.getPlanVersionSnapshot(healedPlanVersionId);
+        }
+        catch {
+            return null;
+        }
+        const effectiveAt = entitlement?.effectiveAt || new Date().toISOString();
+        console.info(`[Taskforce Billing] Auto-healing canonical entitlement from billing mirror for account=${accountId} `
+            + `previousState=${currentState || '(none)'} mirrorState=${billingStateFromMirror || '(none)'} stripeStatus=${billingStatus || '(none)'} `
+            + `planVersionId=${healedVersion.planVersionId} planId=${healedVersion.planId} stripePriceId=${stripePriceId || '(none)'}`);
+        return this.transitionCanonicalCommercialState({
+            accountId,
+            planVersionId: healedVersion.planVersionId,
+            state: derivedBillingState,
+            effectiveAt,
+            effectiveUntil: billingRow?.effective_until || null,
+            billingMirrorPlanId: healedVersion.planId,
+            source: 'backfill',
+            updatedBy: 'billing-mirror-auto-heal',
+            createdAt: effectiveAt
+        });
+    }
     getAccountAccessStatus(accountId) {
         const normalizedAccountId = String(accountId || '').trim();
         if (!normalizedAccountId) {
@@ -851,7 +1101,12 @@ export class PlanEntitlementService {
         }
         const onboardingPolicy = this.getOnboardingPolicy();
         const validation = this.validateOnboardingPolicy(onboardingPolicy);
-        const entitlement = this.tryGetAccountEntitlement(normalizedAccountId);
+        const currentEntitlement = this.tryGetAccountEntitlement(normalizedAccountId);
+        const entitlement = currentEntitlement
+            ? (this.tryAutoHealLegacyPersonalFreeEntitlement(normalizedAccountId, currentEntitlement)
+                || this.tryAutoHealCommercialEntitlementFromBillingMirror(normalizedAccountId, currentEntitlement)
+                || currentEntitlement)
+            : this.tryAutoHealCommercialEntitlementFromBillingMirror(normalizedAccountId, null);
         if (!entitlement) {
             return !validation.valid
                 ? this.buildBlockedAccessStatus({
@@ -949,7 +1204,7 @@ export class PlanEntitlementService {
         if (!normalizedAccountId) {
             throw new TaskforceRuleError('accountId is required', 400, 'ACCOUNT_ID_REQUIRED');
         }
-        const row = this.normalizeExpiredCheckoutPendingRow(normalizedAccountId);
+        const row = this.normalizeExpiredLifecycleRow(normalizedAccountId);
         if (!row?.account_id || !row.plan_version_id) {
             throw new TaskforceRuleError('Entitlement not found', 404, 'ENTITLEMENT_NOT_FOUND');
         }
@@ -989,6 +1244,24 @@ export class PlanEntitlementService {
         const remaining = limit === null ? null : Math.max(0, limit - used);
         return { used, limit, remaining };
     }
+    countAiProfileUsage(workspaceId) {
+        const normalizedWorkspaceId = String(workspaceId || '').trim();
+        if (!normalizedWorkspaceId) {
+            throw new TaskforceRuleError('workspaceId is required', 400, 'WORKSPACE_ID_REQUIRED');
+        }
+        const row = this.db.prepare(`
+            SELECT COUNT(*) AS c
+            FROM ai_profiles
+            WHERE tenant_id = ?
+              AND workspace_id = ?
+              AND archived_at IS NULL
+              AND seat_scope = 'cloud_metered'
+        `).get(this.tenantId, normalizedWorkspaceId);
+        const used = Math.max(0, Number(row?.c || 0));
+        const { limit } = this.resolveAiProfileLimitForWorkspace(normalizedWorkspaceId);
+        const remaining = limit === null ? null : Math.max(0, limit - used);
+        return { used, limit, remaining };
+    }
     assertSeatAvailable(workspaceId) {
         const seatUsage = this.countWorkspaceSeatUsage(workspaceId, { includeInvited: true });
         if (seatUsage.limit !== null && seatUsage.used >= seatUsage.limit) {
@@ -1026,6 +1299,19 @@ export class PlanEntitlementService {
             }
             return { allowed: true, reasonCode: 'OK', state: entitlement.state, seatUsage, feature };
         }
+        if (featureKey === DOCUMENT_CLOUD_STORAGE_FEATURE_KEY && feature.access === 'limited') {
+            const configuredLimitMb = this.readPositiveIntegerConfig(feature.config?.[DOCUMENT_CLOUD_STORAGE_LIMIT_CONFIG_KEY], 1) ?? 1;
+            const storageLimitBytes = configuredLimitMb * 1024 * 1024;
+            const rawRequestedBytes = input.context?.requestedBytes ?? input.context?.sizeBytes ?? input.context?.pendingSizeBytes;
+            const requestedBytesNumber = Number(rawRequestedBytes);
+            const requestedBytes = Number.isFinite(requestedBytesNumber)
+                ? Math.max(0, Math.floor(requestedBytesNumber))
+                : 0;
+            const usedBytes = this.countWorkspaceStorageUsageBytes(workspaceId);
+            if ((usedBytes + requestedBytes) > storageLimitBytes) {
+                return { allowed: false, reasonCode: 'UPLOAD_STORAGE_LIMIT_REACHED', state: entitlement.state, feature };
+            }
+        }
         return { allowed: true, reasonCode: 'OK', state: entitlement.state, feature };
     }
     getUserAccountPlanMode(userId) {
@@ -1067,6 +1353,20 @@ export class PlanEntitlementService {
             entitlementState: 'active'
         };
     }
+    resolveInviteAcceptanceDefaultEntitlement() {
+        const defaultPersonalVersion = this.tryGetDefaultPlanVersionByMode('personal', { allowFallback: true });
+        if (!defaultPersonalVersion)
+            return null;
+        if (this.isTeamPlanVersion(defaultPersonalVersion))
+            return null;
+        if (!this.planVersionHasActiveFreePricing(defaultPersonalVersion.planVersionId))
+            return null;
+        return {
+            planVersionId: defaultPersonalVersion.planVersionId,
+            planId: defaultPersonalVersion.planId,
+            commercialState: 'active'
+        };
+    }
     // ─── Plan catalog admin ───────────────────────────────────────────────────
     isValidEntitlementTransition(fromState, toState) {
         if (fromState === toState)
@@ -1094,6 +1394,7 @@ export class PlanEntitlementService {
     upsertPlanCatalog(input) {
         const planId = String(input.planId || '').trim().toLowerCase();
         const displayName = String(input.displayName || '').trim();
+        const description = String(input.description || '').trim() || null;
         const initialMode = String(input.initialMode || '').trim().toLowerCase() === 'team'
             ? 'team'
             : 'personal';
@@ -1119,7 +1420,7 @@ export class PlanEntitlementService {
         });
         const now = new Date().toISOString();
         const existing = this.db.prepare(`
-            SELECT plan_id, status
+            SELECT plan_id, status, description
             FROM plan_catalog
             WHERE tenant_id = ? AND plan_id = ?
             LIMIT 1
@@ -1136,13 +1437,14 @@ export class PlanEntitlementService {
                         : 'archived';
         const tx = this.db.transaction(() => {
             this.db.prepare(`
-                INSERT INTO plan_catalog (plan_id, tenant_id, display_name, status, created_at, updated_at)
-                VALUES (?, ?, ?, ?, ?, ?)
+                INSERT INTO plan_catalog (plan_id, tenant_id, display_name, description, status, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
                 ON CONFLICT (plan_id) DO UPDATE SET
                     display_name = excluded.display_name,
+                    description = excluded.description,
                     status = excluded.status,
                     updated_at = excluded.updated_at
-            `).run(planId, this.tenantId, displayName, status, now, now);
+            `).run(planId, this.tenantId, displayName, description, status, now, now);
             if (isNewPlan) {
                 this.db.prepare(`
                     INSERT INTO plan_versions (plan_version_id, tenant_id, plan_id, version_number, is_default, seat_limit, metadata_json, created_at, updated_at)
@@ -1168,11 +1470,11 @@ export class PlanEntitlementService {
         });
         tx();
         this.repairPlanDefaultVersionIfNeeded(planId);
-        return { planId, displayName, status };
+        return { planId, displayName, description, status };
     }
     listPlanCatalog() {
         const rows = this.db.prepare(`
-            SELECT plan_id, display_name, status, created_at, updated_at
+            SELECT plan_id, display_name, description, status, created_at, updated_at
             FROM plan_catalog
             WHERE tenant_id = ?
             ORDER BY updated_at DESC, created_at DESC
@@ -1180,21 +1482,76 @@ export class PlanEntitlementService {
         return rows.map((row) => ({
             planId: String(row.plan_id || ''),
             displayName: String(row.display_name || ''),
+            description: typeof row.description === 'string' && row.description.trim().length > 0 ? row.description.trim() : null,
             status: String(row.status || '').trim().toLowerCase() === 'archived' ? 'archived' : 'active',
             createdAt: String(row.created_at || ''),
             updatedAt: String(row.updated_at || '')
         }));
     }
     listPlanFeatureCatalog() {
+        const overrides = this.listPlanFeatureCatalogOverrideMap();
         return DEFAULT_PLAN_FEATURE_CATALOG.map((feature) => ({
             featureKey: feature.featureKey,
             label: feature.label,
             description: feature.description,
+            publicLabel: overrides.get(feature.featureKey)?.publicLabel ?? feature.publicLabel ?? null,
+            publicDescription: overrides.get(feature.featureKey)?.publicDescription ?? feature.publicDescription ?? null,
+            publicDisplayOrder: overrides.get(feature.featureKey)?.publicDisplayOrder ?? feature.publicDisplayOrder ?? null,
             allowedAccessModes: [...feature.allowedAccessModes],
             configTemplate: { ...feature.configTemplate },
             ...(feature.dependsOn?.length ? { dependsOn: [...feature.dependsOn] } : {})
         }));
     }
+    updatePlanFeatureCatalogMarketingCopy(input) {
+        const featureKey = this.canonicalizePlanFeatureKey(input.featureKey);
+        if (!featureKey)
+            throw new TaskforceRuleError('featureKey is required', 400, 'FEATURE_KEY_REQUIRED');
+        const catalogFeature = DEFAULT_PLAN_FEATURE_CATALOG.find((feature) => feature.featureKey === featureKey);
+        if (!catalogFeature)
+            throw new TaskforceRuleError('Unknown plan feature key', 404, 'PLAN_FEATURE_NOT_FOUND');
+        const publicLabel = this.normalizeOptionalCatalogMarketingCopy(input.publicLabel);
+        const publicDescription = this.normalizeOptionalCatalogMarketingCopy(input.publicDescription);
+        const publicDisplayOrder = this.normalizeOptionalCatalogDisplayOrder(input.publicDisplayOrder);
+        const now = new Date().toISOString();
+        const tx = this.db.transaction(() => {
+            if (!publicLabel && !publicDescription && publicDisplayOrder === null) {
+                this.db.prepare(`
+                    DELETE FROM plan_feature_catalog_overrides
+                    WHERE tenant_id = ? AND feature_key = ?
+                `).run(this.tenantId, featureKey);
+                return;
+            }
+            this.db.prepare(`
+                INSERT INTO plan_feature_catalog_overrides (
+                    tenant_id,
+                    feature_key,
+                    public_label,
+                    public_description,
+                    public_display_order,
+                    created_at,
+                    updated_at
+                )
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT (tenant_id, feature_key) DO UPDATE SET
+                    public_label = excluded.public_label,
+                    public_description = excluded.public_description,
+                    public_display_order = excluded.public_display_order,
+                    updated_at = excluded.updated_at
+            `).run(this.tenantId, featureKey, publicLabel, publicDescription, publicDisplayOrder, now, now);
+        });
+        tx();
+        return this.listPlanFeatureCatalog().find((feature) => feature.featureKey === featureKey) || {
+            featureKey: catalogFeature.featureKey,
+            label: catalogFeature.label,
+            description: catalogFeature.description,
+            publicLabel,
+            publicDescription,
+            publicDisplayOrder,
+            allowedAccessModes: [...catalogFeature.allowedAccessModes],
+            configTemplate: { ...catalogFeature.configTemplate },
+            ...(catalogFeature.dependsOn?.length ? { dependsOn: [...catalogFeature.dependsOn] } : {})
+        };
+    }
     listPlanVersions(planId) {
         const normalizedPlanId = String(planId || '').trim().toLowerCase();
         if (!normalizedPlanId)
@@ -1385,9 +1742,13 @@ export class PlanEntitlementService {
         `).all(this.tenantId, planVersionId);
         const features = {};
         for (const featureRow of featuresRows) {
-            const key = String(featureRow.feature_key || '').trim();
+            const originalKey = String(featureRow.feature_key || '').trim();
+            const key = this.canonicalizePlanFeatureKey(originalKey);
             if (!key)
                 continue;
+            if (key === WORKSPACES_FEATURE_KEY && originalKey === LEGACY_WORKSPACES_FEATURE_KEY && features[key]) {
+                continue;
+            }
             features[key] = {
                 featureKey: key,
                 access: this.normalizeFeatureAccess(featureRow.access),
@@ -1417,7 +1778,7 @@ export class PlanEntitlementService {
             ...currentVersion.features
         };
         for (const feature of features) {
-            const featureKey = String(feature.featureKey || '').trim();
+            const featureKey = this.canonicalizePlanFeatureKey(feature.featureKey);
             if (!featureKey)
                 continue;
             const access = this.normalizeFeatureAccess(feature.access);