@taskforcehq/taskforce 0.3.324 → 0.3.327

package/dist/sync/v3/localWorkstreamOutboxService.js

@@ -0,0 +1,579 @@
+import { applyWorkstreamCommentForDurableSync, applyWorkstreamCreateForDurableSync, applyWorkstreamLifecycleForDurableSync, applyWorkstreamMetadataForDurableSync, DurableWorkstreamApplyError, resolveWorkstreamAttachmentsForDurableSync, } from '../../core/WorkstreamDurableMutationService.js';
+import { serializeInitiativeForSync, serializeWorkstreamForSync } from '../planningSyncPayload.js';
+import { findPlanningAttachmentMetadataMismatch, validateCanonicalPlanningAttachmentLinks, } from '../planningCanonicalFields.js';
+import { buildWorkstreamActivityEventId } from './workstreamActivityIdentity.js';
+import { validateWorkstreamActivityAuthoritativeRevision } from './workstreamActivityAuthoritativeRevision.js';
+import { validateDurableWorkstreamComment, validateDurableWorkstreamCommentPayload, validateDurableWorkstreamCreatePayload, validateDurableWorkstreamMetadataPatch, validateDurableWorkstreamMetadataPayload, validateEmptyWorkstreamPayload, } from './workstreamMutationPayload.js';
+import { serializeEntityActivityForSync, WORKSPACE_SYNC_ENTITY_EVENT_APPEND, WORKSPACE_SYNC_ENTITY_EVENT_DOMAIN, } from './taskActivityJournal.js';
+import { fingerprintWorkspaceSyncPayload, } from './syncDurabilityStore.js';
+import { normalizePlanningActivityDetailsForComparison, validateCompactedPlanningAttachmentActivity, } from './planningAttachmentActivityValidation.js';
+import { withOriginActorPayload } from './workspaceSyncV3OriginActor.js';
+export class LocalAuthoritativeWorkstreamError extends Error {
+    code;
+    constructor(message, code = 'WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID') {
+        super(message);
+        this.code = code;
+        this.name = 'LocalAuthoritativeWorkstreamError';
+    }
+}
+export function normalizeLocalWorkstreamOperation(operation) {
+    if (operation.mutationKind === 'create') {
+        return { ...operation, payload: validateDurableWorkstreamCreatePayload(operation.payload) };
+    }
+    if (operation.mutationKind === 'metadata-update') {
+        return { ...operation, payload: validateDurableWorkstreamMetadataPayload(operation.payload) };
+    }
+    if (operation.mutationKind === 'append-comment') {
+        return {
+            ...operation,
+            payload: {
+                ...validateDurableWorkstreamCommentPayload(operation.payload),
+                ...(operation.payload.originActor ? { originActor: operation.payload.originActor } : {}),
+            },
+        };
+    }
+    return {
+        ...operation,
+        payload: validateEmptyWorkstreamPayload(operation.payload, `Workstream ${operation.mutationKind} payload`),
+    };
+}
+function applyLocalMutation(input) {
+    const common = {
+        core: input.core,
+        workspaceId: input.identity.workspaceId,
+        workstreamId: input.operation.entityId,
+        updatedAt: input.now,
+        actorRef: input.actorRef,
+        entityEventId: input.activityEventId,
+    };
+    if (input.operation.mutationKind === 'create') {
+        return applyWorkstreamCreateForDurableSync({
+            ...common,
+            payload: input.operation.payload,
+            provisional: true,
+        });
+    }
+    if (input.operation.mutationKind === 'metadata-update') {
+        return applyWorkstreamMetadataForDurableSync({ ...common, patch: input.operation.payload.patch });
+    }
+    if (input.operation.mutationKind === 'append-comment') {
+        return applyWorkstreamCommentForDurableSync({ ...common, comment: input.operation.payload.comment });
+    }
+    return applyWorkstreamLifecycleForDurableSync({ ...common, mutationKind: input.operation.mutationKind });
+}
+export function enqueueLocalWorkstreamMutation(input) {
+    let operation = normalizeLocalWorkstreamOperation(input.operation);
+    if (operation.mutationKind === 'create') {
+        operation = {
+            ...operation,
+            payload: {
+                ...operation.payload,
+                attachments: resolveWorkstreamAttachmentsForDurableSync(input.core, input.identity.workspaceId, operation.entityId, operation.payload.attachments) || [],
+            },
+        };
+    }
+    else if (operation.mutationKind === 'metadata-update' && operation.payload.patch.attachments) {
+        operation = {
+            ...operation,
+            payload: {
+                patch: {
+                    ...operation.payload.patch,
+                    attachments: resolveWorkstreamAttachmentsForDurableSync(input.core, input.identity.workspaceId, operation.entityId, operation.payload.patch.attachments) || [],
+                },
+            },
+        };
+    }
+    else if (operation.mutationKind === 'append-comment') {
+        operation = {
+            ...operation,
+            payload: withOriginActorPayload(operation.payload, input.actorRef),
+        };
+    }
+    const activityEventId = buildWorkstreamActivityEventId({
+        workspaceId: input.identity.workspaceId,
+        clientId: input.identity.clientId,
+        operationId: input.identity.operationId,
+        workstreamId: operation.entityId,
+        mutationKind: operation.mutationKind,
+    });
+    const result = input.store.enqueueLocalOperation({
+        identity: input.identity,
+        domain: 'workstream',
+        entityId: operation.entityId,
+        mutationKind: operation.mutationKind,
+        revisionSource: operation.mutationKind === 'create' ? 'explicit' : 'current',
+        baseEntityRevision: operation.mutationKind === 'create' ? '0' : operation.baseEntityRevision,
+        baseLifecycleRevision: operation.mutationKind === 'create' ? '0' : operation.baseLifecycleRevision,
+        payload: operation.payload,
+        ...(operation.mutationKind === 'metadata-update'
+            ? { queuedMetadataSuccessorDomain: 'workstream' }
+            : {}),
+        now: input.now,
+        applyLocalMutation: () => applyLocalMutation({
+            core: input.core,
+            identity: input.identity,
+            operation,
+            now: input.now,
+            actorRef: input.actorRef,
+            activityEventId,
+        }),
+        ...(input.requireV3PlanningOwnership ? { requireV3PlanningOwnership: 'workstream' } : {}),
+    });
+    if (!result.enqueued)
+        return { enqueued: false };
+    try {
+        input.core.notifyDurableWorkstreamCommitted(input.identity.workspaceId, operation.entityId);
+    }
+    catch (error) {
+        try {
+            input.onPostCommitError?.(error);
+        }
+        catch { /* mutation and outbox remain committed */ }
+    }
+    return { enqueued: true, workstream: result.mutationResult };
+}
+function assertExactKeys(value, expected, label) {
+    const actual = Object.keys(value).sort();
+    const keys = [...expected].sort();
+    if (actual.length !== keys.length || actual.some((key, index) => key !== keys[index])) {
+        throw new LocalAuthoritativeWorkstreamError(`${label} has missing or unsupported fields.`);
+    }
+}
+function attachmentLinkSemantics(value) {
+    try {
+        return validateCanonicalPlanningAttachmentLinks(value).map((attachment) => {
+            const { referenceNumber: _referenceNumber, referenceLabel: _referenceLabel, ...semantic } = attachment;
+            return semantic;
+        });
+    }
+    catch {
+        throw new LocalAuthoritativeWorkstreamError('Workstream attachment link semantics are invalid.', 'WORKSPACE_SYNC_PLANNING_ATTACHMENT_LINK_INVALID');
+    }
+}
+function isCanonicalIso(value) {
+    if (typeof value !== 'string')
+        return false;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
+}
+function validateMutationSemantics(input) {
+    if (input.record.mutationKind === 'create') {
+        const requested = validateDurableWorkstreamCreatePayload(input.payload);
+        const comparable = {
+            initiativeId: input.authoritative.initiativeId,
+            title: input.authoritative.title,
+            description: input.authoritative.description,
+            ownerId: input.authoritative.ownerId,
+            order: input.authoritative.order,
+            attachments: attachmentLinkSemantics(input.authoritative.attachments),
+            createdAt: input.authoritative.createdAt,
+        };
+        const expected = { ...requested, attachments: attachmentLinkSemantics(requested.attachments) };
+        if (fingerprintWorkspaceSyncPayload(comparable) !== fingerprintWorkspaceSyncPayload(expected)) {
+            throw new LocalAuthoritativeWorkstreamError('Authoritative workstream create body does not match the captured operation.');
+        }
+    }
+    else if (input.record.mutationKind === 'metadata-update') {
+        assertExactKeys(input.payload, ['patch'], 'Captured workstream metadata payload');
+        const patch = validateDurableWorkstreamMetadataPatch(input.payload.patch);
+        for (const [key, value] of Object.entries(patch)) {
+            const actualValue = key === 'attachments'
+                ? attachmentLinkSemantics(input.authoritative[key])
+                : input.authoritative[key];
+            const expectedValue = key === 'attachments' ? attachmentLinkSemantics(value) : value;
+            if (fingerprintWorkspaceSyncPayload(actualValue) !== fingerprintWorkspaceSyncPayload(expectedValue)) {
+                throw new LocalAuthoritativeWorkstreamError('Authoritative workstream metadata does not match the captured patch.');
+            }
+        }
+    }
+    else if (input.record.mutationKind === 'append-comment') {
+        assertExactKeys(input.payload, input.payload.originActor === undefined ? ['comment'] : ['comment', 'originActor'], 'Captured workstream comment payload');
+        const comment = validateDurableWorkstreamComment(input.payload.comment);
+        const installed = input.authoritative.comments?.find((candidate) => candidate.id === comment.id);
+        const expectedComment = {
+            ...comment,
+            ...(comment.author === 'user' && installed ? { author: installed.author } : {}),
+            submittedAuthor: comment.submittedAuthor
+                || (comment.author === 'user' && installed ? installed.author : comment.author),
+        };
+        if (!installed || !installed.author
+            || fingerprintWorkspaceSyncPayload(installed) !== fingerprintWorkspaceSyncPayload(expectedComment)) {
+            throw new LocalAuthoritativeWorkstreamError('Authoritative workstream comment does not match the captured operation.');
+        }
+    }
+    else {
+        validateEmptyWorkstreamPayload(input.payload, 'Captured workstream lifecycle payload');
+        if (input.authoritative.isArchived !== (input.record.mutationKind === 'archive')) {
+            throw new LocalAuthoritativeWorkstreamError('Authoritative workstream lifecycle does not match the captured operation.');
+        }
+    }
+}
+function validateActivitySemantics(input) {
+    const details = input.activity.details;
+    if (input.record.mutationKind === 'create') {
+        if (!details)
+            throw new LocalAuthoritativeWorkstreamError('Workstream create activity details are missing.');
+        assertExactKeys(details, ['title', 'ownerId', 'initiativeId'], 'Workstream create activity details');
+        if (details.title !== input.authoritative.title
+            || (details.ownerId ?? null) !== input.authoritative.ownerId
+            || (details.initiativeId ?? null) !== input.authoritative.initiativeId) {
+            throw new LocalAuthoritativeWorkstreamError('Workstream create activity details do not match authority.');
+        }
+    }
+    else if (input.record.mutationKind === 'metadata-update') {
+        const patch = validateDurableWorkstreamMetadataPatch(input.payload.patch);
+        const changes = details?.changes;
+        if (!details || Object.keys(details).length !== 1 || !changes || typeof changes !== 'object' || Array.isArray(changes)) {
+            throw new LocalAuthoritativeWorkstreamError('Workstream metadata activity changes are invalid.');
+        }
+        const changeRecord = changes;
+        const patchKeys = Object.keys(patch).sort();
+        const changeKeys = Object.keys(changeRecord).sort();
+        if (changeKeys.some((key) => !patchKeys.includes(key))) {
+            throw new LocalAuthoritativeWorkstreamError('Workstream metadata activity fields do not match the captured patch.');
+        }
+        for (const key of changeKeys) {
+            const change = changeRecord[key];
+            if (key === 'attachments') {
+                let links;
+                try {
+                    links = validateCanonicalPlanningAttachmentLinks(input.authoritative.attachments);
+                }
+                catch {
+                    throw new LocalAuthoritativeWorkstreamError('Authoritative workstream attachments are invalid.', 'WORKSPACE_SYNC_PLANNING_ATTACHMENT_LINK_INVALID');
+                }
+                validateCompactedPlanningAttachmentActivity({
+                    change,
+                    authoritativeLinks: links,
+                    invalid: (message) => new LocalAuthoritativeWorkstreamError(message, 'WORKSPACE_SYNC_PLANNING_ATTACHMENT_ACTIVITY_INVALID'),
+                });
+                continue;
+            }
+            const changeTo = change && typeof change === 'object' && !Array.isArray(change)
+                ? change.to
+                : undefined;
+            const expectedTo = input.authoritative[key];
+            if (!change || typeof change !== 'object' || Array.isArray(change)
+                || fingerprintWorkspaceSyncPayload(changeTo) !== fingerprintWorkspaceSyncPayload(expectedTo)) {
+                throw new LocalAuthoritativeWorkstreamError('Workstream metadata activity values do not match authority.');
+            }
+        }
+    }
+    else if (input.record.mutationKind === 'append-comment') {
+        const comment = validateDurableWorkstreamComment(input.payload.comment);
+        if (!details)
+            throw new LocalAuthoritativeWorkstreamError('Workstream comment activity details are missing.');
+        assertExactKeys(details, ['commentId', 'submittedAuthor', 'preview'], 'Workstream comment activity details');
+        if (details.commentId !== comment.id
+            || details.submittedAuthor !== (comment.submittedAuthor
+                || (comment.author === 'user'
+                    ? input.authoritative.comments?.find((candidate) => candidate.id === comment.id)?.author
+                    : comment.author))
+            || details.preview !== comment.text.slice(0, 160)
+            || (comment.author === 'user'
+                ? input.activity.actor !== input.authoritative.comments?.find((candidate) => candidate.id === comment.id)?.author
+                : input.activity.actor !== comment.author)) {
+            throw new LocalAuthoritativeWorkstreamError('Workstream comment activity does not match the captured comment.');
+        }
+    }
+    else if (details !== undefined && Object.keys(details).length > 0) {
+        throw new LocalAuthoritativeWorkstreamError('Workstream lifecycle activity must not contain details.');
+    }
+    if (input.record.mutationKind !== 'append-comment' && input.activity.createdAt !== input.authoritative.updatedAt) {
+        throw new LocalAuthoritativeWorkstreamError('Workstream activity timestamp does not match authoritative state.');
+    }
+    const provisional = input.core.getEntityEventForSync({
+        workspaceId: input.record.workspaceId,
+        eventId: input.activity.id,
+    });
+    if (!provisional)
+        throw new LocalAuthoritativeWorkstreamError('Provisional workstream activity is missing.');
+    if (input.activity.action !== provisional.action) {
+        throw new LocalAuthoritativeWorkstreamError('Authoritative workstream activity action differs from the captured mutation.');
+    }
+    const expectedDetails = JSON.parse(JSON.stringify(provisional.details || {}));
+    if (input.record.mutationKind === 'append-comment') {
+        const comment = validateDurableWorkstreamComment(input.payload.comment);
+        expectedDetails.submittedAuthor = comment.submittedAuthor
+            || (comment.author === 'user' ? input.activity.actor : comment.author);
+    }
+    const authoritativeAttachmentLinks = validateCanonicalPlanningAttachmentLinks(input.authoritative.attachments);
+    const comparableExpectedDetails = normalizePlanningActivityDetailsForComparison(expectedDetails, input.record.mutationKind, authoritativeAttachmentLinks);
+    const comparableAuthoritativeDetails = normalizePlanningActivityDetailsForComparison((input.activity.details || {}), input.record.mutationKind, authoritativeAttachmentLinks);
+    if (fingerprintWorkspaceSyncPayload(comparableExpectedDetails)
+        !== fingerprintWorkspaceSyncPayload(comparableAuthoritativeDetails)) {
+        throw new LocalAuthoritativeWorkstreamError('Authoritative workstream activity details differ from the captured mutation.');
+    }
+}
+function validateWholeAuthoritativeBody(input) {
+    const local = input.core.getWorkstream(input.record.entityId, input.workspaceId);
+    if (!local)
+        throw new LocalAuthoritativeWorkstreamError('Captured local workstream is missing.');
+    const expected = JSON.parse(JSON.stringify(serializeWorkstreamForSync(local)));
+    expected.updatedAt = input.authoritative.updatedAt;
+    if (input.record.mutationKind === 'create') {
+        expected.referenceNumber = input.authoritative.referenceNumber;
+        expected.referenceLabel = input.authoritative.referenceLabel;
+    }
+    expected.attachments = input.authoritative.attachments;
+    for (const field of input.successorOwnedFields) {
+        expected[field] = input.authoritative[field];
+    }
+    if (input.record.mutationKind === 'append-comment') {
+        const comment = validateDurableWorkstreamComment(input.payload.comment);
+        if (comment.author === 'user') {
+            const authoritativeComment = input.authoritative.comments?.find((candidate) => candidate.id === comment.id);
+            const expectedComments = expected.comments;
+            const expectedComment = expectedComments?.find((candidate) => candidate.id === comment.id);
+            if (!authoritativeComment || !expectedComment) {
+                throw new LocalAuthoritativeWorkstreamError('Authoritative bound comment is missing.');
+            }
+            expectedComment.author = authoritativeComment.author;
+            expectedComment.submittedAuthor = comment.submittedAuthor || authoritativeComment.author;
+        }
+    }
+    if (fingerprintWorkspaceSyncPayload(expected) !== fingerprintWorkspaceSyncPayload(input.authoritative)) {
+        throw new LocalAuthoritativeWorkstreamError('Authoritative workstream body rewrites state outside the captured mutation.');
+    }
+}
+function isBoundedAttachmentRebase(record, payload) {
+    if (record.mutationKind !== 'metadata-update' || record.workstreamMetadataRevisionRebaseCount !== 1) {
+        return false;
+    }
+    assertExactKeys(payload, ['patch'], 'Captured workstream metadata payload');
+    const patch = validateDurableWorkstreamMetadataPatch(payload.patch);
+    return Object.keys(patch).length === 1 && Object.prototype.hasOwnProperty.call(patch, 'attachments');
+}
+function readSuccessorOwnedMetadataFields(input) {
+    const fields = new Set();
+    for (const successor of input.store.listActiveOutboxSuccessors(input.identity)) {
+        if (successor.domain !== 'workstream'
+            || successor.entityId !== input.entityId
+            || successor.mutationKind !== 'metadata-update') {
+            throw new LocalAuthoritativeWorkstreamError('Active workstream successor is not a metadata update.');
+        }
+        let payload;
+        try {
+            payload = JSON.parse(successor.payloadJson);
+        }
+        catch {
+            throw new LocalAuthoritativeWorkstreamError('Captured workstream successor payload is not valid JSON.');
+        }
+        if (fingerprintWorkspaceSyncPayload(payload) !== successor.payloadFingerprint
+            || !payload || typeof payload !== 'object' || Array.isArray(payload)) {
+            throw new LocalAuthoritativeWorkstreamError('Captured workstream successor payload fingerprint is invalid.');
+        }
+        assertExactKeys(payload, ['patch'], 'Captured workstream successor payload');
+        for (const field of Object.keys(validateDurableWorkstreamMetadataPatch(payload.patch)))
+            fields.add(field);
+    }
+    return fields;
+}
+export function applyAuthoritativeWorkstreamAndAck(input) {
+    if (!input.response || typeof input.response !== 'object' || Array.isArray(input.response)) {
+        throw new LocalAuthoritativeWorkstreamError('Authoritative workstream response must be an object.');
+    }
+    const response = input.response;
+    const authoritative = response.authoritative;
+    const activity = response.activity;
+    if (!authoritative || typeof authoritative !== 'object'
+        || !activity || typeof activity !== 'object'
+        || !response.activityRevision || typeof response.activityRevision !== 'object') {
+        throw new LocalAuthoritativeWorkstreamError('Authoritative workstream response is incomplete.');
+    }
+    const responseRecord = response;
+    assertExactKeys(responseRecord, [
+        'success', 'contractVersion', 'workspaceId', 'clientId', 'operationId', 'acceptedSequence',
+        'operationHighWatermark', 'authoritative', 'dependencies', 'activity', 'activityRevision',
+    ], 'Authoritative workstream response');
+    assertExactKeys(authoritative, [
+        'domain', 'entityId', 'mutationKind', 'sequence', 'entityRevision', 'lifecycleRevision', 'payload',
+    ], 'Authoritative workstream record');
+    assertExactKeys(activity, [
+        'id', 'workspaceId', 'entityType', 'entityId', 'action', 'actor', 'actorType', 'details', 'createdAt',
+    ], 'Authoritative workstream activity');
+    assertExactKeys(response.activityRevision, [
+        'domain', 'entityId', 'sequence', 'entityRevision', 'lifecycleRevision',
+    ], 'Authoritative workstream activity revision');
+    const workstream = authoritative.payload;
+    if (!Array.isArray(response.dependencies) || response.dependencies.length > 1) {
+        throw new LocalAuthoritativeWorkstreamError('Authoritative workstream dependencies are invalid.');
+    }
+    const dependency = response.dependencies[0];
+    if (dependency) {
+        assertExactKeys(dependency, [
+            'domain', 'entityId', 'sequence', 'entityRevision', 'lifecycleRevision',
+            'canonicalFingerprint', 'payload',
+        ], 'Authoritative workstream dependency');
+        if (dependency.domain !== 'initiative'
+            || dependency.entityId !== dependency.payload?.id
+            || typeof dependency.sequence !== 'string' || !/^[1-9]\d*$/.test(dependency.sequence)
+            || typeof dependency.entityRevision !== 'string' || !/^[1-9]\d*$/.test(dependency.entityRevision)
+            || typeof dependency.lifecycleRevision !== 'string' || !/^\d+$/.test(dependency.lifecycleRevision)
+            || typeof dependency.canonicalFingerprint !== 'string'
+            || !/^[a-f0-9]{64}$/.test(dependency.canonicalFingerprint)
+            || fingerprintWorkspaceSyncPayload(dependency.payload) !== dependency.canonicalFingerprint
+            || fingerprintWorkspaceSyncPayload(serializeInitiativeForSync(dependency.payload))
+                !== dependency.canonicalFingerprint) {
+            throw new LocalAuthoritativeWorkstreamError('Authoritative workstream dependency is invalid.');
+        }
+    }
+    const expectedActivityId = buildWorkstreamActivityEventId({
+        workspaceId: input.identity.workspaceId,
+        clientId: input.identity.clientId,
+        operationId: input.identity.operationId,
+        workstreamId: input.record.entityId,
+        mutationKind: input.record.mutationKind,
+    });
+    if (response.success !== true || response.contractVersion !== 3
+        || response.workspaceId !== input.identity.workspaceId
+        || response.clientId !== input.identity.clientId
+        || response.operationId !== input.identity.operationId
+        || authoritative.domain !== 'workstream'
+        || authoritative.entityId !== input.record.entityId
+        || authoritative.mutationKind !== input.record.mutationKind
+        || typeof authoritative.entityRevision !== 'string' || !/^[1-9]\d*$/.test(authoritative.entityRevision)
+        || typeof authoritative.lifecycleRevision !== 'string' || !/^\d+$/.test(authoritative.lifecycleRevision)
+        || !workstream || workstream.id !== input.record.entityId || !workstream.referenceNumber
+        || activity.id !== expectedActivityId || activity.workspaceId !== input.identity.workspaceId
+        || activity.entityType !== 'workstream' || activity.entityId !== input.record.entityId
+        || !(input.record.mutationKind === 'metadata-update'
+            ? ['workstream-updated', 'workstream-attachments-changed', 'workstream-relationship-changed'].includes(activity.action)
+            : activity.action === `workstream-${input.record.mutationKind === 'append-comment' ? 'comment-added' : input.record.mutationKind === 'create' ? 'created' : input.record.mutationKind === 'archive' ? 'archived' : 'unarchived'}`)
+        || typeof activity.actor !== 'string' || !activity.actor.trim()
+        || !['human', 'ai', 'system'].includes(activity.actorType)
+        || !isCanonicalIso(activity.createdAt)) {
+        throw new LocalAuthoritativeWorkstreamError('Authoritative workstream identity or activity is invalid.');
+    }
+    let payload;
+    try {
+        payload = JSON.parse(input.record.payloadJson);
+    }
+    catch {
+        throw new LocalAuthoritativeWorkstreamError('Captured workstream payload is not valid JSON.');
+    }
+    if (fingerprintWorkspaceSyncPayload(payload) !== input.record.payloadFingerprint || !payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        throw new LocalAuthoritativeWorkstreamError('Captured workstream payload fingerprint is invalid.');
+    }
+    const boundedAttachmentRebase = isBoundedAttachmentRebase(input.record, payload);
+    const expectedEntityRevision = (BigInt(input.record.baseEntityRevision) + 1n).toString();
+    const expectedLifecycleRevision = (BigInt(input.record.baseLifecycleRevision)
+        + (input.record.mutationKind === 'archive' || input.record.mutationKind === 'unarchive' ? 1n : 0n)).toString();
+    if ((boundedAttachmentRebase
+        ? BigInt(authoritative.entityRevision) <= BigInt(input.record.baseEntityRevision)
+            || BigInt(authoritative.lifecycleRevision) < BigInt(input.record.baseLifecycleRevision)
+        : authoritative.entityRevision !== expectedEntityRevision
+            || authoritative.lifecycleRevision !== expectedLifecycleRevision)) {
+        throw new LocalAuthoritativeWorkstreamError('Authoritative workstream revisions do not advance the captured bases exactly once.');
+    }
+    const successorOwnedFields = readSuccessorOwnedMetadataFields({
+        store: input.store,
+        identity: input.identity,
+        entityId: input.record.entityId,
+    });
+    validateMutationSemantics({ record: input.record, payload: payload, authoritative: workstream });
+    if (!boundedAttachmentRebase) {
+        validateWholeAuthoritativeBody({
+            core: input.core,
+            workspaceId: input.identity.workspaceId,
+            record: input.record,
+            payload: payload,
+            authoritative: workstream,
+            successorOwnedFields,
+        });
+    }
+    let authoritativeAttachments;
+    try {
+        authoritativeAttachments = validateCanonicalPlanningAttachmentLinks(workstream.attachments);
+    }
+    catch {
+        throw new LocalAuthoritativeWorkstreamError('Authoritative workstream attachments are invalid.');
+    }
+    const locallyCanonicalAttachments = resolveWorkstreamAttachmentsForDurableSync(input.core, input.identity.workspaceId, workstream.id, authoritativeAttachments) || [];
+    const dependencyAssetId = findPlanningAttachmentMetadataMismatch(authoritativeAttachments, locallyCanonicalAttachments);
+    if (dependencyAssetId) {
+        throw new DurableWorkstreamApplyError('Authoritative workstream attachments are waiting for matching local asset metadata.', 'WORKSTREAM_ATTACHMENT_NOT_READY', 425, dependencyAssetId);
+    }
+    validateActivitySemantics({
+        core: input.core,
+        record: input.record,
+        payload: payload,
+        authoritative: workstream,
+        activity,
+    });
+    const revision = validateWorkstreamActivityAuthoritativeRevision({
+        response: response,
+        authoritative: authoritative,
+        activityId: expectedActivityId,
+        invalid: (message) => new LocalAuthoritativeWorkstreamError(message),
+    });
+    const canonicalFingerprint = fingerprintWorkspaceSyncPayload(workstream);
+    const missingInitiativeId = workstream.initiativeId
+        && !input.core.getInitiative(workstream.initiativeId, input.identity.workspaceId)
+        ? workstream.initiativeId
+        : null;
+    if (missingInitiativeId && dependency?.entityId !== missingInitiativeId) {
+        throw new LocalAuthoritativeWorkstreamError('Authoritative workstream initiative dependency is missing.');
+    }
+    const authoritativeRecords = [{
+            domain: 'workstream', entityId: workstream.id, mutationKind: authoritative.mutationKind,
+            entityRevision: authoritative.entityRevision, lifecycleRevision: authoritative.lifecycleRevision,
+            sequence: revision.workstreamSequence, canonicalFingerprint,
+        }, {
+            domain: WORKSPACE_SYNC_ENTITY_EVENT_DOMAIN, entityId: activity.id,
+            mutationKind: WORKSPACE_SYNC_ENTITY_EVENT_APPEND,
+            entityRevision: revision.activityRevision.entityRevision,
+            lifecycleRevision: revision.activityRevision.lifecycleRevision,
+            sequence: revision.activityRevision.sequence,
+            canonicalFingerprint: fingerprintWorkspaceSyncPayload(serializeEntityActivityForSync(activity)),
+        }];
+    const installed = input.store.applyAuthoritativeAndAck({
+        identity: input.identity,
+        leaseOwner: input.leaseOwner,
+        now: input.now,
+        response,
+        acceptedSequence: revision.operationHighWatermark,
+        authoritative: authoritativeRecords,
+        applyAuthoritative: () => {
+            if (missingInitiativeId && dependency) {
+                const installedInitiative = input.core.installDurableInitiativeAuthoritativeForSync(dependency.payload, input.identity.workspaceId);
+                if (fingerprintWorkspaceSyncPayload(serializeInitiativeForSync(installedInitiative))
+                    !== fingerprintWorkspaceSyncPayload(dependency.payload)) {
+                    throw new LocalAuthoritativeWorkstreamError('Installed workstream initiative dependency does not match its authoritative fingerprint.');
+                }
+            }
+            input.core.upsertEntityEventForSync(activity, { allowAuthoritativeReplacement: true });
+            const installedActivity = input.core.getEntityEventForSync({
+                workspaceId: input.identity.workspaceId,
+                eventId: activity.id,
+            });
+            if (!installedActivity
+                || fingerprintWorkspaceSyncPayload(serializeEntityActivityForSync(installedActivity))
+                    !== fingerprintWorkspaceSyncPayload(serializeEntityActivityForSync(activity))) {
+                throw new LocalAuthoritativeWorkstreamError('Installed workstream activity does not match its authoritative fingerprint.');
+            }
+            if (input.store.hasActiveOutboxSuccessor(input.identity)) {
+                const provisional = input.core.getWorkstream(workstream.id, input.identity.workspaceId);
+                if (!provisional)
+                    throw new LocalAuthoritativeWorkstreamError('Captured local workstream is missing.');
+                return provisional;
+            }
+            const updated = input.core.installDurableWorkstreamAuthoritativeForSync(workstream, input.identity.workspaceId);
+            if (fingerprintWorkspaceSyncPayload(serializeWorkstreamForSync(updated)) !== canonicalFingerprint) {
+                throw new LocalAuthoritativeWorkstreamError('Installed workstream does not match the authoritative payload.');
+            }
+            return updated;
+        },
+    });
+    try {
+        input.core.notifyDurableWorkstreamCommitted(input.identity.workspaceId, workstream.id);
+    }
+    catch (error) {
+        try {
+            input.onPostCommitError?.(error);
+        }
+        catch { /* authoritative apply remains committed */ }
+    }
+    return installed;
+}
+export { DurableWorkstreamApplyError };

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

@@ -0,0 +1,10 @@
+import { applyAuthoritativeWorkstreamTaskOrderAndAck, type LocalWorkstreamTaskOrderOutboxCore } from './localWorkstreamTaskOrderOutboxService.js';
+import type { LocalOutboxOperationHandler } from './localOutboxOperationHandler.js';
+import { type WorkspaceSyncOutboxRecord } from './syncDurabilityStore.js';
+import type { WorkspaceSyncV3WorkstreamTaskOrderEnvelope } from './workspaceSyncV3OperationProtocol.js';
+export declare function buildWorkstreamTaskOrderEnvelope(record: WorkspaceSyncOutboxRecord): WorkspaceSyncV3WorkstreamTaskOrderEnvelope;
+export declare function createLocalWorkstreamTaskOrderOutboxHandler(input: {
+    store: Parameters<typeof applyAuthoritativeWorkstreamTaskOrderAndAck>[0]['store'];
+    core: LocalWorkstreamTaskOrderOutboxCore;
+    onPostCommitError?: (error: unknown) => void;
+}): LocalOutboxOperationHandler;

package/dist/sync/v3/localWorkstreamTaskOrderOutboxHandler.js

@@ -0,0 +1,57 @@
+import { applyAuthoritativeWorkstreamTaskOrderAndAck, LocalAuthoritativeWorkstreamTaskOrderError, } from './localWorkstreamTaskOrderOutboxService.js';
+import { fingerprintWorkspaceSyncPayload, WorkspaceSyncIdempotencyConflictError, WorkspaceSyncRevisionConflictError, } from './syncDurabilityStore.js';
+export function buildWorkstreamTaskOrderEnvelope(record) {
+    let payload;
+    try {
+        payload = JSON.parse(record.payloadJson);
+    }
+    catch {
+        throw new Error('Local workstream task order outbox payload is not valid JSON.');
+    }
+    if (fingerprintWorkspaceSyncPayload(payload) !== record.payloadFingerprint
+        || !payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        throw new Error('Local workstream task order outbox payload is invalid.');
+    }
+    const source = payload;
+    if (!Array.isArray(source.taskIds) || Object.keys(source).some((key) => key !== 'taskIds')) {
+        throw new Error('Local workstream task order outbox payload must contain taskIds.');
+    }
+    const taskIds = source.taskIds.map((taskId) => String(taskId || '').trim());
+    if (taskIds.some((taskId) => !taskId) || new Set(taskIds).size !== taskIds.length) {
+        throw new Error('Local workstream task order outbox payload contains invalid task ids.');
+    }
+    return {
+        contractVersion: 3,
+        workspaceId: record.workspaceId,
+        clientId: record.clientId,
+        operationId: record.operationId,
+        operation: {
+            domain: 'workstream-task-order',
+            entityId: record.entityId,
+            mutationKind: 'replace',
+            baseEntityRevision: record.baseEntityRevision,
+            baseLifecycleRevision: '0',
+            payload: { taskIds },
+        },
+    };
+}
+export function createLocalWorkstreamTaskOrderOutboxHandler(input) {
+    return {
+        key: 'workstream-task-order/replace',
+        supports: (record) => record.domain === 'workstream-task-order' && record.mutationKind === 'replace',
+        buildEnvelope: buildWorkstreamTaskOrderEnvelope,
+        applyAuthoritative: (applyInput) => {
+            if (!applyInput.record) {
+                throw new Error('The claimed workstream task order outbox record is required for authoritative apply.');
+            }
+            return applyAuthoritativeWorkstreamTaskOrderAndAck({
+                ...input,
+                ...applyInput,
+                record: applyInput.record,
+            });
+        },
+        isPermanentApplyError: (error) => error instanceof LocalAuthoritativeWorkstreamTaskOrderError
+            || error instanceof WorkspaceSyncIdempotencyConflictError
+            || error instanceof WorkspaceSyncRevisionConflictError,
+    };
+}