@taskforcehq/taskforce 0.3.326 → 0.3.327

package/dist/sync/v3/durableInitiativeMutationRouter.js

@@ -0,0 +1,287 @@
+import { randomUUID } from 'crypto';
+import { serializeInitiativeForSync } from '../planningSyncPayload.js';
+import { validateDurableInitiativeComment, validateDurableInitiativeCreatePayload, validateDurableInitiativeMetadataPatch, } from './initiativeMutationPayload.js';
+import { runDurableInitiativeMutation, } from './initiativeMutationService.js';
+import { LocalSyncIdentityStore } from './localSyncIdentityStore.js';
+import { enqueueLocalInitiativeMutation, } from './localInitiativeOutboxService.js';
+import { isWorkspaceSyncV3PlanningActivationEnabled } from './planningActivation.js';
+import { serializeEntityActivityForSync } from './taskActivityJournal.js';
+import { WorkspaceSyncDurabilityStore, WorkspaceSyncIdempotencyConflictError } from './syncDurabilityStore.js';
+import { buildInitiativeActivityEventId } from './initiativeActivityIdentity.js';
+const OPERATION_LEASE_MS = 30_000;
+export class DurableInitiativeMutationRouterDisabledError extends Error {
+    code = 'WORKSPACE_SYNC_V3_INITIATIVE_ACTIVATION_DISABLED';
+    constructor() {
+        super('Durable initiative activation is disabled.');
+        this.name = 'DurableInitiativeMutationRouterDisabledError';
+    }
+}
+export class DurableInitiativeMutationRouterInProgressError extends Error {
+    retryAt;
+    code = 'WORKSPACE_SYNC_OPERATION_IN_PROGRESS';
+    statusCode = 409;
+    constructor(retryAt) {
+        super('The durable initiative mutation is already in progress.');
+        this.retryAt = retryAt;
+        this.name = 'DurableInitiativeMutationRouterInProgressError';
+    }
+}
+export function createDurableInitiativeMutationRouter(input) {
+    const store = new WorkspaceSyncDurabilityStore(input.core.getDatabaseAdapter());
+    let persistedOwnershipChecked = false;
+    const enabled = isWorkspaceSyncV3PlanningActivationEnabled({
+        domain: 'initiative',
+        runtimeMode: input.runtimeMode,
+        surface: input.surface,
+        env: input.env,
+        readPersistedProjectionOwner: () => {
+            persistedOwnershipChecked = true;
+            return store.readInitiativeProjectionOwnership({
+                tenantId: input.tenantId,
+                workspaceId: input.workspaceId,
+            }).owner;
+        },
+    });
+    const identityStore = new LocalSyncIdentityStore(input.core.getDatabaseAdapter());
+    const createOperationId = input.createOperationId || (() => `operation-${randomUUID()}`);
+    const createCommentId = input.createCommentId || (() => `comment-${randomUUID()}`);
+    const now = input.now || (() => new Date());
+    const serviceCore = input.deferPostCommitNotification
+        ? new Proxy(input.core, {
+            get(target, property) {
+                const value = Reflect.get(target, property, target);
+                if (property === 'notifyDurableInitiativeCommitted' && typeof value === 'function') {
+                    return (...args) => input.deferPostCommitNotification?.(() => value.apply(target, args));
+                }
+                return typeof value === 'function' ? value.bind(target) : value;
+            },
+        })
+        : input.core;
+    const assertEnabled = () => {
+        if (!enabled)
+            throw new DurableInitiativeMutationRouterDisabledError();
+    };
+    const mutate = (initiativeId, buildOperation) => {
+        assertEnabled();
+        const acceptedAt = now();
+        const acceptedAtIso = acceptedAt.toISOString();
+        const operationId = String(createOperationId() || '').trim();
+        if (!operationId)
+            throw new Error('Operation id is required.');
+        const clientId = input.runtimeMode === 'local'
+            ? identityStore.getOrCreateClientId(acceptedAtIso)
+            : String(input.cloudClientId || `${input.surface}-cloud`).trim();
+        if (!clientId)
+            throw new Error('Client id is required.');
+        const identity = {
+            tenantId: input.tenantId,
+            workspaceId: input.workspaceId,
+            clientId,
+            operationId,
+        };
+        const replayState = input.core.getDatabaseAdapter().transaction(() => {
+            const persistedOutbox = store.readOutboxOperation(identity);
+            if (persistedOutbox) {
+                if (persistedOutbox.domain !== 'initiative' || persistedOutbox.entityId !== initiativeId) {
+                    throw new WorkspaceSyncIdempotencyConflictError();
+                }
+                return {
+                    revisions: {
+                        entityRevision: persistedOutbox.baseEntityRevision,
+                        lifecycleRevision: persistedOutbox.baseLifecycleRevision,
+                    },
+                    persistedOutbox,
+                    committedResponse: null,
+                    processingCreatedAt: null,
+                };
+            }
+            const operationState = store.readOperationStateForUpdate(identity);
+            if (operationState?.status === 'committed') {
+                if (!operationState.responseJson)
+                    throw new Error('Committed operation is missing its response.');
+                const response = JSON.parse(operationState.responseJson);
+                if (response.authoritative.entityId !== initiativeId) {
+                    throw new WorkspaceSyncIdempotencyConflictError();
+                }
+                const lifecycleMutation = response.authoritative.mutationKind === 'archive'
+                    || response.authoritative.mutationKind === 'unarchive';
+                return {
+                    revisions: {
+                        entityRevision: String(BigInt(response.authoritative.entityRevision) - 1n),
+                        lifecycleRevision: lifecycleMutation
+                            ? String(BigInt(response.authoritative.lifecycleRevision) - 1n)
+                            : response.authoritative.lifecycleRevision,
+                    },
+                    persistedOutbox: null,
+                    committedResponse: response,
+                    processingCreatedAt: null,
+                };
+            }
+            return {
+                revisions: store.readEntityRevisionCoordinates({
+                    tenantId: input.tenantId,
+                    workspaceId: input.workspaceId,
+                    domain: 'initiative',
+                    entityId: initiativeId,
+                }),
+                persistedOutbox: null,
+                committedResponse: null,
+                processingCreatedAt: operationState?.status === 'processing' ? operationState.createdAt : null,
+            };
+        })();
+        let operation = buildOperation(replayState.revisions);
+        if (replayState.persistedOutbox) {
+            if (replayState.persistedOutbox.mutationKind !== operation.mutationKind) {
+                throw new WorkspaceSyncIdempotencyConflictError();
+            }
+        }
+        else if (replayState.committedResponse) {
+            const response = replayState.committedResponse;
+            if (response.authoritative.mutationKind !== operation.mutationKind) {
+                throw new WorkspaceSyncIdempotencyConflictError();
+            }
+        }
+        if (input.surface === 'mcp' && (operation.mutationKind === 'create' || operation.mutationKind === 'append-comment')) {
+            let generatedAt = replayState.processingCreatedAt || acceptedAtIso;
+            if (replayState.persistedOutbox) {
+                const persistedPayload = JSON.parse(replayState.persistedOutbox.payloadJson);
+                generatedAt = operation.mutationKind === 'create'
+                    ? String(persistedPayload.createdAt || '')
+                    : String(persistedPayload.comment?.timestamp || '');
+            }
+            else if (replayState.committedResponse) {
+                const authoritative = replayState.committedResponse.authoritative.payload;
+                if (operation.mutationKind === 'create') {
+                    generatedAt = String(authoritative.createdAt || '');
+                }
+                else {
+                    const commentPayload = operation.payload.comment;
+                    const comment = (authoritative.comments || []).find((candidate) => candidate.id === commentPayload.id);
+                    if (!comment)
+                        throw new Error('Committed initiative comment is missing from the authoritative response.');
+                    generatedAt = comment.timestamp;
+                }
+            }
+            if (operation.mutationKind === 'create') {
+                operation = { ...operation, payload: { ...operation.payload, createdAt: generatedAt } };
+            }
+            else {
+                operation = {
+                    ...operation,
+                    payload: { comment: { ...operation.payload.comment, timestamp: generatedAt } },
+                };
+            }
+        }
+        if (input.runtimeMode === 'local') {
+            const captured = enqueueLocalInitiativeMutation({
+                store,
+                core: serviceCore,
+                identity,
+                operation,
+                now: acceptedAtIso,
+                actorRef: input.actorRef,
+                onPostCommitError: input.onPostCommitError,
+                requireV3PlanningOwnership: persistedOwnershipChecked,
+            });
+            const provisionalInitiative = captured.initiative
+                || input.core.getInitiative(operation.entityId, input.workspaceId)
+                || undefined;
+            const activity = input.core.getEntityEventForSync({
+                workspaceId: input.workspaceId,
+                eventId: buildInitiativeActivityEventId({
+                    workspaceId: input.workspaceId,
+                    clientId,
+                    operationId,
+                    initiativeId: operation.entityId,
+                    mutationKind: operation.mutationKind,
+                }),
+            });
+            return {
+                state: 'pending',
+                route: 'local-outbox',
+                operationId,
+                ...(provisionalInitiative
+                    ? { provisionalInitiative: serializeInitiativeForSync(provisionalInitiative) }
+                    : {}),
+                ...(activity ? { provisionalActivity: serializeEntityActivityForSync(activity) } : {}),
+            };
+        }
+        const result = runDurableInitiativeMutation({
+            store,
+            core: serviceCore,
+            ...identity,
+            operation,
+            now: acceptedAtIso,
+            leaseExpiresAt: new Date(acceptedAt.getTime() + OPERATION_LEASE_MS).toISOString(),
+            actorRef: input.actorRef,
+            onPostCommitError: input.onPostCommitError,
+        });
+        if (result.state === 'in_progress') {
+            throw new DurableInitiativeMutationRouterInProgressError(result.retryAt);
+        }
+        return {
+            state: 'committed',
+            route: 'cloud-acceptance',
+            operationId,
+            authoritativeInitiative: result.response.authoritative.payload,
+            authoritativeActivity: result.response.activity,
+        };
+    };
+    return {
+        enabled,
+        create(initiativeId, payload) {
+            assertEnabled();
+            const canonicalPayload = validateDurableInitiativeCreatePayload(payload);
+            const entityId = String(initiativeId || '').trim();
+            return mutate(entityId, () => ({
+                domain: 'initiative',
+                entityId,
+                mutationKind: 'create',
+                baseEntityRevision: '0',
+                baseLifecycleRevision: '0',
+                payload: canonicalPayload,
+            }));
+        },
+        updateMetadata(initiativeId, patch) {
+            assertEnabled();
+            const canonicalPatch = validateDurableInitiativeMetadataPatch(patch);
+            const entityId = String(initiativeId || '').trim();
+            return mutate(entityId, (revisions) => ({
+                domain: 'initiative', entityId, mutationKind: 'metadata-update',
+                baseEntityRevision: revisions.entityRevision, baseLifecycleRevision: revisions.lifecycleRevision,
+                payload: { patch: canonicalPatch },
+            }));
+        },
+        appendComment(initiativeId, comment) {
+            assertEnabled();
+            const commentId = String(comment.id || createCommentId() || '').trim();
+            if (!commentId)
+                throw new Error('Comment id is required.');
+            const canonicalComment = validateDurableInitiativeComment({ ...comment, id: commentId });
+            const entityId = String(initiativeId || '').trim();
+            return mutate(entityId, (revisions) => ({
+                domain: 'initiative', entityId, mutationKind: 'append-comment',
+                baseEntityRevision: revisions.entityRevision, baseLifecycleRevision: revisions.lifecycleRevision,
+                payload: { comment: canonicalComment },
+            }));
+        },
+        archive(initiativeId) {
+            assertEnabled();
+            const entityId = String(initiativeId || '').trim();
+            return mutate(entityId, (revisions) => ({
+                domain: 'initiative', entityId, mutationKind: 'archive',
+                baseEntityRevision: revisions.entityRevision, baseLifecycleRevision: revisions.lifecycleRevision,
+                payload: {},
+            }));
+        },
+        unarchive(initiativeId) {
+            assertEnabled();
+            const entityId = String(initiativeId || '').trim();
+            return mutate(entityId, (revisions) => ({
+                domain: 'initiative', entityId, mutationKind: 'unarchive',
+                baseEntityRevision: revisions.entityRevision, baseLifecycleRevision: revisions.lifecycleRevision,
+                payload: {},
+            }));
+        },
+    };
+}

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

@@ -0,0 +1,36 @@
+export type DurableOperationRevisionMode = 'none' | 'metadata' | 'both';
+export interface DurableOperationAuthoritativeEntry<Payload = unknown> {
+    domain: string;
+    entityId: string;
+    mutationKind: string;
+    entityRevision?: string;
+    lifecycleRevision?: string;
+    payload?: Payload;
+}
+export declare class DurableOperationReplayInvalidResponseError extends Error {
+    readonly code = "DURABLE_OPERATION_REPLAY_INVALID_RESPONSE";
+    constructor(message?: string);
+}
+export declare class DurableOperationReplayIdentityConflictError extends Error {
+    readonly code = "DURABLE_OPERATION_REPLAY_IDENTITY_CONFLICT";
+    constructor(message?: string);
+}
+export interface DurableOperationReplayResult<Payload = unknown> {
+    response: Readonly<Record<string, unknown>>;
+    authoritative: DurableOperationAuthoritativeEntry<Payload>;
+    authoritativeEntries: Array<DurableOperationAuthoritativeEntry<unknown>>;
+    baseEntityRevision?: string;
+    baseLifecycleRevision?: string;
+}
+export declare function readDurableOperationReplay<Payload = unknown>(input: {
+    responseJson: string;
+    operationId: string;
+    domain: string;
+    entityId?: string;
+    mutationKind: string;
+    revisionMode: DurableOperationRevisionMode;
+    authoritativeMode?: 'single' | 'multiple';
+    requirePayload?: boolean;
+    predicate?: (entry: Readonly<DurableOperationAuthoritativeEntry<unknown>>, response: Readonly<Record<string, unknown>>) => boolean;
+    maxAuthoritativeEntries?: number;
+}): DurableOperationReplayResult<Payload>;

package/dist/sync/v3/durableOperationReplay.js

@@ -0,0 +1,103 @@
+export class DurableOperationReplayInvalidResponseError extends Error {
+    code = 'DURABLE_OPERATION_REPLAY_INVALID_RESPONSE';
+    constructor(message = 'Committed durable operation response is invalid.') {
+        super(message);
+        this.name = 'DurableOperationReplayInvalidResponseError';
+    }
+}
+export class DurableOperationReplayIdentityConflictError extends Error {
+    code = 'DURABLE_OPERATION_REPLAY_IDENTITY_CONFLICT';
+    constructor(message = 'Operation identity was already used for a different durable mutation.') {
+        super(message);
+        this.name = 'DurableOperationReplayIdentityConflictError';
+    }
+}
+const DEFAULT_MAX_AUTHORITATIVE_ENTRIES = 1_024;
+const POSITIVE_REVISION = /^[1-9]\d*$/;
+const NON_NEGATIVE_REVISION = /^(0|[1-9]\d*)$/;
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function requiredIdentityText(value) {
+    return typeof value === 'string' && value.trim() === value && value.length > 0 ? value : null;
+}
+function invalidResponse(message) {
+    throw new DurableOperationReplayInvalidResponseError(message);
+}
+function parseEntry(value, revisionMode) {
+    if (!isRecord(value))
+        invalidResponse();
+    const domain = requiredIdentityText(value.domain);
+    const entityId = requiredIdentityText(value.entityId);
+    const mutationKind = requiredIdentityText(value.mutationKind);
+    if (!domain || !entityId || !mutationKind)
+        invalidResponse();
+    const entry = { domain, entityId, mutationKind };
+    if (Object.prototype.hasOwnProperty.call(value, 'payload'))
+        entry.payload = value.payload;
+    if (revisionMode !== 'none') {
+        const entityRevision = requiredIdentityText(value.entityRevision);
+        const lifecycleRevision = requiredIdentityText(value.lifecycleRevision);
+        if (!entityRevision || !lifecycleRevision)
+            invalidResponse();
+        if (!POSITIVE_REVISION.test(entityRevision) || !NON_NEGATIVE_REVISION.test(lifecycleRevision)) {
+            invalidResponse();
+        }
+        if (revisionMode === 'both' && !POSITIVE_REVISION.test(lifecycleRevision))
+            invalidResponse();
+        entry.entityRevision = entityRevision;
+        entry.lifecycleRevision = lifecycleRevision;
+    }
+    return entry;
+}
+export function readDurableOperationReplay(input) {
+    let response;
+    try {
+        response = JSON.parse(input.responseJson);
+    }
+    catch {
+        invalidResponse();
+    }
+    if (!isRecord(response) || !requiredIdentityText(response.operationId))
+        invalidResponse();
+    if (response.operationId !== input.operationId)
+        throw new DurableOperationReplayIdentityConflictError();
+    const maxEntries = input.maxAuthoritativeEntries ?? DEFAULT_MAX_AUTHORITATIVE_ENTRIES;
+    if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) {
+        throw new TypeError('maxAuthoritativeEntries must be a positive safe integer.');
+    }
+    const authoritativeMode = input.authoritativeMode ?? 'single';
+    const hasMultipleEntries = Array.isArray(response.authoritative);
+    if ((authoritativeMode === 'multiple') !== hasMultipleEntries)
+        invalidResponse();
+    const rawEntries = hasMultipleEntries ? response.authoritative : [response.authoritative];
+    if (rawEntries.length < 1 || rawEntries.length > maxEntries)
+        invalidResponse();
+    const authoritativeEntries = rawEntries.map((entry) => parseEntry(entry, input.revisionMode));
+    const matches = authoritativeEntries.filter((entry) => (entry.domain === input.domain
+        && entry.mutationKind === input.mutationKind
+        && (input.entityId === undefined || entry.entityId === input.entityId)
+        && (input.predicate?.(entry, response) ?? true)));
+    if (matches.length === 0)
+        throw new DurableOperationReplayIdentityConflictError();
+    if (matches.length > 1)
+        invalidResponse('Committed durable operation response has ambiguous authoritative entries.');
+    const authoritative = matches[0];
+    if (input.requirePayload && (!Object.prototype.hasOwnProperty.call(authoritative, 'payload')
+        || !isRecord(authoritative.payload)))
+        invalidResponse();
+    if (input.revisionMode === 'none') {
+        return { response, authoritative, authoritativeEntries };
+    }
+    const entityRevision = authoritative.entityRevision;
+    const lifecycleRevision = authoritative.lifecycleRevision;
+    return {
+        response,
+        authoritative,
+        authoritativeEntries,
+        baseEntityRevision: (BigInt(entityRevision) - 1n).toString(),
+        baseLifecycleRevision: input.revisionMode === 'both'
+            ? (BigInt(lifecycleRevision) - 1n).toString()
+            : lifecycleRevision,
+    };
+}

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

@@ -0,0 +1,49 @@
+import type { TaskItem } from '../../core/Taskforce.js';
+import type { DatabaseAdapter } from '../../storage/databaseAdapter.js';
+import { type LocalTaskAttachmentLinksOutboxCore } from './localTaskAttachmentLinksOutboxService.js';
+import { type DurableTaskAttachmentLinksServiceCore } from './taskAttachmentLinksMutationService.js';
+import { type WorkspaceSyncV3TaskAttachmentLink } from './workspaceSyncV3NestedTaskCodecs.js';
+export declare function resolveTaskAttachmentLinksMutationCapability(input: {
+    runtimeMode: 'local' | 'cloud';
+    surface: 'http' | 'mcp';
+    env?: NodeJS.ProcessEnv;
+    readPersistedProjectionOwner?: () => 'v2' | 'v3';
+}): boolean;
+export type DurableTaskAttachmentLinksMutationRouterCore = DurableTaskAttachmentLinksServiceCore & LocalTaskAttachmentLinksOutboxCore & {
+    getDatabaseAdapter(): DatabaseAdapter;
+    getTask(id: string, workspaceId?: string): TaskItem | null;
+};
+export declare class DurableTaskAttachmentLinksRouterDisabledError extends Error {
+    readonly code = "WORKSPACE_SYNC_V3_TASK_ATTACHMENT_LINKS_ROUTER_DISABLED";
+    constructor();
+}
+export declare class DurableTaskAttachmentLinksRouterInProgressError extends Error {
+    readonly retryAt: string;
+    readonly code = "WORKSPACE_SYNC_OPERATION_IN_PROGRESS";
+    constructor(retryAt: string);
+}
+export declare function createDurableTaskAttachmentLinksMutationRouter(input: {
+    core: DurableTaskAttachmentLinksMutationRouterCore;
+    runtimeMode: 'local' | 'cloud';
+    surface: 'http' | 'mcp';
+    tenantId: string;
+    workspaceId: string;
+    actorRef: string;
+    env?: NodeJS.ProcessEnv;
+    cloudClientId?: string;
+    operationId?: string;
+    now?: () => Date;
+    onPostCommitError?: (error: unknown) => void;
+    deferPostCommitNotification?: (notify: () => void) => void;
+}): {
+    enabled: boolean;
+    replace(args: {
+        taskId: string;
+        links: readonly WorkspaceSyncV3TaskAttachmentLink[];
+    }): {
+        state: "pending" | "committed";
+        route: "local-outbox" | "cloud-acceptance";
+        operationId: string;
+        task: TaskItem;
+    };
+};

package/dist/sync/v3/durableTaskAttachmentLinksMutationRouter.js

@@ -0,0 +1,198 @@
+import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
+import { LocalSyncIdentityStore } from './localSyncIdentityStore.js';
+import { enqueueLocalTaskAttachmentLinksMutation, } from './localTaskAttachmentLinksOutboxService.js';
+import { DurableTaskAttachmentLinksMutationError, runDurableTaskAttachmentLinksReplace, } from './taskAttachmentLinksMutationService.js';
+import { WorkspaceSyncDurabilityStore, WorkspaceSyncEntityBusyError } from './syncDurabilityStore.js';
+import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
+const OPERATION_LEASE_MS = 30_000;
+function enabled(value) {
+    return /^(1|true|on|yes)$/i.test(String(value || '').trim());
+}
+export function resolveTaskAttachmentLinksMutationCapability(input) {
+    const env = input.env || process.env;
+    const activationKey = input.surface === 'http'
+        ? 'TASKFORCE_SYNC_V3_TASK_ATTACHMENT_LINKS_HTTP_ACTIVATION_ENABLED'
+        : 'TASKFORCE_SYNC_V3_TASK_ATTACHMENT_LINKS_MCP_ACTIVATION_ENABLED';
+    if (input.runtimeMode === 'local'
+        && input.surface === 'mcp'
+        && !Object.prototype.hasOwnProperty.call(env, activationKey)
+        && input.readPersistedProjectionOwner?.() === 'v3') {
+        return true;
+    }
+    const activation = env[activationKey];
+    if (!enabled(env.TASKFORCE_SYNC_V3_TASK_ATTACHMENT_LINKS_ENABLED) || !enabled(activation))
+        return false;
+    return input.runtimeMode === 'cloud' || (enabled(env.TASKFORCE_SYNC_V3_LOCAL_CAPTURE_ENABLED)
+        && enabled(env.TASKFORCE_SYNC_V3_LOCAL_DISPATCH_ENABLED)
+        && enabled(env.TASKFORCE_SYNC_V3_TASK_ATTACHMENT_LINKS_CAPTURE_ENABLED));
+}
+export class DurableTaskAttachmentLinksRouterDisabledError extends Error {
+    code = 'WORKSPACE_SYNC_V3_TASK_ATTACHMENT_LINKS_ROUTER_DISABLED';
+    constructor() {
+        super('Durable task attachment-link routing is disabled.');
+        this.name = 'DurableTaskAttachmentLinksRouterDisabledError';
+    }
+}
+export class DurableTaskAttachmentLinksRouterInProgressError extends Error {
+    retryAt;
+    code = 'WORKSPACE_SYNC_OPERATION_IN_PROGRESS';
+    constructor(retryAt) {
+        super('The durable task attachment-link mutation is already in progress.');
+        this.retryAt = retryAt;
+        this.name = 'DurableTaskAttachmentLinksRouterInProgressError';
+    }
+}
+function required(value, label) {
+    const text = String(value || '').trim();
+    if (!text)
+        throw new DurableTaskAttachmentLinksMutationError(`${label} is required.`, 'TASK_ATTACHMENT_LINKS_INVALID', 400);
+    return text;
+}
+function operationIdRequired(value) {
+    const operationId = String(value || '').trim();
+    if (!operationId)
+        throw new DurableTaskAttachmentLinksMutationError('x-taskforce-operation-id is required for durable task attachment links.', 'WORKSPACE_SYNC_OPERATION_ID_REQUIRED', 400);
+    return operationId;
+}
+export function createDurableTaskAttachmentLinksMutationRouter(input) {
+    const tenantId = required(input.tenantId, 'Tenant id');
+    const workspaceId = required(input.workspaceId, 'Workspace id');
+    const actorRef = required(input.actorRef, 'Actor ref');
+    const store = new WorkspaceSyncDurabilityStore(input.core.getDatabaseAdapter());
+    let persistedOwnershipChecked = false;
+    const isEnabled = resolveTaskAttachmentLinksMutationCapability({
+        ...input,
+        readPersistedProjectionOwner: () => {
+            persistedOwnershipChecked = true;
+            return store.readCombinedProjectionOwnership({ tenantId, workspaceId }).owner;
+        },
+    });
+    const identityStore = new LocalSyncIdentityStore(input.core.getDatabaseAdapter());
+    const now = input.now || (() => new Date());
+    const serviceCore = input.deferPostCommitNotification
+        ? new Proxy(input.core, {
+            get(target, property) {
+                const value = Reflect.get(target, property, target);
+                if (property === 'notifyDurableTaskMetadataCommitted' && typeof value === 'function') {
+                    return (...args) => input.deferPostCommitNotification?.(() => value.apply(target, args));
+                }
+                return typeof value === 'function' ? value.bind(target) : value;
+            },
+        })
+        : input.core;
+    return {
+        enabled: isEnabled,
+        replace(args) {
+            if (!isEnabled)
+                throw new DurableTaskAttachmentLinksRouterDisabledError();
+            const taskId = required(args.taskId, 'Task id');
+            let links;
+            try {
+                links = serializeWorkspaceSyncV3TaskAttachmentLinksPayload({ taskId, links: args.links }).links;
+            }
+            catch (error) {
+                throw new DurableTaskAttachmentLinksMutationError(error instanceof Error ? error.message : 'Task attachment links are invalid.', 'TASK_ATTACHMENT_LINKS_INVALID', 400);
+            }
+            const acceptedAt = now();
+            const acceptedAtIso = acceptedAt.toISOString();
+            const operationId = operationIdRequired(input.operationId);
+            const clientId = input.runtimeMode === 'local'
+                ? identityStore.getOrCreateClientId(acceptedAtIso)
+                : required(input.cloudClientId || `${input.surface}-cloud`, 'Cloud client id');
+            const identity = { tenantId, workspaceId, clientId, operationId };
+            if (input.runtimeMode === 'local') {
+                const existing = store.readOutboxOperation(identity);
+                if (existing) {
+                    if (existing.domain !== 'task-attachment-links' || existing.entityId !== taskId
+                        || existing.mutationKind !== 'replace') {
+                        throw new DurableTaskAttachmentLinksMutationError('Operation identity is assigned to another local mutation.', 'TASK_ATTACHMENT_LINKS_IDENTITY_CONFLICT', 409);
+                    }
+                    let payload;
+                    try {
+                        payload = JSON.parse(existing.payloadJson);
+                    }
+                    catch {
+                        throw new DurableTaskAttachmentLinksMutationError('Captured task attachment-link payload is invalid.', 'TASK_ATTACHMENT_LINKS_IDENTITY_CONFLICT', 409);
+                    }
+                    let frozen;
+                    try {
+                        frozen = serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
+                            taskId, links: payload.links || [],
+                        }).links;
+                    }
+                    catch {
+                        throw new DurableTaskAttachmentLinksMutationError('Captured task attachment-link payload is invalid.', 'TASK_ATTACHMENT_LINKS_IDENTITY_CONFLICT', 409);
+                    }
+                    if (canonicalWorkspaceSyncJson(frozen) !== canonicalWorkspaceSyncJson(links)) {
+                        throw new DurableTaskAttachmentLinksMutationError('Operation identity is assigned to different task attachment links.', 'TASK_ATTACHMENT_LINKS_IDENTITY_CONFLICT', 409);
+                    }
+                    const task = input.core.getTask(taskId, workspaceId);
+                    if (!task)
+                        throw new DurableTaskAttachmentLinksMutationError('Task not found.', 'TASK_NOT_FOUND', 404);
+                    const installed = input.core.listTaskAttachmentLinksForDurableSync(taskId, workspaceId);
+                    if (canonicalWorkspaceSyncJson(installed) !== canonicalWorkspaceSyncJson(frozen)) {
+                        throw new DurableTaskAttachmentLinksMutationError('Captured task attachment links do not match local state.', 'TASK_ATTACHMENT_LINKS_IDENTITY_CONFLICT', 409);
+                    }
+                    return { state: 'pending', route: 'local-outbox', operationId, task };
+                }
+                let result;
+                try {
+                    result = enqueueLocalTaskAttachmentLinksMutation({
+                        store, core: serviceCore, identity, taskId, links, now: acceptedAtIso,
+                        actorRef, onPostCommitError: input.onPostCommitError,
+                        requireV3CombinedOwnership: persistedOwnershipChecked,
+                    });
+                }
+                catch (error) {
+                    if (error instanceof WorkspaceSyncEntityBusyError)
+                        throw new DurableTaskAttachmentLinksMutationError('Another durable task operation must finish before replacing these attachment links.', 'TASK_ATTACHMENT_LINKS_DEPENDENCY_PENDING', 409, error.details, error.retryable, error.retryAfterAt, error.retryHint);
+                    throw error;
+                }
+                const task = result.task || input.core.getTask(taskId, workspaceId);
+                if (!task)
+                    throw new DurableTaskAttachmentLinksMutationError('Task not found.', 'TASK_NOT_FOUND', 404);
+                return { state: 'pending', route: 'local-outbox', operationId, task };
+            }
+            const committedResponseJson = store.readCommittedOperationResponse(identity);
+            let coordinates;
+            if (committedResponseJson) {
+                let response;
+                try {
+                    response = JSON.parse(committedResponseJson);
+                }
+                catch {
+                    throw new DurableTaskAttachmentLinksMutationError('Committed task attachment-link response is invalid.', 'TASK_ATTACHMENT_LINKS_IDENTITY_CONFLICT', 409);
+                }
+                const projection = response.authoritative?.attachmentLinks;
+                const acceptedRevision = String(projection?.entityRevision || '');
+                const lifecycleRevision = String(projection?.lifecycleRevision || '');
+                if (response.workspaceId !== workspaceId || response.clientId !== clientId
+                    || response.operationId !== operationId || projection?.entityId !== taskId
+                    || !/^[1-9]\d*$/.test(acceptedRevision) || !/^(0|[1-9]\d*)$/.test(lifecycleRevision)) {
+                    throw new DurableTaskAttachmentLinksMutationError('Committed task attachment-link response identity is invalid.', 'TASK_ATTACHMENT_LINKS_IDENTITY_CONFLICT', 409);
+                }
+                coordinates = {
+                    entityRevision: String(BigInt(acceptedRevision) - 1n),
+                    lifecycleRevision,
+                };
+            }
+            else {
+                coordinates = store.readEntityRevisionCoordinates({
+                    tenantId, workspaceId, domain: 'task-attachment-links', entityId: taskId,
+                });
+            }
+            const result = runDurableTaskAttachmentLinksReplace({
+                store, core: serviceCore, tenantId, workspaceId, clientId, operationId, taskId, links,
+                baseEntityRevision: coordinates.entityRevision, baseLifecycleRevision: coordinates.lifecycleRevision,
+                now: acceptedAtIso, leaseExpiresAt: new Date(acceptedAt.getTime() + OPERATION_LEASE_MS).toISOString(),
+                actorRef, onPostCommitError: input.onPostCommitError,
+            });
+            if (result.state === 'in_progress')
+                throw new DurableTaskAttachmentLinksRouterInProgressError(result.retryAt);
+            const task = input.core.getTask(taskId, workspaceId);
+            if (!task)
+                throw new DurableTaskAttachmentLinksMutationError('Task not found.', 'TASK_NOT_FOUND', 404);
+            return { state: 'committed', route: 'cloud-acceptance', operationId, task };
+        },
+    };
+}