@taskforcehq/taskforce 0.3.305 → 0.3.306

package/dist/core/PlanEntitlementService.js

@@ -3,6 +3,7 @@ import { DOCUMENT_CLOUD_STORAGE_FEATURE_KEY, WORKSPACES_FEATURE_KEY, AI_PROFILES
 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,13 +148,13 @@ 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 (featureKey === AI_PROFILES_FEATURE_KEY) {
+        if (normalizedFeatureKey === AI_PROFILES_FEATURE_KEY) {
             if (access === 'limited') {
                 const limit = this.readPositiveIntegerConfig(config[AI_PROFILES_LIMIT_CONFIG_KEY], 1);
                 return {
@@ -144,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,
@@ -255,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)
@@ -547,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 };
         }
@@ -577,11 +664,17 @@ export class PlanEntitlementService {
             throw error;
         }
         const feature = entitlement.version.features[AI_PROFILES_FEATURE_KEY] || null;
-        if (!feature || feature.access !== 'limited') {
+        if (!feature || feature.access === 'disabled') {
             return { limit: null, feature };
         }
         const configuredLimit = this.readPositiveIntegerConfig(feature.config?.[AI_PROFILES_LIMIT_CONFIG_KEY], 1);
-        return { limit: configuredLimit ?? 1, feature };
+        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();
@@ -678,6 +771,16 @@ export class PlanEntitlementService {
             throw error;
         }
     }
+    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 || {};
         const policy = billing.onboardingPolicy && typeof billing.onboardingPolicy === 'object'
@@ -686,16 +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
+                planId: explicitPlanId || resolvedLegacyPlanId
             };
         }
         return {
             mode: 'require_plan_selection',
-            planVersionId: null
+            planId: null
         };
     }
     validateOnboardingPolicy(input) {
@@ -705,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
                 }
             };
         }
@@ -797,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,
@@ -811,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();
@@ -887,6 +1020,80 @@ export class PlanEntitlementService {
             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) {
@@ -896,8 +1103,10 @@ export class PlanEntitlementService {
         const validation = this.validateOnboardingPolicy(onboardingPolicy);
         const currentEntitlement = this.tryGetAccountEntitlement(normalizedAccountId);
         const entitlement = currentEntitlement
-            ? (this.tryAutoHealLegacyPersonalFreeEntitlement(normalizedAccountId, currentEntitlement) || currentEntitlement)
-            : null;
+            ? (this.tryAutoHealLegacyPersonalFreeEntitlement(normalizedAccountId, currentEntitlement)
+                || this.tryAutoHealCommercialEntitlementFromBillingMirror(normalizedAccountId, currentEntitlement)
+                || currentEntitlement)
+            : this.tryAutoHealCommercialEntitlementFromBillingMirror(normalizedAccountId, null);
         if (!entitlement) {
             return !validation.valid
                 ? this.buildBlockedAccessStatus({
@@ -995,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');
         }
@@ -1045,6 +1254,8 @@ export class PlanEntitlementService {
             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);
@@ -1142,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)
@@ -1169,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';
@@ -1194,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
@@ -1211,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)
@@ -1243,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
@@ -1255,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)
@@ -1460,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),
@@ -1492,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);

package/dist/core/PlanFeatureCatalog.test.d.ts

@@ -0,0 +1 @@
+export {};