@taskforcehq/taskforce 0.3.301 → 0.3.302

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)
@@ -1269,7 +1270,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 +1297,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 +1332,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',
@@ -2788,10 +2796,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 +2889,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 +3237,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 +4056,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 +4067,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 +4086,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')
@@ -5770,6 +5900,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 +5910,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 +5957,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 +6005,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 +6013,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 +6090,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 +6118,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 +6128,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 +6222,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 +6252,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 +6263,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',

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

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

package/dist/core/UserProfileAvatarDrafts.test.js

@@ -0,0 +1,102 @@
+import { describe, expect, it } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { TaskforceCore } from './Taskforce';
+function makeProjectRoot() {
+    return fs.mkdtempSync(path.join(os.tmpdir(), 'taskforce-user-avatar-'));
+}
+function seedPlans(core) {
+    core.upsertPlanCatalog({ planId: 'starter', displayName: 'Starter', status: 'active' });
+    core.updatePlanVersion({
+        planId: 'starter',
+        versionNumber: 1,
+        seatLimit: 1
+    });
+    core.updateGlobalSettings({
+        auth: {
+            signupMonetizationStrategy: 'auto_assign_default',
+            defaultSignupPlanVersionId: 'starter-v1'
+        }
+    });
+}
+function openCore(projectRoot) {
+    const core = new TaskforceCore({
+        projectRoot,
+        storagePath: path.join(projectRoot, '.taskforce')
+    });
+    seedPlans(core);
+    return core;
+}
+describe('TaskforceCore user profile avatar drafts', () => {
+    it('persists avatarUrl on profile updates and exposes it in resolved identity', () => {
+        const projectRoot = makeProjectRoot();
+        const core = openCore(projectRoot);
+        try {
+            const created = core.registerPasswordUser({
+                email: 'avatar-user@example.com',
+                password: 'password123'
+            });
+            const updated = core.updateUserProfile(created.userId, {
+                displayName: 'Avatar User',
+                avatarUrl: `/api/taskforce/context/${encodeURIComponent(`users/${created.userId}/profile/avatar/headshot.png`)}`
+            });
+            expect(updated).toMatchObject({
+                userId: created.userId,
+                displayName: 'Avatar User',
+                avatarUrl: `/api/taskforce/context/${encodeURIComponent(`users/${created.userId}/profile/avatar/headshot.png`)}`
+            });
+            expect(core.resolveUserIdentity(created.userId)?.avatarUrl).toBe(`/api/taskforce/context/${encodeURIComponent(`users/${created.userId}/profile/avatar/headshot.png`)}`);
+        }
+        finally {
+            core.close();
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+    it('tracks, finalizes, discards, and cleans up stale avatar upload drafts', () => {
+        const projectRoot = makeProjectRoot();
+        const core = openCore(projectRoot);
+        try {
+            const created = core.registerPasswordUser({
+                email: 'draft-user@example.com',
+                password: 'password123'
+            });
+            const draft = core.createUserAvatarUploadDraft({
+                userId: created.userId,
+                draftId: 'avatar-draft-1',
+                storageKey: `users/${created.userId}/profile/avatar/avatar-draft-1-headshot.png`,
+                mimeType: 'image/png',
+                originalFilename: 'headshot.png',
+                sizeBytes: 1024,
+                storageProvider: 'r2'
+            });
+            expect(draft.finalizedAt).toBeNull();
+            expect(core.markUserAvatarUploadDraftFinalized(created.userId, draft.draftId)?.finalizedAt).toEqual(expect.any(String));
+            expect(core.markUserAvatarUploadDraftConsumed(created.userId, draft.draftId)?.consumedAt).toEqual(expect.any(String));
+            expect(core.discardUserAvatarUploadDraft(created.userId, draft.draftId)?.discardedAt).toEqual(expect.any(String));
+            core.createUserAvatarUploadDraft({
+                userId: created.userId,
+                draftId: 'avatar-draft-stale',
+                storageKey: `users/${created.userId}/profile/avatar/avatar-draft-stale-headshot.png`,
+                mimeType: 'image/png',
+                originalFilename: 'stale.png',
+                sizeBytes: 512,
+                storageProvider: 'r2'
+            });
+            const db = core.db;
+            db.prepare(`
+                UPDATE user_avatar_upload_drafts
+                SET created_at = ?, updated_at = ?
+                WHERE tenant_id = ? AND user_id = ? AND draft_id = ?
+            `).run('2026-01-01T00:00:00.000Z', '2026-01-01T00:00:00.000Z', core.getTenantId(), created.userId, 'avatar-draft-stale');
+            const stale = core.cleanupStaleUserAvatarUploadDrafts(created.userId, '2026-02-01T00:00:00.000Z');
+            expect(stale).toHaveLength(1);
+            expect(stale[0]?.draftId).toBe('avatar-draft-stale');
+            expect(core.getUserAvatarUploadDraft(created.userId, 'avatar-draft-stale')?.discardedAt).toEqual(expect.any(String));
+        }
+        finally {
+            core.close();
+            fs.rmSync(projectRoot, { recursive: true, force: true });
+        }
+    });
+});

package/dist/core/taskReferencePolicy.d.ts

@@ -0,0 +1,28 @@
+import type { DatabaseAdapter } from '../storage/databaseAdapter.js';
+import type { TaskItem } from './Taskforce.js';
+interface TaskReferencePolicyDeps<TTask> {
+    db: DatabaseAdapter;
+    tenantId: string;
+    normalizeWorkspaceId: (workspaceId?: string) => string;
+    sanitizeTaskReferenceNumber: (value: unknown) => number | null;
+    rowToTask: (row: any) => TTask;
+    getTask: (id: string, workspaceId?: string) => TTask | null;
+}
+export declare function getTaskReferenceSequenceValue<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string): number;
+export declare function getLocalTaskReferenceSequenceValue<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string): number;
+export declare function getMaxTaskReferenceNumber<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string, excludeTaskId?: string | null): number;
+export declare function getMaxLocalTaskReferenceNumber<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string, excludeTaskId?: string | null): number;
+export declare function persistTaskReferenceSequence<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string, referenceNumber: number): void;
+export declare function persistLocalTaskReferenceSequence<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string, referenceNumber: number): void;
+export declare function allocateNextTaskReferenceNumber<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string, excludeTaskId?: string | null): number;
+export declare function allocateNextLocalTaskReferenceNumber<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string, excludeTaskId?: string | null): number;
+export declare function relocateTaskReferenceConflict<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string, referenceNumber: number, claimantTaskId?: string | null, updatedAt?: string | null): {
+    taskId: string;
+    referenceNumber: number;
+} | null;
+export declare function reserveTaskReferenceNumber<TTask>(deps: TaskReferencePolicyDeps<TTask>, workspaceId: string, preferredReferenceNumber?: number | null, currentTaskId?: string | null): number;
+export declare function getTaskByReferenceNumber<TTask>(deps: TaskReferencePolicyDeps<TTask>, referenceNumber: number, workspaceId?: string): TTask | null;
+export declare function getTaskByLocalReferenceNumber<TTask>(deps: TaskReferencePolicyDeps<TTask>, referenceNumber: number, workspaceId?: string): TTask | null;
+export declare function resolveTaskIdentifier(deps: TaskReferencePolicyDeps<TaskItem>, value: string, workspaceId?: string): TaskItem | null;
+export declare function deriveTaskReferenceLabel(task: Pick<TaskItem, 'referenceNumber' | 'localReferenceNumber'>): string;
+export {};