@taskforcehq/taskforce 0.3.301 → 0.3.303

package/dist/core/Taskforce.js

@@ -31,7 +31,8 @@ import { normalizePriorityDefinitions as normalizePriorityDefinitionsInternal, n
 import { DEFAULT_CATEGORY_LABEL, DEFAULT_CATEGORY_VALUE, DEFAULT_TYPE_VALUE, } from '../shared/taxonomyDefaults.js';
 import { cloneDefaultWorkflowDefinitions, DEFAULT_WORKFLOW_VALUE, } from '../shared/workflowDefaults.js';
 import { getBuiltInTaxonomyLibraryPack, getDefaultStarterTaxonomyLibraryPack, getEmergencyStarterTaxonomyLibraryPack } from '../shared/taxonomyLibrary.js';
-import { formatTaskReference, parseTaskReference, } from '../utils/taskReferences.js';
+import { parseTaskReference, } from '../utils/taskReferences.js';
+import { allocateNextLocalTaskReferenceNumber as allocateNextLocalTaskReferenceNumberPolicy, deriveTaskReferenceLabel, allocateNextTaskReferenceNumber as allocateNextTaskReferenceNumberPolicy, getLocalTaskReferenceSequenceValue as getLocalTaskReferenceSequenceValuePolicy, getMaxLocalTaskReferenceNumber as getMaxLocalTaskReferenceNumberPolicy, getMaxTaskReferenceNumber as getMaxTaskReferenceNumberPolicy, getTaskByLocalReferenceNumber as getTaskByLocalReferenceNumberPolicy, getTaskByReferenceNumber as getTaskByReferenceNumberPolicy, getTaskReferenceSequenceValue as getTaskReferenceSequenceValuePolicy, persistLocalTaskReferenceSequence as persistLocalTaskReferenceSequencePolicy, persistTaskReferenceSequence as persistTaskReferenceSequencePolicy, relocateTaskReferenceConflict as relocateTaskReferenceConflictPolicy, reserveTaskReferenceNumber as reserveTaskReferenceNumberPolicy, resolveTaskIdentifier as resolveTaskIdentifierPolicy, } from './taskReferencePolicy.js';
 import { formatInitiativeReference, formatWorkstreamReference, } from '../utils/planningReferences.js';
 import { getDocumentReferenceLabel } from '../utils/documentReferences.js';
 import { getImageReferenceLabel } from '../utils/imageReferences.js';
@@ -1109,7 +1110,7 @@ export class TaskforceCore {
             : path.resolve(this.projectRoot, storagePath);
         this.dbPath = path.resolve(this.basePath, 'taskforce.db');
         this.configFile = path.resolve(this.basePath, 'config.json');
-        this.globalSettingsDbPath = path.resolve(os.homedir(), '.tasknexus', 'taskforce-global.db');
+        this.globalSettingsDbPath = path.resolve(os.homedir(), '.taskforce', 'taskforce-global.db');
         this.ensureDirectories();
         this.migrateLegacyGlobalSettingsDbIfNeeded();
         // Initialize Database Adapter (SQLite default; Postgres scaffolded)
@@ -1174,7 +1175,6 @@ export class TaskforceCore {
             writeGlobalConfig: (config) => this.writeGlobalConfig(config),
         });
         this.planEntitlementService.repairPlanCatalogDefaultsIfNeeded();
-        this.planEntitlementService.repairSignupMonetizationSettingsIfNeeded();
         this.planEntitlementService.normalizeLegacyPlanDataIfNeeded();
         this.planEntitlementService.backfillAccountEntitlements();
         this.repairDetachedAnnotatedAttachmentSessions();
@@ -1208,11 +1208,14 @@ export class TaskforceCore {
     upsertCanonicalEntitlementRecord(input) {
         return this.planEntitlementService.upsertCanonicalEntitlementRecord(input);
     }
+    transitionCanonicalCommercialState(input) {
+        return this.planEntitlementService.transitionCanonicalCommercialState(input);
+    }
     resolveWorkspaceLimitForUser(userId) {
         return this.planEntitlementService.resolveWorkspaceLimitForUser(userId);
     }
-    resolveRegistrationPlanAssignment(selectedPlanVersionIdRaw) {
-        return this.planEntitlementService.resolveRegistrationPlanAssignment(selectedPlanVersionIdRaw);
+    resolveRegistrationOnboardingOutcome(selectedPlanVersionIdRaw) {
+        return this.planEntitlementService.resolveRegistrationOnboardingOutcome(selectedPlanVersionIdRaw);
     }
     createUserBillingRecord(userId, options) {
         return this.planEntitlementService.createUserBillingRecord(userId, options);
@@ -1269,7 +1272,6 @@ export class TaskforceCore {
         if (fs.existsSync(this.globalSettingsDbPath))
             return;
         const candidates = [
-            path.resolve(os.homedir(), '.taskforce', 'taskforce-global.db'),
             path.resolve(this.basePath, '_global', 'taskforce-global.db')
         ];
         for (const legacyPath of candidates) {
@@ -1297,6 +1299,7 @@ export class TaskforceCore {
                 tenant_id TEXT NOT NULL DEFAULT 'default',
                 workspace_id TEXT NOT NULL DEFAULT 'default',
                 reference_number INTEGER,
+                local_reference_number INTEGER,
                 title TEXT NOT NULL,
                 description TEXT,
                 status TEXT NOT NULL,
@@ -1331,6 +1334,13 @@ export class TaskforceCore {
                 PRIMARY KEY (tenant_id, workspace_id)
             );
 
+            CREATE TABLE IF NOT EXISTS workspace_local_task_reference_sequences (
+                tenant_id TEXT NOT NULL DEFAULT 'default',
+                workspace_id TEXT NOT NULL DEFAULT 'default',
+                next_reference_number INTEGER NOT NULL DEFAULT 0,
+                PRIMARY KEY (tenant_id, workspace_id)
+            );
+
             CREATE TABLE IF NOT EXISTS initiatives (
                 id TEXT PRIMARY KEY,
                 tenant_id TEXT NOT NULL DEFAULT 'default',
@@ -2590,11 +2600,11 @@ export class TaskforceCore {
         const config = this.readConfig(workspaceId, userId) || {};
         return typeof config.jsonBackupEnabled === 'boolean';
     }
-    getSignupMonetizationSettings() {
-        return this.planEntitlementService.getSignupMonetizationSettings();
+    getOnboardingPolicy() {
+        return this.planEntitlementService.getOnboardingPolicy();
     }
-    validateSignupMonetizationSettings(input) {
-        return this.planEntitlementService.validateSignupMonetizationSettings(input);
+    validateOnboardingPolicy(input) {
+        return this.planEntitlementService.validateOnboardingPolicy(input);
     }
     updateGlobalSettings(settings) {
         updateGlobalSettingsService(this.getGlobalSettingsServiceDeps(), settings);
@@ -2788,10 +2798,12 @@ export class TaskforceCore {
         const dueDate = this.sanitizeDateOnly(row.due_date);
         const scheduledWeekKey = row.scheduled_week_key || (scheduledDate ? this.dateOnlyToIsoWeekKey(scheduledDate) : null);
         const referenceNumber = this.sanitizeTaskReferenceNumber(row.reference_number);
+        const localReferenceNumber = this.sanitizeTaskReferenceNumber(row.local_reference_number);
         return {
             id: taskId,
             referenceNumber,
-            referenceLabel: formatTaskReference(referenceNumber),
+            localReferenceNumber,
+            referenceLabel: deriveTaskReferenceLabel({ referenceNumber, localReferenceNumber }),
             title: row.title,
             description: row.description,
             status: this.normalizeStatusValue(row.status),
@@ -2879,31 +2891,24 @@ export class TaskforceCore {
         const normalized = Math.floor(numeric);
         return normalized > 0 ? normalized : null;
     }
+    getTaskReferencePolicyDeps() {
+        return {
+            db: this.db,
+            tenantId: this.tenantId,
+            normalizeWorkspaceId: this.normalizeWorkspaceId.bind(this),
+            sanitizeTaskReferenceNumber: this.sanitizeTaskReferenceNumber.bind(this),
+            rowToTask: this.rowToTask.bind(this),
+            getTask: this.getTask.bind(this),
+        };
+    }
     getTaskByReferenceNumber(referenceNumber, workspaceId) {
-        const normalizedReferenceNumber = this.sanitizeTaskReferenceNumber(referenceNumber);
-        if (!normalizedReferenceNumber)
-            return null;
-        const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
-        const row = this.db.prepare(`
-            SELECT * FROM tasks
-            WHERE tenant_id = ? AND workspace_id = ? AND reference_number = ?
-            LIMIT 1
-        `).get(this.tenantId, normalizedWorkspaceId, normalizedReferenceNumber);
-        if (!row)
-            return null;
-        return this.rowToTask(row);
+        return getTaskByReferenceNumberPolicy(this.getTaskReferencePolicyDeps(), referenceNumber, workspaceId);
+    }
+    getTaskByLocalReferenceNumber(referenceNumber, workspaceId) {
+        return getTaskByLocalReferenceNumberPolicy(this.getTaskReferencePolicyDeps(), referenceNumber, workspaceId);
     }
     resolveTaskIdentifier(value, workspaceId) {
-        const normalizedValue = String(value || '').trim();
-        if (!normalizedValue)
-            return null;
-        const referenceNumber = parseTaskReference(normalizedValue);
-        if (referenceNumber) {
-            const exactReferenceMatch = this.getTaskByReferenceNumber(referenceNumber, workspaceId);
-            if (exactReferenceMatch)
-                return exactReferenceMatch;
-        }
-        return this.getTask(normalizedValue, workspaceId);
+        return resolveTaskIdentifierPolicy(this.getTaskReferencePolicyDeps(), value, workspaceId);
     }
     getInitiative(id, workspaceId) {
         const normalizedId = String(id || '').trim();
@@ -3234,42 +3239,35 @@ export class TaskforceCore {
         });
         return this.listChecklistItems(normalizedTaskId, normalizedWorkspaceId);
     }
-    reserveTaskReferenceNumber(workspaceId, preferredReferenceNumber) {
-        const normalizedWorkspaceId = this.normalizeWorkspaceId(workspaceId);
-        const preferred = this.sanitizeTaskReferenceNumber(preferredReferenceNumber);
-        if (preferred) {
-            const existing = this.db.prepare(`
-                SELECT id
-                FROM tasks
-                WHERE tenant_id = ? AND workspace_id = ? AND reference_number = ?
-                LIMIT 1
-            `).get(this.tenantId, normalizedWorkspaceId, preferred);
-            if (!existing?.id) {
-                this.db.prepare(`
-                    INSERT INTO workspace_task_reference_sequences (tenant_id, workspace_id, next_reference_number)
-                    VALUES (?, ?, ?)
-                    ON CONFLICT (tenant_id, workspace_id) DO UPDATE SET
-                        next_reference_number = CASE
-                            WHEN workspace_task_reference_sequences.next_reference_number < EXCLUDED.next_reference_number
-                                THEN EXCLUDED.next_reference_number
-                            ELSE workspace_task_reference_sequences.next_reference_number
-                        END
-                `).run(this.tenantId, normalizedWorkspaceId, preferred);
-                return preferred;
-            }
-        }
-        const row = this.db.prepare(`
-            INSERT INTO workspace_task_reference_sequences (tenant_id, workspace_id, next_reference_number)
-            VALUES (?, ?, 1)
-            ON CONFLICT (tenant_id, workspace_id) DO UPDATE SET
-                next_reference_number = workspace_task_reference_sequences.next_reference_number + 1
-            RETURNING next_reference_number
-        `).get(this.tenantId, normalizedWorkspaceId);
-        const referenceNumber = this.sanitizeTaskReferenceNumber(row?.next_reference_number);
-        if (!referenceNumber) {
-            throw new TaskforceRuleError('Failed to allocate task reference number', 500, 'TASK_REFERENCE_ALLOC_FAILED');
-        }
-        return referenceNumber;
+    getTaskReferenceSequenceValue(workspaceId) {
+        return getTaskReferenceSequenceValuePolicy(this.getTaskReferencePolicyDeps(), workspaceId);
+    }
+    getLocalTaskReferenceSequenceValue(workspaceId) {
+        return getLocalTaskReferenceSequenceValuePolicy(this.getTaskReferencePolicyDeps(), workspaceId);
+    }
+    getMaxTaskReferenceNumber(workspaceId, excludeTaskId) {
+        return getMaxTaskReferenceNumberPolicy(this.getTaskReferencePolicyDeps(), workspaceId, excludeTaskId);
+    }
+    getMaxLocalTaskReferenceNumber(workspaceId, excludeTaskId) {
+        return getMaxLocalTaskReferenceNumberPolicy(this.getTaskReferencePolicyDeps(), workspaceId, excludeTaskId);
+    }
+    persistTaskReferenceSequence(workspaceId, referenceNumber) {
+        persistTaskReferenceSequencePolicy(this.getTaskReferencePolicyDeps(), workspaceId, referenceNumber);
+    }
+    persistLocalTaskReferenceSequence(workspaceId, referenceNumber) {
+        persistLocalTaskReferenceSequencePolicy(this.getTaskReferencePolicyDeps(), workspaceId, referenceNumber);
+    }
+    allocateNextTaskReferenceNumber(workspaceId, excludeTaskId) {
+        return allocateNextTaskReferenceNumberPolicy(this.getTaskReferencePolicyDeps(), workspaceId, excludeTaskId);
+    }
+    allocateNextLocalTaskReferenceNumber(workspaceId, excludeTaskId) {
+        return allocateNextLocalTaskReferenceNumberPolicy(this.getTaskReferencePolicyDeps(), workspaceId, excludeTaskId);
+    }
+    relocateTaskReferenceConflict(workspaceId, referenceNumber, claimantTaskId, updatedAt) {
+        return relocateTaskReferenceConflictPolicy(this.getTaskReferencePolicyDeps(), workspaceId, referenceNumber, claimantTaskId, updatedAt);
+    }
+    reserveTaskReferenceNumber(workspaceId, preferredReferenceNumber, currentTaskId) {
+        return reserveTaskReferenceNumberPolicy(this.getTaskReferencePolicyDeps(), workspaceId, preferredReferenceNumber, currentTaskId);
     }
     reserveGenericReferenceNumber(params) {
         const normalizedWorkspaceId = this.normalizeWorkspaceId(params.workspaceId);
@@ -4060,7 +4058,7 @@ export class TaskforceCore {
         if (!normalizedUserId || normalizedUserId === 'anonymous')
             return null;
         const row = this.db.prepare(`
-            SELECT id, email, display_name, system_role, COALESCE(beta_access, 1) AS beta_access
+            SELECT id, email, display_name, avatar_url, system_role, COALESCE(beta_access, 1) AS beta_access
             FROM users
             WHERE tenant_id = ? AND id = ?
             LIMIT 1
@@ -4071,13 +4069,17 @@ export class TaskforceCore {
             userId: row.id,
             email: row.email,
             displayName: row.display_name || null,
+            avatarUrl: row.avatar_url || null,
             systemRole: this.normalizeSystemRole(row.system_role, 'user'),
             betaAccess: row.beta_access === undefined || row.beta_access === null ? true : Boolean(row.beta_access)
         };
     }
-    updateUserDisplayName(userId, displayName) {
+    updateUserProfile(userId, input) {
         const normalizedUserId = String(userId || '').trim();
-        const trimmedDisplayName = String(displayName || '').trim();
+        const trimmedDisplayName = String(input.displayName || '').trim();
+        const normalizedAvatarUrl = input.avatarUrl === undefined
+            ? undefined
+            : (typeof input.avatarUrl === 'string' && input.avatarUrl.trim().length > 0 ? input.avatarUrl.trim() : null);
         if (!normalizedUserId)
             return null;
         if (!trimmedDisplayName) {
@@ -4086,15 +4088,145 @@ export class TaskforceCore {
         if (trimmedDisplayName.length > 120) {
             throw new TaskforceRuleError('Display name must be 120 characters or fewer', 400, 'DISPLAY_NAME_TOO_LONG');
         }
-        const result = this.db.prepare(`
-            UPDATE users
-            SET display_name = ?, updated_at = ?
-            WHERE tenant_id = ? AND id = ?
-        `).run(trimmedDisplayName, new Date().toISOString(), this.tenantId, normalizedUserId);
+        const now = new Date().toISOString();
+        const result = normalizedAvatarUrl === undefined
+            ? this.db.prepare(`
+                UPDATE users
+                SET display_name = ?, updated_at = ?
+                WHERE tenant_id = ? AND id = ?
+            `).run(trimmedDisplayName, now, this.tenantId, normalizedUserId)
+            : this.db.prepare(`
+                UPDATE users
+                SET display_name = ?, avatar_url = ?, updated_at = ?
+                WHERE tenant_id = ? AND id = ?
+            `).run(trimmedDisplayName, normalizedAvatarUrl, now, this.tenantId, normalizedUserId);
         if (Number(result?.changes || 0) <= 0)
             return null;
         return this.resolveUserIdentity(normalizedUserId);
     }
+    updateUserDisplayName(userId, displayName) {
+        return this.updateUserProfile(userId, { displayName });
+    }
+    createUserAvatarUploadDraft(input) {
+        const draftId = String(input.draftId || '').trim();
+        const userId = String(input.userId || '').trim();
+        const storageKey = String(input.storageKey || '').trim();
+        const mimeType = String(input.mimeType || 'application/octet-stream').trim() || 'application/octet-stream';
+        const originalFilename = String(input.originalFilename || '').trim() || 'avatar';
+        const sizeBytes = Number.isFinite(Number(input.sizeBytes)) ? Math.max(0, Math.floor(Number(input.sizeBytes))) : 0;
+        const storageProvider = input.storageProvider === 'r2' || input.storageProvider === 'external' ? input.storageProvider : 'local';
+        if (!draftId)
+            throw new TaskforceRuleError('draftId is required', 400, 'AVATAR_DRAFT_ID_REQUIRED');
+        if (!userId)
+            throw new TaskforceRuleError('userId is required', 400, 'USER_ID_REQUIRED');
+        if (!storageKey)
+            throw new TaskforceRuleError('storageKey is required', 400, 'AVATAR_STORAGE_KEY_REQUIRED');
+        const now = new Date().toISOString();
+        this.db.prepare(`
+            INSERT INTO user_avatar_upload_drafts (
+                draft_id, tenant_id, user_id, storage_key, mime_type, original_filename, size_bytes, storage_provider,
+                finalized_at, consumed_at, discarded_at, created_at, updated_at
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, NULL, ?, ?)
+        `).run(draftId, this.tenantId, userId, storageKey, mimeType, originalFilename, sizeBytes, storageProvider, now, now);
+        return this.getUserAvatarUploadDraft(userId, draftId);
+    }
+    getUserAvatarUploadDraft(userId, draftId) {
+        const normalizedUserId = String(userId || '').trim();
+        const normalizedDraftId = String(draftId || '').trim();
+        if (!normalizedUserId || !normalizedDraftId)
+            return null;
+        const row = this.db.prepare(`
+            SELECT draft_id, user_id, storage_key, mime_type, original_filename, size_bytes, storage_provider,
+                   finalized_at, consumed_at, discarded_at, created_at, updated_at
+            FROM user_avatar_upload_drafts
+            WHERE tenant_id = ? AND user_id = ? AND draft_id = ?
+            LIMIT 1
+        `).get(this.tenantId, normalizedUserId, normalizedDraftId);
+        if (!row?.draft_id)
+            return null;
+        return {
+            draftId: String(row.draft_id),
+            userId: String(row.user_id || normalizedUserId),
+            storageKey: String(row.storage_key || ''),
+            mimeType: String(row.mime_type || 'application/octet-stream'),
+            originalFilename: String(row.original_filename || 'avatar'),
+            sizeBytes: Number(row.size_bytes || 0),
+            storageProvider: String(row.storage_provider || 'local') === 'r2'
+                ? 'r2'
+                : String(row.storage_provider || 'local') === 'external'
+                    ? 'external'
+                    : 'local',
+            finalizedAt: row.finalized_at ? String(row.finalized_at) : null,
+            consumedAt: row.consumed_at ? String(row.consumed_at) : null,
+            discardedAt: row.discarded_at ? String(row.discarded_at) : null,
+            createdAt: String(row.created_at || ''),
+            updatedAt: String(row.updated_at || '')
+        };
+    }
+    markUserAvatarUploadDraftFinalized(userId, draftId) {
+        const existing = this.getUserAvatarUploadDraft(userId, draftId);
+        if (!existing || existing.discardedAt)
+            return null;
+        const now = new Date().toISOString();
+        this.db.prepare(`
+            UPDATE user_avatar_upload_drafts
+            SET finalized_at = COALESCE(finalized_at, ?), updated_at = ?
+            WHERE tenant_id = ? AND user_id = ? AND draft_id = ? AND discarded_at IS NULL
+        `).run(now, now, this.tenantId, existing.userId, existing.draftId);
+        return this.getUserAvatarUploadDraft(existing.userId, existing.draftId);
+    }
+    markUserAvatarUploadDraftConsumed(userId, draftId) {
+        const existing = this.getUserAvatarUploadDraft(userId, draftId);
+        if (!existing || existing.discardedAt)
+            return null;
+        const now = new Date().toISOString();
+        this.db.prepare(`
+            UPDATE user_avatar_upload_drafts
+            SET consumed_at = COALESCE(consumed_at, ?), updated_at = ?
+            WHERE tenant_id = ? AND user_id = ? AND draft_id = ? AND discarded_at IS NULL
+        `).run(now, now, this.tenantId, existing.userId, existing.draftId);
+        return this.getUserAvatarUploadDraft(existing.userId, existing.draftId);
+    }
+    discardUserAvatarUploadDraft(userId, draftId) {
+        const existing = this.getUserAvatarUploadDraft(userId, draftId);
+        if (!existing || existing.discardedAt)
+            return existing;
+        const now = new Date().toISOString();
+        this.db.prepare(`
+            UPDATE user_avatar_upload_drafts
+            SET discarded_at = ?, updated_at = ?
+            WHERE tenant_id = ? AND user_id = ? AND draft_id = ? AND discarded_at IS NULL
+        `).run(now, now, this.tenantId, existing.userId, existing.draftId);
+        return this.getUserAvatarUploadDraft(existing.userId, existing.draftId);
+    }
+    cleanupStaleUserAvatarUploadDrafts(userId, olderThanIso) {
+        const normalizedUserId = String(userId || '').trim();
+        const cutoff = String(olderThanIso || '').trim();
+        if (!normalizedUserId || !cutoff)
+            return [];
+        const rows = this.db.prepare(`
+            SELECT draft_id
+            FROM user_avatar_upload_drafts
+            WHERE tenant_id = ?
+              AND user_id = ?
+              AND discarded_at IS NULL
+              AND consumed_at IS NULL
+              AND created_at < ?
+        `).all(this.tenantId, normalizedUserId, cutoff);
+        const staleDrafts = rows
+            .map((row) => this.getUserAvatarUploadDraft(normalizedUserId, String(row?.draft_id || '')))
+            .filter((row) => Boolean(row && !row.discardedAt));
+        if (staleDrafts.length === 0)
+            return [];
+        const now = new Date().toISOString();
+        this.db.prepare(`
+            UPDATE user_avatar_upload_drafts
+            SET discarded_at = ?, updated_at = ?
+            WHERE tenant_id = ? AND user_id = ? AND discarded_at IS NULL AND consumed_at IS NULL AND created_at < ?
+        `).run(now, now, this.tenantId, normalizedUserId, cutoff);
+        return staleDrafts;
+    }
     getSystemRole(userId) {
         const normalizedUserId = String(userId || '').trim();
         if (!normalizedUserId || normalizedUserId === 'anonymous')
@@ -4245,6 +4377,193 @@ export class TaskforceCore {
         `).run(enabled ? 1 : 0, new Date().toISOString(), this.tenantId, normalizedUserId);
         return Number(result?.changes || 0) > 0;
     }
+    purgeSystemUser(input) {
+        const targetUserId = String(input.targetUserId || '').trim();
+        const actorUserId = String(input.actorUserId || '').trim();
+        const emailConfirmation = String(input.emailConfirmation || '').trim().toLowerCase();
+        if (!targetUserId) {
+            throw new TaskforceRuleError('targetUserId is required', 400, 'TARGET_USER_ID_REQUIRED');
+        }
+        if (!actorUserId || actorUserId === 'anonymous') {
+            throw new TaskforceRuleError('actorUserId is required', 400, 'ACTOR_USER_ID_REQUIRED');
+        }
+        if (!emailConfirmation) {
+            throw new TaskforceRuleError('Email confirmation is required', 400, 'EMAIL_CONFIRMATION_REQUIRED');
+        }
+        if (targetUserId === actorUserId) {
+            throw new TaskforceRuleError('Cannot purge the current system admin session user', 400, 'CURRENT_SYSTEM_USER_PURGE_FORBIDDEN');
+        }
+        return this.db.transaction(() => {
+            const user = this.db.prepare(`
+                SELECT
+                    id,
+                    email,
+                    COALESCE(system_role, 'user') AS system_role,
+                    COALESCE(is_disabled, 0) AS is_disabled
+                FROM users
+                WHERE tenant_id = ? AND id = ?
+                LIMIT 1
+            `).get(this.tenantId, targetUserId);
+            if (!user?.id || !user.email) {
+                throw new TaskforceRuleError('User not found', 404, 'USER_NOT_FOUND');
+            }
+            const normalizedEmail = String(user.email).trim().toLowerCase();
+            if (normalizedEmail !== emailConfirmation) {
+                throw new TaskforceRuleError('Email confirmation did not match the target user', 400, 'EMAIL_CONFIRMATION_MISMATCH');
+            }
+            const currentRole = this.normalizeSystemRole(user.system_role, 'user');
+            const isDisabled = Boolean(user.is_disabled);
+            if (currentRole === 'system_admin' && !isDisabled && this.countSystemAdmins() <= 1) {
+                throw new TaskforceRuleError('Cannot purge the last enabled system admin', 400, 'LAST_SYSTEM_ADMIN_REQUIRED');
+            }
+            const elevatedWorkspaceMemberships = this.db.prepare(`
+                SELECT
+                    m.workspace_id AS workspace_id,
+                    COALESCE(m.role, 'member') AS role,
+                    w.name AS workspace_name
+                FROM workspace_memberships m
+                LEFT JOIN workspaces w
+                  ON w.tenant_id = m.tenant_id
+                 AND w.id = m.workspace_id
+                WHERE m.tenant_id = ?
+                  AND m.user_id = ?
+                  AND COALESCE(m.status, 'active') = 'active'
+                  AND COALESCE(m.role, 'member') IN ('owner', 'admin')
+                ORDER BY COALESCE(w.updated_at, w.created_at) DESC, w.name ASC
+                LIMIT 10
+            `).all(this.tenantId, targetUserId);
+            if (elevatedWorkspaceMemberships.length > 0) {
+                throw new TaskforceRuleError('Cannot purge a user with active owner/admin workspace memberships', 409, 'SYSTEM_USER_PURGE_BLOCKED_ACTIVE_WORKSPACE_ROLE', {
+                    memberships: elevatedWorkspaceMemberships.map((membership) => ({
+                        workspaceId: membership.workspace_id ? String(membership.workspace_id) : null,
+                        workspaceName: membership.workspace_name ? String(membership.workspace_name) : null,
+                        role: membership.role ? String(membership.role) : null
+                    }))
+                });
+            }
+            const billingRow = this.db.prepare(`
+                SELECT
+                    stripe_customer_id,
+                    stripe_subscription_id,
+                    stripe_price_id,
+                    stripe_status,
+                    billing_interval
+                FROM user_billing
+                WHERE tenant_id = ? AND user_id = ?
+                LIMIT 1
+            `).get(this.tenantId, targetUserId);
+            const hasCommercialBillingState = [
+                billingRow?.stripe_customer_id,
+                billingRow?.stripe_subscription_id,
+                billingRow?.stripe_price_id,
+                billingRow?.stripe_status,
+                billingRow?.billing_interval
+            ].some((value) => String(value || '').trim().length > 0);
+            if (hasCommercialBillingState) {
+                throw new TaskforceRuleError('Cannot purge a user with active commercial billing state', 409, 'SYSTEM_USER_PURGE_BLOCKED_BILLING_STATE');
+            }
+            const now = new Date().toISOString();
+            const runCount = (sql, ...params) => Number(this.db.prepare(sql).run(...params)?.changes || 0);
+            const unassignedTaskCount = runCount(`
+                UPDATE tasks
+                SET assignee = 'unassigned',
+                    updated_at = ?
+                WHERE tenant_id = ?
+                  AND assignee = ?
+                  AND is_archived = 0
+            `, now, this.tenantId, targetUserId);
+            const clearedInitiativeOwnerCount = runCount(`
+                UPDATE initiatives
+                SET owner_id = NULL,
+                    updated_at = ?
+                WHERE tenant_id = ?
+                  AND owner_id = ?
+            `, now, this.tenantId, targetUserId);
+            const clearedWorkstreamOwnerCount = runCount(`
+                UPDATE workstreams
+                SET owner_id = NULL,
+                    updated_at = ?
+                WHERE tenant_id = ?
+                  AND owner_id = ?
+            `, now, this.tenantId, targetUserId);
+            const deletedEntitlementCount = runCount(`
+                DELETE FROM account_entitlements
+                WHERE tenant_id = ?
+                  AND account_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedWorkspaceMembershipCount = runCount(`
+                DELETE FROM workspace_memberships
+                WHERE tenant_id = ?
+                  AND user_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedAuthTokenCount = runCount(`
+                DELETE FROM auth_tokens
+                WHERE tenant_id = ?
+                  AND user_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedAvatarDraftCount = runCount(`
+                DELETE FROM user_avatar_upload_drafts
+                WHERE tenant_id = ?
+                  AND user_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedMcpAccessTokenCount = runCount(`
+                DELETE FROM mcp_access_tokens
+                WHERE tenant_id = ?
+                  AND user_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedMcpOauthAuthCodeCount = runCount(`
+                DELETE FROM mcp_oauth_auth_codes
+                WHERE tenant_id = ?
+                  AND user_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedMcpOauthConnectorGrantCount = runCount(`
+                DELETE FROM mcp_oauth_connector_grants
+                WHERE tenant_id = ?
+                  AND user_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedUiStateCount = runCount(`
+                DELETE FROM ui_state
+                WHERE tenant_id = ?
+                  AND user_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedUserPreferenceCount = runCount(`
+                DELETE FROM user_preferences
+                WHERE tenant_id = ?
+                  AND user_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedUserBillingCount = runCount(`
+                DELETE FROM user_billing
+                WHERE tenant_id = ?
+                  AND user_id = ?
+            `, this.tenantId, targetUserId);
+            const deletedUserCount = runCount(`
+                DELETE FROM users
+                WHERE tenant_id = ?
+                  AND id = ?
+            `, this.tenantId, targetUserId);
+            if (deletedUserCount !== 1) {
+                throw new TaskforceRuleError('User not found', 404, 'USER_NOT_FOUND');
+            }
+            return {
+                targetUserId,
+                email: String(user.email),
+                unassignedTaskCount,
+                clearedInitiativeOwnerCount,
+                clearedWorkstreamOwnerCount,
+                deletedWorkspaceMembershipCount,
+                deletedAuthTokenCount,
+                deletedAvatarDraftCount,
+                deletedMcpAccessTokenCount,
+                deletedMcpOauthAuthCodeCount,
+                deletedMcpOauthConnectorGrantCount,
+                deletedUiStateCount,
+                deletedUserPreferenceCount,
+                deletedEntitlementCount,
+                deletedUserBillingCount,
+                deletedUserCount
+            };
+        })();
+    }
     clearActiveAssignmentsForUnavailableActor(actorId, workspaceId, updatedAt) {
         const normalizedActorId = String(actorId || '').trim();
         const normalizedWorkspaceId = String(workspaceId || 'default').trim() || 'default';
@@ -5199,7 +5518,20 @@ export class TaskforceCore {
         const assignFirstSystemAdmin = !this.hasAnySystemAdmin();
         const betaAccess = input.betaAccess !== false;
         const requestedWorkspaceId = String(input.workspaceId || '').trim();
-        const registrationPlanAssignment = this.resolveRegistrationPlanAssignment(input.planVersionId);
+        const onboardingOutcome = this.resolveRegistrationOnboardingOutcome(input.planVersionId);
+        const applyRegistrationCommercialState = (accountId, now) => {
+            this.transitionCanonicalCommercialState({
+                accountId,
+                planVersionId: onboardingOutcome.planVersionId,
+                state: onboardingOutcome.commercialState,
+                effectiveAt: now,
+                billingMirrorPlanId: onboardingOutcome.planId,
+                source: 'registration',
+                updatedBy: 'registration',
+                createdAt: now,
+                updatedAt: now
+            });
+        };
         if (!requestedWorkspaceId || requestedWorkspaceId.toLowerCase() === 'default') {
             const now = new Date().toISOString();
             const userId = this.generateEntityId('user');
@@ -5208,32 +5540,14 @@ export class TaskforceCore {
                 INSERT INTO users (id, tenant_id, email, display_name, auth_provider, external_auth_id, password_hash, system_role, beta_access, is_disabled, created_at, updated_at)
                 VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 0, ?, ?)
             `).run(userId, this.tenantId, email, displayName, 'password', email, hashPassword(password), assignFirstSystemAdmin ? 'system_admin' : 'user', betaAccess ? 1 : 0, now, now);
-            if (registrationPlanAssignment.requiresPlanSelection) {
-                this.createUserBillingRecord(userId, {
-                    entitlementState: 'pending_plan_selection',
-                    planId: null
-                });
-            }
-            if (!registrationPlanAssignment.requiresPlanSelection && registrationPlanAssignment.planVersionId && registrationPlanAssignment.planId) {
-                this.createUserBillingRecord(userId, {
-                    entitlementState: 'active',
-                    planId: registrationPlanAssignment.planId
-                });
-                this.upsertCanonicalEntitlementRecord({
-                    accountId: userId,
-                    planVersionId: registrationPlanAssignment.planVersionId,
-                    state: 'active',
-                    effectiveAt: now,
-                    updatedBy: 'registration',
-                    createdAt: now,
-                    updatedAt: now
-                });
-            }
+            applyRegistrationCommercialState(userId, now);
             return {
                 userId,
                 workspaceId: null,
                 role: 'member',
-                planSelectionRequired: registrationPlanAssignment.requiresPlanSelection
+                planSelectionRequired: onboardingOutcome.requiresPlanSelection,
+                checkoutPending: onboardingOutcome.checkoutPending,
+                commercialState: onboardingOutcome.commercialState
             };
         }
         const workspaceId = requestedWorkspaceId;
@@ -5251,27 +5565,12 @@ export class TaskforceCore {
                 WHERE tenant_id = ? AND id = ?
             `).run(new Date().toISOString(), this.tenantId, created.userId);
         }
-        if (registrationPlanAssignment.requiresPlanSelection) {
-            this.createUserBillingRecord(created.userId, {
-                entitlementState: 'pending_plan_selection',
-                planId: null
-            });
-        }
-        if (!registrationPlanAssignment.requiresPlanSelection && registrationPlanAssignment.planVersionId && registrationPlanAssignment.planId) {
-            this.createUserBillingRecord(created.userId, {
-                entitlementState: 'active',
-                planId: registrationPlanAssignment.planId
-            });
-            this.upsertCanonicalEntitlementRecord({
-                accountId: created.userId,
-                planVersionId: registrationPlanAssignment.planVersionId,
-                state: 'active',
-                updatedBy: 'registration'
-            });
-        }
+        applyRegistrationCommercialState(created.userId);
         return {
             ...created,
-            planSelectionRequired: registrationPlanAssignment.requiresPlanSelection
+            planSelectionRequired: onboardingOutcome.requiresPlanSelection,
+            checkoutPending: onboardingOutcome.checkoutPending,
+            commercialState: onboardingOutcome.commercialState
         };
     }
     createOneTimeAuthToken(userId, purpose, ttlSeconds, workspaceId) {
@@ -5770,6 +6069,9 @@ export class TaskforceCore {
         this.assertRequiredTaskTaxonomies(normalizedInput.taxonomies, normalizedWorkspaceId);
         const incomingId = String(normalizedInput.id || '').trim();
         const incomingReferenceNumber = this.sanitizeTaskReferenceNumber(normalizedInput.referenceNumber);
+        const useProvisionalLocalReference = options?.provisionalLocalReference === true
+            && options?.allowClientProvidedId !== true
+            && !incomingReferenceNumber;
         if (incomingId && !allowClientProvidedId) {
             throw new TaskforceRuleError('Client-supplied task id is not allowed for this operation.', 400, 'TASK_ID_NOT_ALLOWED');
         }
@@ -5777,7 +6079,15 @@ export class TaskforceCore {
             throw new TaskforceRuleError('Client-supplied task reference number is not allowed for this operation.', 400, 'TASK_REFERENCE_NOT_ALLOWED');
         }
         const id = incomingId || this.generateId();
-        const referenceNumber = this.reserveTaskReferenceNumber(normalizedWorkspaceId, incomingReferenceNumber);
+        if (incomingReferenceNumber && options?.preferIncomingReferenceNumberOnConflict === true) {
+            this.relocateTaskReferenceConflict(normalizedWorkspaceId, incomingReferenceNumber, id, options?.syncUpdatedAt);
+        }
+        const referenceNumber = useProvisionalLocalReference
+            ? null
+            : this.reserveTaskReferenceNumber(normalizedWorkspaceId, incomingReferenceNumber, id);
+        const localReferenceNumber = useProvisionalLocalReference
+            ? this.allocateNextLocalTaskReferenceNumber(normalizedWorkspaceId, id)
+            : null;
         const normalizedCategory = normalizedInput.category || TaskforceCore.DEFAULT_CATEGORY_VALUE;
         const normalizedType = normalizedInput.type || this.resolveDefaultTypeValue(normalizedWorkspaceId);
         const createdByInput = String(normalizedInput.createdBy || '').trim() || undefined;
@@ -5816,7 +6126,8 @@ export class TaskforceCore {
         const task = {
             id,
             referenceNumber,
-            referenceLabel: formatTaskReference(referenceNumber),
+            localReferenceNumber,
+            referenceLabel: deriveTaskReferenceLabel({ referenceNumber, localReferenceNumber }),
             title: normalizedInput.title || 'Untitled Task',
             description: normalizedDescription || null,
             category: normalizedCategory,
@@ -5863,6 +6174,7 @@ export class TaskforceCore {
                 id, tenant_id, title, description, status, priority, complexity, type, category,
                 workspace_id,
                 reference_number,
+                local_reference_number,
                 approach, created_at, updated_at, is_archived, taxonomies, created_by, assignee,
                 scheduled_date, due_date, scheduled_week_key, order_in_day,
                 workstream_id
@@ -5870,6 +6182,7 @@ export class TaskforceCore {
                 @id, @tenantId, @title, @description, @status, @priority, @complexity, @type, @category,
                 @workspaceId,
                 @referenceNumber,
+                @localReferenceNumber,
                 @approach, @createdAt, @updatedAt, 0, @taxonomies, @createdBy, @assignee,
                 @scheduledDate, @dueDate, @scheduledWeekKey, @orderInDay,
                 @workstreamId
@@ -5946,7 +6259,8 @@ export class TaskforceCore {
                         created.push(this.createTask(batch[i], {
                             persistBackup: false,
                             workspaceId: options?.workspaceId,
-                            allowClientProvidedId: options?.allowClientProvidedId
+                            allowClientProvidedId: options?.allowClientProvidedId,
+                            provisionalLocalReference: options?.provisionalLocalReference
                         }));
                     }
                     if (validateOnly) {
@@ -5973,7 +6287,8 @@ export class TaskforceCore {
                         this.createTask(draft, {
                             persistBackup: false,
                             workspaceId: options?.workspaceId,
-                            allowClientProvidedId: options?.allowClientProvidedId
+                            allowClientProvidedId: options?.allowClientProvidedId,
+                            provisionalLocalReference: options?.provisionalLocalReference
                         });
                         throw validateOnlyRollbackError;
                     })(input);
@@ -5982,7 +6297,8 @@ export class TaskforceCore {
                     created.push(this.createTask(input, {
                         persistBackup: false,
                         workspaceId: options?.workspaceId,
-                        allowClientProvidedId: options?.allowClientProvidedId
+                        allowClientProvidedId: options?.allowClientProvidedId,
+                        provisionalLocalReference: options?.provisionalLocalReference
                     }));
                 }
             }
@@ -6075,7 +6391,19 @@ export class TaskforceCore {
                 }
             }
             if (Object.prototype.hasOwnProperty.call(patch, 'referenceNumber')) {
-                patch.referenceNumber = this.sanitizeTaskReferenceNumber(patch.referenceNumber);
+                const requestedReferenceNumber = this.sanitizeTaskReferenceNumber(patch.referenceNumber);
+                if (requestedReferenceNumber && options?.preferIncomingReferenceNumberOnConflict === true) {
+                    this.relocateTaskReferenceConflict(normalizedWorkspaceId, requestedReferenceNumber, taskId, options?.syncUpdatedAt);
+                }
+                patch.referenceNumber = requestedReferenceNumber
+                    ? this.reserveTaskReferenceNumber(normalizedWorkspaceId, requestedReferenceNumber, taskId)
+                    : requestedReferenceNumber;
+                if (requestedReferenceNumber) {
+                    patch.localReferenceNumber = null;
+                }
+            }
+            if (Object.prototype.hasOwnProperty.call(patch, 'localReferenceNumber')) {
+                patch.localReferenceNumber = this.sanitizeTaskReferenceNumber(patch.localReferenceNumber);
             }
             if (patch.status !== undefined) {
                 patch.status = this.normalizeStatusValue(patch.status);
@@ -6093,7 +6421,10 @@ export class TaskforceCore {
             const updatedTask = {
                 ...existing,
                 ...patch,
-                referenceLabel: formatTaskReference(patch.referenceNumber ?? existing.referenceNumber),
+                referenceLabel: deriveTaskReferenceLabel({
+                    referenceNumber: patch.referenceNumber ?? existing.referenceNumber,
+                    localReferenceNumber: patch.localReferenceNumber ?? existing.localReferenceNumber
+                }),
                 updatedAt: options?.syncUpdatedAt || patch.updatedAt || new Date().toISOString()
             };
             const fields = [];
@@ -6101,13 +6432,14 @@ export class TaskforceCore {
             const mappableFields = [
                 'title', 'description', 'status', 'completedAt', 'priority', 'complexity', 'type', 'category',
                 'approach', 'canceledReason', 'createdBy', 'assignee', 'scheduledDate', 'dueDate',
-                'scheduledWeekKey', 'orderInDay', 'workstreamId', 'referenceNumber'
+                'scheduledWeekKey', 'orderInDay', 'workstreamId', 'referenceNumber', 'localReferenceNumber'
             ];
             const propertyToColumn = {
                 canceledReason: 'canceled_reason',
                 completedAt: 'completed_at',
                 createdBy: 'created_by',
                 referenceNumber: 'reference_number',
+                localReferenceNumber: 'local_reference_number',
                 scheduledDate: 'scheduled_date',
                 dueDate: 'due_date',
                 scheduledWeekKey: 'scheduled_week_key',