@taskforcehq/taskforce 0.3.326 → 0.3.327

package/dist/sync/v3/localTaskAttachmentLinksOutboxHandler.js

@@ -0,0 +1,70 @@
+import { EntityEventIdentityCollisionError } from '../../core/TaskActivityService.js';
+import { applyAuthoritativeTaskAttachmentLinksAndAck, LocalAuthoritativeTaskAttachmentLinksError, } from './localTaskAttachmentLinksOutboxService.js';
+import { fingerprintWorkspaceSyncPayload, WorkspaceSyncIdempotencyConflictError, WorkspaceSyncRevisionConflictError, } from './syncDurabilityStore.js';
+import { validateWorkspaceSyncV3TaskAttachmentLinksPayload } from './workspaceSyncV3NestedTaskCodecs.js';
+import { parseWorkspaceSyncV3OriginActor } from './workspaceSyncV3OriginActor.js';
+export function buildTaskAttachmentLinksEnvelope(record) {
+    let payload;
+    try {
+        payload = JSON.parse(record.payloadJson);
+    }
+    catch {
+        throw new Error('Local task attachment-link outbox payload is not valid JSON.');
+    }
+    if (fingerprintWorkspaceSyncPayload(payload) !== record.payloadFingerprint
+        || !payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        throw new Error('Local task attachment-link outbox payload is invalid.');
+    }
+    const source = payload;
+    if (!Object.prototype.hasOwnProperty.call(source, 'links')
+        || Object.keys(source).some((key) => key !== 'links' && key !== 'originActor')) {
+        throw new Error('Local task attachment-link outbox payload must contain links and optional originActor.');
+    }
+    const aggregate = validateWorkspaceSyncV3TaskAttachmentLinksPayload({ taskId: record.entityId, links: source.links });
+    return {
+        contractVersion: 3,
+        workspaceId: record.workspaceId,
+        clientId: record.clientId,
+        operationId: record.operationId,
+        operation: {
+            domain: 'task-attachment-links', entityId: record.entityId, mutationKind: 'replace',
+            baseEntityRevision: record.baseEntityRevision, baseLifecycleRevision: '0',
+            payload: {
+                links: aggregate.links,
+                ...(source.originActor !== undefined
+                    ? { originActor: parseWorkspaceSyncV3OriginActor(source.originActor) }
+                    : {}),
+            },
+        },
+    };
+}
+export function createLocalTaskAttachmentLinksOutboxHandler(input) {
+    return {
+        key: 'task-attachment-links/replace',
+        supports: (record) => record.domain === 'task-attachment-links' && record.mutationKind === 'replace',
+        buildEnvelope: buildTaskAttachmentLinksEnvelope,
+        resolveDispatchReadiness: (record) => {
+            const envelope = buildTaskAttachmentLinksEnvelope(record);
+            for (const link of envelope.operation.payload.links) {
+                const readiness = input.core.getWorkspaceAssetDispatchReadiness(link.assetId, record.workspaceId);
+                if (!readiness.ready)
+                    return {
+                        ready: false,
+                        retryable: readiness.retryable,
+                        errorCode: readiness.retryable
+                            ? 'TASK_ATTACHMENT_ASSET_NOT_READY'
+                            : 'TASK_ATTACHMENT_ASSET_INVALID',
+                        errorMessage: readiness.reason,
+                    };
+            }
+            return { ready: true };
+        },
+        applyAuthoritative: (applyInput) => applyAuthoritativeTaskAttachmentLinksAndAck({
+            store: input.store, core: input.core, ...applyInput, onPostCommitError: input.onPostCommitError,
+        }),
+        isPermanentApplyError: (error) => error instanceof LocalAuthoritativeTaskAttachmentLinksError
+            || error instanceof WorkspaceSyncIdempotencyConflictError
+            || error instanceof WorkspaceSyncRevisionConflictError
+            || error instanceof EntityEventIdentityCollisionError,
+    };
+}

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

@@ -0,0 +1,45 @@
+import type { TaskEvent, TaskItem } from '../../core/Taskforce.js';
+import type { DurableTaskAttachmentLinksServiceCore } from './taskAttachmentLinksMutationService.js';
+import { WorkspaceSyncDurabilityStore, type WorkspaceSyncOperationIdentity } from './syncDurabilityStore.js';
+import { type WorkspaceSyncV3TaskAttachmentLink } from './workspaceSyncV3NestedTaskCodecs.js';
+export interface LocalTaskAttachmentLinksOutboxCore extends DurableTaskAttachmentLinksServiceCore {
+    getWorkspaceAssetDispatchReadiness(assetId: string, workspaceId: string): {
+        ready: boolean;
+        retryable: boolean;
+        reason: string;
+    };
+    upsertEntityEventForSync(event: TaskEvent, options?: {
+        allowAuthoritativeReplacement?: boolean;
+    }): unknown;
+}
+export declare class LocalAuthoritativeTaskAttachmentLinksError extends Error {
+    readonly code = "WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID";
+    constructor(message: string);
+}
+export declare class LocalTaskAttachmentLinksDependencyPendingError extends Error {
+    readonly code = "TASK_ATTACHMENT_ASSET_NOT_READY";
+    constructor(message: string);
+}
+export declare function enqueueLocalTaskAttachmentLinksMutation(input: {
+    store: WorkspaceSyncDurabilityStore;
+    core: LocalTaskAttachmentLinksOutboxCore;
+    identity: WorkspaceSyncOperationIdentity;
+    taskId: string;
+    links: readonly WorkspaceSyncV3TaskAttachmentLink[];
+    now: string;
+    actorRef: string;
+    requireV3CombinedOwnership?: boolean;
+    onPostCommitError?: (error: unknown) => void;
+}): {
+    enqueued: boolean;
+    task?: TaskItem;
+};
+export declare function applyAuthoritativeTaskAttachmentLinksAndAck(input: {
+    store: WorkspaceSyncDurabilityStore;
+    core: LocalTaskAttachmentLinksOutboxCore;
+    identity: WorkspaceSyncOperationIdentity;
+    leaseOwner: string;
+    response: unknown;
+    now: string;
+    onPostCommitError?: (error: unknown) => void;
+}): TaskItem;

package/dist/sync/v3/localTaskAttachmentLinksOutboxService.js

@@ -0,0 +1,291 @@
+import { projectResolvedTaskAttachmentLinksForDurableSync } from '../../core/TaskAttachmentLinksDurableMutationService.js';
+import { selectDurableTaskMetadataPatch } from '../../core/TaskDurableSyncMutationService.js';
+import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
+import { buildTaskAttachmentLinksActivityEventId } from './taskAttachmentLinksActivityIdentity.js';
+import { canonicalizeEntityActivityDetailsForSync, serializeTaskActivityForSync, } from './taskActivityJournal.js';
+import { fingerprintWorkspaceSyncPayload, } from './syncDurabilityStore.js';
+import { serializeTaskRootForSync } from './workspaceSyncV3TaskRootProjection.js';
+import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
+import { withOriginActorPayload } from './workspaceSyncV3OriginActor.js';
+export class LocalAuthoritativeTaskAttachmentLinksError extends Error {
+    code = 'WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID';
+    constructor(message) {
+        super(message);
+        this.name = 'LocalAuthoritativeTaskAttachmentLinksError';
+    }
+}
+export class LocalTaskAttachmentLinksDependencyPendingError extends Error {
+    code = 'TASK_ATTACHMENT_ASSET_NOT_READY';
+    constructor(message) {
+        super(message);
+        this.name = 'LocalTaskAttachmentLinksDependencyPendingError';
+    }
+}
+function validCompactedAttachmentActivity(details, links) {
+    if (!details || typeof details !== 'object' || Array.isArray(details)
+        || Object.keys(details).join(',') !== 'changes')
+        return false;
+    const changes = details.changes;
+    if (!changes || typeof changes !== 'object' || Array.isArray(changes)
+        || Object.keys(changes).join(',') !== 'attachments')
+        return false;
+    const attachmentChange = changes.attachments;
+    if (!attachmentChange || typeof attachmentChange !== 'object' || Array.isArray(attachmentChange))
+        return false;
+    const compact = attachmentChange;
+    const keys = Object.keys(compact);
+    const allowedKeys = new Set(['fromCount', 'toCount', 'added', 'removed', 'updated']);
+    if (keys.some((key) => !allowedKeys.has(key))
+        || !Object.prototype.hasOwnProperty.call(compact, 'fromCount')
+        || !Object.prototype.hasOwnProperty.call(compact, 'toCount'))
+        return false;
+    if (typeof compact.fromCount !== 'number' || typeof compact.toCount !== 'number')
+        return false;
+    const fromCount = compact.fromCount;
+    const toCount = compact.toCount;
+    if (!Number.isSafeInteger(fromCount) || fromCount < 0
+        || !Number.isSafeInteger(toCount) || toCount !== links.length)
+        return false;
+    const labels = (key) => {
+        if (compact[key] === undefined)
+            return [];
+        if (!Array.isArray(compact[key]))
+            return null;
+        const values = compact[key];
+        if (values.some((value) => typeof value !== 'string'
+            || !value.trim() || /[\\/?#]/.test(value) || /^data:|^[a-z]+:\/\//i.test(value)))
+            return null;
+        return values;
+    };
+    const added = labels('added');
+    const removed = labels('removed');
+    const updated = labels('updated');
+    if (!added || !removed || !updated
+        || removed.length + updated.length > fromCount
+        || added.length + updated.length > toCount
+        || added.length - removed.length !== toCount - fromCount)
+        return false;
+    const authoritativeLabels = new Set(links.map((link) => String(link.referenceLabel || link.assetId).trim()));
+    return [...added, ...updated].every((label) => authoritativeLabels.has(label));
+}
+function canonicalLinks(taskId, links) {
+    try {
+        return serializeWorkspaceSyncV3TaskAttachmentLinksPayload({ taskId, links }).links;
+    }
+    catch (error) {
+        throw new LocalAuthoritativeTaskAttachmentLinksError(error instanceof Error ? error.message : 'Task attachment links are invalid.');
+    }
+}
+function canonicalTimestamp(value, label) {
+    const text = String(value || '');
+    const parsed = Date.parse(text);
+    if (!Number.isFinite(parsed) || new Date(parsed).toISOString() !== text) {
+        throw new LocalAuthoritativeTaskAttachmentLinksError(`${label} is invalid.`);
+    }
+    return text;
+}
+function requireRevision(value, label) {
+    const text = String(value || '').trim();
+    if (!/^(0|[1-9]\d*)$/.test(text))
+        throw new LocalAuthoritativeTaskAttachmentLinksError(`${label} is invalid.`);
+    return text;
+}
+export function enqueueLocalTaskAttachmentLinksMutation(input) {
+    const requestedLinks = canonicalLinks(input.taskId, input.links);
+    let attachments;
+    try {
+        attachments = input.core.resolveTaskAttachmentLinksForDurableSync(requestedLinks, input.identity.workspaceId, { requireDispatchReady: false });
+    }
+    catch (error) {
+        throw new LocalAuthoritativeTaskAttachmentLinksError(error instanceof Error ? error.message : 'Task attachment links are invalid.');
+    }
+    const links = canonicalLinks(input.taskId, projectResolvedTaskAttachmentLinksForDurableSync(attachments));
+    const activityEventId = buildTaskAttachmentLinksActivityEventId({
+        workspaceId: input.identity.workspaceId, clientId: input.identity.clientId,
+        operationId: input.identity.operationId, taskId: input.taskId,
+    });
+    const rootRevision = input.store.readEntityRevisionCoordinates({
+        tenantId: input.identity.tenantId, workspaceId: input.identity.workspaceId,
+        domain: 'task', entityId: input.taskId,
+    });
+    const result = input.store.enqueueLocalOperation({
+        identity: input.identity,
+        domain: 'task-attachment-links', entityId: input.taskId, mutationKind: 'replace',
+        revisionSource: 'current', payload: withOriginActorPayload({ links }, input.actorRef),
+        additionalTargets: [{
+                domain: 'task', entityId: input.taskId, mutationKind: 'metadata-update',
+                baseEntityRevision: rootRevision.entityRevision, baseLifecycleRevision: rootRevision.lifecycleRevision,
+                ownsTaskMetadata: true,
+            }],
+        queuedTaskSuccessor: true,
+        ...(input.requireV3CombinedOwnership ? { requireV3PlanningOwnership: 'combined' } : {}),
+        now: input.now,
+        applyLocalMutation: () => {
+            const existing = input.core.getTask(input.taskId, input.identity.workspaceId);
+            if (!existing)
+                throw new LocalAuthoritativeTaskAttachmentLinksError('Task not found.');
+            if (existing.isArchived)
+                throw new LocalAuthoritativeTaskAttachmentLinksError('Archived tasks are read-only.');
+            const previousLinks = input.core.listTaskAttachmentLinksForDurableSync(input.taskId, input.identity.workspaceId);
+            const currentMs = Date.parse(String(existing.updatedAt || existing.createdAt));
+            const requestedMs = Date.parse(input.now);
+            const updatedAt = Number.isFinite(currentMs) && currentMs >= requestedMs
+                ? new Date(currentMs + 1).toISOString() : input.now;
+            const task = input.core.updateTask(input.taskId, { attachments }, input.identity.workspaceId, {
+                persistBackup: false, emitRealtime: false, syncUpdatedAt: updatedAt,
+                actorRef: input.actorRef, taskEventId: activityEventId, taskEventAction: 'task-attachments-changed',
+                taskEventDetails: canonicalizeEntityActivityDetailsForSync({
+                    changes: { attachments: { from: previousLinks, to: links } },
+                }),
+                preferExplicitAttachmentRole: true,
+                preferExplicitAttachmentAssetId: true,
+                allowV3OwnedMetadataWrite: true,
+            });
+            if (!task)
+                throw new LocalAuthoritativeTaskAttachmentLinksError('Task not found.');
+            return task;
+        },
+    });
+    if (!result.enqueued)
+        return { enqueued: false };
+    try {
+        input.core.notifyDurableTaskMetadataCommitted(input.identity.workspaceId, input.taskId);
+    }
+    catch (error) {
+        try {
+            input.onPostCommitError?.(error);
+        }
+        catch { /* local mutation and outbox remain committed */ }
+    }
+    return { enqueued: true, task: result.mutationResult };
+}
+export function applyAuthoritativeTaskAttachmentLinksAndAck(input) {
+    if (!input.response || typeof input.response !== 'object' || Array.isArray(input.response)) {
+        throw new LocalAuthoritativeTaskAttachmentLinksError('Authoritative task attachment-link response must be an object.');
+    }
+    const response = input.response;
+    const root = response.authoritative?.root;
+    const attachmentLinks = response.authoritative?.attachmentLinks;
+    const activity = response.activity;
+    if (response.success !== true || response.contractVersion !== 3
+        || response.workspaceId !== input.identity.workspaceId
+        || response.clientId !== input.identity.clientId || response.operationId !== input.identity.operationId
+        || !root || !attachmentLinks || !activity
+        || root.domain !== 'task' || root.mutationKind !== 'metadata-update'
+        || attachmentLinks.domain !== 'task-attachment-links' || attachmentLinks.mutationKind !== 'replace'
+        || root.entityId !== attachmentLinks.entityId || root.payload.id !== root.entityId
+        || attachmentLinks.payload.taskId !== attachmentLinks.entityId
+        || activity.entityType !== 'task' || activity.entityId !== root.entityId || activity.taskId !== root.entityId
+        || activity.action !== 'task-attachments-changed') {
+        throw new LocalAuthoritativeTaskAttachmentLinksError('Authoritative task attachment-link response identity is invalid.');
+    }
+    const rootSequence = requireRevision(root.sequence, 'Authoritative root sequence');
+    const attachmentLinksSequence = requireRevision(attachmentLinks.sequence, 'Authoritative attachment-link sequence');
+    const activitySequence = requireRevision(response.activityRevision?.sequence, 'Authoritative activity sequence');
+    const operationHighWatermark = requireRevision(response.operationHighWatermark, 'Authoritative operation high watermark');
+    if (requireRevision(response.acceptedSequence, 'Authoritative accepted sequence') !== rootSequence
+        || BigInt(attachmentLinksSequence) !== BigInt(rootSequence) + 1n
+        || BigInt(activitySequence) !== BigInt(attachmentLinksSequence) + 1n
+        || activitySequence !== operationHighWatermark
+        || response.activityRevision.domain !== 'entity-event'
+        || response.activityRevision.entityId !== activity.id
+        || requireRevision(response.activityRevision.entityRevision, 'Authoritative activity entity revision') !== '1'
+        || requireRevision(response.activityRevision.lifecycleRevision, 'Authoritative activity lifecycle revision') !== '0') {
+        throw new LocalAuthoritativeTaskAttachmentLinksError('Authoritative task attachment-link operation ordering is invalid.');
+    }
+    const rootPayload = serializeTaskRootForSync(root.payload);
+    const attachmentLinksPayload = serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
+        taskId: attachmentLinks.entityId, links: attachmentLinks.payload.links,
+    });
+    const activityPayload = serializeTaskActivityForSync(activity);
+    const expectedActivityId = buildTaskAttachmentLinksActivityEventId({
+        workspaceId: input.identity.workspaceId, clientId: input.identity.clientId,
+        operationId: input.identity.operationId, taskId: root.entityId,
+    });
+    const validActivityDetails = validCompactedAttachmentActivity(activity.details, attachmentLinksPayload.links);
+    if (activity.id !== expectedActivityId
+        || activity.workspaceId !== input.identity.workspaceId
+        || !String(activity.actor || '').trim()
+        || !['human', 'ai', 'system'].includes(activity.actorType)
+        || canonicalTimestamp(activity.createdAt, 'Authoritative task attachment-link activity timestamp')
+            !== canonicalTimestamp(rootPayload.updatedAt, 'Authoritative task root timestamp')
+        || !validActivityDetails) {
+        throw new LocalAuthoritativeTaskAttachmentLinksError('Authoritative task attachment-link activity is invalid.');
+    }
+    const task = input.store.applyAuthoritativeAndAck({
+        identity: input.identity, leaseOwner: input.leaseOwner, now: input.now, response,
+        acceptedSequence: operationHighWatermark,
+        authoritative: [{
+                domain: 'task', entityId: root.entityId, mutationKind: 'metadata-update',
+                entityRevision: requireRevision(root.entityRevision, 'Authoritative root entity revision'),
+                lifecycleRevision: requireRevision(root.lifecycleRevision, 'Authoritative root lifecycle revision'),
+                sequence: rootSequence, canonicalFingerprint: fingerprintWorkspaceSyncPayload(rootPayload),
+            }, {
+                domain: 'task-attachment-links', entityId: attachmentLinks.entityId, mutationKind: 'replace',
+                entityRevision: requireRevision(attachmentLinks.entityRevision, 'Authoritative attachment-link entity revision'),
+                lifecycleRevision: requireRevision(attachmentLinks.lifecycleRevision, 'Authoritative attachment-link lifecycle revision'),
+                sequence: attachmentLinksSequence, canonicalFingerprint: fingerprintWorkspaceSyncPayload(attachmentLinksPayload),
+            }, {
+                domain: 'entity-event', entityId: activity.id, mutationKind: 'append',
+                entityRevision: requireRevision(response.activityRevision.entityRevision, 'Authoritative activity entity revision'),
+                lifecycleRevision: requireRevision(response.activityRevision.lifecycleRevision, 'Authoritative activity lifecycle revision'),
+                sequence: activitySequence, canonicalFingerprint: fingerprintWorkspaceSyncPayload(activityPayload),
+            }],
+        applyAuthoritative: () => {
+            const existing = input.core.getTask(root.entityId, input.identity.workspaceId);
+            if (!existing)
+                throw new LocalAuthoritativeTaskAttachmentLinksError('Authoritative task root does not exist locally.');
+            if (input.store.hasActiveOutboxSuccessor(input.identity)) {
+                input.core.upsertEntityEventForSync(activity, { allowAuthoritativeReplacement: true });
+                return existing;
+            }
+            let attachments;
+            try {
+                attachments = input.core.resolveTaskAttachmentLinksForDurableSync(attachmentLinksPayload.links, input.identity.workspaceId, { adoptAuthoritativeReferenceNumber: true });
+            }
+            catch (error) {
+                if (String(error?.code || '') === 'TASK_ATTACHMENT_ASSET_NOT_READY'
+                    || Number(error?.statusCode) === 425) {
+                    throw new LocalTaskAttachmentLinksDependencyPendingError(error instanceof Error ? error.message : 'Authoritative task attachment links are not ready locally.');
+                }
+                throw new LocalAuthoritativeTaskAttachmentLinksError(error instanceof Error ? error.message : 'Authoritative task attachment links are unavailable locally.');
+            }
+            const rootPatch = {
+                ...selectDurableTaskMetadataPatch(rootPayload),
+                status: rootPayload.status,
+                completedAt: rootPayload.completedAt,
+                canceledReason: rootPayload.canceledReason,
+                attachments,
+            };
+            const updated = input.core.updateTask(root.entityId, rootPatch, input.identity.workspaceId, {
+                persistBackup: false, emitRealtime: false, skipTaskEvents: true,
+                syncUpdatedAt: canonicalTimestamp(rootPayload.updatedAt, 'Authoritative task root timestamp'),
+                preferExplicitAttachmentRole: true,
+                preferExplicitAttachmentAssetId: true,
+                allowV3OwnedMetadataWrite: true,
+                allowV3OwnedLifecycleWrite: true,
+            });
+            if (!updated)
+                throw new LocalAuthoritativeTaskAttachmentLinksError('Authoritative task root disappeared locally.');
+            input.core.upsertEntityEventForSync(activity, { allowAuthoritativeReplacement: true });
+            const installedLinks = input.core.listTaskAttachmentLinksForDurableSync(updated.id, input.identity.workspaceId);
+            if (canonicalWorkspaceSyncJson(serializeTaskRootForSync(updated)) !== canonicalWorkspaceSyncJson(rootPayload)
+                || canonicalWorkspaceSyncJson(serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
+                    taskId: updated.id, links: installedLinks,
+                })) !== canonicalWorkspaceSyncJson(attachmentLinksPayload)) {
+                throw new LocalAuthoritativeTaskAttachmentLinksError('Installed task attachment-link state does not match authority.');
+            }
+            return updated;
+        },
+    });
+    try {
+        input.core.notifyDurableTaskMetadataCommitted(input.identity.workspaceId, root.entityId);
+    }
+    catch (error) {
+        try {
+            input.onPostCommitError?.(error);
+        }
+        catch { /* authoritative state and ack remain committed */ }
+    }
+    return task;
+}

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

@@ -0,0 +1,10 @@
+import { type LocalTaskChecklistOutboxCore } from './localTaskChecklistOutboxService.js';
+import type { LocalOutboxOperationHandler } from './localOutboxOperationHandler.js';
+import { WorkspaceSyncDurabilityStore, type WorkspaceSyncOutboxRecord } from './syncDurabilityStore.js';
+import type { WorkspaceSyncV3TaskChecklistEnvelope } from './workspaceSyncV3OperationProtocol.js';
+export declare function buildTaskChecklistEnvelope(record: WorkspaceSyncOutboxRecord): WorkspaceSyncV3TaskChecklistEnvelope;
+export declare function createLocalTaskChecklistOutboxHandler(input: {
+    store: WorkspaceSyncDurabilityStore;
+    core: LocalTaskChecklistOutboxCore;
+    onPostCommitError?: (error: unknown) => void;
+}): LocalOutboxOperationHandler;

package/dist/sync/v3/localTaskChecklistOutboxHandler.js

@@ -0,0 +1,54 @@
+import { EntityEventIdentityCollisionError } from '../../core/TaskActivityService.js';
+import { applyAuthoritativeTaskChecklistAndAck, LocalAuthoritativeTaskChecklistError, } from './localTaskChecklistOutboxService.js';
+import { fingerprintWorkspaceSyncPayload, WorkspaceSyncIdempotencyConflictError, WorkspaceSyncRevisionConflictError, } from './syncDurabilityStore.js';
+import { validateWorkspaceSyncV3TaskChecklistPayload } from './workspaceSyncV3NestedTaskCodecs.js';
+import { parseWorkspaceSyncV3OriginActor } from './workspaceSyncV3OriginActor.js';
+export function buildTaskChecklistEnvelope(record) {
+    let payload;
+    try {
+        payload = JSON.parse(record.payloadJson);
+    }
+    catch {
+        throw new Error('Local task checklist outbox payload is not valid JSON.');
+    }
+    if (fingerprintWorkspaceSyncPayload(payload) !== record.payloadFingerprint
+        || !payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        throw new Error('Local task checklist outbox payload is invalid.');
+    }
+    const source = payload;
+    if (!Object.prototype.hasOwnProperty.call(source, 'items')
+        || Object.keys(source).some((key) => key !== 'items' && key !== 'originActor')) {
+        throw new Error('Local task checklist outbox payload must contain items and optional originActor.');
+    }
+    const checklist = validateWorkspaceSyncV3TaskChecklistPayload({ taskId: record.entityId, items: source.items });
+    return {
+        contractVersion: 3,
+        workspaceId: record.workspaceId,
+        clientId: record.clientId,
+        operationId: record.operationId,
+        operation: {
+            domain: 'task-checklist', entityId: record.entityId, mutationKind: 'replace',
+            baseEntityRevision: record.baseEntityRevision, baseLifecycleRevision: '0',
+            payload: {
+                items: checklist.items,
+                ...(source.originActor !== undefined
+                    ? { originActor: parseWorkspaceSyncV3OriginActor(source.originActor) }
+                    : {}),
+            },
+        },
+    };
+}
+export function createLocalTaskChecklistOutboxHandler(input) {
+    return {
+        key: 'task-checklist/replace',
+        supports: (record) => record.domain === 'task-checklist' && record.mutationKind === 'replace',
+        buildEnvelope: buildTaskChecklistEnvelope,
+        applyAuthoritative: (applyInput) => applyAuthoritativeTaskChecklistAndAck({
+            store: input.store, core: input.core, ...applyInput, onPostCommitError: input.onPostCommitError,
+        }),
+        isPermanentApplyError: (error) => error instanceof LocalAuthoritativeTaskChecklistError
+            || error instanceof WorkspaceSyncIdempotencyConflictError
+            || error instanceof WorkspaceSyncRevisionConflictError
+            || error instanceof EntityEventIdentityCollisionError,
+    };
+}

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

@@ -0,0 +1,47 @@
+import type { ChecklistItem, TaskEvent, TaskItem } from '../../core/Taskforce.js';
+import { WorkspaceSyncDurabilityStore, type WorkspaceSyncOperationIdentity } from './syncDurabilityStore.js';
+export interface LocalTaskChecklistOutboxCore {
+    getTask(id: string, workspaceId?: string): TaskItem | null;
+    updateTask(id: string, updates: Partial<TaskItem>, workspaceId?: string, options?: {
+        persistBackup?: boolean;
+        emitRealtime?: boolean;
+        syncUpdatedAt?: string;
+        actorRef?: string;
+        skipTaskEvents?: boolean;
+        taskEventId?: string;
+        taskEventAction?: string;
+        allowV3OwnedMetadataWrite?: boolean;
+        allowV3OwnedLifecycleWrite?: boolean;
+    }): TaskItem | null;
+    upsertEntityEventForSync(event: TaskEvent, options?: {
+        allowAuthoritativeReplacement?: boolean;
+    }): unknown;
+    notifyDurableTaskMetadataCommitted(workspaceId: string, taskId: string): void;
+}
+export declare class LocalAuthoritativeTaskChecklistError extends Error {
+    readonly code = "WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID";
+    constructor(message: string);
+}
+export declare function enqueueLocalTaskChecklistMutation(input: {
+    store: WorkspaceSyncDurabilityStore;
+    core: LocalTaskChecklistOutboxCore;
+    identity: WorkspaceSyncOperationIdentity;
+    taskId: string;
+    items: readonly Partial<ChecklistItem>[];
+    now: string;
+    actorRef: string;
+    requireV3CombinedOwnership?: boolean;
+    onPostCommitError?: (error: unknown) => void;
+}): {
+    enqueued: boolean;
+    task?: TaskItem;
+};
+export declare function applyAuthoritativeTaskChecklistAndAck(input: {
+    store: WorkspaceSyncDurabilityStore;
+    core: LocalTaskChecklistOutboxCore;
+    identity: WorkspaceSyncOperationIdentity;
+    leaseOwner: string;
+    response: unknown;
+    now: string;
+    onPostCommitError?: (error: unknown) => void;
+}): TaskItem;