@taskforcehq/taskforce 0.3.324 → 0.3.327

package/dist/sync/v3/localTaxonomyCompositeOutboxService.js

@@ -0,0 +1,290 @@
+import { applyTaxonomyCompositeMutation, fingerprintTaxonomyTaskRemapProjection, validateTaxonomyTaskRemapPatches, WORKSPACE_SYNC_TAXONOMY_REPLACE_WITH_REMAPS, } from './taxonomyCompositeMutationService.js';
+import { fingerprintWorkspaceSyncPayload, } from './syncDurabilityStore.js';
+import { WORKSPACE_SYNC_TAXONOMY_DOMAIN, WORKSPACE_SYNC_TAXONOMY_ENTITY_ID, } from './taxonomyMutationService.js';
+import { serializeTaxonomyStateForSync, validateCanonicalTaxonomyState, } from './taxonomySyncPayload.js';
+export class LocalAuthoritativeTaxonomyCompositeError extends Error {
+    code = 'WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID';
+    constructor(message) {
+        super(message);
+        this.name = 'LocalAuthoritativeTaxonomyCompositeError';
+    }
+}
+function exactKeys(value, expected) {
+    const actual = Object.keys(value).sort();
+    const keys = [...expected].sort();
+    return actual.length === keys.length && actual.every((key, index) => key === keys[index]);
+}
+function normalizeAuthoritativeTaskRemapPayload(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const source = raw;
+    if (!exactKeys(source, ['id', 'category', 'type', 'priority', 'updatedAt']))
+        return null;
+    if (typeof source.id !== 'string' || !source.id.trim()
+        || typeof source.category !== 'string' || !source.category.trim()
+        || typeof source.type !== 'string' || !source.type.trim()
+        || typeof source.priority !== 'number' || !Number.isInteger(source.priority)
+        || typeof source.updatedAt !== 'string'
+        || !Number.isFinite(Date.parse(source.updatedAt))
+        || new Date(source.updatedAt).toISOString() !== source.updatedAt)
+        return null;
+    return {
+        id: source.id.trim(),
+        category: source.category.trim(),
+        type: source.type.trim(),
+        priority: source.priority,
+        updatedAt: source.updatedAt,
+    };
+}
+export function enqueueLocalTaxonomyCompositeReplacement(input) {
+    const taxonomyState = validateCanonicalTaxonomyState(input.taxonomyState);
+    const taskPatches = validateTaxonomyTaskRemapPatches(input.taskPatches, taxonomyState);
+    const result = input.store.enqueueLocalOperation({
+        identity: input.identity,
+        domain: WORKSPACE_SYNC_TAXONOMY_DOMAIN,
+        entityId: WORKSPACE_SYNC_TAXONOMY_ENTITY_ID,
+        mutationKind: WORKSPACE_SYNC_TAXONOMY_REPLACE_WITH_REMAPS,
+        revisionSource: 'current',
+        additionalTargets: taskPatches.map((entry) => ({
+            domain: 'task',
+            entityId: entry.entityId,
+            mutationKind: 'taxonomy-remap',
+            baseEntityRevision: entry.baseEntityRevision,
+            baseLifecycleRevision: entry.baseLifecycleRevision,
+            ownsTaskMetadata: true,
+        })),
+        payload: { state: taxonomyState, taskPatches },
+        now: input.now,
+        applyLocalMutation: () => applyTaxonomyCompositeMutation({
+            core: input.core,
+            workspaceId: input.identity.workspaceId,
+            taxonomyState,
+            taskPatches,
+            updatedAt: input.now,
+        }),
+    });
+    if (!result.enqueued)
+        return { enqueued: false };
+    if (input.notifyCommitted !== false) {
+        try {
+            input.core.notifyDurableTaxonomyCompositeCommitted(input.identity.workspaceId, taskPatches.map((entry) => entry.entityId));
+        }
+        catch (error) {
+            try {
+                input.onPostCommitError?.(error);
+            }
+            catch { /* local state and outbox remain committed */ }
+        }
+    }
+    return { enqueued: true };
+}
+function parseOutboxPayload(record) {
+    let payload;
+    try {
+        payload = JSON.parse(record.payloadJson);
+    }
+    catch {
+        throw new LocalAuthoritativeTaxonomyCompositeError('Claimed composite outbox payload is invalid.');
+    }
+    if (fingerprintWorkspaceSyncPayload(payload) !== record.payloadFingerprint) {
+        throw new LocalAuthoritativeTaxonomyCompositeError('Claimed composite outbox payload fingerprint is invalid.');
+    }
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload) || !exactKeys(payload, ['state', 'taskPatches'])) {
+        throw new LocalAuthoritativeTaxonomyCompositeError('Claimed composite outbox payload is invalid.');
+    }
+    const source = payload;
+    try {
+        const state = validateCanonicalTaxonomyState(source.state);
+        return {
+            state,
+            taskPatches: validateTaxonomyTaskRemapPatches(source.taskPatches, state),
+        };
+    }
+    catch (error) {
+        throw new LocalAuthoritativeTaxonomyCompositeError(`Claimed composite outbox payload is invalid: ${error.message}`);
+    }
+}
+export function assertTaxonomyCompositeOutboxTargets(input) {
+    const expected = [{
+            domain: WORKSPACE_SYNC_TAXONOMY_DOMAIN,
+            entityId: WORKSPACE_SYNC_TAXONOMY_ENTITY_ID,
+            mutationKind: WORKSPACE_SYNC_TAXONOMY_REPLACE_WITH_REMAPS,
+            baseEntityRevision: input.record.baseEntityRevision,
+            baseLifecycleRevision: input.record.baseLifecycleRevision,
+            ownsTaskMetadata: false,
+            ownsTaskLifecycle: false,
+            ownsTaskAssignee: false,
+        }, ...input.taskPatches.map((entry) => ({
+            domain: 'task',
+            entityId: entry.entityId,
+            mutationKind: 'taxonomy-remap',
+            baseEntityRevision: entry.baseEntityRevision,
+            baseLifecycleRevision: entry.baseLifecycleRevision,
+            ownsTaskMetadata: true,
+            ownsTaskLifecycle: false,
+            ownsTaskAssignee: false,
+        }))].sort((left, right) => (left.domain < right.domain ? -1 : left.domain > right.domain ? 1
+        : left.entityId < right.entityId ? -1 : left.entityId > right.entityId ? 1 : 0));
+    const actual = input.store.listOutboxTargets(input.identity);
+    if (actual.length !== expected.length
+        || actual.some((entry, index) => (entry.domain !== expected[index].domain
+            || entry.entityId !== expected[index].entityId
+            || entry.mutationKind !== expected[index].mutationKind
+            || entry.baseEntityRevision !== expected[index].baseEntityRevision
+            || entry.baseLifecycleRevision !== expected[index].baseLifecycleRevision
+            || entry.ownsTaskMetadata !== expected[index].ownsTaskMetadata
+            || entry.ownsTaskLifecycle !== expected[index].ownsTaskLifecycle
+            || entry.ownsTaskAssignee !== expected[index].ownsTaskAssignee)))
+        throw new LocalAuthoritativeTaxonomyCompositeError('Composite outbox targets do not match the claimed payload.');
+}
+export function applyAuthoritativeTaxonomyCompositeAndAck(input) {
+    if (!input.response || typeof input.response !== 'object' || Array.isArray(input.response)) {
+        throw new LocalAuthoritativeTaxonomyCompositeError('Authoritative composite response must be an object.');
+    }
+    const responseRecord = input.response;
+    if (!exactKeys(responseRecord, [
+        'success', 'contractVersion', 'workspaceId', 'clientId', 'operationId',
+        'acceptedSequence', 'operationHighWatermark', 'authoritative', 'taskAuthoritative',
+    ]))
+        throw new LocalAuthoritativeTaxonomyCompositeError('Authoritative composite response contains missing or unknown fields.');
+    const response = input.response;
+    const { state: requestedState, taskPatches } = parseOutboxPayload(input.record);
+    assertTaxonomyCompositeOutboxTargets({
+        store: input.store,
+        identity: input.identity,
+        record: input.record,
+        taskPatches,
+    });
+    const authoritative = response.authoritative;
+    const isRevision = (value) => (typeof value === 'string' && /^(0|[1-9]\d*)$/.test(value));
+    if (!authoritative || typeof authoritative !== 'object' || Array.isArray(authoritative)
+        || !exactKeys(authoritative, [
+            'domain', 'entityId', 'mutationKind', 'sequence', 'entityRevision',
+            'lifecycleRevision', 'updatedAt', 'payload',
+        ])
+        || response.success !== true
+        || response.contractVersion !== 3
+        || response.workspaceId !== input.identity.workspaceId
+        || response.clientId !== input.identity.clientId
+        || response.operationId !== input.identity.operationId
+        || input.record.domain !== WORKSPACE_SYNC_TAXONOMY_DOMAIN
+        || input.record.entityId !== WORKSPACE_SYNC_TAXONOMY_ENTITY_ID
+        || input.record.mutationKind !== WORKSPACE_SYNC_TAXONOMY_REPLACE_WITH_REMAPS
+        || authoritative?.domain !== WORKSPACE_SYNC_TAXONOMY_DOMAIN
+        || authoritative.entityId !== WORKSPACE_SYNC_TAXONOMY_ENTITY_ID
+        || authoritative.mutationKind !== WORKSPACE_SYNC_TAXONOMY_REPLACE_WITH_REMAPS
+        || !isRevision(authoritative.sequence)
+        || !isRevision(authoritative.entityRevision)
+        || authoritative.lifecycleRevision !== '0'
+        || response.acceptedSequence !== authoritative.sequence
+        || BigInt(authoritative.entityRevision) !== BigInt(input.record.baseEntityRevision) + 1n
+        || !Number.isFinite(Date.parse(authoritative.updatedAt))
+        || new Date(authoritative.updatedAt).toISOString() !== authoritative.updatedAt
+        || !Array.isArray(response.taskAuthoritative)
+        || response.taskAuthoritative.length !== taskPatches.length)
+        throw new LocalAuthoritativeTaxonomyCompositeError('Authoritative composite identity or revision is invalid.');
+    let authoritativeState;
+    try {
+        authoritativeState = validateCanonicalTaxonomyState(authoritative.payload);
+    }
+    catch {
+        throw new LocalAuthoritativeTaxonomyCompositeError('Authoritative taxonomy state is invalid.');
+    }
+    if (fingerprintWorkspaceSyncPayload(authoritativeState) !== fingerprintWorkspaceSyncPayload(requestedState)) {
+        throw new LocalAuthoritativeTaxonomyCompositeError('Authoritative taxonomy state does not match the claimed replacement.');
+    }
+    const authoritativeRevisions = [{
+            domain: authoritative.domain,
+            entityId: authoritative.entityId,
+            mutationKind: authoritative.mutationKind,
+            entityRevision: authoritative.entityRevision,
+            lifecycleRevision: authoritative.lifecycleRevision,
+            sequence: authoritative.sequence,
+            canonicalFingerprint: fingerprintWorkspaceSyncPayload(authoritativeState),
+        }];
+    const authoritativeTasks = new Map();
+    response.taskAuthoritative.forEach((entry, index) => {
+        const requested = taskPatches[index];
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry) || !exactKeys(entry, [
+            'domain', 'entityId', 'mutationKind', 'sequence', 'entityRevision', 'lifecycleRevision', 'payload',
+        ]))
+            throw new LocalAuthoritativeTaxonomyCompositeError('Authoritative task remap contains missing or unknown fields.');
+        const normalizedTask = normalizeAuthoritativeTaskRemapPayload(entry.payload);
+        if (entry.domain !== 'task'
+            || entry.entityId !== requested.entityId
+            || entry.mutationKind !== 'taxonomy-remap'
+            || !isRevision(entry.sequence)
+            || !isRevision(entry.entityRevision)
+            || !isRevision(entry.lifecycleRevision)
+            || BigInt(entry.entityRevision) !== BigInt(requested.baseEntityRevision) + 1n
+            || entry.lifecycleRevision !== requested.baseLifecycleRevision
+            || BigInt(entry.sequence) !== BigInt(authoritative.sequence) + BigInt(index + 1)
+            || !normalizedTask
+            || normalizedTask.id !== requested.entityId
+            || normalizedTask.updatedAt !== authoritative.updatedAt)
+            throw new LocalAuthoritativeTaxonomyCompositeError('Authoritative task remap identity or revision is invalid.');
+        for (const field of Object.keys(requested.patch)) {
+            if (normalizedTask[field] !== requested.patch[field]) {
+                throw new LocalAuthoritativeTaxonomyCompositeError('Authoritative task remap does not match the claimed patch.');
+            }
+        }
+        authoritativeTasks.set(entry.entityId, normalizedTask);
+        authoritativeRevisions.push({
+            domain: entry.domain,
+            entityId: entry.entityId,
+            mutationKind: entry.mutationKind,
+            entityRevision: entry.entityRevision,
+            lifecycleRevision: entry.lifecycleRevision,
+            sequence: entry.sequence,
+            canonicalFingerprint: fingerprintTaxonomyTaskRemapProjection(normalizedTask),
+        });
+    });
+    if (response.operationHighWatermark !== authoritativeRevisions[authoritativeRevisions.length - 1].sequence) {
+        throw new LocalAuthoritativeTaxonomyCompositeError('Authoritative composite sequence range is invalid.');
+    }
+    input.store.applyAuthoritativeAndAck({
+        identity: input.identity,
+        leaseOwner: input.leaseOwner,
+        now: input.now,
+        response,
+        acceptedSequence: response.operationHighWatermark,
+        authoritative: authoritativeRevisions,
+        applyAuthoritative: () => {
+            const installedState = input.core.replaceTaxonomyStateForDurableSync({
+                workspaceId: input.identity.workspaceId,
+                taxonomyState: authoritativeState,
+                updatedAt: authoritative.updatedAt,
+            });
+            if (fingerprintWorkspaceSyncPayload(serializeTaxonomyStateForSync(installedState)) !== fingerprintWorkspaceSyncPayload(authoritativeState)) {
+                throw new LocalAuthoritativeTaxonomyCompositeError('Installed taxonomy state does not match authoritative state.');
+            }
+            for (const entry of taskPatches) {
+                const expected = authoritativeTasks.get(entry.entityId);
+                const task = input.core.applyTaskTaxonomyRemapForDurableSync({
+                    workspaceId: input.identity.workspaceId,
+                    taskId: entry.entityId,
+                    patch: entry.patch,
+                    updatedAt: authoritative.updatedAt,
+                });
+                if (!expected || fingerprintTaxonomyTaskRemapProjection(task) !== fingerprintTaxonomyTaskRemapProjection(expected)) {
+                    throw new LocalAuthoritativeTaxonomyCompositeError(`Installed task ${entry.entityId} does not match authoritative state.`);
+                }
+            }
+            input.store.markTaskTaxonomyProjectionOwned({
+                tenantId: input.identity.tenantId,
+                workspaceId: input.identity.workspaceId,
+                taskIds: taskPatches.map((entry) => entry.entityId),
+                now: authoritative.updatedAt,
+            });
+        },
+    });
+    try {
+        input.core.notifyDurableTaxonomyCompositeCommitted(input.identity.workspaceId, taskPatches.map((entry) => entry.entityId));
+    }
+    catch (error) {
+        try {
+            input.onPostCommitError?.(error);
+        }
+        catch { /* authoritative state and ack remain committed */ }
+    }
+}

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

@@ -0,0 +1,9 @@
+import { type LocalTaxonomyOutboxCore } from './localTaxonomyOutboxService.js';
+import type { LocalOutboxOperationHandler } from './localOutboxOperationHandler.js';
+import { WorkspaceSyncDurabilityStore } from './syncDurabilityStore.js';
+import { type DurableTaxonomyCompositeCore } from './taxonomyCompositeMutationService.js';
+export declare function createLocalTaxonomyOutboxHandler(input: {
+    store: WorkspaceSyncDurabilityStore;
+    core: LocalTaxonomyOutboxCore & DurableTaxonomyCompositeCore;
+    onPostCommitError?: (error: unknown) => void;
+}): LocalOutboxOperationHandler;

package/dist/sync/v3/localTaxonomyOutboxHandler.js

@@ -0,0 +1,106 @@
+import { applyAuthoritativeTaxonomyAndAck, LocalAuthoritativeTaxonomyError, } from './localTaxonomyOutboxService.js';
+import { fingerprintWorkspaceSyncPayload, WorkspaceSyncIdempotencyConflictError, WorkspaceSyncRevisionConflictError, } from './syncDurabilityStore.js';
+import { WORKSPACE_SYNC_TAXONOMY_DOMAIN, WORKSPACE_SYNC_TAXONOMY_ENTITY_ID, WORKSPACE_SYNC_TAXONOMY_REPLACE_STATE, } from './taxonomyMutationService.js';
+import { DurableTaxonomyMutationError, validateCanonicalTaxonomyState } from './taxonomySyncPayload.js';
+import { applyAuthoritativeTaxonomyCompositeAndAck, assertTaxonomyCompositeOutboxTargets, LocalAuthoritativeTaxonomyCompositeError, } from './localTaxonomyCompositeOutboxService.js';
+import { validateTaxonomyTaskRemapPatches, WORKSPACE_SYNC_TAXONOMY_REPLACE_WITH_REMAPS, } from './taxonomyCompositeMutationService.js';
+function buildTaxonomyEnvelope(store, record) {
+    if (record.entityId !== WORKSPACE_SYNC_TAXONOMY_ENTITY_ID || record.baseLifecycleRevision !== '0') {
+        throw new Error('Local taxonomy outbox identity or lifecycle revision is invalid.');
+    }
+    let payload;
+    try {
+        payload = JSON.parse(record.payloadJson);
+    }
+    catch {
+        throw new Error('Local taxonomy outbox payload is not valid JSON.');
+    }
+    if (fingerprintWorkspaceSyncPayload(payload) !== record.payloadFingerprint) {
+        throw new Error('Local taxonomy outbox payload fingerprint does not match persisted content.');
+    }
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload))
+        throw new Error('Local taxonomy outbox payload must be an object.');
+    const source = payload;
+    if (record.mutationKind === WORKSPACE_SYNC_TAXONOMY_REPLACE_WITH_REMAPS) {
+        if (Object.keys(source).length !== 2 || !Object.prototype.hasOwnProperty.call(source, 'state') || !Object.prototype.hasOwnProperty.call(source, 'taskPatches')) {
+            throw new Error('Local composite taxonomy outbox payload must contain exactly state and taskPatches.');
+        }
+        const state = validateCanonicalTaxonomyState(source.state);
+        const taskPatches = validateTaxonomyTaskRemapPatches(source.taskPatches, state);
+        assertTaxonomyCompositeOutboxTargets({
+            store,
+            identity: record,
+            record,
+            taskPatches,
+        });
+        return {
+            contractVersion: 3,
+            workspaceId: record.workspaceId,
+            clientId: record.clientId,
+            operationId: record.operationId,
+            operation: {
+                domain: WORKSPACE_SYNC_TAXONOMY_DOMAIN,
+                entityId: WORKSPACE_SYNC_TAXONOMY_ENTITY_ID,
+                mutationKind: WORKSPACE_SYNC_TAXONOMY_REPLACE_WITH_REMAPS,
+                baseEntityRevision: record.baseEntityRevision,
+                baseLifecycleRevision: '0',
+                payload: {
+                    state,
+                    taskPatches,
+                },
+            },
+        };
+    }
+    if (Object.keys(source).length !== 1 || !Object.prototype.hasOwnProperty.call(source, 'state')) {
+        throw new Error('Local taxonomy outbox payload must contain exactly state.');
+    }
+    return {
+        contractVersion: 3,
+        workspaceId: record.workspaceId,
+        clientId: record.clientId,
+        operationId: record.operationId,
+        operation: {
+            domain: WORKSPACE_SYNC_TAXONOMY_DOMAIN,
+            entityId: WORKSPACE_SYNC_TAXONOMY_ENTITY_ID,
+            mutationKind: WORKSPACE_SYNC_TAXONOMY_REPLACE_STATE,
+            baseEntityRevision: record.baseEntityRevision,
+            baseLifecycleRevision: '0',
+            payload: { state: validateCanonicalTaxonomyState(source.state) },
+        },
+    };
+}
+export function createLocalTaxonomyOutboxHandler(input) {
+    return {
+        key: 'taxonomy/replace-state',
+        supports: (record) => record.domain === WORKSPACE_SYNC_TAXONOMY_DOMAIN
+            && (record.mutationKind === WORKSPACE_SYNC_TAXONOMY_REPLACE_STATE
+                || record.mutationKind === WORKSPACE_SYNC_TAXONOMY_REPLACE_WITH_REMAPS),
+        buildEnvelope: (record) => buildTaxonomyEnvelope(input.store, record),
+        applyAuthoritative: (applyInput) => {
+            if (!applyInput.record) {
+                throw new Error('The claimed taxonomy outbox record is required for authoritative apply.');
+            }
+            if (applyInput.record.mutationKind === WORKSPACE_SYNC_TAXONOMY_REPLACE_WITH_REMAPS) {
+                return applyAuthoritativeTaxonomyCompositeAndAck({
+                    store: input.store,
+                    core: input.core,
+                    ...applyInput,
+                    record: applyInput.record,
+                    onPostCommitError: input.onPostCommitError,
+                });
+            }
+            return applyAuthoritativeTaxonomyAndAck({
+                store: input.store,
+                core: input.core,
+                ...applyInput,
+                record: applyInput.record,
+                onPostCommitError: input.onPostCommitError,
+            });
+        },
+        isPermanentApplyError: (error) => (error instanceof LocalAuthoritativeTaxonomyError
+            || error instanceof LocalAuthoritativeTaxonomyCompositeError
+            || error instanceof DurableTaxonomyMutationError
+            || error instanceof WorkspaceSyncIdempotencyConflictError
+            || error instanceof WorkspaceSyncRevisionConflictError),
+    };
+}

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

@@ -0,0 +1,30 @@
+import type { NormalizedWorkspaceTaxonomyState, WorkspaceTaxonomyState } from '../../shared/taxonomyState.js';
+import { WorkspaceSyncDurabilityStore, type WorkspaceSyncOperationIdentity, type WorkspaceSyncOutboxRecord } from './syncDurabilityStore.js';
+import type { DurableTaxonomyServiceCore } from './taxonomyMutationService.js';
+export type LocalTaxonomyOutboxCore = DurableTaxonomyServiceCore;
+export declare class LocalAuthoritativeTaxonomyError extends Error {
+    readonly code = "WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID";
+    constructor(message: string);
+}
+export declare function enqueueLocalTaxonomyReplacement(input: {
+    store: WorkspaceSyncDurabilityStore;
+    core: LocalTaxonomyOutboxCore;
+    identity: WorkspaceSyncOperationIdentity;
+    taxonomyState: WorkspaceTaxonomyState;
+    now: string;
+    onPostCommitError?: (error: unknown) => void;
+    notifyCommitted?: boolean;
+}): {
+    enqueued: boolean;
+    taxonomyState?: NormalizedWorkspaceTaxonomyState;
+};
+export declare function applyAuthoritativeTaxonomyAndAck(input: {
+    store: WorkspaceSyncDurabilityStore;
+    core: LocalTaxonomyOutboxCore;
+    identity: WorkspaceSyncOperationIdentity;
+    record: WorkspaceSyncOutboxRecord;
+    leaseOwner: string;
+    response: unknown;
+    now: string;
+    onPostCommitError?: (error: unknown) => void;
+}): NormalizedWorkspaceTaxonomyState;

package/dist/sync/v3/localTaxonomyOutboxService.js

@@ -0,0 +1,181 @@
+import { fingerprintWorkspaceSyncPayload, } from './syncDurabilityStore.js';
+import { WORKSPACE_SYNC_TAXONOMY_DOMAIN, WORKSPACE_SYNC_TAXONOMY_ENTITY_ID, WORKSPACE_SYNC_TAXONOMY_REPLACE_STATE, } from './taxonomyMutationService.js';
+import { DurableTaxonomyMutationError, serializeTaxonomyStateForSync, validateCanonicalTaxonomyState, } from './taxonomySyncPayload.js';
+export class LocalAuthoritativeTaxonomyError extends Error {
+    code = 'WORKSPACE_SYNC_AUTHORITATIVE_RESPONSE_INVALID';
+    constructor(message) {
+        super(message);
+        this.name = 'LocalAuthoritativeTaxonomyError';
+    }
+}
+function hasExactKeys(value, expected) {
+    const actual = Object.keys(value).sort();
+    const canonical = [...expected].sort();
+    return actual.length === canonical.length && actual.every((key, index) => key === canonical[index]);
+}
+function assertNoTaskRemap(core, state, workspaceId) {
+    const incompatibleTaskIds = core.listTaskIdsIncompatibleWithTaxonomyStateForSync(state, workspaceId);
+    if (incompatibleTaskIds.length > 0) {
+        throw new DurableTaxonomyMutationError(`Taxonomy replacement requires task remaps for ${incompatibleTaskIds.length} task(s).`, 'DURABLE_TAXONOMY_REMAP_REQUIRED', 409);
+    }
+}
+export function enqueueLocalTaxonomyReplacement(input) {
+    const taxonomyState = validateCanonicalTaxonomyState(input.taxonomyState);
+    const enqueued = input.store.enqueueLocalOperation({
+        identity: input.identity,
+        domain: WORKSPACE_SYNC_TAXONOMY_DOMAIN,
+        entityId: WORKSPACE_SYNC_TAXONOMY_ENTITY_ID,
+        mutationKind: WORKSPACE_SYNC_TAXONOMY_REPLACE_STATE,
+        revisionSource: 'current',
+        payload: { state: taxonomyState },
+        now: input.now,
+        applyLocalMutation: () => {
+            assertNoTaskRemap(input.core, taxonomyState, input.identity.workspaceId);
+            const installed = input.core.replaceTaxonomyStateForDurableSync({
+                workspaceId: input.identity.workspaceId,
+                taxonomyState,
+                updatedAt: input.now,
+            });
+            if (fingerprintWorkspaceSyncPayload(serializeTaxonomyStateForSync(installed)) !== fingerprintWorkspaceSyncPayload(taxonomyState)) {
+                throw new DurableTaxonomyMutationError('Installed taxonomy state does not match the captured canonical payload.', 'DURABLE_TAXONOMY_STATE_INVALID', 409);
+            }
+            return installed;
+        },
+    });
+    if (!enqueued.enqueued)
+        return { enqueued: false, taxonomyState };
+    if (input.notifyCommitted !== false) {
+        try {
+            input.core.notifyDurableTaxonomyCommitted(input.identity.workspaceId);
+        }
+        catch (error) {
+            try {
+                input.onPostCommitError?.(error);
+            }
+            catch { /* state and outbox remain committed */ }
+        }
+    }
+    return { enqueued: true, taxonomyState: enqueued.mutationResult };
+}
+export function applyAuthoritativeTaxonomyAndAck(input) {
+    if (!input.response || typeof input.response !== 'object' || Array.isArray(input.response)) {
+        throw new LocalAuthoritativeTaxonomyError('Authoritative taxonomy response must be an object.');
+    }
+    const responseRecord = input.response;
+    if (!hasExactKeys(responseRecord, [
+        'success', 'contractVersion', 'workspaceId', 'clientId', 'operationId', 'acceptedSequence', 'authoritative',
+    ])) {
+        throw new LocalAuthoritativeTaxonomyError('Authoritative taxonomy response contains missing or unknown fields.');
+    }
+    const response = input.response;
+    const authoritative = response.authoritative;
+    const authoritativeRecord = authoritative && typeof authoritative === 'object' && !Array.isArray(authoritative)
+        ? authoritative
+        : null;
+    if (response.success !== true
+        || response.contractVersion !== 3
+        || response.workspaceId !== input.identity.workspaceId
+        || response.clientId !== input.identity.clientId
+        || response.operationId !== input.identity.operationId
+        || !authoritativeRecord
+        || !hasExactKeys(authoritativeRecord, [
+            'domain', 'entityId', 'mutationKind', 'sequence', 'entityRevision', 'lifecycleRevision', 'updatedAt', 'payload',
+        ])
+        || authoritative.domain !== WORKSPACE_SYNC_TAXONOMY_DOMAIN
+        || authoritative.entityId !== WORKSPACE_SYNC_TAXONOMY_ENTITY_ID
+        || authoritative.mutationKind !== WORKSPACE_SYNC_TAXONOMY_REPLACE_STATE
+        || typeof authoritative.sequence !== 'string' || !/^[1-9]\d*$/.test(authoritative.sequence)
+        || typeof authoritative.entityRevision !== 'string' || !/^[1-9]\d*$/.test(authoritative.entityRevision)
+        || authoritative.lifecycleRevision !== '0'
+        || response.acceptedSequence !== authoritative.sequence
+        || typeof authoritative.updatedAt !== 'string'
+        || !Number.isFinite(Date.parse(authoritative.updatedAt))
+        || new Date(authoritative.updatedAt).toISOString() !== authoritative.updatedAt) {
+        throw new LocalAuthoritativeTaxonomyError('Authoritative taxonomy response identity or revision is invalid.');
+    }
+    const record = input.record;
+    if (record.tenantId !== input.identity.tenantId
+        || record.workspaceId !== input.identity.workspaceId
+        || record.clientId !== input.identity.clientId
+        || record.operationId !== input.identity.operationId
+        || record.domain !== WORKSPACE_SYNC_TAXONOMY_DOMAIN
+        || record.entityId !== WORKSPACE_SYNC_TAXONOMY_ENTITY_ID
+        || record.mutationKind !== WORKSPACE_SYNC_TAXONOMY_REPLACE_STATE
+        || record.baseLifecycleRevision !== '0'
+        || BigInt(authoritative.entityRevision) !== BigInt(record.baseEntityRevision) + 1n) {
+        throw new LocalAuthoritativeTaxonomyError('Authoritative taxonomy response does not match the claimed outbox revision.');
+    }
+    let outboxPayload;
+    try {
+        outboxPayload = JSON.parse(record.payloadJson);
+    }
+    catch {
+        throw new LocalAuthoritativeTaxonomyError('Claimed taxonomy outbox payload is invalid.');
+    }
+    if (fingerprintWorkspaceSyncPayload(outboxPayload) !== record.payloadFingerprint) {
+        throw new LocalAuthoritativeTaxonomyError('Claimed taxonomy outbox payload fingerprint is invalid.');
+    }
+    if (!outboxPayload || typeof outboxPayload !== 'object' || Array.isArray(outboxPayload)) {
+        throw new LocalAuthoritativeTaxonomyError('Claimed taxonomy outbox payload is invalid.');
+    }
+    const outboxPayloadRecord = outboxPayload;
+    if (!hasExactKeys(outboxPayloadRecord, ['state'])) {
+        throw new LocalAuthoritativeTaxonomyError('Claimed taxonomy outbox payload is invalid.');
+    }
+    let requestedState;
+    try {
+        requestedState = validateCanonicalTaxonomyState(outboxPayloadRecord.state);
+    }
+    catch {
+        throw new LocalAuthoritativeTaxonomyError('Claimed taxonomy outbox state is invalid.');
+    }
+    let taxonomyState;
+    try {
+        taxonomyState = validateCanonicalTaxonomyState(authoritative.payload);
+    }
+    catch (error) {
+        throw new LocalAuthoritativeTaxonomyError(`Authoritative taxonomy payload is invalid: ${error.message}`);
+    }
+    const canonicalFingerprint = fingerprintWorkspaceSyncPayload(taxonomyState);
+    if (canonicalFingerprint !== fingerprintWorkspaceSyncPayload(requestedState)) {
+        throw new LocalAuthoritativeTaxonomyError('Authoritative taxonomy payload does not match the claimed replacement.');
+    }
+    const installed = input.store.applyAuthoritativeAndAck({
+        identity: input.identity,
+        leaseOwner: input.leaseOwner,
+        now: input.now,
+        response,
+        acceptedSequence: authoritative.sequence,
+        authoritative: {
+            domain: WORKSPACE_SYNC_TAXONOMY_DOMAIN,
+            entityId: WORKSPACE_SYNC_TAXONOMY_ENTITY_ID,
+            mutationKind: WORKSPACE_SYNC_TAXONOMY_REPLACE_STATE,
+            entityRevision: authoritative.entityRevision,
+            lifecycleRevision: authoritative.lifecycleRevision,
+            sequence: authoritative.sequence,
+            canonicalFingerprint,
+        },
+        applyAuthoritative: () => {
+            assertNoTaskRemap(input.core, taxonomyState, input.identity.workspaceId);
+            const state = input.core.replaceTaxonomyStateForDurableSync({
+                workspaceId: input.identity.workspaceId,
+                taxonomyState,
+                updatedAt: authoritative.updatedAt,
+            });
+            if (fingerprintWorkspaceSyncPayload(serializeTaxonomyStateForSync(state)) !== canonicalFingerprint) {
+                throw new LocalAuthoritativeTaxonomyError('Installed taxonomy state does not match the authoritative payload.');
+            }
+            return state;
+        },
+    });
+    try {
+        input.core.notifyDurableTaxonomyCommitted(input.identity.workspaceId);
+    }
+    catch (error) {
+        try {
+            input.onPostCommitError?.(error);
+        }
+        catch { /* state and acknowledgement remain committed */ }
+    }
+    return installed;
+}

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

@@ -0,0 +1,8 @@
+import type { LocalOutboxOperationHandler } from './localOutboxOperationHandler.js';
+import { type LocalWorkflowRuntimeOutboxCore } from './localWorkflowRuntimeOutboxService.js';
+import { WorkspaceSyncDurabilityStore } from './syncDurabilityStore.js';
+export declare function createLocalWorkflowRuntimeOutboxHandler(input: {
+    store: WorkspaceSyncDurabilityStore;
+    core: LocalWorkflowRuntimeOutboxCore;
+    onPostCommitError?: (error: unknown) => void;
+}): LocalOutboxOperationHandler;