@taskforcehq/taskforce 0.3.169 → 0.3.300

package/dist/core/PlanEntitlementService.js

@@ -0,0 +1,1442 @@
+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';
+const LEGACY_REMOVED_PLAN_FEATURE_KEYS = Object.freeze([
+    'documents.workspace_access'
+]);
+/**
+ * Handles all plan catalog, plan version, and account entitlement logic.
+ * Extracted from Taskforce.ts to reduce monolith size.
+ */
+export class PlanEntitlementService {
+    db;
+    tenantId;
+    deps;
+    constructor(db, tenantId, deps) {
+        this.db = db;
+        this.tenantId = tenantId;
+        this.deps = deps;
+    }
+    generateEntityId(prefix) {
+        return `${prefix}-${generateUuidV7()}`;
+    }
+    parseJsonObject(raw) {
+        if (typeof raw !== 'string' || !raw.trim())
+            return {};
+        try {
+            const parsed = JSON.parse(raw);
+            return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+                ? parsed
+                : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    // ─── Normalizers ─────────────────────────────────────────────────────────
+    normalizeEntitlementState(value) {
+        const normalized = String(value || '').trim().toLowerCase();
+        if (normalized === 'active' || normalized === 'trialing' || normalized === 'grace' || normalized === 'suspended' || normalized === 'canceled') {
+            return normalized;
+        }
+        return 'canceled';
+    }
+    normalizeFeatureAccess(value) {
+        const normalized = String(value || '').trim().toLowerCase();
+        if (normalized === 'enabled' || normalized === 'limited' || normalized === 'disabled') {
+            return normalized;
+        }
+        return 'disabled';
+    }
+    readPositiveIntegerConfig(value, minimum) {
+        const numeric = Number(value);
+        if (!Number.isFinite(numeric))
+            return null;
+        return Math.max(minimum, Math.floor(numeric));
+    }
+    normalizePlanVersionTrialDays(value) {
+        if (value === null || value === undefined || value === '')
+            return 0;
+        const numeric = Number(value);
+        if (!Number.isFinite(numeric) || !Number.isInteger(numeric)) {
+            throw new TaskforceRuleError('trialDays must be an integer between 0 and 99.', 400, 'PLAN_TRIAL_DAYS_INVALID');
+        }
+        const normalized = Math.floor(numeric);
+        if (normalized < 0 || normalized > 99) {
+            throw new TaskforceRuleError('trialDays must be an integer between 0 and 99.', 400, 'PLAN_TRIAL_DAYS_INVALID');
+        }
+        return normalized;
+    }
+    readPlanVersionTrialDays(metadata) {
+        const rawValue = metadata.trialDays;
+        if (rawValue === null || rawValue === undefined || rawValue === '')
+            return 0;
+        const numeric = Number(rawValue);
+        if (!Number.isFinite(numeric) || !Number.isInteger(numeric))
+            return 0;
+        const normalized = Math.floor(numeric);
+        return normalized >= 0 && normalized <= 99 ? normalized : 0;
+    }
+    applyPlanVersionTrialDaysMetadata(metadata, trialDays) {
+        const nextMetadata = metadata && typeof metadata === 'object' ? { ...metadata } : {};
+        if (trialDays === undefined) {
+            return nextMetadata;
+        }
+        nextMetadata.trialDays = trialDays;
+        return nextMetadata;
+    }
+    sanitizePlanFeatureConfig(featureKey, access, config) {
+        if (featureKey === 'collaboration.seat_limit')
+            return {};
+        if (featureKey === DOCUMENT_CLOUD_STORAGE_FEATURE_KEY) {
+            const limit = this.readPositiveIntegerConfig(config[DOCUMENT_CLOUD_STORAGE_LIMIT_CONFIG_KEY], 1);
+            if (access === 'limited') {
+                return {
+                    [DOCUMENT_CLOUD_STORAGE_LIMIT_CONFIG_KEY]: limit ?? 1024
+                };
+            }
+            if (limit !== null) {
+                return {
+                    [DOCUMENT_CLOUD_STORAGE_LIMIT_CONFIG_KEY]: limit
+                };
+            }
+            return {};
+        }
+        if (featureKey === WORKSPACES_FEATURE_KEY) {
+            const limit = this.readPositiveIntegerConfig(config[WORKSPACES_LIMIT_CONFIG_KEY], 1);
+            return {
+                [WORKSPACES_LIMIT_CONFIG_KEY]: limit ?? 1
+            };
+        }
+        return config && typeof config === 'object' ? { ...config } : {};
+    }
+    isEntitlementStateAllowed(state) {
+        return state === 'active' || state === 'trialing' || state === 'grace';
+    }
+    // ─── Plan defaults repair ─────────────────────────────────────────────────
+    repairPlanDefaultVersionIfNeeded(planIdRaw) {
+        const planId = String(planIdRaw || '').trim().toLowerCase();
+        if (!planId)
+            return;
+        const rows = this.db.prepare(`
+            SELECT plan_version_id, version_number, is_default
+            FROM plan_versions
+            WHERE tenant_id = ? AND plan_id = ?
+            ORDER BY version_number DESC, created_at DESC
+        `).all(this.tenantId, planId);
+        if (rows.length === 0)
+            return;
+        const defaultRows = rows.filter((row) => Boolean(row.is_default) && row.plan_version_id);
+        if (defaultRows.length === 1)
+            return;
+        const fallback = rows.find((row) => row.plan_version_id) || null;
+        if (!fallback?.plan_version_id)
+            return;
+        const now = new Date().toISOString();
+        this.db.prepare(`
+            UPDATE plan_versions
+            SET is_default = CASE WHEN plan_version_id = ? THEN 1 ELSE 0 END,
+                updated_at = ?
+            WHERE tenant_id = ? AND plan_id = ?
+        `).run(String(fallback.plan_version_id), now, this.tenantId, planId);
+    }
+    repairPlanCatalogDefaultsIfNeeded() {
+        const planRows = this.db.prepare(`
+            SELECT DISTINCT plan_id
+            FROM plan_versions
+            WHERE tenant_id = ?
+        `).all(this.tenantId);
+        for (const row of planRows) {
+            const planId = String(row.plan_id || '').trim().toLowerCase();
+            if (!planId)
+                continue;
+            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();
+        this.removeLegacyPlanFeatureRows();
+    }
+    removeLegacyPlanFeatureRows() {
+        const featureKeys = [...LEGACY_REMOVED_PLAN_FEATURE_KEYS];
+        if (featureKeys.length < 1)
+            return;
+        const placeholders = featureKeys.map(() => '?').join(', ');
+        this.db.prepare(`
+            DELETE FROM plan_feature_matrix
+            WHERE tenant_id = ?
+              AND feature_key IN (${placeholders})
+        `).run(this.tenantId, ...featureKeys);
+    }
+    migrateLegacySeatLimitFeatureConfigToVersionSeatLimit() {
+        const rows = this.db.prepare(`
+            SELECT pfm.plan_version_id, pfm.config_json, pv.seat_limit
+            FROM plan_feature_matrix pfm
+            JOIN plan_versions pv
+              ON pv.tenant_id = pfm.tenant_id
+             AND pv.plan_version_id = pfm.plan_version_id
+            WHERE pfm.tenant_id = ?
+              AND pfm.feature_key = 'collaboration.seat_limit'
+        `).all(this.tenantId);
+        if (rows.length < 1)
+            return;
+        const now = new Date().toISOString();
+        const tx = this.db.transaction(() => {
+            for (const row of rows) {
+                const planVersionId = String(row.plan_version_id || '').trim();
+                if (!planVersionId)
+                    continue;
+                const config = this.parseJsonObject(row.config_json);
+                const legacySeatLimit = this.readPositiveIntegerConfig(config.seatLimit ?? config.seat_limit, 1);
+                if (legacySeatLimit !== null && row.seat_limit === null) {
+                    this.db.prepare(`
+                        UPDATE plan_versions
+                        SET seat_limit = ?, updated_at = ?
+                        WHERE tenant_id = ? AND plan_version_id = ?
+                    `).run(legacySeatLimit, now, this.tenantId, planVersionId);
+                }
+                if (Object.keys(config).length > 0) {
+                    this.db.prepare(`
+                        UPDATE plan_feature_matrix
+                        SET config_json = ?, updated_at = ?
+                        WHERE tenant_id = ? AND plan_version_id = ? AND feature_key = 'collaboration.seat_limit'
+                    `).run('{}', now, this.tenantId, planVersionId);
+                }
+            }
+        });
+        tx();
+    }
+    normalizeLegacyBillingMirrorRows() {
+        const defaultPersonalVersion = this.tryGetDefaultPlanVersionByMode('personal', { allowFallback: true });
+        if (!defaultPersonalVersion)
+            return;
+        const rows = this.db.prepare(`
+            SELECT user_id, tier, entitlement_state
+            FROM user_billing
+            WHERE tenant_id = ?
+        `).all(this.tenantId);
+        if (rows.length < 1)
+            return;
+        const now = new Date().toISOString();
+        const tx = this.db.transaction(() => {
+            for (const row of rows) {
+                const userId = String(row.user_id || '').trim();
+                if (!userId)
+                    continue;
+                const tier = String(row.tier || '').trim().toLowerCase();
+                const state = String(row.entitlement_state || '').trim().toLowerCase();
+                if (state === 'pending_plan_selection')
+                    continue;
+                if (tier === 'free' || state === 'free') {
+                    this.db.prepare(`
+                        UPDATE user_billing
+                        SET tier = ?, entitlement_state = 'active', updated_at = ?
+                        WHERE tenant_id = ? AND user_id = ?
+                    `).run(defaultPersonalVersion.planId, now, this.tenantId, userId);
+                }
+            }
+        });
+        tx();
+    }
+    backfillAccountEntitlements() {
+        const defaultPersonalVersion = this.tryGetDefaultPlanVersionByMode('personal', { allowFallback: true });
+        if (!defaultPersonalVersion) {
+            return;
+        }
+        const users = this.db.prepare(`
+            SELECT
+                u.id AS user_id,
+                ub.tier,
+                ub.entitlement_state,
+                ub.created_at AS billing_created_at,
+                ub.updated_at AS billing_updated_at
+            FROM users u
+            LEFT JOIN user_billing ub
+              ON ub.tenant_id = u.tenant_id
+             AND ub.user_id = u.id
+            LEFT JOIN account_entitlements ae
+              ON ae.tenant_id = u.tenant_id
+             AND ae.account_id = u.id
+            WHERE u.tenant_id = ?
+              AND ae.account_id IS NULL
+        `).all(this.tenantId);
+        for (const row of users) {
+            const accountId = String(row.user_id || '').trim();
+            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({
+                accountId,
+                planVersionId: planVersion.planVersionId,
+                state: this.resolveCanonicalEntitlementStateFromBilling(row.entitlement_state),
+                effectiveAt: row.billing_created_at ? String(row.billing_created_at) : undefined,
+                updatedBy: 'backfill',
+                createdAt: row.billing_created_at ? String(row.billing_created_at) : undefined,
+                updatedAt: row.billing_updated_at ? String(row.billing_updated_at) : undefined
+            });
+        }
+    }
+    // ─── Internal helpers ─────────────────────────────────────────────────────
+    getRequiredDefaultPlanVersion(planIdRaw) {
+        const planId = String(planIdRaw || '').trim().toLowerCase();
+        if (!planId) {
+            throw new TaskforceRuleError('planId is required', 400, 'PLAN_ID_REQUIRED');
+        }
+        const planRow = this.db.prepare(`
+            SELECT plan_id, status
+            FROM plan_catalog
+            WHERE tenant_id = ? AND plan_id = ?
+            LIMIT 1
+        `).get(this.tenantId, planId);
+        if (!planRow?.plan_id) {
+            throw new TaskforceRuleError(`Required plan "${planId}" is missing`, 500, 'PLAN_NOT_CONFIGURED');
+        }
+        if (String(planRow.status || '').trim().toLowerCase() !== 'active') {
+            throw new TaskforceRuleError(`Required plan "${planId}" is not active`, 500, 'PLAN_NOT_ACTIVE');
+        }
+        this.repairPlanDefaultVersionIfNeeded(planId);
+        const versionRow = this.db.prepare(`
+            SELECT plan_version_id
+            FROM plan_versions
+            WHERE tenant_id = ? AND plan_id = ? AND is_default = 1
+            ORDER BY version_number DESC
+            LIMIT 1
+        `).get(this.tenantId, planId);
+        if (!versionRow?.plan_version_id) {
+            throw new TaskforceRuleError(`Required default version for "${planId}" is missing`, 500, 'DEFAULT_PLAN_VERSION_NOT_CONFIGURED');
+        }
+        return this.getPlanVersionSnapshot(String(versionRow.plan_version_id));
+    }
+    resolveCanonicalEntitlementStateFromBilling(raw) {
+        return this.normalizeEntitlementState(raw);
+    }
+    upsertCanonicalEntitlementRecord(input) {
+        const now = new Date().toISOString();
+        const createdAt = input.createdAt || now;
+        const updatedAt = input.updatedAt || now;
+        this.db.prepare(`
+            INSERT INTO account_entitlements (account_id, tenant_id, plan_version_id, entitlement_state, effective_at, effective_until, updated_by, created_at, updated_at)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+            ON CONFLICT (account_id) DO UPDATE SET
+                plan_version_id = excluded.plan_version_id,
+                entitlement_state = excluded.entitlement_state,
+                effective_at = excluded.effective_at,
+                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);
+    }
+    isFeatureEnabledForPlanMode(feature) {
+        return Boolean(feature && feature.access !== 'disabled');
+    }
+    syncManagedTeamFeatures(features) {
+        const normalized = {};
+        for (const [featureKey, feature] of Object.entries(features || {})) {
+            normalized[featureKey] = {
+                featureKey,
+                access: this.normalizeFeatureAccess(feature.access),
+                config: feature.config && typeof feature.config === 'object' ? { ...feature.config } : {}
+            };
+        }
+        const teamManagement = normalized['collaboration.team_management'];
+        normalized['collaboration.invites'] = {
+            featureKey: 'collaboration.invites',
+            access: this.isFeatureEnabledForPlanMode(teamManagement) ? 'enabled' : 'disabled',
+            config: {}
+        };
+        return normalized;
+    }
+    normalizePlanFeatureDependencies(features) {
+        const normalized = this.syncManagedTeamFeatures(features);
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const [featureKey, dependencies] of Object.entries(PLAN_FEATURE_DEPENDENCIES)) {
+                const feature = normalized[featureKey];
+                if (!feature || feature.access === 'disabled')
+                    continue;
+                const unmetDependency = dependencies.some((dependencyKey) => {
+                    const dependencyFeature = normalized[dependencyKey];
+                    return !dependencyFeature || dependencyFeature.access === 'disabled';
+                });
+                if (!unmetDependency)
+                    continue;
+                normalized[featureKey] = {
+                    ...feature,
+                    access: 'disabled'
+                };
+                changed = true;
+            }
+        }
+        return normalized;
+    }
+    isTeamPlanVersion(version) {
+        const teamFeature = version?.features?.['collaboration.team_management'];
+        return this.isFeatureEnabledForPlanMode(teamFeature);
+    }
+    assertSeatLimitCompatibleWithMode(input) {
+        const modeLabel = String(input.modeLabel || 'plan version').trim() || 'plan version';
+        const isTeam = this.isTeamPlanVersion({ features: input.features || {} });
+        if (!isTeam)
+            return;
+        if (input.seatLimit === null || !Number.isFinite(input.seatLimit) || input.seatLimit <= 0) {
+            throw new TaskforceRuleError(`${modeLabel} requires a positive seat limit when team management is enabled.`, 409, 'PLAN_SEAT_LIMIT_REQUIRED');
+        }
+    }
+    buildPlanModeFeatures(mode) {
+        const access = mode === 'team' ? 'enabled' : 'disabled';
+        return [
+            { featureKey: 'collaboration.invites', access, config: {} },
+            { featureKey: 'collaboration.team_management', access, config: {} }
+        ];
+    }
+    resolveWorkspaceLimitForUser(userId) {
+        const normalizedUserId = String(userId || '').trim();
+        if (!normalizedUserId) {
+            return { limit: 1, feature: null };
+        }
+        const entitlement = this.getAccountEntitlement(normalizedUserId);
+        const feature = entitlement.version.features[WORKSPACES_FEATURE_KEY] || null;
+        if (!feature || feature.access === 'disabled') {
+            return { limit: 1, feature };
+        }
+        const configuredLimit = this.readPositiveIntegerConfig(feature.config?.[WORKSPACES_LIMIT_CONFIG_KEY], 1);
+        if (configuredLimit !== null) {
+            return { limit: configuredLimit, feature };
+        }
+        return { limit: null, feature };
+    }
+    planHasAnyActivePricing(planIdRaw) {
+        const planId = String(planIdRaw || '').trim().toLowerCase();
+        if (!planId)
+            return false;
+        const row = this.db.prepare(`
+            SELECT COUNT(*) AS count
+            FROM billing_price_mappings bpm
+            JOIN plan_versions pv
+              ON pv.tenant_id = bpm.tenant_id
+             AND pv.plan_version_id = bpm.plan_version_id
+            WHERE bpm.tenant_id = ?
+              AND pv.plan_id = ?
+              AND bpm.active = 1
+        `).get(this.tenantId, planId);
+        return Number(row?.count || 0) > 0;
+    }
+    tryGetDefaultPlanVersionByPlanId(planIdRaw) {
+        const planId = String(planIdRaw || '').trim().toLowerCase();
+        if (!planId)
+            return null;
+        try {
+            return this.getRequiredDefaultPlanVersion(planId);
+        }
+        catch (error) {
+            if (error instanceof TaskforceRuleError) {
+                if (error.code === 'PLAN_NOT_CONFIGURED'
+                    || error.code === 'PLAN_NOT_ACTIVE'
+                    || error.code === 'DEFAULT_PLAN_VERSION_NOT_CONFIGURED') {
+                    return null;
+                }
+            }
+            throw error;
+        }
+    }
+    getActiveDefaultPlanVersions() {
+        const rows = this.db.prepare(`
+            SELECT 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
+            WHERE v.tenant_id = ?
+              AND v.is_default = 1
+              AND COALESCE(p.status, 'active') = 'active'
+            ORDER BY p.updated_at DESC, p.created_at DESC, v.version_number DESC, v.created_at DESC
+        `).all(this.tenantId);
+        return rows
+            .map((row) => String(row.plan_version_id || '').trim())
+            .filter(Boolean)
+            .map((planVersionId) => this.getPlanVersionSnapshot(planVersionId));
+    }
+    getDefaultPlanVersionByMode(mode, options = {}) {
+        const versions = this.getActiveDefaultPlanVersions();
+        const matching = versions.find((version) => this.isTeamPlanVersion(version) === (mode === 'team'));
+        if (matching) {
+            return matching;
+        }
+        if (options.allowFallback && versions.length > 0) {
+            return versions[0];
+        }
+        throw new TaskforceRuleError(`No active default ${mode} plan version is configured`, 500, 'DEFAULT_PLAN_VERSION_NOT_CONFIGURED');
+    }
+    tryGetDefaultPlanVersionByMode(mode, options = {}) {
+        try {
+            return this.getDefaultPlanVersionByMode(mode, options);
+        }
+        catch (error) {
+            if (error instanceof TaskforceRuleError) {
+                if (error.code === 'DEFAULT_PLAN_VERSION_NOT_CONFIGURED') {
+                    return null;
+                }
+            }
+            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 });
+            }
+            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,
+                    planId: String(row.plan_id)
+                });
+            }
+            return {
+                requiresPlanSelection: false,
+                planVersionId: String(row.plan_version_id),
+                planId: String(row.plan_id)
+            };
+        }
+        const signupSettings = this.getSignupMonetizationSettings();
+        if (signupSettings.strategy === 'plan_selection_required') {
+            return {
+                requiresPlanSelection: true,
+                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)
+            : null;
+        if (!configuredVersion) {
+            throw new TaskforceRuleError('Default signup plan version is required when signup strategy is auto-assign default.', 500, 'SIGNUP_PLAN_VERSION_REQUIRED');
+        }
+        return {
+            requiresPlanSelection: false,
+            planVersionId: configuredVersion.planVersionId,
+            planId: configuredVersion.planId
+        };
+    }
+    // ─── Public billing methods ───────────────────────────────────────────────
+    createUserBillingRecord(userId, options) {
+        const now = new Date().toISOString();
+        const entitlementState = String(options?.entitlementState || 'active').trim().toLowerCase() || 'active';
+        const planId = typeof options?.planId === 'string'
+            ? options.planId.trim().toLowerCase()
+            : '';
+        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(userId, this.tenantId, entitlementState, planId, now, now);
+    }
+    getUserEntitlement(userId) {
+        const account = this.getAccountEntitlement(userId);
+        return {
+            entitlementState: account.state,
+            tier: account.planId
+        };
+    }
+    hasAccountEntitlement(accountId) {
+        const normalizedAccountId = String(accountId || '').trim();
+        if (!normalizedAccountId)
+            return false;
+        return this.tryGetAccountEntitlement(normalizedAccountId) !== null;
+    }
+    tryGetAccountEntitlement(accountId) {
+        try {
+            return this.getAccountEntitlement(accountId);
+        }
+        catch (error) {
+            if (error instanceof TaskforceRuleError && error.code === 'ENTITLEMENT_NOT_FOUND') {
+                return null;
+            }
+            throw error;
+        }
+    }
+    getAccountAccessStatus(accountId) {
+        const normalizedAccountId = String(accountId || '').trim();
+        if (!normalizedAccountId) {
+            throw new TaskforceRuleError('accountId is required', 400, 'ACCOUNT_ID_REQUIRED');
+        }
+        const signupSettings = this.getSignupMonetizationSettings();
+        const validation = this.validateSignupMonetizationSettings(signupSettings);
+        const entitlement = this.tryGetAccountEntitlement(normalizedAccountId);
+        if (entitlement && 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 {
+                gate: 'plan_selection_required',
+                hasEntitlement: false,
+                canAccessApp: false,
+                canAccessPlans: true,
+                signupMonetizationStrategy: signupSettings.strategy,
+                planSelectionRequired: true,
+                message: 'Choose a plan to continue.',
+                entitlement: null
+            };
+        }
+        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
+            };
+        }
+        return {
+            gate: 'missing_entitlement',
+            hasEntitlement: false,
+            canAccessApp: false,
+            canAccessPlans: true,
+            signupMonetizationStrategy: signupSettings.strategy,
+            planSelectionRequired: false,
+            message: 'No entitlement is linked to this account.',
+            entitlement: null
+        };
+    }
+    getEffectivePlanVersion(accountId) {
+        const normalizedAccountId = String(accountId || '').trim();
+        if (!normalizedAccountId) {
+            throw new TaskforceRuleError('accountId is required', 400, 'ACCOUNT_ID_REQUIRED');
+        }
+        const row = this.db.prepare(`
+            SELECT v.plan_version_id, v.plan_id, v.version_number, v.is_default, v.seat_limit, v.metadata_json
+            FROM account_entitlements e
+            JOIN plan_versions v ON v.plan_version_id = e.plan_version_id
+            WHERE e.tenant_id = ? AND e.account_id = ?
+            LIMIT 1
+        `).get(this.tenantId, normalizedAccountId);
+        if (!row?.plan_version_id || !row.plan_id) {
+            throw new TaskforceRuleError('Plan version not found for account', 404, 'PLAN_VERSION_NOT_FOUND');
+        }
+        const featuresRows = this.db.prepare(`
+            SELECT feature_key, access, config_json
+            FROM plan_feature_matrix
+            WHERE tenant_id = ? AND plan_version_id = ?
+        `).all(this.tenantId, row.plan_version_id);
+        const features = {};
+        for (const featureRow of featuresRows) {
+            const featureKey = String(featureRow.feature_key || '').trim();
+            if (!featureKey)
+                continue;
+            features[featureKey] = {
+                featureKey,
+                access: this.normalizeFeatureAccess(featureRow.access),
+                config: this.parseJsonObject(featureRow.config_json || '{}')
+            };
+        }
+        const metadata = this.parseJsonObject(row.metadata_json || '{}');
+        return {
+            planVersionId: String(row.plan_version_id),
+            planId: String(row.plan_id),
+            versionNumber: Number(row.version_number || 1),
+            isDefault: Boolean(row.is_default),
+            seatLimit: row.seat_limit === null || row.seat_limit === undefined
+                ? null
+                : Math.max(0, Number(row.seat_limit)),
+            trialDays: this.readPlanVersionTrialDays(metadata),
+            metadata,
+            features
+        };
+    }
+    getAccountEntitlement(accountId) {
+        const normalizedAccountId = String(accountId || '').trim();
+        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);
+        if (!row?.account_id || !row.plan_version_id) {
+            throw new TaskforceRuleError('Entitlement not found', 404, 'ENTITLEMENT_NOT_FOUND');
+        }
+        const version = this.getEffectivePlanVersion(normalizedAccountId);
+        return {
+            accountId: String(row.account_id),
+            planVersionId: String(row.plan_version_id),
+            planId: version.planId,
+            state: this.normalizeEntitlementState(row.entitlement_state),
+            effectiveAt: row.effective_at ? String(row.effective_at) : null,
+            effectiveUntil: row.effective_until ? String(row.effective_until) : null,
+            version
+        };
+    }
+    countWorkspaceSeatUsage(workspaceId, options = {}) {
+        const normalizedWorkspaceId = String(workspaceId || '').trim();
+        if (!normalizedWorkspaceId) {
+            throw new TaskforceRuleError('workspaceId is required', 400, 'WORKSPACE_ID_REQUIRED');
+        }
+        const accountId = this.deps.getWorkspaceOwnerUserId(normalizedWorkspaceId);
+        if (!accountId) {
+            return { used: 0, limit: null, remaining: null };
+        }
+        const entitlement = this.getAccountEntitlement(accountId);
+        const includeInvited = options.includeInvited !== false;
+        const statuses = includeInvited ? ['active', 'invited', 'disabled'] : ['active', 'disabled'];
+        const placeholders = statuses.map(() => '?').join(', ');
+        const row = this.db.prepare(`
+            SELECT COUNT(*) AS c
+            FROM workspace_memberships
+            WHERE tenant_id = ?
+              AND workspace_id = ?
+              AND COALESCE(status, 'active') IN (${placeholders})
+        `).get(this.tenantId, normalizedWorkspaceId, ...statuses);
+        const used = Math.max(0, Number(row?.c || 0));
+        const limit = entitlement.version.seatLimit;
+        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) {
+            throw new TaskforceRuleError('Seat limit reached for this workspace', 403, 'SEAT_LIMIT_REACHED', seatUsage);
+        }
+    }
+    evaluateFeatureAccess(input) {
+        const workspaceId = String(input.workspaceId || '').trim();
+        const featureKey = String(input.featureKey || '').trim();
+        if (!workspaceId) {
+            return { allowed: false, reasonCode: 'WORKSPACE_ID_REQUIRED', state: 'canceled' };
+        }
+        if (!featureKey) {
+            return { allowed: false, reasonCode: 'FEATURE_KEY_REQUIRED', state: 'canceled' };
+        }
+        const accountId = this.deps.getWorkspaceOwnerUserId(workspaceId);
+        if (!accountId) {
+            return { allowed: false, reasonCode: 'ENTITLEMENT_NOT_FOUND', state: 'canceled' };
+        }
+        const entitlement = this.getAccountEntitlement(accountId);
+        if (!this.isEntitlementStateAllowed(entitlement.state)) {
+            return { allowed: false, reasonCode: 'ENTITLEMENT_STATE_BLOCKED', state: entitlement.state };
+        }
+        const feature = entitlement.version.features[featureKey];
+        if (!feature) {
+            return { allowed: false, reasonCode: 'FEATURE_DISABLED', state: entitlement.state };
+        }
+        if (feature.access === 'disabled') {
+            return { allowed: false, reasonCode: 'FEATURE_DISABLED', state: entitlement.state, feature };
+        }
+        if (featureKey === 'collaboration.seat_limit') {
+            const seatUsage = this.countWorkspaceSeatUsage(workspaceId, { includeInvited: true });
+            if (seatUsage.limit !== null && seatUsage.used >= seatUsage.limit) {
+                return { allowed: false, reasonCode: 'SEAT_LIMIT_REACHED', state: entitlement.state, seatUsage, feature };
+            }
+            return { allowed: true, reasonCode: 'OK', state: entitlement.state, seatUsage, feature };
+        }
+        return { allowed: true, reasonCode: 'OK', state: entitlement.state, feature };
+    }
+    getUserAccountPlanMode(userId) {
+        const normalizedUserId = String(userId || '').trim();
+        if (!normalizedUserId)
+            return 'personal';
+        const entitlement = this.getAccountEntitlement(normalizedUserId);
+        return this.isTeamPlanVersion(entitlement.version) ? 'team' : 'personal';
+    }
+    setUserAccountPlanMode(userId, mode) {
+        const normalizedUserId = String(userId || '').trim();
+        if (!normalizedUserId) {
+            throw new TaskforceRuleError('userId is required', 400, 'USER_ID_REQUIRED');
+        }
+        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({
+            accountId: normalizedUserId,
+            planVersionId,
+            state: entitlementState,
+            effectiveAt: now,
+            updatedBy: 'legacy-plan-mode',
+            createdAt: now,
+            updatedAt: now
+        });
+        return normalizedMode;
+    }
+    getRequiredDefaultPlanVersionId(planId) {
+        return this.getRequiredDefaultPlanVersion(planId).planVersionId;
+    }
+    getDefaultPlanVersionIdByMode(mode, options = {}) {
+        return this.getDefaultPlanVersionByMode(mode, options).planVersionId;
+    }
+    getBillingMirrorProfileForPlanVersion(planVersionId) {
+        const version = this.getPlanVersionSnapshot(planVersionId);
+        return {
+            planId: version.planId,
+            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 = {
+            trialing: ['active', 'grace', 'canceled'],
+            active: ['grace', 'suspended', 'canceled'],
+            grace: ['active', 'suspended', 'canceled'],
+            suspended: ['active', 'canceled'],
+            canceled: ['trialing', 'active']
+        };
+        return allowed[fromState].includes(toState);
+    }
+    addEntitlementAuditLog(input) {
+        const now = new Date().toISOString();
+        const id = this.generateEntityId('ent-audit');
+        this.db.prepare(`
+            INSERT INTO entitlement_audit_log (
+                id, tenant_id, actor_user_id, actor_role, account_id, action, reason, before_json, after_json, request_id, created_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        `).run(id, this.tenantId, String(input.actorUserId || 'anonymous').trim() || 'anonymous', String(input.actorRole || 'system_admin').trim() || 'system_admin', String(input.accountId || '').trim(), String(input.action || '').trim(), input.reason ? String(input.reason) : null, JSON.stringify(input.before && typeof input.before === 'object' ? input.before : {}), JSON.stringify(input.after && typeof input.after === 'object' ? input.after : {}), input.requestId ? String(input.requestId) : null, now);
+    }
+    upsertPlanCatalog(input) {
+        const planId = String(input.planId || '').trim().toLowerCase();
+        const displayName = String(input.displayName || '').trim();
+        const initialMode = String(input.initialMode || '').trim().toLowerCase() === 'team'
+            ? 'team'
+            : 'personal';
+        const initialSeatLimit = input.initialSeatLimit === null || input.initialSeatLimit === undefined
+            ? null
+            : Math.max(0, Math.floor(Number(input.initialSeatLimit)));
+        const initialTrialDays = this.normalizePlanVersionTrialDays(input.initialTrialDays);
+        if (!planId)
+            throw new TaskforceRuleError('planId is required', 400, 'PLAN_ID_REQUIRED');
+        if (!displayName)
+            throw new TaskforceRuleError('displayName is required', 400, 'PLAN_DISPLAY_NAME_REQUIRED');
+        this.assertSeatLimitCompatibleWithMode({
+            seatLimit: initialSeatLimit,
+            features: this.buildPlanModeFeatures(initialMode).reduce((acc, feature) => {
+                acc[feature.featureKey] = {
+                    featureKey: feature.featureKey,
+                    access: feature.access,
+                    config: feature.config
+                };
+                return acc;
+            }, {}),
+            modeLabel: 'New team plan'
+        });
+        const now = new Date().toISOString();
+        const existing = this.db.prepare(`
+            SELECT plan_id, status
+            FROM plan_catalog
+            WHERE tenant_id = ? AND plan_id = ?
+            LIMIT 1
+        `).get(this.tenantId, planId);
+        const isNewPlan = !existing?.plan_id;
+        const status = input.status === 'active'
+            ? 'active'
+            : input.status === 'archived'
+                ? 'archived'
+                : isNewPlan
+                    ? 'archived'
+                    : String(existing?.status || '').trim().toLowerCase() === 'active'
+                        ? 'active'
+                        : '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 (?, ?, ?, ?, ?, ?)
+                ON CONFLICT (plan_id) DO UPDATE SET
+                    display_name = excluded.display_name,
+                    status = excluded.status,
+                    updated_at = excluded.updated_at
+            `).run(planId, this.tenantId, displayName, 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)
+                    VALUES (?, ?, ?, 1, 1, NULL, ?, ?, ?)
+                    ON CONFLICT (plan_version_id) DO NOTHING
+                `).run(`${planId}-v1`, this.tenantId, planId, JSON.stringify(this.applyPlanVersionTrialDaysMetadata({}, initialTrialDays)), now, now);
+                this.db.prepare(`
+                    UPDATE plan_versions
+                    SET seat_limit = ?, updated_at = ?
+                    WHERE tenant_id = ? AND plan_version_id = ?
+                `).run(initialSeatLimit, now, this.tenantId, `${planId}-v1`);
+                for (const feature of this.buildPlanModeFeatures(initialMode)) {
+                    this.db.prepare(`
+                        INSERT INTO plan_feature_matrix (tenant_id, plan_version_id, feature_key, access, config_json, created_at, updated_at)
+                        VALUES (?, ?, ?, ?, ?, ?, ?)
+                        ON CONFLICT (tenant_id, plan_version_id, feature_key) DO UPDATE SET
+                            access = excluded.access,
+                            config_json = excluded.config_json,
+                            updated_at = excluded.updated_at
+                    `).run(this.tenantId, `${planId}-v1`, feature.featureKey, feature.access, JSON.stringify(feature.config), now, now);
+                }
+            }
+        });
+        tx();
+        this.repairPlanDefaultVersionIfNeeded(planId);
+        return { planId, displayName, status };
+    }
+    listPlanCatalog() {
+        const rows = this.db.prepare(`
+            SELECT plan_id, display_name, status, created_at, updated_at
+            FROM plan_catalog
+            WHERE tenant_id = ?
+            ORDER BY updated_at DESC, created_at DESC
+        `).all(this.tenantId);
+        return rows.map((row) => ({
+            planId: String(row.plan_id || ''),
+            displayName: String(row.display_name || ''),
+            status: String(row.status || '').trim().toLowerCase() === 'archived' ? 'archived' : 'active',
+            createdAt: String(row.created_at || ''),
+            updatedAt: String(row.updated_at || '')
+        }));
+    }
+    listPlanFeatureCatalog() {
+        return DEFAULT_PLAN_FEATURE_CATALOG.map((feature) => ({
+            featureKey: feature.featureKey,
+            label: feature.label,
+            description: feature.description,
+            allowedAccessModes: [...feature.allowedAccessModes],
+            configTemplate: { ...feature.configTemplate },
+            ...(feature.dependsOn?.length ? { dependsOn: [...feature.dependsOn] } : {})
+        }));
+    }
+    listPlanVersions(planId) {
+        const normalizedPlanId = String(planId || '').trim().toLowerCase();
+        if (!normalizedPlanId)
+            throw new TaskforceRuleError('planId is required', 400, 'PLAN_ID_REQUIRED');
+        this.repairPlanDefaultVersionIfNeeded(normalizedPlanId);
+        const rows = this.db.prepare(`
+            SELECT plan_version_id
+            FROM plan_versions
+            WHERE tenant_id = ? AND plan_id = ?
+            ORDER BY version_number DESC
+        `).all(this.tenantId, normalizedPlanId);
+        return rows
+            .map((row) => String(row.plan_version_id || '').trim())
+            .filter(Boolean)
+            .map((planVersionId) => this.getPlanVersionSnapshot(planVersionId));
+    }
+    getPlanVersionFeatures(planId, versionId) {
+        const normalizedPlanId = String(planId || '').trim().toLowerCase();
+        const normalizedVersionId = String(versionId || '').trim();
+        if (!normalizedPlanId)
+            throw new TaskforceRuleError('planId is required', 400, 'PLAN_ID_REQUIRED');
+        if (!normalizedVersionId)
+            throw new TaskforceRuleError('versionId is required', 400, 'PLAN_VERSION_ID_REQUIRED');
+        const version = this.getPlanVersionSnapshot(normalizedVersionId);
+        if (version.planId !== normalizedPlanId) {
+            throw new TaskforceRuleError('Plan version does not belong to plan', 404, 'PLAN_VERSION_NOT_FOUND');
+        }
+        return version;
+    }
+    searchAccountsByEmail(query, limit = 20) {
+        const q = String(query || '').trim().toLowerCase();
+        if (!q)
+            return [];
+        const safeLimit = Math.max(1, Math.min(100, Math.floor(Number(limit) || 20)));
+        const rows = this.db.prepare(`
+            SELECT id, email, display_name, is_disabled
+            FROM users
+            WHERE tenant_id = ?
+              AND (LOWER(email) LIKE ? OR LOWER(COALESCE(display_name, '')) LIKE ? OR LOWER(id) LIKE ?)
+            ORDER BY updated_at DESC, created_at DESC
+            LIMIT ?
+        `).all(this.tenantId, `%${q}%`, `%${q}%`, `%${q}%`, safeLimit);
+        return rows.map((row) => ({
+            accountId: String(row.id || ''),
+            email: String(row.email || ''),
+            displayName: row.display_name ? String(row.display_name) : null,
+            disabled: Boolean(row.is_disabled)
+        }));
+    }
+    createPlanVersion(input) {
+        const planId = String(input.planId || '').trim().toLowerCase();
+        const versionNumber = Math.max(1, Math.floor(Number(input.versionNumber) || 1));
+        if (!planId)
+            throw new TaskforceRuleError('planId is required', 400, 'PLAN_ID_REQUIRED');
+        const catalog = this.db.prepare(`
+            SELECT plan_id FROM plan_catalog WHERE tenant_id = ? AND plan_id = ? LIMIT 1
+        `).get(this.tenantId, planId);
+        if (!catalog?.plan_id) {
+            throw new TaskforceRuleError('Plan not found', 404, 'PLAN_NOT_FOUND');
+        }
+        const planVersionId = `${planId}-v${versionNumber}`;
+        const existingVersion = this.db.prepare(`
+            SELECT plan_version_id
+            FROM plan_versions
+            WHERE tenant_id = ? AND plan_version_id = ?
+            LIMIT 1
+        `).get(this.tenantId, planVersionId);
+        if (existingVersion?.plan_version_id) {
+            throw new TaskforceRuleError('Plan version already exists', 409, 'PLAN_VERSION_EXISTS');
+        }
+        const isDefault = input.isDefault === true;
+        const seatLimit = input.seatLimit === null || input.seatLimit === undefined
+            ? null
+            : Math.max(0, Math.floor(Number(input.seatLimit)));
+        const trialDays = this.normalizePlanVersionTrialDays(input.trialDays);
+        const baseMetadata = input.metadata && typeof input.metadata === 'object' ? input.metadata : {};
+        const metadata = this.applyPlanVersionTrialDaysMetadata(baseMetadata, trialDays);
+        this.assertSeatLimitCompatibleWithMode({
+            seatLimit,
+            features: {},
+            modeLabel: `Plan version ${planVersionId}`
+        });
+        const now = new Date().toISOString();
+        const tx = this.db.transaction(() => {
+            if (isDefault) {
+                this.db.prepare(`
+                    UPDATE plan_versions
+                    SET is_default = 0, updated_at = ?
+                    WHERE tenant_id = ? AND plan_id = ?
+                `).run(now, this.tenantId, planId);
+            }
+            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)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+            `).run(planVersionId, this.tenantId, planId, versionNumber, isDefault ? 1 : 0, seatLimit, JSON.stringify(metadata), now, now);
+        });
+        tx();
+        this.repairPlanDefaultVersionIfNeeded(planId);
+        return this.getPlanVersionSnapshot(planVersionId);
+    }
+    updatePlanVersion(input) {
+        const planId = String(input.planId || '').trim().toLowerCase();
+        const versionNumber = Math.max(1, Math.floor(Number(input.versionNumber) || 1));
+        if (!planId)
+            throw new TaskforceRuleError('planId is required', 400, 'PLAN_ID_REQUIRED');
+        const planVersionId = `${planId}-v${versionNumber}`;
+        const existing = this.db.prepare(`
+            SELECT plan_version_id, is_default, metadata_json, seat_limit
+            FROM plan_versions
+            WHERE tenant_id = ? AND plan_version_id = ? AND plan_id = ?
+            LIMIT 1
+        `).get(this.tenantId, planVersionId, planId);
+        if (!existing?.plan_version_id) {
+            throw new TaskforceRuleError('Plan version not found', 404, 'PLAN_VERSION_NOT_FOUND');
+        }
+        const existingDefault = Boolean(existing.is_default);
+        const nextDefault = input.isDefault === undefined ? existingDefault : input.isDefault === true;
+        if (existingDefault && !nextDefault) {
+            const alternate = this.db.prepare(`
+                SELECT plan_version_id
+                FROM plan_versions
+                WHERE tenant_id = ? AND plan_id = ? AND plan_version_id != ? AND is_default = 1
+                LIMIT 1
+            `).get(this.tenantId, planId, planVersionId);
+            if (!alternate?.plan_version_id) {
+                throw new TaskforceRuleError('A plan must have exactly one default version', 409, 'PLAN_DEFAULT_VERSION_REQUIRED');
+            }
+        }
+        const seatLimit = input.seatLimit === undefined
+            ? (existing.seat_limit === null || existing.seat_limit === undefined ? null : Math.max(0, Number(existing.seat_limit)))
+            : input.seatLimit === null
+                ? null
+                : Math.max(0, Math.floor(Number(input.seatLimit)));
+        const baseMetadata = input.metadata === undefined
+            ? this.parseJsonObject(existing.metadata_json || '{}')
+            : (input.metadata && typeof input.metadata === 'object' ? input.metadata : {});
+        const trialDays = input.trialDays === undefined
+            ? undefined
+            : this.normalizePlanVersionTrialDays(input.trialDays);
+        const metadata = this.applyPlanVersionTrialDaysMetadata(baseMetadata, trialDays);
+        const currentFeatures = this.getPlanVersionSnapshot(planVersionId).features;
+        this.assertSeatLimitCompatibleWithMode({
+            seatLimit,
+            features: currentFeatures,
+            modeLabel: `Plan version ${planVersionId}`
+        });
+        const now = new Date().toISOString();
+        const tx = this.db.transaction(() => {
+            if (nextDefault) {
+                this.db.prepare(`
+                    UPDATE plan_versions
+                    SET is_default = CASE WHEN plan_version_id = ? THEN 1 ELSE 0 END,
+                        updated_at = ?
+                    WHERE tenant_id = ? AND plan_id = ?
+                `).run(planVersionId, now, this.tenantId, planId);
+            }
+            else {
+                this.db.prepare(`
+                    UPDATE plan_versions
+                    SET updated_at = ?
+                    WHERE tenant_id = ? AND plan_id = ?
+                `).run(now, this.tenantId, planId);
+            }
+            this.db.prepare(`
+                UPDATE plan_versions
+                SET seat_limit = ?, metadata_json = ?, updated_at = ?
+                WHERE tenant_id = ? AND plan_version_id = ?
+            `).run(seatLimit, JSON.stringify(metadata), now, this.tenantId, planVersionId);
+        });
+        tx();
+        this.repairPlanDefaultVersionIfNeeded(planId);
+        return this.getPlanVersionSnapshot(planVersionId);
+    }
+    getPlanVersionSnapshot(planVersionId) {
+        const row = this.db.prepare(`
+            SELECT plan_version_id, plan_id, version_number, is_default, seat_limit, metadata_json
+            FROM plan_versions
+            WHERE tenant_id = ? AND plan_version_id = ?
+            LIMIT 1
+        `).get(this.tenantId, planVersionId);
+        if (!row?.plan_version_id || !row.plan_id) {
+            throw new TaskforceRuleError('Plan version not found', 404, 'PLAN_VERSION_NOT_FOUND');
+        }
+        const featuresRows = this.db.prepare(`
+            SELECT feature_key, access, config_json
+            FROM plan_feature_matrix
+            WHERE tenant_id = ? AND plan_version_id = ?
+        `).all(this.tenantId, planVersionId);
+        const features = {};
+        for (const featureRow of featuresRows) {
+            const key = String(featureRow.feature_key || '').trim();
+            if (!key)
+                continue;
+            features[key] = {
+                featureKey: key,
+                access: this.normalizeFeatureAccess(featureRow.access),
+                config: this.parseJsonObject(featureRow.config_json || '{}')
+            };
+        }
+        const metadata = this.parseJsonObject(row.metadata_json || '{}');
+        return {
+            planVersionId: String(row.plan_version_id),
+            planId: String(row.plan_id),
+            versionNumber: Number(row.version_number || 1),
+            isDefault: Boolean(row.is_default),
+            seatLimit: row.seat_limit === null || row.seat_limit === undefined ? null : Number(row.seat_limit),
+            trialDays: this.readPlanVersionTrialDays(metadata),
+            metadata,
+            features: this.normalizePlanFeatureDependencies(features)
+        };
+    }
+    updatePlanVersionFeatures(input) {
+        const planVersionId = String(input.planVersionId || '').trim();
+        if (!planVersionId)
+            throw new TaskforceRuleError('planVersionId is required', 400, 'PLAN_VERSION_ID_REQUIRED');
+        const now = new Date().toISOString();
+        const features = Array.isArray(input.features) ? input.features : [];
+        const currentVersion = this.getPlanVersionSnapshot(planVersionId);
+        const nextFeatures = {
+            ...currentVersion.features
+        };
+        for (const feature of features) {
+            const featureKey = String(feature.featureKey || '').trim();
+            if (!featureKey)
+                continue;
+            const access = this.normalizeFeatureAccess(feature.access);
+            const rawConfig = feature.config && typeof feature.config === 'object' ? feature.config : {};
+            nextFeatures[featureKey] = {
+                featureKey,
+                access,
+                config: this.sanitizePlanFeatureConfig(featureKey, access, rawConfig)
+            };
+        }
+        const normalizedNextFeatures = this.normalizePlanFeatureDependencies(nextFeatures);
+        this.assertSeatLimitCompatibleWithMode({
+            seatLimit: currentVersion.seatLimit,
+            features: normalizedNextFeatures,
+            modeLabel: `Plan version ${planVersionId}`
+        });
+        const tx = this.db.transaction(() => {
+            for (const [featureKey, feature] of Object.entries(normalizedNextFeatures)) {
+                const access = this.normalizeFeatureAccess(feature.access);
+                const rawConfig = feature.config && typeof feature.config === 'object' ? feature.config : {};
+                const config = this.sanitizePlanFeatureConfig(featureKey, access, rawConfig);
+                this.db.prepare(`
+                    INSERT INTO plan_feature_matrix (tenant_id, plan_version_id, feature_key, access, config_json, created_at, updated_at)
+                    VALUES (?, ?, ?, ?, ?, ?, ?)
+                    ON CONFLICT (tenant_id, plan_version_id, feature_key) DO UPDATE SET
+                        access = excluded.access,
+                        config_json = excluded.config_json,
+                        updated_at = excluded.updated_at
+                `).run(this.tenantId, planVersionId, featureKey, access, JSON.stringify(config), now, now);
+            }
+        });
+        tx();
+        const snapshot = this.getPlanVersionSnapshot(planVersionId);
+        this.assertSeatLimitCompatibleWithMode({
+            seatLimit: snapshot.seatLimit,
+            features: this.normalizePlanFeatureDependencies(snapshot.features),
+            modeLabel: `Plan version ${planVersionId}`
+        });
+        return snapshot;
+    }
+    updateAccountEntitlement(input) {
+        const accountId = String(input.accountId || '').trim();
+        if (!accountId)
+            throw new TaskforceRuleError('accountId is required', 400, 'ACCOUNT_ID_REQUIRED');
+        const existing = 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);
+        const before = existing?.account_id ? this.getAccountEntitlement(accountId) : null;
+        const nextPlanVersionId = String(input.planVersionId || before?.planVersionId || '').trim();
+        if (!nextPlanVersionId) {
+            throw new TaskforceRuleError('planVersionId is required', 400, 'PLAN_VERSION_ID_REQUIRED');
+        }
+        const currentState = before?.state || 'active';
+        const nextState = this.normalizeEntitlementState(input.entitlementState || currentState);
+        if (before && !this.isValidEntitlementTransition(before.state, nextState)) {
+            throw new TaskforceRuleError('Invalid entitlement state transition', 409, 'INVALID_STATE_TRANSITION');
+        }
+        const normalizedReason = typeof input.reason === 'string' ? input.reason.trim() : '';
+        if ((nextState === 'suspended' || nextState === 'canceled') && !normalizedReason) {
+            throw new TaskforceRuleError('Reason is required when setting state to suspended/canceled.', 400, 'ENTITLEMENT_REASON_REQUIRED');
+        }
+        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({
+            accountId,
+            planVersionId: nextPlanVersionId,
+            state: nextState,
+            effectiveAt,
+            effectiveUntil,
+            updatedBy: String(input.actorUserId || 'system').trim() || 'system',
+            createdAt: before?.effectiveAt || now,
+            updatedAt: now
+        });
+        const after = this.getAccountEntitlement(accountId);
+        this.addEntitlementAuditLog({
+            actorUserId: input.actorUserId,
+            actorRole: input.actorRole,
+            accountId,
+            action: 'account-entitlement-update',
+            reason: normalizedReason || undefined,
+            before: before || {
+                accountId,
+                missing: true
+            },
+            after,
+            requestId: input.requestId
+        });
+        return after;
+    }
+    listEntitlementAuditLog(accountId, limit = 100, offset = 0) {
+        const normalizedAccountId = String(accountId || '').trim();
+        const safeLimit = Math.max(1, Math.min(500, Math.floor(Number(limit) || 100)));
+        const safeOffset = Math.max(0, Math.floor(Number(offset) || 0));
+        const rows = this.db.prepare(`
+            SELECT id, account_id, action, actor_user_id, actor_role, reason, before_json, after_json, created_at
+            FROM entitlement_audit_log
+            WHERE tenant_id = ? AND account_id = ?
+            ORDER BY created_at DESC
+            LIMIT ?
+            OFFSET ?
+        `).all(this.tenantId, normalizedAccountId, safeLimit, safeOffset);
+        return rows.map((row) => ({
+            id: String(row.id || ''),
+            accountId: String(row.account_id || ''),
+            action: String(row.action || ''),
+            actorUserId: String(row.actor_user_id || ''),
+            actorRole: String(row.actor_role || ''),
+            reason: row.reason ? String(row.reason) : null,
+            before: this.parseJsonObject(row.before_json || '{}'),
+            after: this.parseJsonObject(row.after_json || '{}'),
+            createdAt: String(row.created_at || '')
+        }));
+    }
+    getAccountEntitlementsPayload(input) {
+        const workspaceId = String(input.workspaceId || '').trim();
+        const userId = String(input.userId || '').trim();
+        const accountId = this.deps.getWorkspaceOwnerUserId(workspaceId) || userId;
+        const entitlement = this.getAccountEntitlement(accountId);
+        const seatUsage = this.countWorkspaceSeatUsage(workspaceId, { includeInvited: true });
+        const features = Object.values(entitlement.version.features).reduce((acc, feature) => {
+            const evaluation = this.evaluateFeatureAccess({
+                userId,
+                workspaceId,
+                featureKey: feature.featureKey
+            });
+            acc[feature.featureKey] = {
+                allowed: evaluation.allowed,
+                access: feature.access,
+                config: feature.config
+            };
+            return acc;
+        }, {});
+        return {
+            accountId,
+            workspaceId,
+            planId: entitlement.planId,
+            planVersionId: entitlement.planVersionId,
+            state: entitlement.state,
+            effectiveAt: entitlement.effectiveAt,
+            effectiveUntil: entitlement.effectiveUntil,
+            seatUsage,
+            features
+        };
+    }
+}