@taskforcehq/taskforce 0.3.324 → 0.3.327

package/dist/sync/v3/localOperationIdentityStore.d.ts

@@ -0,0 +1,81 @@
+import type { TaskItem } from '../../core/Taskforce.js';
+export interface LocalOperationIdentityStore {
+    getOrCreate(fingerprint: string, createOperationId: () => string): Promise<{
+        operationId: string;
+        created: boolean;
+    }>;
+    deleteIfMatches(fingerprint: string, operationId: string): Promise<void>;
+}
+export type LocalTaskCreateAttempt = {
+    workspaceId: string;
+    operationId: string;
+    task: Partial<TaskItem>;
+};
+export type LocalTaskCreateAttemptClaim = LocalTaskCreateAttempt & {
+    created: boolean;
+    resolved: boolean;
+};
+export interface LocalTaskCreateAttemptStore {
+    getForParticipant(workspaceId: string, participantId: string): Promise<LocalTaskCreateAttemptClaim | null>;
+    listPending(workspaceId: string): Promise<LocalTaskCreateAttemptClaim[]>;
+    claim(workspaceId: string, participantId: string, task: Partial<TaskItem>, createOperationId: () => string): Promise<LocalTaskCreateAttemptClaim>;
+    markResolved(workspaceId: string, operationId: string): Promise<void>;
+    abandonIfMatches(workspaceId: string, operationId: string): Promise<void>;
+}
+export type LocalWorkstreamCreateAttempt = {
+    fingerprint: string;
+    operationId: string;
+    workstream: Record<string, unknown>;
+};
+export interface LocalWorkstreamCreateAttemptStore {
+    claim(fingerprint: string, workstream: Record<string, unknown>, createOperationId: () => string): Promise<LocalWorkstreamCreateAttempt & {
+        created: boolean;
+    }>;
+    deleteIfMatches(fingerprint: string, operationId: string): Promise<void>;
+}
+/**
+ * Persists unfinished browser operation identities. A read-write IndexedDB
+ * transaction makes get-or-create atomic with other tabs using this database.
+ */
+export declare class IndexedDbLocalOperationIdentityStore implements LocalOperationIdentityStore {
+    private readonly indexedDb;
+    private readonly databaseName;
+    constructor(indexedDb?: IDBFactory, databaseName?: string);
+    getOrCreate(fingerprintValue: string, createOperationId: () => string): Promise<{
+        operationId: string;
+        created: boolean;
+    }>;
+    deleteIfMatches(fingerprintValue: string, operationIdValue: string): Promise<void>;
+    private open;
+}
+/**
+ * Pins each draft's original create payload and operation identity until local
+ * capture is conclusive. Drafts remain independent across tabs and sessions;
+ * an unfinished receipt may be replayed only through its original participant
+ * identity. listPending supports independent background recovery after the
+ * originating tab has closed.
+ */
+export declare class IndexedDbLocalTaskCreateAttemptStore implements LocalTaskCreateAttemptStore {
+    private readonly indexedDb;
+    private readonly databaseName;
+    constructor(indexedDb?: IDBFactory, databaseName?: string);
+    getForParticipant(workspaceIdValue: string, participantIdValue: string): Promise<LocalTaskCreateAttemptClaim | null>;
+    listPending(workspaceIdValue: string): Promise<LocalTaskCreateAttemptClaim[]>;
+    claim(workspaceIdValue: string, participantIdValue: string, task: Partial<TaskItem>, createOperationId: () => string): Promise<LocalTaskCreateAttemptClaim>;
+    markResolved(workspaceIdValue: string, operationIdValue: string): Promise<void>;
+    abandonIfMatches(workspaceIdValue: string, operationIdValue: string): Promise<void>;
+    private mutateState;
+    private open;
+}
+export declare class IndexedDbLocalWorkstreamCreateAttemptStore implements LocalWorkstreamCreateAttemptStore {
+    private readonly indexedDb;
+    private readonly databaseName;
+    constructor(indexedDb?: IDBFactory, databaseName?: string);
+    claim(fingerprintValue: string, workstream: Record<string, unknown>, createOperationId: () => string): Promise<LocalWorkstreamCreateAttempt & {
+        created: boolean;
+    }>;
+    deleteIfMatches(fingerprintValue: string, operationIdValue: string): Promise<void>;
+    private open;
+}
+export declare function canonicalLocalOperationJson(value: unknown): string;
+export declare function fingerprintLocalOperation(value: unknown, cryptoImpl?: Pick<Crypto, 'subtle'>): Promise<string>;

package/dist/sync/v3/localOperationIdentityStore.js

@@ -0,0 +1,388 @@
+import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
+const DATABASE_NAME = 'taskforce-workspace-sync-v3';
+const DATABASE_VERSION = 3;
+const STORE_NAME = 'operation-identities';
+const TASK_CREATE_ATTEMPT_STORE_NAME = 'task-create-attempts';
+const WORKSTREAM_CREATE_ATTEMPT_STORE_NAME = 'workstream-create-attempts';
+function readTaskCreateAttempts(state) {
+    if (!state)
+        return [];
+    const attempts = Array.isArray(state.attempts) ? [...state.attempts] : [];
+    if (state.active && !attempts.some((attempt) => attempt.operationId === state.active?.operationId)) {
+        attempts.push(state.active);
+    }
+    return attempts;
+}
+function writeTaskCreateAttempts(state, attempts) {
+    delete state.active;
+    state.attempts = attempts;
+}
+function requireText(value, label) {
+    const normalized = String(value || '').trim();
+    if (!normalized)
+        throw new Error(`${label} is required.`);
+    return normalized;
+}
+function requestError(request, fallback) {
+    return request.error || new Error(fallback);
+}
+function ensureLocalOperationIdentitySchema(db) {
+    if (!db.objectStoreNames.contains(STORE_NAME))
+        db.createObjectStore(STORE_NAME, { keyPath: 'fingerprint' });
+    if (!db.objectStoreNames.contains(TASK_CREATE_ATTEMPT_STORE_NAME)) {
+        db.createObjectStore(TASK_CREATE_ATTEMPT_STORE_NAME, { keyPath: 'workspaceId' });
+    }
+    if (!db.objectStoreNames.contains(WORKSTREAM_CREATE_ATTEMPT_STORE_NAME)) {
+        db.createObjectStore(WORKSTREAM_CREATE_ATTEMPT_STORE_NAME, { keyPath: 'fingerprint' });
+    }
+}
+function openLocalOperationIdentityDatabase(indexedDb, databaseName) {
+    if (!indexedDb)
+        return Promise.reject(new Error('IndexedDB is unavailable.'));
+    return new Promise((resolve, reject) => {
+        const request = indexedDb.open(databaseName, DATABASE_VERSION);
+        let terminal = false;
+        request.onupgradeneeded = () => ensureLocalOperationIdentitySchema(request.result);
+        request.onsuccess = () => {
+            const db = request.result;
+            if (terminal) {
+                db.close();
+                return;
+            }
+            terminal = true;
+            db.onversionchange = () => db.close();
+            resolve(db);
+        };
+        request.onerror = () => {
+            if (terminal)
+                return;
+            terminal = true;
+            reject(requestError(request, 'Failed to open the local operation identity database.'));
+        };
+        request.onblocked = () => {
+            // Blocked upgrades may still succeed after older connections close.
+            // Keep the request pending instead of creating a rejected-promise/late-success leak.
+        };
+    });
+}
+/**
+ * Persists unfinished browser operation identities. A read-write IndexedDB
+ * transaction makes get-or-create atomic with other tabs using this database.
+ */
+export class IndexedDbLocalOperationIdentityStore {
+    indexedDb;
+    databaseName;
+    constructor(indexedDb = globalThis.indexedDB, databaseName = DATABASE_NAME) {
+        this.indexedDb = indexedDb;
+        this.databaseName = databaseName;
+    }
+    async getOrCreate(fingerprintValue, createOperationId) {
+        const fingerprint = requireText(fingerprintValue, 'fingerprint');
+        const db = await this.open();
+        try {
+            return await new Promise((resolve, reject) => {
+                const transaction = db.transaction(STORE_NAME, 'readwrite');
+                const store = transaction.objectStore(STORE_NAME);
+                const request = store.get(fingerprint);
+                let operationId = '';
+                let created = false;
+                request.onsuccess = () => {
+                    try {
+                        const existing = request.result;
+                        if (existing) {
+                            operationId = requireText(existing.operationId, 'stored operationId');
+                            return;
+                        }
+                        operationId = requireText(createOperationId(), 'operationId');
+                        created = true;
+                        store.add({ fingerprint, operationId });
+                    }
+                    catch (error) {
+                        transaction.abort();
+                        reject(error);
+                    }
+                };
+                request.onerror = () => reject(requestError(request, 'Failed to read the local operation identity.'));
+                transaction.oncomplete = () => resolve({ operationId, created });
+                transaction.onerror = () => reject(transaction.error || new Error('Failed to persist the local operation identity.'));
+                transaction.onabort = () => reject(transaction.error || new Error('Persisting the local operation identity was aborted.'));
+            });
+        }
+        finally {
+            db.close();
+        }
+    }
+    async deleteIfMatches(fingerprintValue, operationIdValue) {
+        const fingerprint = requireText(fingerprintValue, 'fingerprint');
+        const operationId = requireText(operationIdValue, 'operationId');
+        const db = await this.open();
+        try {
+            await new Promise((resolve, reject) => {
+                const transaction = db.transaction(STORE_NAME, 'readwrite');
+                const store = transaction.objectStore(STORE_NAME);
+                const request = store.get(fingerprint);
+                request.onsuccess = () => {
+                    const existing = request.result;
+                    if (existing?.operationId === operationId)
+                        store.delete(fingerprint);
+                };
+                request.onerror = () => reject(requestError(request, 'Failed to read the local operation identity.'));
+                transaction.oncomplete = () => resolve();
+                transaction.onerror = () => reject(transaction.error || new Error('Failed to delete the local operation identity.'));
+                transaction.onabort = () => reject(transaction.error || new Error('Deleting the local operation identity was aborted.'));
+            });
+        }
+        finally {
+            db.close();
+        }
+    }
+    open() {
+        return openLocalOperationIdentityDatabase(this.indexedDb, this.databaseName);
+    }
+}
+/**
+ * Pins each draft's original create payload and operation identity until local
+ * capture is conclusive. Drafts remain independent across tabs and sessions;
+ * an unfinished receipt may be replayed only through its original participant
+ * identity. listPending supports independent background recovery after the
+ * originating tab has closed.
+ */
+export class IndexedDbLocalTaskCreateAttemptStore {
+    indexedDb;
+    databaseName;
+    constructor(indexedDb = globalThis.indexedDB, databaseName = DATABASE_NAME) {
+        this.indexedDb = indexedDb;
+        this.databaseName = databaseName;
+    }
+    async getForParticipant(workspaceIdValue, participantIdValue) {
+        const workspaceId = requireText(workspaceIdValue, 'workspaceId');
+        const participantId = requireText(participantIdValue, 'participantId');
+        const db = await this.open();
+        try {
+            return await new Promise((resolve, reject) => {
+                const transaction = db.transaction(TASK_CREATE_ATTEMPT_STORE_NAME, 'readonly');
+                const store = transaction.objectStore(TASK_CREATE_ATTEMPT_STORE_NAME);
+                const request = store.get(workspaceId);
+                let claim = null;
+                request.onsuccess = () => {
+                    const state = request.result;
+                    const attempt = readTaskCreateAttempts(state)
+                        .find((candidate) => candidate.participantId === participantId);
+                    if (attempt)
+                        claim = { ...attempt, created: false, resolved: false };
+                };
+                request.onerror = () => reject(requestError(request, 'Failed to read the local task-create attempt.'));
+                transaction.oncomplete = () => resolve(claim);
+                transaction.onerror = () => reject(transaction.error || new Error('Failed to claim the local task-create attempt.'));
+                transaction.onabort = () => reject(transaction.error || new Error('Claiming the local task-create attempt was aborted.'));
+            });
+        }
+        finally {
+            db.close();
+        }
+    }
+    async listPending(workspaceIdValue) {
+        const workspaceId = requireText(workspaceIdValue, 'workspaceId');
+        const db = await this.open();
+        try {
+            return await new Promise((resolve, reject) => {
+                const transaction = db.transaction(TASK_CREATE_ATTEMPT_STORE_NAME, 'readonly');
+                const store = transaction.objectStore(TASK_CREATE_ATTEMPT_STORE_NAME);
+                const request = store.get(workspaceId);
+                let attempts = [];
+                request.onsuccess = () => {
+                    attempts = readTaskCreateAttempts(request.result)
+                        .map((attempt) => ({ ...attempt, created: false, resolved: false }));
+                };
+                request.onerror = () => reject(requestError(request, 'Failed to list local task-create attempts.'));
+                transaction.oncomplete = () => resolve(attempts);
+                transaction.onerror = () => reject(transaction.error || new Error('Failed to list local task-create attempts.'));
+                transaction.onabort = () => reject(transaction.error || new Error('Listing local task-create attempts was aborted.'));
+            });
+        }
+        finally {
+            db.close();
+        }
+    }
+    async claim(workspaceIdValue, participantIdValue, task, createOperationId) {
+        const workspaceId = requireText(workspaceIdValue, 'workspaceId');
+        const participantId = requireText(participantIdValue, 'participantId');
+        const db = await this.open();
+        try {
+            return await new Promise((resolve, reject) => {
+                const transaction = db.transaction(TASK_CREATE_ATTEMPT_STORE_NAME, 'readwrite');
+                const store = transaction.objectStore(TASK_CREATE_ATTEMPT_STORE_NAME);
+                const request = store.get(workspaceId);
+                let attempt = null;
+                let created = false;
+                request.onsuccess = () => {
+                    try {
+                        const state = request.result || { workspaceId };
+                        const attempts = readTaskCreateAttempts(state);
+                        const existing = attempts.find((candidate) => candidate.participantId === participantId);
+                        if (existing) {
+                            attempt = { ...existing, created: false, resolved: false };
+                            return;
+                        }
+                        const active = {
+                            workspaceId,
+                            operationId: requireText(createOperationId(), 'operationId'),
+                            task,
+                            participantId,
+                        };
+                        created = true;
+                        attempts.push(active);
+                        writeTaskCreateAttempts(state, attempts);
+                        store.put(state);
+                        attempt = { ...active, created: true, resolved: false };
+                    }
+                    catch (error) {
+                        transaction.abort();
+                        reject(error);
+                    }
+                };
+                request.onerror = () => reject(requestError(request, 'Failed to read the local task-create attempt.'));
+                transaction.oncomplete = () => {
+                    if (!attempt)
+                        return reject(new Error('Local task-create attempt was not prepared.'));
+                    resolve({ ...attempt, created });
+                };
+                transaction.onerror = () => reject(transaction.error || new Error('Failed to persist the local task-create attempt.'));
+                transaction.onabort = () => reject(transaction.error || new Error('Persisting the local task-create attempt was aborted.'));
+            });
+        }
+        finally {
+            db.close();
+        }
+    }
+    async markResolved(workspaceIdValue, operationIdValue) {
+        const operationId = requireText(operationIdValue, 'operationId');
+        await this.mutateState(workspaceIdValue, (attempts) => attempts.filter((attempt) => attempt.operationId !== operationId));
+    }
+    async abandonIfMatches(workspaceIdValue, operationIdValue) {
+        await this.mutateState(workspaceIdValue, (attempts) => {
+            const operationId = requireText(operationIdValue, 'operationId');
+            return attempts.filter((attempt) => attempt.operationId !== operationId);
+        });
+    }
+    async mutateState(workspaceIdValue, mutate) {
+        const workspaceId = requireText(workspaceIdValue, 'workspaceId');
+        const db = await this.open();
+        try {
+            await new Promise((resolve, reject) => {
+                const transaction = db.transaction(TASK_CREATE_ATTEMPT_STORE_NAME, 'readwrite');
+                const store = transaction.objectStore(TASK_CREATE_ATTEMPT_STORE_NAME);
+                const request = store.get(workspaceId);
+                request.onsuccess = () => {
+                    const state = request.result || { workspaceId };
+                    const attempts = mutate(readTaskCreateAttempts(state));
+                    if (attempts.length === 0)
+                        store.delete(workspaceId);
+                    else {
+                        writeTaskCreateAttempts(state, attempts);
+                        store.put(state);
+                    }
+                };
+                request.onerror = () => reject(requestError(request, 'Failed to read the local task-create state.'));
+                transaction.oncomplete = () => resolve();
+                transaction.onerror = () => reject(transaction.error || new Error('Failed to update the local task-create state.'));
+                transaction.onabort = () => reject(transaction.error || new Error('Updating the local task-create state was aborted.'));
+            });
+        }
+        finally {
+            db.close();
+        }
+    }
+    open() {
+        return openLocalOperationIdentityDatabase(this.indexedDb, this.databaseName);
+    }
+}
+export class IndexedDbLocalWorkstreamCreateAttemptStore {
+    indexedDb;
+    databaseName;
+    constructor(indexedDb = globalThis.indexedDB, databaseName = DATABASE_NAME) {
+        this.indexedDb = indexedDb;
+        this.databaseName = databaseName;
+    }
+    async claim(fingerprintValue, workstream, createOperationId) {
+        const fingerprint = requireText(fingerprintValue, 'fingerprint');
+        const db = await this.open();
+        try {
+            return await new Promise((resolve, reject) => {
+                const transaction = db.transaction(WORKSTREAM_CREATE_ATTEMPT_STORE_NAME, 'readwrite');
+                const store = transaction.objectStore(WORKSTREAM_CREATE_ATTEMPT_STORE_NAME);
+                const request = store.get(fingerprint);
+                let attempt = null;
+                let created = false;
+                request.onsuccess = () => {
+                    try {
+                        const existing = request.result;
+                        if (existing) {
+                            attempt = existing;
+                            return;
+                        }
+                        attempt = {
+                            fingerprint,
+                            operationId: requireText(createOperationId(), 'operationId'),
+                            workstream,
+                        };
+                        created = true;
+                        store.add(attempt);
+                    }
+                    catch (error) {
+                        transaction.abort();
+                        reject(error);
+                    }
+                };
+                request.onerror = () => reject(requestError(request, 'Failed to read the workstream-create attempt.'));
+                transaction.oncomplete = () => {
+                    if (!attempt)
+                        return reject(new Error('Workstream-create attempt was not prepared.'));
+                    resolve({ ...attempt, created });
+                };
+                transaction.onerror = () => reject(transaction.error || new Error('Failed to persist the workstream-create attempt.'));
+                transaction.onabort = () => reject(transaction.error || new Error('Persisting the workstream-create attempt was aborted.'));
+            });
+        }
+        finally {
+            db.close();
+        }
+    }
+    async deleteIfMatches(fingerprintValue, operationIdValue) {
+        const fingerprint = requireText(fingerprintValue, 'fingerprint');
+        const operationId = requireText(operationIdValue, 'operationId');
+        const db = await this.open();
+        try {
+            await new Promise((resolve, reject) => {
+                const transaction = db.transaction(WORKSTREAM_CREATE_ATTEMPT_STORE_NAME, 'readwrite');
+                const store = transaction.objectStore(WORKSTREAM_CREATE_ATTEMPT_STORE_NAME);
+                const request = store.get(fingerprint);
+                request.onsuccess = () => {
+                    const existing = request.result;
+                    if (existing?.operationId === operationId)
+                        store.delete(fingerprint);
+                };
+                request.onerror = () => reject(requestError(request, 'Failed to read the workstream-create attempt.'));
+                transaction.oncomplete = () => resolve();
+                transaction.onerror = () => reject(transaction.error || new Error('Failed to delete the workstream-create attempt.'));
+                transaction.onabort = () => reject(transaction.error || new Error('Deleting the workstream-create attempt was aborted.'));
+            });
+        }
+        finally {
+            db.close();
+        }
+    }
+    open() {
+        return openLocalOperationIdentityDatabase(this.indexedDb, this.databaseName);
+    }
+}
+export function canonicalLocalOperationJson(value) {
+    return canonicalWorkspaceSyncJson(value);
+}
+export async function fingerprintLocalOperation(value, cryptoImpl = globalThis.crypto) {
+    if (!cryptoImpl?.subtle)
+        throw new Error('Web Crypto is unavailable.');
+    const bytes = new TextEncoder().encode(canonicalLocalOperationJson(value));
+    const digest = await cryptoImpl.subtle.digest('SHA-256', bytes);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}

package/dist/sync/v3/localOutboxDispatchCapability.d.ts

@@ -0,0 +1,7 @@
+export type LocalOutboxDispatchCapability = {
+    localOutboxDispatch: boolean;
+};
+export declare function resolveLocalOutboxDispatchCapability(input: {
+    runtimeMode: 'local' | 'cloud';
+    env?: NodeJS.ProcessEnv;
+}): LocalOutboxDispatchCapability;

package/dist/sync/v3/localOutboxDispatchCapability.js

@@ -0,0 +1,13 @@
+function isEnabled(value) {
+    return /^(1|true|on|yes)$/i.test(String(value || '').trim());
+}
+export function resolveLocalOutboxDispatchCapability(input) {
+    const env = input.env || process.env;
+    return {
+        localOutboxDispatch: input.runtimeMode === 'local'
+            && (isEnabled(env.TASKFORCE_SYNC_V3_TASKS_ENABLED)
+                || isEnabled(env.TASKFORCE_SYNC_V3_INITIATIVES_ENABLED))
+            && isEnabled(env.TASKFORCE_SYNC_V3_LOCAL_CAPTURE_ENABLED)
+            && isEnabled(env.TASKFORCE_SYNC_V3_LOCAL_DISPATCH_ENABLED),
+    };
+}

package/dist/sync/v3/localOutboxDispatchRuntime.d.ts

@@ -0,0 +1,16 @@
+import type { TaskforceCore, TaskforceSyncCapable } from '../../core/Taskforce.js';
+import type { LocalOutboxOperationHandler } from './localOutboxOperationHandler.js';
+import { WorkspaceSyncDurabilityStore } from './syncDurabilityStore.js';
+export type LocalOutboxDispatchCore = TaskforceCore & TaskforceSyncCapable;
+export declare function createLocalOutboxDispatchHandlers(input: {
+    store: WorkspaceSyncDurabilityStore;
+    core: LocalOutboxDispatchCore;
+    env?: NodeJS.ProcessEnv;
+}): LocalOutboxOperationHandler[];
+export declare function prepareLocalOutboxDispatch(input: {
+    store: WorkspaceSyncDurabilityStore;
+    handlers: readonly LocalOutboxOperationHandler[];
+    core: LocalOutboxDispatchCore;
+    workspaceId: string;
+    now: string;
+}): void;