@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/sync/v3/localTaskDeleteOutboxHandler.js

@@ -0,0 +1,54 @@
+import { DurableTaskDeleteMutationError } from '../../core/TaskDurableDeleteMutationService.js';
+import { TaskforceRuleError } from '../../core/Taskforce.js';
+import { applyAuthoritativeTaskDeleteAndAck, LocalAuthoritativeTaskDeleteError, } from './localTaskDeleteOutboxService.js';
+import { WorkspaceSyncIdempotencyConflictError, WorkspaceSyncRevisionConflictError, fingerprintWorkspaceSyncPayload, } from './syncDurabilityStore.js';
+function buildEnvelope(record) {
+    let payload;
+    try {
+        payload = JSON.parse(record.payloadJson);
+    }
+    catch {
+        throw new LocalAuthoritativeTaskDeleteError('Persisted task delete payload is invalid.');
+    }
+    if (fingerprintWorkspaceSyncPayload(payload) !== record.payloadFingerprint) {
+        throw new LocalAuthoritativeTaskDeleteError('Persisted task delete payload fingerprint is invalid.');
+    }
+    return {
+        contractVersion: 3,
+        workspaceId: record.workspaceId,
+        clientId: record.clientId,
+        operationId: record.operationId,
+        operation: {
+            domain: 'task',
+            entityId: record.entityId,
+            mutationKind: 'delete',
+            baseEntityRevision: record.baseEntityRevision,
+            baseLifecycleRevision: record.baseLifecycleRevision,
+            payload: payload,
+        },
+    };
+}
+export function createLocalTaskDeleteOutboxHandler(input) {
+    return {
+        key: 'task/delete',
+        supports: (record) => record.domain === 'task' && record.mutationKind === 'delete',
+        buildEnvelope,
+        applyAuthoritative: (applyInput) => {
+            if (!applyInput.record) {
+                throw new LocalAuthoritativeTaskDeleteError('Persisted task delete operation context is missing.');
+            }
+            applyAuthoritativeTaskDeleteAndAck({
+                store: input.store,
+                core: input.core,
+                ...applyInput,
+                record: applyInput.record,
+                onPostCommitError: input.onPostCommitError,
+            });
+        },
+        isPermanentApplyError: (error) => (error instanceof LocalAuthoritativeTaskDeleteError
+            || error instanceof DurableTaskDeleteMutationError
+            || error instanceof TaskforceRuleError
+            || error instanceof WorkspaceSyncIdempotencyConflictError
+            || error instanceof WorkspaceSyncRevisionConflictError),
+    };
+}

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

@@ -0,0 +1,38 @@
+import type { DeletedTaskRecord, TaskRelationshipRecord } from '../../core/Taskforce.js';
+import { type DurableTaskDeleteCore } from '../../core/TaskDurableDeleteMutationService.js';
+import { WorkspaceSyncDurabilityStore, type WorkspaceSyncOperationIdentity, type WorkspaceSyncOutboxRecord } from './syncDurabilityStore.js';
+export interface LocalTaskDeleteOutboxCore extends DurableTaskDeleteCore {
+    getDeletedTask(id: string, workspaceId?: string): DeletedTaskRecord | null;
+    installDurableTaskDeleteAuthoritativeForSync(input: {
+        taskId: string;
+        deletedAt: string;
+        relationships: TaskRelationshipRecord[];
+    }, workspaceId?: string): DeletedTaskRecord;
+    notifyDurableTaskDeleteCommitted(workspaceId: string, taskId: string): void;
+}
+export declare class LocalAuthoritativeTaskDeleteError extends Error {
+    readonly code = "WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID";
+    constructor(message: string);
+}
+export declare function enqueueLocalTaskDeleteMutation(input: {
+    store: WorkspaceSyncDurabilityStore;
+    core: LocalTaskDeleteOutboxCore;
+    identity: WorkspaceSyncOperationIdentity;
+    taskId: string;
+    now: string;
+    actorRef: string;
+    onPostCommitError?: (error: unknown) => void;
+}): {
+    enqueued: boolean;
+    deleted?: DeletedTaskRecord;
+};
+export declare function applyAuthoritativeTaskDeleteAndAck(input: {
+    store: WorkspaceSyncDurabilityStore;
+    core: LocalTaskDeleteOutboxCore;
+    identity: WorkspaceSyncOperationIdentity;
+    leaseOwner: string;
+    response: unknown;
+    record: WorkspaceSyncOutboxRecord;
+    now: string;
+    onPostCommitError?: (error: unknown) => void;
+}): DeletedTaskRecord;

package/dist/sync/v3/localTaskDeleteOutboxService.js

@@ -0,0 +1,235 @@
+import { applyTaskDeleteForDurableSync, DurableTaskDeleteMutationError, prepareTaskDeleteForDurableSync, } from '../../core/TaskDurableDeleteMutationService.js';
+import { fingerprintWorkspaceSyncPayload, WorkspaceSyncIdempotencyConflictError, } from './syncDurabilityStore.js';
+export class LocalAuthoritativeTaskDeleteError extends Error {
+    code = 'WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID';
+    constructor(message) {
+        super(message);
+        this.name = 'LocalAuthoritativeTaskDeleteError';
+    }
+}
+function parsePersistedPayload(record) {
+    let payload;
+    try {
+        payload = JSON.parse(record.payloadJson);
+    }
+    catch {
+        throw new LocalAuthoritativeTaskDeleteError('Persisted task delete payload is invalid.');
+    }
+    if (fingerprintWorkspaceSyncPayload(payload) !== record.payloadFingerprint) {
+        throw new LocalAuthoritativeTaskDeleteError('Persisted task delete payload fingerprint is invalid.');
+    }
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        throw new LocalAuthoritativeTaskDeleteError('Persisted task delete payload must be an object.');
+    }
+    const value = payload;
+    if (Object.keys(value).join(',') !== 'relationships' || !Array.isArray(value.relationships)) {
+        throw new LocalAuthoritativeTaskDeleteError('Persisted task delete payload fields are invalid.');
+    }
+    const relationships = value.relationships.map((raw) => {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new LocalAuthoritativeTaskDeleteError('Persisted relationship delete base is invalid.');
+        }
+        const entry = raw;
+        const keys = Object.keys(entry).sort().join(',');
+        const entityId = typeof entry.entityId === 'string' ? entry.entityId.trim() : '';
+        const baseEntityRevision = String(entry.baseEntityRevision ?? '');
+        const baseLifecycleRevision = String(entry.baseLifecycleRevision ?? '');
+        if (keys !== 'baseEntityRevision,baseLifecycleRevision,entityId'
+            || !entityId
+            || !/^(0|[1-9]\d*)$/.test(baseEntityRevision)
+            || !/^(0|[1-9]\d*)$/.test(baseLifecycleRevision)) {
+            throw new LocalAuthoritativeTaskDeleteError('Persisted relationship delete base is invalid.');
+        }
+        return { entityId, baseEntityRevision, baseLifecycleRevision };
+    });
+    if (new Set(relationships.map((entry) => entry.entityId)).size !== relationships.length) {
+        throw new LocalAuthoritativeTaskDeleteError('Persisted relationship delete bases are not unique.');
+    }
+    return { relationships };
+}
+export function enqueueLocalTaskDeleteMutation(input) {
+    const taskId = String(input.taskId || '').trim();
+    if (!taskId)
+        throw new DurableTaskDeleteMutationError('Task not found.', 'TASK_NOT_FOUND', 404);
+    const result = input.store.runLocalTaskDeleteCaptureTransaction({
+        tenantId: input.identity.tenantId,
+        workspaceId: input.identity.workspaceId,
+        taskId,
+        now: input.now,
+        apply: () => {
+            const prior = input.store.readOutboxOperation(input.identity);
+            if (prior) {
+                if (prior.domain !== 'task' || prior.entityId !== taskId || prior.mutationKind !== 'delete') {
+                    throw new WorkspaceSyncIdempotencyConflictError();
+                }
+                parsePersistedPayload(prior);
+                return { enqueued: false, deleted: input.core.getDeletedTask(taskId, input.identity.workspaceId) || undefined };
+            }
+            const activeIncidentRelationship = input.store.listActiveTaskRelationshipOperationIds({
+                tenantId: input.identity.tenantId,
+                workspaceId: input.identity.workspaceId,
+            }).map((relationshipId) => input.core.getTaskRelationshipForSync(relationshipId, input.identity.workspaceId)).find((relationship) => relationship && (relationship.sourceTaskId === taskId || relationship.targetTaskId === taskId));
+            if (activeIncidentRelationship) {
+                throw new DurableTaskDeleteMutationError('An incident task relationship operation must finish before the task can be deleted.', 'TASK_DELETE_RELATIONSHIP_SET_CHANGED', 409);
+            }
+            const plan = prepareTaskDeleteForDurableSync({
+                core: input.core,
+                workspaceId: input.identity.workspaceId,
+                taskId,
+            });
+            if (plan.relationships.length > 99) {
+                throw new DurableTaskDeleteMutationError('Task has too many relationships for one durable delete operation.', 'TASK_DELETE_RELATIONSHIP_SET_CHANGED', 409);
+            }
+            const relationships = plan.relationships.map((relationship) => ({
+                entityId: relationship.id,
+                ...input.store.readEntityRevisionCoordinates({
+                    tenantId: input.identity.tenantId,
+                    workspaceId: input.identity.workspaceId,
+                    domain: 'task-relationship',
+                    entityId: relationship.id,
+                }),
+            })).map((entry) => ({
+                entityId: entry.entityId,
+                baseEntityRevision: entry.entityRevision,
+                baseLifecycleRevision: entry.lifecycleRevision,
+            }));
+            const captured = input.store.enqueueLocalOperation({
+                identity: input.identity,
+                domain: 'task',
+                entityId: taskId,
+                mutationKind: 'delete',
+                revisionSource: 'current',
+                ownership: { taskMetadata: true, taskLifecycle: true },
+                payload: { relationships },
+                now: input.now,
+                applyLocalMutation: () => applyTaskDeleteForDurableSync({
+                    core: input.core,
+                    workspaceId: input.identity.workspaceId,
+                    taskId,
+                    expectedRelationshipIds: relationships.map((relationship) => relationship.entityId),
+                    deletedAt: input.now,
+                    actorRef: input.actorRef,
+                    source: 'ui',
+                }),
+            });
+            return {
+                enqueued: captured.enqueued,
+                deleted: input.core.getDeletedTask(taskId, input.identity.workspaceId) || undefined,
+            };
+        },
+    });
+    if (result.enqueued) {
+        try {
+            input.core.notifyDurableTaskDeleteCommitted(input.identity.workspaceId, taskId);
+        }
+        catch (error) {
+            try {
+                input.onPostCommitError?.(error);
+            }
+            catch { /* local capture remains committed */ }
+        }
+    }
+    return result;
+}
+export function applyAuthoritativeTaskDeleteAndAck(input) {
+    if (!input.response || typeof input.response !== 'object' || Array.isArray(input.response)) {
+        throw new LocalAuthoritativeTaskDeleteError('Authoritative task delete response must be an object.');
+    }
+    const response = input.response;
+    const persisted = parsePersistedPayload(input.record);
+    const authoritative = Array.isArray(response.authoritative) ? response.authoritative : [];
+    if (response.success !== true
+        || response.contractVersion !== 3
+        || response.workspaceId !== input.identity.workspaceId
+        || response.clientId !== input.identity.clientId
+        || response.operationId !== input.identity.operationId
+        || typeof response.acceptedSequence !== 'string'
+        || !/^(0|[1-9]\d*)$/.test(response.acceptedSequence)
+        || authoritative.length !== persisted.relationships.length + 1) {
+        throw new LocalAuthoritativeTaskDeleteError('Authoritative task delete response identity is invalid.');
+    }
+    const normalized = authoritative.map((raw) => {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new LocalAuthoritativeTaskDeleteError('Authoritative task delete revision is invalid.');
+        }
+        const entry = raw;
+        const domain = entry.domain;
+        const entityId = typeof entry.entityId === 'string' ? entry.entityId.trim() : '';
+        const sequence = String(entry.sequence ?? '');
+        const entityRevision = String(entry.entityRevision ?? '');
+        const lifecycleRevision = String(entry.lifecycleRevision ?? '');
+        if ((domain !== 'task' && domain !== 'task-relationship')
+            || !entityId || entry.mutationKind !== 'delete'
+            || !/^(0|[1-9]\d*)$/.test(sequence)
+            || !/^(0|[1-9]\d*)$/.test(entityRevision)
+            || !/^(0|[1-9]\d*)$/.test(lifecycleRevision)) {
+            throw new LocalAuthoritativeTaskDeleteError('Authoritative task delete revision is invalid.');
+        }
+        return { domain, entityId, sequence, entityRevision, lifecycleRevision, payload: entry.payload };
+    });
+    const taskEntry = normalized.find((entry) => entry.domain === 'task');
+    const taskPayload = taskEntry?.payload;
+    const deletedAt = typeof taskPayload?.deletedAt === 'string' ? taskPayload.deletedAt : '';
+    if (!taskEntry || taskEntry.entityId !== input.record.entityId
+        || taskPayload?.taskId !== input.record.entityId
+        || !Number.isFinite(Date.parse(deletedAt)) || new Date(deletedAt).toISOString() !== deletedAt) {
+        throw new LocalAuthoritativeTaskDeleteError('Authoritative task tombstone is invalid.');
+    }
+    const expectedRelationshipIds = persisted.relationships.map((entry) => entry.entityId).sort();
+    const relationshipEntries = normalized.filter((entry) => entry.domain === 'task-relationship');
+    const expectedFirstSequence = BigInt(response.acceptedSequence) - BigInt(normalized.length - 1);
+    const sortedSequences = normalized
+        .map((entry) => BigInt(entry.sequence))
+        .sort((left, right) => left < right ? -1 : left > right ? 1 : 0);
+    const hasContiguousSequenceRange = expectedFirstSequence >= 0n && sortedSequences.every((sequence, index) => sequence === expectedFirstSequence + BigInt(index));
+    if (relationshipEntries.map((entry) => entry.entityId).sort().join('\u0000') !== expectedRelationshipIds.join('\u0000')
+        || new Set(normalized.map((entry) => `${entry.domain}\u0000${entry.entityId}`)).size !== normalized.length
+        || new Set(normalized.map((entry) => entry.sequence)).size !== normalized.length
+        || !hasContiguousSequenceRange) {
+        throw new LocalAuthoritativeTaskDeleteError('Authoritative relationship tombstone set is incomplete.');
+    }
+    const relationships = relationshipEntries.map((entry) => {
+        const relationship = entry.payload;
+        if (!relationship || typeof relationship !== 'object'
+            || relationship.id !== entry.entityId
+            || relationship.workspaceId !== input.identity.workspaceId
+            || relationship.deletedAt !== deletedAt
+            || relationship.updatedAt !== deletedAt
+            || (relationship.sourceTaskId !== input.record.entityId && relationship.targetTaskId !== input.record.entityId)) {
+            throw new LocalAuthoritativeTaskDeleteError('Authoritative relationship tombstone is invalid.');
+        }
+        return relationship;
+    });
+    const installed = input.store.applyAuthoritativeAndAck({
+        identity: input.identity,
+        leaseOwner: input.leaseOwner,
+        now: input.now,
+        response,
+        acceptedSequence: response.acceptedSequence,
+        authoritative: normalized.map((entry) => ({
+            domain: entry.domain,
+            entityId: entry.entityId,
+            mutationKind: 'delete',
+            entityRevision: entry.entityRevision,
+            lifecycleRevision: entry.lifecycleRevision,
+            sequence: entry.sequence,
+            canonicalFingerprint: fingerprintWorkspaceSyncPayload(entry.payload),
+            metadataOwned: entry.domain === 'task',
+        })),
+        applyAuthoritative: () => input.core.installDurableTaskDeleteAuthoritativeForSync({
+            taskId: input.record.entityId,
+            deletedAt,
+            relationships,
+        }, input.identity.workspaceId),
+    });
+    try {
+        input.core.notifyDurableTaskDeleteCommitted(input.identity.workspaceId, input.record.entityId);
+    }
+    catch (error) {
+        try {
+            input.onPostCommitError?.(error);
+        }
+        catch { /* authoritative state remains committed */ }
+    }
+    return installed;
+}

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

@@ -0,0 +1,28 @@
+import type { TaskEvent, TaskItem } from '../../core/Taskforce.js';
+import { WorkspaceSyncDurabilityStore, type WorkspaceSyncOperationIdentity } from './syncDurabilityStore.js';
+import type { LocalOutboxOperationHandler } from './localOutboxOperationHandler.js';
+export interface LocalTaskLegacyRootAdoptionCore {
+    getTask(id: string, workspaceId?: string): TaskItem | null;
+    installWorkspaceSyncV3TaskRootAuthoritativeForSync(task: TaskItem, workspaceId: string): TaskItem;
+    upsertEntityEventForSync(event: TaskEvent, options?: {
+        allowAuthoritativeReplacement?: boolean;
+    }): unknown;
+    notifyDurableTaskCreateCommitted(workspaceId: string, taskId: string): void;
+}
+export declare class LocalTaskLegacyRootAdoptionError extends Error {
+    readonly code = "WORKSPACE_SYNC_LEGACY_ROOT_ADOPTION_INVALID";
+    constructor(message: string);
+}
+export declare function enqueueLocalTaskLegacyRootAdoption(input: {
+    store: WorkspaceSyncDurabilityStore;
+    core: LocalTaskLegacyRootAdoptionCore;
+    identity: WorkspaceSyncOperationIdentity;
+    taskId: string;
+    now: string;
+}): {
+    enqueued: boolean;
+};
+export declare function createLocalTaskLegacyRootAdoptionHandler(input: {
+    store: WorkspaceSyncDurabilityStore;
+    core: LocalTaskLegacyRootAdoptionCore;
+}): LocalOutboxOperationHandler;

package/dist/sync/v3/localTaskLegacyRootAdoption.js

@@ -0,0 +1,219 @@
+import { serializeTaskForSync } from '../taskSyncPayload.js';
+import { buildTaskCreateActivityEventId } from './taskCreateActivityIdentity.js';
+import { validateTaskActivityAuthoritativeRevision } from './taskActivityAuthoritativeRevision.js';
+import { serializeTaskActivityForSync, WORKSPACE_SYNC_ENTITY_EVENT_APPEND, WORKSPACE_SYNC_ENTITY_EVENT_DOMAIN, } from './taskActivityJournal.js';
+import { validateTaskLegacyRootAdoptionCandidate } from './taskLegacyRootAdoptionService.js';
+import { fingerprintWorkspaceSyncPayload, } from './syncDurabilityStore.js';
+import { serializeTaskRootForSync } from './workspaceSyncV3TaskRootProjection.js';
+export class LocalTaskLegacyRootAdoptionError extends Error {
+    code = 'WORKSPACE_SYNC_LEGACY_ROOT_ADOPTION_INVALID';
+    constructor(message) {
+        super(message);
+        this.name = 'LocalTaskLegacyRootAdoptionError';
+    }
+}
+export function enqueueLocalTaskLegacyRootAdoption(input) {
+    const task = input.core.getTask(input.taskId, input.identity.workspaceId);
+    if (!task || task.referenceNumber !== null || !Number.isInteger(task.localReferenceNumber)
+        || Number(task.localReferenceNumber) < 1) {
+        throw new LocalTaskLegacyRootAdoptionError('Task is not an unowned provisional legacy root.');
+    }
+    const projection = input.store.readCombinedProjectionOwnership({
+        tenantId: input.identity.tenantId,
+        workspaceId: input.identity.workspaceId,
+    });
+    if (projection.owner !== 'v3') {
+        throw new LocalTaskLegacyRootAdoptionError('Combined v3 ownership is required for legacy root adoption.');
+    }
+    const ownership = input.store.readWorkspaceDomainOwnership({
+        tenantId: input.identity.tenantId,
+        workspaceId: input.identity.workspaceId,
+        domain: 'task',
+        entityId: input.taskId,
+    });
+    if (ownership.owned || ownership.entityRevision !== '0') {
+        throw new LocalTaskLegacyRootAdoptionError('Task root already has durable ownership.');
+    }
+    const adoptedRoot = validateTaskLegacyRootAdoptionCandidate(serializeTaskRootForSync(task), task.id);
+    const frozenFingerprint = fingerprintWorkspaceSyncPayload(adoptedRoot);
+    const result = input.store.enqueueLocalOperation({
+        identity: input.identity,
+        dispatchClass: 'legacy-adoption',
+        domain: 'task',
+        entityId: task.id,
+        mutationKind: 'create',
+        revisionSource: 'current',
+        ownership: { taskMetadata: true, taskLifecycle: true, taskAssignee: true },
+        payload: { adoptedRoot },
+        now: input.now,
+        requireV3PlanningOwnership: 'combined',
+        requiredCurrentRevision: { entityRevision: 0, lifecycleRevision: 0 },
+        validateLockedState: () => {
+            const current = input.core.getTask(input.taskId, input.identity.workspaceId);
+            if (!current || current.referenceNumber !== null || !Number.isInteger(current.localReferenceNumber)
+                || Number(current.localReferenceNumber) < 1
+                || fingerprintWorkspaceSyncPayload(serializeTaskRootForSync(current)) !== frozenFingerprint) {
+                throw new LocalTaskLegacyRootAdoptionError('Legacy task root changed before adoption could be enqueued.');
+            }
+        },
+        applyLocalMutation: () => undefined,
+    });
+    return { enqueued: result.enqueued };
+}
+function buildEnvelope(record) {
+    let payload;
+    try {
+        payload = JSON.parse(record.payloadJson);
+    }
+    catch {
+        throw new LocalTaskLegacyRootAdoptionError('Legacy root adoption payload is not valid JSON.');
+    }
+    if (fingerprintWorkspaceSyncPayload(payload) !== record.payloadFingerprint
+        || !payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        throw new LocalTaskLegacyRootAdoptionError('Legacy root adoption payload fingerprint is invalid.');
+    }
+    const source = payload;
+    if (Object.keys(source).length !== 1 || !Object.prototype.hasOwnProperty.call(source, 'adoptedRoot')) {
+        throw new LocalTaskLegacyRootAdoptionError('Legacy root adoption payload must contain exactly adoptedRoot.');
+    }
+    if (record.baseEntityRevision !== '0' || record.baseLifecycleRevision !== '0') {
+        throw new LocalTaskLegacyRootAdoptionError('Legacy root adoption base revisions must both be 0.');
+    }
+    return {
+        contractVersion: 3,
+        workspaceId: record.workspaceId,
+        clientId: record.clientId,
+        operationId: record.operationId,
+        operation: {
+            domain: 'task',
+            entityId: record.entityId,
+            mutationKind: 'create',
+            baseEntityRevision: '0',
+            baseLifecycleRevision: '0',
+            payload: {
+                adoptedRoot: validateTaskLegacyRootAdoptionCandidate(source.adoptedRoot, record.entityId),
+            },
+        },
+    };
+}
+function applyAuthoritative(input) {
+    if (!input.response || typeof input.response !== 'object' || Array.isArray(input.response)) {
+        throw new LocalTaskLegacyRootAdoptionError('Legacy root adoption response must be an object.');
+    }
+    const response = input.response;
+    const authoritative = response.authoritative;
+    const task = authoritative?.payload;
+    if (response.success !== true
+        || response.contractVersion !== 3
+        || response.workspaceId !== input.identity.workspaceId
+        || response.clientId !== input.identity.clientId
+        || response.operationId !== input.identity.operationId
+        || response.adoptedLegacyRoot !== true
+        || response.provisionalTaskId !== authoritative?.entityId
+        || authoritative?.domain !== 'task'
+        || authoritative.mutationKind !== 'create'
+        || !task || task.id !== response.provisionalTaskId
+        || !Number.isInteger(Number(task.referenceNumber)) || Number(task.referenceNumber) < 1) {
+        throw new LocalTaskLegacyRootAdoptionError('Legacy root adoption response identity is invalid.');
+    }
+    if (!input.record) {
+        throw new LocalTaskLegacyRootAdoptionError('Legacy root adoption outbox record is required.');
+    }
+    const frozenEnvelope = buildEnvelope(input.record);
+    const frozenRoot = serializeTaskRootForSync(frozenEnvelope.operation.payload.adoptedRoot);
+    const current = input.core.getTask(task.id, input.identity.workspaceId);
+    if (!current || fingerprintWorkspaceSyncPayload(serializeTaskRootForSync(current))
+        !== fingerprintWorkspaceSyncPayload(frozenRoot)) {
+        throw new LocalTaskLegacyRootAdoptionError('Local legacy task root changed after adoption was queued.');
+    }
+    const authoritativeRoot = serializeTaskRootForSync(task);
+    if (fingerprintWorkspaceSyncPayload(authoritativeRoot) !== fingerprintWorkspaceSyncPayload({
+        ...frozenRoot,
+        referenceNumber: authoritativeRoot.referenceNumber,
+    })) {
+        throw new LocalTaskLegacyRootAdoptionError('Cloud adoption changed the frozen legacy task root.');
+    }
+    const expectedActivityId = buildTaskCreateActivityEventId({
+        workspaceId: input.identity.workspaceId,
+        clientId: input.identity.clientId,
+        operationId: input.identity.operationId,
+        taskId: task.id,
+    });
+    if (!response.activity || response.activity.id !== expectedActivityId
+        || response.activity.workspaceId !== input.identity.workspaceId
+        || response.activity.entityType !== 'task' || response.activity.entityId !== task.id
+        || response.activity.taskId !== task.id
+        || response.activity.action !== 'task-created'
+        || typeof response.activity.actor !== 'string' || !response.activity.actor.trim()
+        || !['human', 'ai', 'system'].includes(response.activity.actorType)
+        || response.activity.createdAt !== frozenRoot.createdAt
+        || !response.activity.details || typeof response.activity.details !== 'object'
+        || Array.isArray(response.activity.details)
+        || Object.keys(response.activity.details).sort().join(',') !== 'status,title,workstreamId'
+        || response.activity.details.title !== frozenRoot.title
+        || response.activity.details.status !== frozenRoot.status
+        || (response.activity.details.workstreamId ?? null) !== (frozenRoot.workstreamId ?? null)) {
+        throw new LocalTaskLegacyRootAdoptionError('Legacy root adoption activity identity is invalid.');
+    }
+    const revision = validateTaskActivityAuthoritativeRevision({
+        response: response,
+        authoritative: authoritative,
+        activityId: response.activity.id,
+        invalid: (message) => new LocalTaskLegacyRootAdoptionError(message),
+    });
+    const canonicalFingerprint = fingerprintWorkspaceSyncPayload(serializeTaskForSync(task));
+    input.store.applyAuthoritativeAndAck({
+        identity: input.identity,
+        leaseOwner: input.leaseOwner,
+        now: input.now,
+        response,
+        acceptedSequence: revision.operationHighWatermark,
+        authoritative: [{
+                domain: 'task', entityId: task.id, mutationKind: 'create',
+                entityRevision: authoritative.entityRevision,
+                lifecycleRevision: authoritative.lifecycleRevision,
+                sequence: revision.taskSequence,
+                canonicalFingerprint,
+            }, ...(!revision.legacySingleEntry && revision.activityRevision ? [{
+                    domain: WORKSPACE_SYNC_ENTITY_EVENT_DOMAIN,
+                    entityId: response.activity.id,
+                    mutationKind: WORKSPACE_SYNC_ENTITY_EVENT_APPEND,
+                    entityRevision: revision.activityRevision.entityRevision,
+                    lifecycleRevision: revision.activityRevision.lifecycleRevision,
+                    sequence: revision.activityRevision.sequence,
+                    canonicalFingerprint: fingerprintWorkspaceSyncPayload(serializeTaskActivityForSync(response.activity)),
+                }] : [])],
+        applyAuthoritative: () => {
+            const installed = input.core.installWorkspaceSyncV3TaskRootAuthoritativeForSync(task, input.identity.workspaceId);
+            input.core.upsertEntityEventForSync(response.activity, { allowAuthoritativeReplacement: true });
+            if (fingerprintWorkspaceSyncPayload(serializeTaskRootForSync(installed))
+                !== fingerprintWorkspaceSyncPayload(serializeTaskRootForSync(task))) {
+                throw new LocalTaskLegacyRootAdoptionError('Installed legacy task root does not match cloud authority.');
+            }
+        },
+    });
+    try {
+        input.core.notifyDurableTaskCreateCommitted(input.identity.workspaceId, task.id);
+    }
+    catch { /* authoritative adoption and acknowledgement remain committed */ }
+}
+export function createLocalTaskLegacyRootAdoptionHandler(input) {
+    return {
+        key: 'task/adopt-legacy-root',
+        supports: (record) => {
+            if (record.domain !== 'task' || record.mutationKind !== 'create')
+                return false;
+            try {
+                const payload = JSON.parse(record.payloadJson);
+                return Object.prototype.hasOwnProperty.call(payload, 'adoptedRoot');
+            }
+            catch {
+                return false;
+            }
+        },
+        buildEnvelope,
+        resolveDispatchReadiness: () => ({ ready: true }),
+        applyAuthoritative: (applyInput) => applyAuthoritative({ store: input.store, core: input.core, ...applyInput }),
+        isPermanentApplyError: (error) => error instanceof LocalTaskLegacyRootAdoptionError,
+    };
+}

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

@@ -0,0 +1,49 @@
+import { type LocalTaskOperationClientDependencies, type LocalTaskOperationResult } from './localTaskOperationClient.js';
+export type LocalTaskLifecycleMutationResult = LocalTaskOperationResult;
+export type LocalTaskLifecycleMutationInput = {
+    workspaceId: string;
+    entityId: string;
+    isAuthenticated: boolean;
+    dispatchEnabled?: boolean;
+} & ({
+    mutationKind: 'archive';
+    cancellation: boolean;
+    reason: string | null;
+} | {
+    mutationKind: 'unarchive';
+} | {
+    mutationKind: 'complete';
+} | {
+    mutationKind: 'reopen';
+    assignee: string | null;
+});
+export declare function createLocalTaskLifecycleClient(dependencies?: LocalTaskOperationClientDependencies): {
+    mutate: (input: LocalTaskLifecycleMutationInput) => Promise<LocalTaskLifecycleMutationResult>;
+    archive(input: {
+        workspaceId: string;
+        entityId: string;
+        cancellation: boolean;
+        reason: string | null;
+        isAuthenticated: boolean;
+        dispatchEnabled?: boolean;
+    }): Promise<LocalTaskOperationResult>;
+    unarchive(input: {
+        workspaceId: string;
+        entityId: string;
+        isAuthenticated: boolean;
+        dispatchEnabled?: boolean;
+    }): Promise<LocalTaskOperationResult>;
+    complete(input: {
+        workspaceId: string;
+        entityId: string;
+        isAuthenticated: boolean;
+        dispatchEnabled?: boolean;
+    }): Promise<LocalTaskOperationResult>;
+    reopen(input: {
+        workspaceId: string;
+        entityId: string;
+        assignee: string | null;
+        isAuthenticated: boolean;
+        dispatchEnabled?: boolean;
+    }): Promise<LocalTaskOperationResult>;
+};