@taskforcehq/taskforce 0.3.326 → 0.3.327

package/dist/sync/v3/workspaceSyncV3TaskCommentAudit.js

@@ -0,0 +1,250 @@
+import { createHash } from 'crypto';
+import { LocalSyncIdentityStore } from './localSyncIdentityStore.js';
+import { enqueueLocalTaskCommentReconciliation } from './localTaskCommentOutboxService.js';
+import { serializeTaskActivityForSync } from './taskActivityJournal.js';
+import { fingerprintWorkspaceSyncPayload, WorkspaceSyncDurabilityStore, WorkspaceSyncEntityBusyError, } from './syncDurabilityStore.js';
+import { serializeWorkspaceSyncV3TaskCommentsPayload } from './workspaceSyncV3NestedTaskCodecs.js';
+import { buildWorkspaceSyncV3TaskCommentReconcileProvenance, indexWorkspaceSyncV3TaskCommentProvenanceEvidence, } from './taskCommentReconcileProvenance.js';
+const AUDIT_STATE_KEY_PREFIX = 'sync.v3.task-comment-audit.v1:';
+export const TASK_COMMENT_AUDIT_SWEEP_INTERVAL_MS = 15 * 60 * 1000;
+function stateKey(workspaceId) {
+    return `${AUDIT_STATE_KEY_PREFIX}${workspaceId}`;
+}
+function assertSynchronousHookResult(result, label) {
+    if (result && typeof result.then === 'function') {
+        throw new Error(`${label} must be synchronous.`);
+    }
+}
+function normalizeCursor(value) {
+    const cursor = String(value || '').trim();
+    if (!cursor)
+        return null;
+    if (cursor.length > 250 || !/^[A-Za-z0-9._:-]+$/.test(cursor)) {
+        throw new Error('Task comment audit cursor is invalid.');
+    }
+    return cursor;
+}
+function pageSize(value) {
+    if (value === undefined)
+        return 50;
+    if (!Number.isInteger(value) || value < 1 || value > 100) {
+        throw new Error('Task comment audit page size must be between 1 and 100.');
+    }
+    return value;
+}
+export function buildWorkspaceSyncV3TaskCommentAuditPage(input) {
+    const workspaceId = String(input.workspaceId || '').trim();
+    const previousCursor = normalizeCursor(input.cursor);
+    const limit = pageSize(input.limit);
+    const rows = input.core.getDatabaseAdapter().prepare(`
+        SELECT id
+        FROM tasks
+        WHERE tenant_id = ? AND workspace_id = ?
+          AND (? = '' OR id > ?)
+        ORDER BY id
+        LIMIT ?
+    `).all(input.core.getTenantId(), workspaceId, previousCursor || '', previousCursor || '', limit + 1);
+    const pageRows = rows.slice(0, limit);
+    const entries = pageRows.map(({ id }) => {
+        const task = input.core.getTask(id, workspaceId);
+        if (!task)
+            throw new Error(`Task comment audit source disappeared: ${id}.`);
+        const comments = serializeWorkspaceSyncV3TaskCommentsPayload({
+            taskId: task.id,
+            comments: task.comments || [],
+        });
+        const commentIds = new Set(comments.comments.map((comment) => comment.id));
+        const activities = input.core.listTaskEvents(task.id, workspaceId)
+            .filter((event) => event.action === 'task-comment-added'
+            && commentIds.has(String(event.details?.commentId || '').trim()))
+            .map((event) => serializeTaskActivityForSync(event));
+        return {
+            taskId: task.id,
+            canonicalFingerprint: fingerprintWorkspaceSyncPayload(comments),
+            commentCount: comments.comments.length,
+            activities,
+        };
+    });
+    const hasMore = rows.length > limit;
+    return {
+        success: true,
+        contractVersion: 3,
+        workspaceId,
+        previousCursor,
+        nextCursor: hasMore ? pageRows.at(-1)?.id || null : null,
+        hasMore,
+        entries,
+    };
+}
+export function readWorkspaceSyncV3TaskCommentAuditState(input) {
+    const row = input.core.getDatabaseAdapter().prepare(`
+        SELECT payload
+        FROM system_settings
+        WHERE tenant_id = ? AND settings_key = ?
+        LIMIT 1
+    `).get(input.core.getTenantId(), stateKey(input.workspaceId));
+    if (!row?.payload)
+        return { cursor: null, nextSweepAt: null };
+    try {
+        const parsed = JSON.parse(row.payload);
+        const persistedNextSweepAt = String(parsed.nextSweepAt || '').trim();
+        const nextSweepAt = persistedNextSweepAt
+            && Number.isFinite(Date.parse(persistedNextSweepAt))
+            ? persistedNextSweepAt
+            : null;
+        return {
+            cursor: normalizeCursor(parsed.cursor),
+            nextSweepAt,
+        };
+    }
+    catch {
+        throw new Error('Persisted task comment audit state is invalid.');
+    }
+}
+export function readWorkspaceSyncV3TaskCommentAuditCursor(input) {
+    return readWorkspaceSyncV3TaskCommentAuditState(input).cursor;
+}
+export function applyWorkspaceSyncV3TaskCommentAuditPage(input) {
+    const workspaceId = String(input.workspaceId || '').trim();
+    const page = input.page;
+    if (page?.success !== true || page.contractVersion !== 3 || page.workspaceId !== workspaceId
+        || !Array.isArray(page.entries) || page.hasMore !== Boolean(page.nextCursor)) {
+        throw new Error('Task comment audit page is invalid.');
+    }
+    const previousCursor = normalizeCursor(page.previousCursor);
+    const nextCursor = normalizeCursor(page.nextCursor);
+    const now = input.now || new Date().toISOString();
+    const tenantId = input.core.getTenantId();
+    const store = new WorkspaceSyncDurabilityStore(input.core.getDatabaseAdapter());
+    let reconciliationsQueued = 0;
+    let activityEventsApplied = 0;
+    let busyEntriesSkipped = 0;
+    return input.core.getDatabaseAdapter().transaction(() => {
+        assertSynchronousHookResult(input.transactionHooks?.beforeApply?.(), 'Task comment audit before-apply hook');
+        const currentState = readWorkspaceSyncV3TaskCommentAuditState({
+            core: input.core,
+            workspaceId,
+        });
+        const currentCursor = currentState.cursor;
+        if (currentCursor !== previousCursor) {
+            if (currentCursor !== nextCursor) {
+                throw new Error('Task comment audit page does not continue the persisted cursor.');
+            }
+            // Multiple browser windows can fetch the same page before either
+            // commits it. The first advances the cursor; later exact copies
+            // still complete their permit boundary as transactional no-ops.
+            const result = {
+                previousCursor: currentCursor,
+                nextCursor: currentCursor,
+                nextSweepAt: currentState.nextSweepAt,
+                reconciliationsQueued: 0,
+                activityEventsApplied: 0,
+                busyEntriesSkipped: 0,
+                stale: true,
+            };
+            assertSynchronousHookResult(input.transactionHooks?.beforeCommit?.(result), 'Task comment audit before-commit hook');
+            return result;
+        }
+        const clientId = new LocalSyncIdentityStore(input.core.getDatabaseAdapter()).getOrCreateClientId(now);
+        let priorTaskId = '';
+        for (const entry of page.entries) {
+            const taskId = String(entry?.taskId || '').trim();
+            const cloudFingerprint = String(entry?.canonicalFingerprint || '').trim();
+            if (!taskId || taskId <= priorTaskId || !/^[a-f0-9]{64}$/.test(cloudFingerprint)
+                || !Number.isInteger(entry.commentCount) || entry.commentCount < 0
+                || !Array.isArray(entry.activities)) {
+                throw new Error('Task comment audit entry is invalid.');
+            }
+            priorTaskId = taskId;
+            const task = input.core.getTask(taskId, workspaceId);
+            if (!task)
+                throw new Error(`Task comment audit target does not exist locally: ${taskId}.`);
+            const localComments = serializeWorkspaceSyncV3TaskCommentsPayload({
+                taskId,
+                comments: task.comments || [],
+            });
+            const localFingerprint = fingerprintWorkspaceSyncPayload(localComments);
+            if (localFingerprint !== cloudFingerprint) {
+                const evidenceByCommentId = indexWorkspaceSyncV3TaskCommentProvenanceEvidence(input.core.listTaskEvents(task.id, workspaceId));
+                const actorEvidence = localComments.comments.map((comment) => ({
+                    commentId: comment.id,
+                    ...evidenceByCommentId.get(comment.id),
+                }));
+                const digest = createHash('sha256').update(fingerprintWorkspaceSyncPayload({
+                    taskId,
+                    localFingerprint,
+                    cloudFingerprint,
+                    actorEvidence,
+                })).digest('hex').slice(0, 32);
+                const operationId = `task-comment-reconcile-audit-${digest}`;
+                const provenance = buildWorkspaceSyncV3TaskCommentReconcileProvenance({
+                    workspaceId,
+                    clientId,
+                    operationId,
+                    taskId,
+                    comments: localComments.comments,
+                    evidenceByCommentId,
+                    aiProfiles: input.core.listAiProfiles(workspaceId),
+                });
+                try {
+                    const queued = enqueueLocalTaskCommentReconciliation({
+                        store,
+                        core: input.core,
+                        identity: {
+                            tenantId,
+                            workspaceId,
+                            clientId,
+                            operationId,
+                        },
+                        taskId,
+                        comments: localComments.comments,
+                        provenance,
+                        now,
+                    });
+                    if (queued.enqueued)
+                        reconciliationsQueued += 1;
+                }
+                catch (error) {
+                    if (!(error instanceof WorkspaceSyncEntityBusyError))
+                        throw error;
+                    busyEntriesSkipped += 1;
+                }
+            }
+            const commentIds = new Set((task.comments || []).map((comment) => comment.id));
+            const existingEventIds = new Set(input.core.listTaskEvents(task.id, workspaceId).map((event) => event.id));
+            for (const activity of entry.activities) {
+                if (activity.workspaceId !== workspaceId || activity.taskId !== taskId
+                    || activity.entityType !== 'task' || activity.entityId !== taskId
+                    || activity.action !== 'task-comment-added'
+                    || !commentIds.has(String(activity.details?.commentId || '').trim())) {
+                    continue;
+                }
+                input.core.upsertTaskEventForSync(activity);
+                if (!existingEventIds.has(activity.id)) {
+                    existingEventIds.add(activity.id);
+                    activityEventsApplied += 1;
+                }
+            }
+        }
+        const nextSweepAt = page.hasMore
+            ? null
+            : new Date(Date.parse(now) + TASK_COMMENT_AUDIT_SWEEP_INTERVAL_MS).toISOString();
+        input.core.getDatabaseAdapter().prepare(`
+            INSERT INTO system_settings (tenant_id, settings_key, payload, updated_at)
+            VALUES (?, ?, ?, ?)
+            ON CONFLICT (tenant_id, settings_key) DO UPDATE SET
+                payload = excluded.payload,
+                updated_at = excluded.updated_at
+        `).run(tenantId, stateKey(workspaceId), JSON.stringify({ cursor: nextCursor, nextSweepAt }), now);
+        const result = {
+            previousCursor,
+            nextCursor,
+            nextSweepAt,
+            reconciliationsQueued,
+            activityEventsApplied,
+            busyEntriesSkipped,
+        };
+        assertSynchronousHookResult(input.transactionHooks?.beforeCommit?.(result), 'Task comment audit before-commit hook');
+        return result;
+    })();
+}

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

@@ -0,0 +1,30 @@
+import type { TaskRelationshipRecord } from '../../core/Taskforce.js';
+import type { WorkspaceSyncJournalRow } from './workspaceSyncJournalReader.js';
+export type WorkspaceSyncV3TaskRelationshipMutationKind = 'link' | 'unlink' | 'delete';
+/** Behavior-dark operation contract. It is not an advertised coverage profile. */
+export declare const WORKSPACE_SYNC_V3_TASK_RELATIONSHIP_OPERATION_PROJECTION: Readonly<{
+    readonly projectionId: "task-relationship/full-v1";
+    readonly domain: "task-relationship";
+    readonly schemaVersion: 1;
+    readonly mutationKinds: readonly string[];
+}>;
+export type WorkspaceSyncV3TaskRelationshipFeedEntry = {
+    sequence: string;
+    projection: 'task-relationship/full-v1';
+    domain: 'task-relationship';
+    entityId: string;
+    mutationKind: WorkspaceSyncV3TaskRelationshipMutationKind;
+    entityRevision: string;
+    lifecycleRevision: string;
+    payloadFingerprint: string;
+    payload: TaskRelationshipRecord;
+    occurredAt: string;
+};
+export declare function serializeTaskRelationshipForSync(raw: Partial<TaskRelationshipRecord>): TaskRelationshipRecord;
+export declare function projectWorkspaceSyncV3TaskRelationshipJournalRow(row: WorkspaceSyncJournalRow): WorkspaceSyncV3TaskRelationshipFeedEntry | null;
+export declare function projectWorkspaceSyncV3TaskRelationshipOperation(input: {
+    rows: readonly WorkspaceSyncJournalRow[];
+    cycleHighWatermark: string;
+    followingRow?: WorkspaceSyncJournalRow | null;
+}): WorkspaceSyncV3TaskRelationshipFeedEntry[] | null;
+export declare function validateWorkspaceSyncV3TaskRelationshipFeedEntry(entry: WorkspaceSyncV3TaskRelationshipFeedEntry): void;

package/dist/sync/v3/workspaceSyncV3TaskRelationshipProjection.js

@@ -0,0 +1,142 @@
+import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
+import { fingerprintWorkspaceSyncPayload, WORKSPACE_SYNC_CONTRACT_VERSION } from './syncDurabilityStore.js';
+import { assertWorkspaceSyncV3OperationBoundary, canonicalWorkspaceSyncSequence, canonicalWorkspaceSyncTimestamp, } from './workspaceSyncV3OperationProjection.js';
+import { projectWorkspaceSyncV3TaskRootOperation } from './workspaceSyncV3TaskRootProjection.js';
+/** Behavior-dark operation contract. It is not an advertised coverage profile. */
+export const WORKSPACE_SYNC_V3_TASK_RELATIONSHIP_OPERATION_PROJECTION = Object.freeze({
+    projectionId: 'task-relationship/full-v1',
+    domain: 'task-relationship',
+    schemaVersion: 1,
+    mutationKinds: Object.freeze(['link', 'unlink', 'delete']),
+});
+const RELATIONSHIP_KINDS = new Set(['dependency', 'related', 'supersedes']);
+function nullableActor(value, label) {
+    if (value === null)
+        return null;
+    const normalized = String(value || '').trim();
+    if (!normalized)
+        throw new Error(`${label} is invalid.`);
+    return normalized;
+}
+export function serializeTaskRelationshipForSync(raw) {
+    const kind = String(raw.kind || '').trim();
+    const relationship = {
+        id: String(raw.id || '').trim(),
+        workspaceId: String(raw.workspaceId || '').trim(),
+        sourceTaskId: String(raw.sourceTaskId || '').trim(),
+        targetTaskId: String(raw.targetTaskId || '').trim(),
+        kind,
+        createdBy: nullableActor(raw.createdBy, 'Task relationship createdBy'),
+        createdAt: canonicalWorkspaceSyncTimestamp(raw.createdAt, 'Task relationship createdAt'),
+        updatedBy: nullableActor(raw.updatedBy, 'Task relationship updatedBy'),
+        updatedAt: canonicalWorkspaceSyncTimestamp(raw.updatedAt, 'Task relationship updatedAt'),
+        deletedBy: nullableActor(raw.deletedBy, 'Task relationship deletedBy'),
+        deletedAt: raw.deletedAt === null
+            ? null
+            : canonicalWorkspaceSyncTimestamp(raw.deletedAt, 'Task relationship deletedAt'),
+    };
+    if (!relationship.id
+        || !relationship.workspaceId
+        || !relationship.sourceTaskId
+        || !relationship.targetTaskId
+        || relationship.sourceTaskId === relationship.targetTaskId
+        || !RELATIONSHIP_KINDS.has(kind)
+        || (kind === 'related' && relationship.sourceTaskId >= relationship.targetTaskId)
+        || (relationship.deletedAt === null) !== (relationship.deletedBy === null)) {
+        throw new Error('Task relationship payload identity is invalid.');
+    }
+    return relationship;
+}
+export function projectWorkspaceSyncV3TaskRelationshipJournalRow(row) {
+    if (row.domain !== 'task-relationship')
+        return null;
+    const sequence = canonicalWorkspaceSyncSequence(row.sequence, 'Task relationship journal sequence');
+    const entityRevision = canonicalWorkspaceSyncSequence(row.entityRevision, 'Task relationship entity revision');
+    const lifecycleRevision = canonicalWorkspaceSyncSequence(row.lifecycleRevision, 'Task relationship lifecycle revision');
+    const occurredAt = canonicalWorkspaceSyncTimestamp(row.occurredAt, 'Task relationship journal occurredAt');
+    if (row.contractVersion !== WORKSPACE_SYNC_CONTRACT_VERSION
+        || !row.entityId
+        || BigInt(entityRevision) < 1n
+        || BigInt(lifecycleRevision) > BigInt(entityRevision)
+        || row.contentSha256 !== null
+        || row.sizeBytes !== null) {
+        throw new Error(`Task relationship journal coordinates are invalid at ${row.sequence}.`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(row.payloadJson);
+    }
+    catch {
+        throw new Error(`Malformed task relationship journal payload at ${row.sequence}.`);
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error(`Task relationship payload is invalid at ${row.sequence}.`);
+    }
+    const payload = serializeTaskRelationshipForSync(raw);
+    if (payload.id !== row.entityId || canonicalWorkspaceSyncJson(payload) !== canonicalWorkspaceSyncJson(raw)) {
+        throw new Error(`Task relationship payload is not canonical at ${row.sequence}.`);
+    }
+    const mutationKind = row.mutationKind;
+    if (!['link', 'unlink', 'delete'].includes(mutationKind)) {
+        throw new Error(`Unsupported task relationship mutation at ${row.sequence}: ${row.mutationKind}.`);
+    }
+    if (mutationKind === 'link') {
+        if (payload.deletedAt !== null || (lifecycleRevision === '0' && entityRevision !== '1')) {
+            throw new Error(`Task relationship link semantics are invalid at ${row.sequence}.`);
+        }
+    }
+    else if (payload.deletedAt === null || BigInt(lifecycleRevision) < 1n) {
+        throw new Error(`Task relationship deletion semantics are invalid at ${row.sequence}.`);
+    }
+    return {
+        sequence,
+        projection: 'task-relationship/full-v1',
+        domain: 'task-relationship',
+        entityId: row.entityId,
+        mutationKind,
+        entityRevision,
+        lifecycleRevision,
+        payloadFingerprint: fingerprintWorkspaceSyncPayload(payload),
+        payload,
+        occurredAt,
+    };
+}
+export function projectWorkspaceSyncV3TaskRelationshipOperation(input) {
+    const relationshipRows = input.rows.filter((row) => row.domain === 'task-relationship');
+    if (relationshipRows.length === 0)
+        return null;
+    assertWorkspaceSyncV3OperationBoundary(input);
+    const first = input.rows[0];
+    if (first.domain === 'task') {
+        if (first.mutationKind !== 'delete' || !projectWorkspaceSyncV3TaskRootOperation(input)) {
+            throw new Error('Task relationship delete composite is invalid.');
+        }
+        return relationshipRows.map((row) => projectWorkspaceSyncV3TaskRelationshipJournalRow(row));
+    }
+    if (input.rows.length !== 1
+        || first.domain !== 'task-relationship'
+        || (first.mutationKind !== 'link' && first.mutationKind !== 'unlink')) {
+        throw new Error('Task relationship operation shape is invalid.');
+    }
+    return [projectWorkspaceSyncV3TaskRelationshipJournalRow(first)];
+}
+export function validateWorkspaceSyncV3TaskRelationshipFeedEntry(entry) {
+    const projected = projectWorkspaceSyncV3TaskRelationshipJournalRow({
+        sequence: entry.sequence,
+        contractVersion: WORKSPACE_SYNC_CONTRACT_VERSION,
+        clientId: 'validation-client',
+        operationId: 'validation-operation',
+        domain: 'task-relationship',
+        entityId: entry.entityId,
+        mutationKind: entry.mutationKind,
+        entityRevision: entry.entityRevision,
+        lifecycleRevision: entry.lifecycleRevision,
+        contentSha256: null,
+        sizeBytes: null,
+        payloadJson: canonicalWorkspaceSyncJson(entry.payload),
+        occurredAt: entry.occurredAt,
+    });
+    if (!projected || canonicalWorkspaceSyncJson(projected) !== canonicalWorkspaceSyncJson(entry)) {
+        throw new Error(`Task relationship feed entry is invalid at ${entry.sequence}.`);
+    }
+}

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

@@ -0,0 +1,40 @@
+import { serializeTaskForSync, type TaskSyncPayload } from '../taskSyncPayload.js';
+import type { TaxonomyTaskRemapAuthoritativePayload } from './taxonomyCompositeMutationService.js';
+import type { WorkspaceSyncJournalRow } from './workspaceSyncJournalReader.js';
+export type WorkspaceSyncV3TaskRootMutationKind = 'create' | 'metadata-update' | 'archive' | 'unarchive' | 'complete' | 'reopen' | 'set-status' | 'taxonomy-remap' | 'delete';
+export type WorkspaceSyncV3TaskRootPayload = Omit<TaskSyncPayload, 'attachments' | 'checklistItems' | 'comments'>;
+export type WorkspaceSyncV3TaskRootTombstone = {
+    taskId: string;
+    deletedAt: string;
+};
+/**
+ * Behavior-dark operation contract. It is not an advertised coverage profile.
+ * Activation also requires taxonomy and task-relationship operation closure.
+ */
+export declare const WORKSPACE_SYNC_V3_TASK_ROOT_OPERATION_PROJECTION: Readonly<{
+    readonly projectionId: "task/root-v1";
+    readonly domain: "task";
+    readonly schemaVersion: 1;
+    readonly mutationKinds: readonly string[];
+}>;
+export type WorkspaceSyncV3TaskRootFeedEntry = {
+    sequence: string;
+    projection: 'task/root-v1';
+    domain: 'task';
+    entityId: string;
+    mutationKind: WorkspaceSyncV3TaskRootMutationKind;
+    entityRevision: string;
+    lifecycleRevision: string;
+    canonicalFingerprint: string;
+    payloadFingerprint: string;
+    payload: WorkspaceSyncV3TaskRootPayload | TaxonomyTaskRemapAuthoritativePayload | WorkspaceSyncV3TaskRootTombstone;
+    occurredAt: string;
+};
+export declare function serializeTaskRootForSync(task: Parameters<typeof serializeTaskForSync>[0]): WorkspaceSyncV3TaskRootPayload;
+export declare function projectWorkspaceSyncV3TaskRootJournalRow(row: WorkspaceSyncJournalRow): WorkspaceSyncV3TaskRootFeedEntry | null;
+export declare function projectWorkspaceSyncV3TaskRootOperation(input: {
+    rows: readonly WorkspaceSyncJournalRow[];
+    cycleHighWatermark: string;
+    followingRow?: WorkspaceSyncJournalRow | null;
+}): WorkspaceSyncV3TaskRootFeedEntry[] | null;
+export declare function validateWorkspaceSyncV3TaskRootFeedEntry(entry: WorkspaceSyncV3TaskRootFeedEntry): void;