@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/core/TaskActivityService.js

@@ -1,3 +1,65 @@
+import { isDeepStrictEqual } from 'node:util';
+export class EntityEventIdentityCollisionError extends Error {
+    code = 'ENTITY_EVENT_IDENTITY_COLLISION';
+    statusCode = 409;
+    constructor(eventId, mismatchedFields = []) {
+        super(`Entity event identity ${eventId} is already owned by another entity${mismatchedFields.length > 0
+            ? ` (mismatched: ${mismatchedFields.join(', ')})`
+            : ''}.`);
+        this.name = 'EntityEventIdentityCollisionError';
+    }
+}
+function mismatchedImmutableEntityEventFields(left, right) {
+    const fields = [];
+    for (const field of ['workspaceId', 'entityType', 'entityId', 'action', 'actor', 'actorType', 'createdAt']) {
+        if (left[field] !== right[field])
+            fields.push(field);
+    }
+    if (!isDeepStrictEqual(normalizeEntityEventDetails(left.details), normalizeEntityEventDetails(right.details))) {
+        fields.push('details');
+    }
+    return fields;
+}
+function sameImmutableEntityEvent(left, right) {
+    return left.id === right.id
+        && left.workspaceId === right.workspaceId
+        && left.entityType === right.entityType
+        && left.entityId === right.entityId
+        && left.action === right.action
+        && left.actor === right.actor
+        && left.actorType === right.actorType
+        && left.createdAt === right.createdAt
+        && isDeepStrictEqual(normalizeEntityEventDetails(left.details), normalizeEntityEventDetails(right.details));
+}
+function insertImmutableEntityEvent(deps, event, options) {
+    const result = deps.db.prepare(`
+        INSERT INTO entity_events (
+            id, tenant_id, workspace_id, entity_type, entity_id, action, actor, actor_type, details_json, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT (id) DO NOTHING
+    `).run(event.id, deps.tenantId, event.workspaceId, event.entityType, event.entityId, event.action, event.actor, event.actorType, JSON.stringify(normalizeEntityEventDetails(event.details)), event.createdAt);
+    if (Number(result?.changes || 0) === 1)
+        return;
+    const existing = getEntityEventForSyncService(deps, {
+        workspaceId: event.workspaceId,
+        eventId: event.id,
+    });
+    if (existing && sameImmutableEntityEvent(existing, event))
+        return;
+    if (existing && options?.allowAuthoritativeReplacement === true
+        && existing.workspaceId === event.workspaceId
+        && existing.entityType === event.entityType
+        && existing.entityId === event.entityId) {
+        const replaced = deps.db.prepare(`
+            UPDATE entity_events
+            SET action = ?, actor = ?, actor_type = ?, details_json = ?, created_at = ?
+            WHERE id = ? AND tenant_id = ? AND workspace_id = ? AND entity_type = ? AND entity_id = ?
+        `).run(event.action, event.actor, event.actorType, JSON.stringify(normalizeEntityEventDetails(event.details)), event.createdAt, event.id, deps.tenantId, event.workspaceId, event.entityType, event.entityId);
+        if (Number(replaced?.changes || 0) === 1)
+            return;
+    }
+    throw new EntityEventIdentityCollisionError(event.id, existing ? mismatchedImmutableEntityEventFields(existing, event) : []);
+}
 function normalizeEntityEventActor(deps, actorRef, workspaceId) {
     const actorProfile = deps.resolveWorkspaceActor(workspaceId, actorRef);
     const actor = String(actorRef || '').trim() || 'system';
@@ -132,15 +194,80 @@ export function listWorkspaceEntityEventsService(deps, workspaceId) {
     `).all(deps.tenantId, normalizedWorkspaceId);
     return rows.map((row) => mapEntityEventRow(deps, row));
 }
-export function listWorkspaceEntityEventsForSyncService(deps, workspaceId) {
+export function listWorkspaceEntityEventsForSyncService(deps, workspaceId, cursor = null, limit) {
     const normalizedWorkspaceId = deps.normalizeWorkspaceId(workspaceId);
-    const rows = deps.db.prepare(`
-        SELECT id, workspace_id, entity_type, entity_id, action, actor, actor_type, details_json, created_at
-        FROM entity_events
-        WHERE tenant_id = ?
-          AND workspace_id = ?
-        ORDER BY created_at ASC, id ASC
-    `).all(deps.tenantId, normalizedWorkspaceId);
+    const normalizedLimit = Number.isFinite(limit) && Number(limit) > 0
+        ? Math.max(1, Math.floor(Number(limit)))
+        : null;
+    const eventSortIdSql = `CASE
+            WHEN entity_type = 'task' THEN 'task-event:' || id
+            ELSE entity_type || ':' || entity_id || ':event:' || id
+        END`;
+    const eventSortIdWithCollationSql = deps.db.provider === 'postgres'
+        ? `(${eventSortIdSql}) COLLATE "C"`
+        : `(${eventSortIdSql}) COLLATE BINARY`;
+    // Task activity belongs in the live feed only while its task exists. This
+    // remains correct after Trash retention/permanent purge removes the
+    // deleted_tasks record: an absent task must not make its old events live.
+    // If the task is restored, a cursorless reconciliation can backfill the
+    // original history while the new restore event advances incremental sync.
+    const liveEntityEventSql = `(
+        entity_type <> 'task'
+        OR EXISTS (
+            SELECT 1
+            FROM tasks
+            WHERE tasks.tenant_id = entity_events.tenant_id
+              AND tasks.workspace_id = entity_events.workspace_id
+              AND tasks.id = entity_events.entity_id
+        )
+    )`;
+    let rows;
+    if (cursor) {
+        const limitSql = normalizedLimit === null ? '' : 'LIMIT ?';
+        const params = [
+            deps.tenantId,
+            normalizedWorkspaceId,
+            cursor.watermark,
+            cursor.watermark,
+            cursor.id,
+        ];
+        if (normalizedLimit !== null)
+            params.push(normalizedLimit);
+        rows = deps.db.prepare(`
+            SELECT id, workspace_id, entity_type, entity_id, action, actor, actor_type, details_json, created_at
+            FROM entity_events
+            WHERE tenant_id = ?
+              AND workspace_id = ?
+              AND ${liveEntityEventSql}
+              AND (
+                  created_at > ?
+                  OR (created_at = ? AND ${eventSortIdWithCollationSql} > ?)
+              )
+            ORDER BY created_at ASC, ${eventSortIdWithCollationSql} ASC
+            ${limitSql}
+        `).all(...params);
+    }
+    else if (normalizedLimit !== null) {
+        rows = deps.db.prepare(`
+            SELECT id, workspace_id, entity_type, entity_id, action, actor, actor_type, details_json, created_at
+            FROM entity_events
+            WHERE tenant_id = ?
+              AND workspace_id = ?
+              AND ${liveEntityEventSql}
+            ORDER BY created_at ASC, ${eventSortIdWithCollationSql} ASC
+            LIMIT ?
+        `).all(deps.tenantId, normalizedWorkspaceId, normalizedLimit);
+    }
+    else {
+        rows = deps.db.prepare(`
+            SELECT id, workspace_id, entity_type, entity_id, action, actor, actor_type, details_json, created_at
+            FROM entity_events
+            WHERE tenant_id = ?
+              AND workspace_id = ?
+              AND ${liveEntityEventSql}
+            ORDER BY created_at ASC, id ASC
+        `).all(deps.tenantId, normalizedWorkspaceId);
+    }
     return rows.map((row) => mapEntityEventSyncRow(deps, row));
 }
 export function listWorkspaceTaskEventsForSyncService(deps, workspaceId) {
@@ -245,7 +372,12 @@ export function buildEntityActivityService(comments, entityEvents, options) {
     });
 }
 export function buildTaskActivityService(comments, taskEvents) {
-    return buildEntityActivityService(comments, taskEvents, {
+    const visibleTaskEvents = taskEvents.filter((event) => {
+        if (event.action !== 'task-updated' || event.details?.saveSource !== 'autosave')
+            return true;
+        return Object.keys(event.details?.changes || {}).length > 0;
+    });
+    return buildEntityActivityService(comments, visibleTaskEvents, {
         hiddenActions: ['task-comment-added']
     });
 }
@@ -260,11 +392,20 @@ export function addEntityEventService(deps, input) {
     const workspaceId = deps.normalizeWorkspaceId(input.workspaceId);
     const createdAt = String(input.createdAt || '').trim() || new Date().toISOString();
     const { actor, actorType } = normalizeEntityEventActor(deps, input.actor, workspaceId);
-    deps.db.prepare(`
-        INSERT INTO entity_events (
-            id, tenant_id, workspace_id, entity_type, entity_id, action, actor, actor_type, details_json, created_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(deps.generateEntityId('entity-event'), deps.tenantId, workspaceId, entityType, entityId, action, actor, actorType, JSON.stringify(normalizeEntityEventDetails(input.details)), createdAt);
+    const eventId = String(input.eventId || '').trim() || deps.generateEntityId('entity-event');
+    insertImmutableEntityEvent(deps, {
+        id: eventId,
+        workspaceId,
+        entityType,
+        entityId,
+        ...(entityType === 'task' ? { taskId: entityId } : {}),
+        action,
+        actor,
+        actorType,
+        details: normalizeEntityEventDetails(input.details),
+        createdAt,
+        actorProfile: null,
+    }, { allowAuthoritativeReplacement: input.allowAuthoritativeReplacement });
 }
 export function addTaskEventService(deps, input) {
     addEntityEventService(deps, {
@@ -273,8 +414,10 @@ export function addTaskEventService(deps, input) {
         workspaceId: input.workspaceId,
         action: input.action,
         actor: input.actor,
+        eventId: input.eventId,
         createdAt: input.createdAt,
         details: input.details,
+        allowAuthoritativeReplacement: input.allowAuthoritativeReplacement,
     });
 }
 export function replaceEntityEventsService(deps, entityType, entityId, workspaceId, entityEvents) {
@@ -300,7 +443,7 @@ export function replaceTaskEventsService(deps, taskId, workspaceId, taskEvents)
         taskId: String(event.taskId || taskId).trim(),
     })));
 }
-export function upsertEntityEventForSyncService(deps, event) {
+export function upsertEntityEventForSyncService(deps, event, options) {
     const workspaceId = deps.normalizeWorkspaceId(event.workspaceId);
     const entityType = normalizeEntityType(event.entityType);
     const normalizedEvent = {
@@ -316,20 +459,11 @@ export function upsertEntityEventForSyncService(deps, event) {
         createdAt: String(event.createdAt || '').trim() || new Date().toISOString(),
         details: normalizeEntityEventDetails(event.details)
     };
-    deps.db.prepare(`
-        INSERT INTO entity_events (
-            id, tenant_id, workspace_id, entity_type, entity_id, action, actor, actor_type, details_json, created_at
-        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-        ON CONFLICT (id) DO UPDATE SET
-            workspace_id = excluded.workspace_id,
-            entity_type = excluded.entity_type,
-            entity_id = excluded.entity_id,
-            action = excluded.action,
-            actor = excluded.actor,
-            actor_type = excluded.actor_type,
-            details_json = excluded.details_json,
-            created_at = excluded.created_at
-    `).run(normalizedEvent.id, deps.tenantId, workspaceId, normalizedEvent.entityType, normalizedEvent.entityId, normalizedEvent.action, normalizedEvent.actor, normalizedEvent.actorType, JSON.stringify(normalizedEvent.details), normalizedEvent.createdAt);
+    insertImmutableEntityEvent(deps, {
+        ...normalizedEvent,
+        ...(normalizedEvent.entityType === 'task' ? { taskId: normalizedEvent.entityId } : {}),
+        actorProfile: null,
+    }, options);
     const actorProfile = normalizedEvent.actor === 'system'
         ? null
         : deps.resolveWorkspaceActor(workspaceId, normalizedEvent.actor);
@@ -347,6 +481,20 @@ export function upsertEntityEventForSyncService(deps, event) {
         actorProfile,
     };
 }
+export function deleteEntityEventForSyncService(deps, input) {
+    const workspaceId = deps.normalizeWorkspaceId(input.workspaceId);
+    const eventId = String(input.eventId || '').trim();
+    const entityType = normalizeEntityType(input.entityType);
+    const entityId = String(input.entityId || '').trim();
+    if (!eventId || !entityId)
+        return false;
+    const result = deps.db.prepare(`
+        DELETE FROM entity_events
+        WHERE id = ? AND tenant_id = ? AND workspace_id = ?
+          AND entity_type = ? AND entity_id = ?
+    `).run(eventId, deps.tenantId, workspaceId, entityType, entityId);
+    return Number(result.changes || 0) === 1;
+}
 export function upsertTaskEventForSyncService(deps, event) {
     return upsertEntityEventForSyncService(deps, {
         ...event,

package/dist/core/TaskAttachmentLinksDurableMutationService.d.ts

@@ -0,0 +1,36 @@
+import type { AttachmentItem } from './Taskforce.js';
+import type { WorkspaceAssetStore } from '../storage/workspaceAssetStore.js';
+import type { WorkspaceSyncV3TaskAttachmentLink } from '../sync/v3/workspaceSyncV3NestedTaskCodecs.js';
+export declare class DurableTaskAttachmentLinksApplyError extends Error {
+    readonly code: 'TASK_ATTACHMENT_ASSET_NOT_READY' | 'TASK_ATTACHMENT_ASSET_INVALID' | 'TASK_ATTACHMENT_LINK_INVALID';
+    readonly statusCode: number;
+    readonly assetId?: string | undefined;
+    constructor(message: string, code: 'TASK_ATTACHMENT_ASSET_NOT_READY' | 'TASK_ATTACHMENT_ASSET_INVALID' | 'TASK_ATTACHMENT_LINK_INVALID', statusCode: number, assetId?: string | undefined);
+}
+export interface DurableTaskAttachmentLinksCore {
+    getWorkspaceAssetStore(): Pick<WorkspaceAssetStore, 'get' | 'listLinksForTask' | 'adoptReadableReferenceNumber'>;
+    getWorkspaceAssetDispatchReadiness(assetId: string, workspaceId: string): {
+        ready: boolean;
+        retryable: boolean;
+        reason: string;
+    };
+}
+export interface DurableWorkspaceTaskAttachmentLinksCore extends DurableTaskAttachmentLinksCore {
+    getWorkspaceAssetStore(): Pick<WorkspaceAssetStore, 'get' | 'listLinksForTask' | 'listLinksForWorkspace' | 'listAllNormalizedByWorkspace' | 'adoptReadableReferenceNumber'>;
+}
+export declare function resolveTaskCardCoverAssetIdForLinks(input: {
+    currentCardCoverAssetId?: string | null;
+    requestedCardCoverAssetId?: string | null;
+    links: readonly WorkspaceSyncV3TaskAttachmentLink[];
+}): string | null;
+export declare function listTaskAttachmentLinksForDurableSync(core: DurableTaskAttachmentLinksCore, workspaceId: string, taskId: string): WorkspaceSyncV3TaskAttachmentLink[];
+export declare function listWorkspaceTaskAttachmentLinksForDurableSync(core: DurableWorkspaceTaskAttachmentLinksCore, workspaceId: string, taskIds: ReadonlySet<string>): Map<string, WorkspaceSyncV3TaskAttachmentLink[]>;
+export declare function resolveTaskAttachmentLinksForDurableSync(core: DurableTaskAttachmentLinksCore, workspaceId: string, links: readonly WorkspaceSyncV3TaskAttachmentLink[], options?: {
+    requireDispatchReady?: boolean;
+    adoptAuthoritativeReferenceNumber?: boolean;
+    ignoreAssetMetadataSnapshots?: boolean;
+}): AttachmentItem[];
+export declare function normalizeTaskAttachmentDescriptorsForDurableSync(core: DurableTaskAttachmentLinksCore, workspaceId: string, attachments: readonly AttachmentItem[], options?: {
+    requireDispatchReady?: boolean;
+}): WorkspaceSyncV3TaskAttachmentLink[];
+export declare function projectResolvedTaskAttachmentLinksForDurableSync(attachments: readonly AttachmentItem[]): WorkspaceSyncV3TaskAttachmentLink[];

package/dist/core/TaskAttachmentLinksDurableMutationService.js

@@ -0,0 +1,240 @@
+import { getDocumentReferenceLabel } from '../utils/documentReferences.js';
+import { getImageReferenceLabel } from '../utils/imageReferences.js';
+export class DurableTaskAttachmentLinksApplyError extends Error {
+    code;
+    statusCode;
+    assetId;
+    constructor(message, code, statusCode, assetId) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.assetId = assetId;
+        this.name = 'DurableTaskAttachmentLinksApplyError';
+    }
+}
+export function resolveTaskCardCoverAssetIdForLinks(input) {
+    const explicitlyRequested = Object.prototype.hasOwnProperty.call(input, 'requestedCardCoverAssetId');
+    const candidate = explicitlyRequested
+        ? String(input.requestedCardCoverAssetId || '').trim()
+        : String(input.currentCardCoverAssetId || '').trim();
+    if (!candidate)
+        return null;
+    const matchingImage = input.links.some((link) => link.assetId === candidate && link.role === 'image');
+    if (!matchingImage && explicitlyRequested) {
+        throw new DurableTaskAttachmentLinksApplyError('Task card cover must reference an image already attached to this task.', 'TASK_ATTACHMENT_LINK_INVALID', 400, candidate);
+    }
+    return matchingImage ? candidate : null;
+}
+function fail(message, code, statusCode, assetId) {
+    throw new DurableTaskAttachmentLinksApplyError(message, code, statusCode, assetId);
+}
+function canonicalAssetPath(asset) {
+    if (asset.storageProvider === 'external') {
+        return /^https?:\/\//i.test(asset.storageKey)
+            ? asset.storageKey
+            : `/api/taskforce/context-link?path=${encodeURIComponent(asset.storageKey)}`;
+    }
+    return asset.kind === 'document'
+        ? `/api/taskforce/documents/${encodeURIComponent(asset.assetId)}/content`
+        : `/api/taskforce/context/${encodeURIComponent(asset.storageKey)}`;
+}
+function canonicalRole(asset, requested) {
+    if (asset.storageProvider === 'external') {
+        if (requested !== 'reference') {
+            fail(`External task attachment asset ${asset.assetId} must use the reference role.`, 'TASK_ATTACHMENT_LINK_INVALID', 400);
+        }
+        return 'reference';
+    }
+    if (requested === 'reference')
+        return 'reference';
+    const expected = asset.kind === 'image' ? 'image' : 'attachment';
+    if (requested !== expected) {
+        fail(`Task attachment role ${requested} does not match asset ${asset.assetId}.`, 'TASK_ATTACHMENT_LINK_INVALID', 400);
+    }
+    return expected;
+}
+function referenceFields(asset) {
+    if (!asset.referenceNumber)
+        return { referenceNumber: null, referenceLabel: null };
+    const referenceLabel = asset.kind === 'document'
+        ? getDocumentReferenceLabel({ referenceNumber: asset.referenceNumber })
+        : asset.kind === 'image'
+            ? getImageReferenceLabel({ referenceNumber: asset.referenceNumber })
+            : null;
+    return { referenceNumber: asset.referenceNumber, referenceLabel: referenceLabel || null };
+}
+function assertReady(core, workspaceId, asset, options) {
+    if (asset.deletedAt) {
+        fail(`Task attachment asset is unavailable: ${asset.assetId}`, 'TASK_ATTACHMENT_ASSET_INVALID', 400);
+    }
+    if (asset.scanStatus === 'infected' || asset.scanStatus === 'failed') {
+        fail(`Task attachment asset failed its readiness check: ${asset.assetId}`, 'TASK_ATTACHMENT_ASSET_INVALID', 400);
+    }
+    if (asset.scanStatus === 'pending') {
+        if (options?.requireDispatchReady === false)
+            return;
+        fail(`Task attachment asset scan is not complete: ${asset.assetId}`, 'TASK_ATTACHMENT_ASSET_NOT_READY', 425);
+    }
+    if (options?.requireDispatchReady === false)
+        return;
+    const readiness = core.getWorkspaceAssetDispatchReadiness(asset.assetId, workspaceId);
+    if (!readiness.ready) {
+        fail(readiness.reason || `Task attachment asset is not ready: ${asset.assetId}`, readiness.retryable ? 'TASK_ATTACHMENT_ASSET_NOT_READY' : 'TASK_ATTACHMENT_ASSET_INVALID', readiness.retryable ? 425 : 400);
+    }
+}
+function canonicalLink(asset, link, fallbackOrder) {
+    return {
+        assetId: asset.assetId,
+        role: link.role,
+        order: Number.isSafeInteger(link.sortOrder) && Number(link.sortOrder) >= 0
+            ? Number(link.sortOrder)
+            : fallbackOrder,
+        ...(link.displayName ? { displayName: link.displayName } : {}),
+        ...(asset.logicalName ? { caption: asset.logicalName } : {}),
+        ...(asset.originalFilename ? { originalFilename: asset.originalFilename } : {}),
+        ...referenceFields(asset),
+    };
+}
+export function listTaskAttachmentLinksForDurableSync(core, workspaceId, taskId) {
+    const store = core.getWorkspaceAssetStore();
+    return store.listLinksForTask(taskId, workspaceId)
+        .map((link, index) => {
+        const asset = store.get(link.assetId, workspaceId);
+        if (!asset) {
+            fail(`Task attachment asset is unavailable because it has not reached this runtime: ${link.assetId}`, 'TASK_ATTACHMENT_ASSET_NOT_READY', 425, link.assetId);
+        }
+        if (asset.deletedAt) {
+            fail(`Task attachment asset is deleted: ${link.assetId}`, 'TASK_ATTACHMENT_ASSET_INVALID', 400);
+        }
+        assertReady(core, workspaceId, asset);
+        return canonicalLink(asset, link, index);
+    })
+        .sort((left, right) => left.order - right.order
+        || (left.assetId < right.assetId ? -1 : left.assetId > right.assetId ? 1 : 0)
+        || (left.role < right.role ? -1 : left.role > right.role ? 1 : 0))
+        .map((link, order) => ({ ...link, order }));
+}
+export function listWorkspaceTaskAttachmentLinksForDurableSync(core, workspaceId, taskIds) {
+    const store = core.getWorkspaceAssetStore();
+    const assets = new Map(store.listAllNormalizedByWorkspace(workspaceId, { includeDeleted: true })
+        .map((asset) => [asset.assetId, asset]));
+    const persistedLinksByTaskId = new Map(Array.from(taskIds, (taskId) => [taskId, []]));
+    for (const link of store.listLinksForWorkspace(workspaceId)) {
+        if (link.targetType !== 'task' || !taskIds.has(link.targetId))
+            continue;
+        persistedLinksByTaskId.get(link.targetId).push(link);
+    }
+    const linksByTaskId = new Map();
+    for (const [taskId, persistedLinks] of persistedLinksByTaskId) {
+        persistedLinks.sort((left, right) => (left.sortOrder ?? Number.MAX_SAFE_INTEGER)
+            - (right.sortOrder ?? Number.MAX_SAFE_INTEGER)
+            || (left.createdAt < right.createdAt ? -1 : left.createdAt > right.createdAt ? 1 : 0)
+            || (left.assetId < right.assetId ? -1 : left.assetId > right.assetId ? 1 : 0));
+        const links = persistedLinks.map((link, index) => {
+            const asset = assets.get(link.assetId);
+            if (!asset) {
+                fail(`Task attachment asset is unavailable because it has not reached this runtime: ${link.assetId}`, 'TASK_ATTACHMENT_ASSET_NOT_READY', 425, link.assetId);
+            }
+            if (asset.deletedAt) {
+                fail(`Task attachment asset is deleted: ${link.assetId}`, 'TASK_ATTACHMENT_ASSET_INVALID', 400);
+            }
+            assertReady(core, workspaceId, asset);
+            return canonicalLink(asset, link, index);
+        }).sort((left, right) => left.order - right.order
+            || (left.assetId < right.assetId ? -1 : left.assetId > right.assetId ? 1 : 0)
+            || (left.role < right.role ? -1 : left.role > right.role ? 1 : 0))
+            .map((link, order) => ({ ...link, order }));
+        linksByTaskId.set(taskId, links);
+    }
+    return linksByTaskId;
+}
+export function resolveTaskAttachmentLinksForDurableSync(core, workspaceId, links, options) {
+    const store = core.getWorkspaceAssetStore();
+    const identities = new Set();
+    return links.map((link, index) => {
+        let asset = store.get(link.assetId, workspaceId);
+        if (!asset) {
+            fail(`Task attachment asset is unavailable because it has not reached this runtime: ${link.assetId}`, 'TASK_ATTACHMENT_ASSET_NOT_READY', 425, link.assetId);
+        }
+        assertReady(core, workspaceId, asset, options);
+        // Replicated apply may align independently hydrated local D-/I- numbers
+        // to cloud authority. Ordinary local/cloud mutation writers must never
+        // adopt a caller-provided reference number.
+        if (options?.adoptAuthoritativeReferenceNumber === true
+            && options?.ignoreAssetMetadataSnapshots !== true
+            && link.referenceNumber != null
+            && asset.referenceNumber !== link.referenceNumber) {
+            asset = store.adoptReadableReferenceNumber(workspaceId, asset.assetId, link.referenceNumber);
+        }
+        const role = canonicalRole(asset, link.role);
+        const identity = `${asset.assetId}\u0000${role}`;
+        if (identities.has(identity)) {
+            fail('Task attachment links must have unique asset and role identities.', 'TASK_ATTACHMENT_LINK_INVALID', 400);
+        }
+        identities.add(identity);
+        const displayName = String(link.displayName
+            || (options?.ignoreAssetMetadataSnapshots === true ? '' : link.originalFilename)
+            || (options?.ignoreAssetMetadataSnapshots === true ? '' : link.caption)
+            || asset.originalFilename
+            || asset.logicalName).trim() || null;
+        const projected = canonicalLink(asset, { role, displayName, sortOrder: index }, index);
+        if (options?.ignoreAssetMetadataSnapshots !== true
+            && ((link.referenceNumber ?? null) !== (projected.referenceNumber ?? null)
+                || (link.referenceLabel ?? null) !== (projected.referenceLabel ?? null))) {
+            fail(`Task attachment reference metadata does not match asset ${asset.assetId}.`, 'TASK_ATTACHMENT_LINK_INVALID', 400);
+        }
+        return {
+            path: canonicalAssetPath(asset),
+            assetId: asset.assetId,
+            linkRole: role,
+            ...(asset.kind === 'document' && asset.storageProvider !== 'external' && projected.caption !== undefined
+                ? { caption: projected.caption } : {}),
+            ...(projected.displayName !== undefined ? { displayName: projected.displayName } : {}),
+            ...(projected.originalFilename !== undefined ? { originalFilename: projected.originalFilename } : {}),
+            ...(projected.referenceNumber !== undefined ? { referenceNumber: projected.referenceNumber } : {}),
+            ...(projected.referenceLabel !== undefined ? { referenceLabel: projected.referenceLabel } : {}),
+        };
+    });
+}
+export function normalizeTaskAttachmentDescriptorsForDurableSync(core, workspaceId, attachments, options) {
+    const store = core.getWorkspaceAssetStore();
+    const identities = new Set();
+    return attachments.map((attachment, order) => {
+        if (typeof attachment === 'string' || !attachment.assetId) {
+            fail('Task attachment is missing its durable asset identity.', 'TASK_ATTACHMENT_LINK_INVALID', 400);
+        }
+        const asset = store.get(attachment.assetId, workspaceId);
+        if (!asset) {
+            fail(`Task attachment asset is unavailable because it has not reached this runtime: ${attachment.assetId}`, 'TASK_ATTACHMENT_ASSET_NOT_READY', 425);
+        }
+        assertReady(core, workspaceId, asset, options);
+        const inferredRole = attachment.linkRole
+            || (asset.storageProvider === 'external' ? 'reference' : asset.kind === 'image' ? 'image' : 'attachment');
+        const role = canonicalRole(asset, inferredRole);
+        const identity = `${asset.assetId}\u0000${role}`;
+        if (identities.has(identity)) {
+            fail('Task attachment links must have unique asset and role identities.', 'TASK_ATTACHMENT_LINK_INVALID', 400);
+        }
+        identities.add(identity);
+        const displayName = String(attachment.displayName || attachment.originalFilename || attachment.caption
+            || asset.logicalName || asset.originalFilename).trim() || null;
+        return canonicalLink(asset, { role, displayName, sortOrder: order }, order);
+    });
+}
+export function projectResolvedTaskAttachmentLinksForDurableSync(attachments) {
+    return attachments.map((attachment, order) => {
+        if (typeof attachment === 'string' || !attachment.assetId || !attachment.linkRole) {
+            fail('Resolved task attachment is missing its durable identity.', 'TASK_ATTACHMENT_LINK_INVALID', 400);
+        }
+        return {
+            assetId: attachment.assetId,
+            role: attachment.linkRole,
+            order,
+            ...(attachment.caption !== undefined ? { caption: attachment.caption } : {}),
+            ...(attachment.displayName !== undefined ? { displayName: attachment.displayName } : {}),
+            ...(attachment.originalFilename !== undefined ? { originalFilename: attachment.originalFilename } : {}),
+            ...(attachment.referenceNumber !== undefined ? { referenceNumber: attachment.referenceNumber } : {}),
+            ...(attachment.referenceLabel !== undefined ? { referenceLabel: attachment.referenceLabel } : {}),
+        };
+    });
+}

package/dist/core/TaskChecklistCommandService.d.ts

@@ -0,0 +1,50 @@
+export interface TaskChecklistItem {
+    id: string;
+    taskId: string;
+    title: string;
+    isCompleted: boolean;
+    order: number;
+    createdAt: string;
+    updatedAt?: string;
+}
+export interface TaskChecklistTask {
+    id: string;
+}
+export interface TaskChecklistReplaceMutation {
+    taskId: string;
+    items: TaskChecklistItem[];
+    operationId: string;
+}
+export interface TaskChecklistCommandServiceDependencies {
+    resolveTask(identifier: unknown): TaskChecklistTask;
+    listItems(taskId: string): TaskChecklistItem[];
+    createId(scope: 'checklist' | 'operation', key: string): string;
+    now(): string;
+    replace(input: TaskChecklistReplaceMutation): TaskChecklistTask | null;
+}
+export declare class TaskChecklistCommandError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code?: string, statusCode?: number, details?: Record<string, unknown>);
+}
+export type ReplaceTaskChecklistCommandResult = {
+    taskId: string;
+    items: TaskChecklistItem[];
+};
+export type AddTaskChecklistItemCommandResult = ReplaceTaskChecklistCommandResult & {
+    item: TaskChecklistItem | null;
+};
+export declare function createTaskChecklistCommandService(deps: TaskChecklistCommandServiceDependencies): {
+    replace(input: {
+        taskId: unknown;
+        items: unknown;
+    }): ReplaceTaskChecklistCommandResult;
+    add(input: {
+        taskId: unknown;
+        title?: unknown;
+        text?: unknown;
+        isCompleted?: unknown;
+        done?: unknown;
+    }): AddTaskChecklistItemCommandResult;
+};