@taskforcehq/taskforce 0.3.328 → 0.3.330

package/dist/sync/v3/workspaceSyncV3CombinedWireContract.js

@@ -1,6 +1,8 @@
 import { WORKSPACE_SYNC_V3_NESTED_COVERAGE_SELECTOR, WORKSPACE_SYNC_V3_NESTED_EXCLUDED_V2_PROJECTIONS, } from './workspaceSyncV3NestedWireContract.js';
 import { WORKSPACE_SYNC_V3_WORKFLOW_COVERAGE_SELECTOR, WORKSPACE_SYNC_V3_WORKFLOW_EXCLUDED_V2_PROJECTIONS, } from './workspaceSyncV3WorkflowWireContract.js';
 import { WORKSPACE_SYNC_V3_PLANNING_ORDER_COVERAGE_SELECTOR, WORKSPACE_SYNC_V3_PLANNING_ORDER_EXCLUDED_V2_PROJECTIONS, } from './workspaceSyncV3PlanningOrderWireContract.js';
+import { WORKSPACE_SYNC_V3_TASK_COVER_COVERAGE_SELECTOR, WORKSPACE_SYNC_V3_TASK_COVER_EXCLUDED_V2_PROJECTIONS, } from './workspaceSyncV3TaskCoverWireContract.js';
+import { WORKSPACE_SYNC_V3_WORKFLOW_TASK_COVER_COVERAGE_SELECTOR, WORKSPACE_SYNC_V3_WORKFLOW_TASK_COVER_EXCLUDED_V2_PROJECTIONS, } from './workspaceSyncV3WorkflowTaskCoverWireContract.js';
 export const WORKSPACE_SYNC_V3_COMBINED_COVERAGE_SELECTOR = Object.freeze({
     coverageProfileId: 'task-planning-metadata',
     coverageVersion: 3,
@@ -27,6 +29,7 @@ export function resolveWorkspaceSyncV3CombinedWireContract(input) {
             nestedWriterPrerequisitesRequired: false,
             workflowWriterPrerequisitesRequired: false,
             planningOrderWriterPrerequisitesRequired: false,
+            taskCoverProjectionRequired: false,
         };
     }
     if (profileId === WORKSPACE_SYNC_V3_NESTED_COVERAGE_SELECTOR.coverageProfileId
@@ -38,6 +41,7 @@ export function resolveWorkspaceSyncV3CombinedWireContract(input) {
             nestedWriterPrerequisitesRequired: true,
             workflowWriterPrerequisitesRequired: false,
             planningOrderWriterPrerequisitesRequired: false,
+            taskCoverProjectionRequired: false,
         };
     }
     if (profileId === WORKSPACE_SYNC_V3_WORKFLOW_COVERAGE_SELECTOR.coverageProfileId
@@ -49,6 +53,7 @@ export function resolveWorkspaceSyncV3CombinedWireContract(input) {
             nestedWriterPrerequisitesRequired: true,
             workflowWriterPrerequisitesRequired: true,
             planningOrderWriterPrerequisitesRequired: false,
+            taskCoverProjectionRequired: false,
         };
     }
     if (profileId === WORKSPACE_SYNC_V3_PLANNING_ORDER_COVERAGE_SELECTOR.coverageProfileId
@@ -60,16 +65,45 @@ export function resolveWorkspaceSyncV3CombinedWireContract(input) {
             nestedWriterPrerequisitesRequired: true,
             workflowWriterPrerequisitesRequired: false,
             planningOrderWriterPrerequisitesRequired: true,
+            taskCoverProjectionRequired: false,
+        };
+    }
+    if (profileId === WORKSPACE_SYNC_V3_TASK_COVER_COVERAGE_SELECTOR.coverageProfileId
+        && version === WORKSPACE_SYNC_V3_TASK_COVER_COVERAGE_SELECTOR.coverageVersion
+        && digest === WORKSPACE_SYNC_V3_TASK_COVER_COVERAGE_SELECTOR.coverageDigest) {
+        return {
+            coverage: WORKSPACE_SYNC_V3_TASK_COVER_COVERAGE_SELECTOR,
+            excludedProjections: WORKSPACE_SYNC_V3_TASK_COVER_EXCLUDED_V2_PROJECTIONS,
+            nestedWriterPrerequisitesRequired: true,
+            workflowWriterPrerequisitesRequired: false,
+            planningOrderWriterPrerequisitesRequired: false,
+            taskCoverProjectionRequired: true,
+        };
+    }
+    if (profileId === WORKSPACE_SYNC_V3_WORKFLOW_TASK_COVER_COVERAGE_SELECTOR.coverageProfileId
+        && version === WORKSPACE_SYNC_V3_WORKFLOW_TASK_COVER_COVERAGE_SELECTOR.coverageVersion
+        && digest === WORKSPACE_SYNC_V3_WORKFLOW_TASK_COVER_COVERAGE_SELECTOR.coverageDigest) {
+        return {
+            coverage: WORKSPACE_SYNC_V3_WORKFLOW_TASK_COVER_COVERAGE_SELECTOR,
+            excludedProjections: WORKSPACE_SYNC_V3_WORKFLOW_TASK_COVER_EXCLUDED_V2_PROJECTIONS,
+            nestedWriterPrerequisitesRequired: true,
+            workflowWriterPrerequisitesRequired: true,
+            planningOrderWriterPrerequisitesRequired: false,
+            taskCoverProjectionRequired: true,
         };
     }
     return null;
 }
 export function resolveWorkspaceSyncV3CombinedCoverageForExclusions(exclusions) {
+    // V8 deliberately shares V7's v2 exclusions. Exclusions alone therefore
+    // identify the active V7 boundary; V8 activation must carry its exact
+    // persisted selector instead of using this legacy reverse lookup.
     for (const coverage of [
         WORKSPACE_SYNC_V3_COMBINED_COVERAGE_SELECTOR,
         WORKSPACE_SYNC_V3_NESTED_COVERAGE_SELECTOR,
         WORKSPACE_SYNC_V3_WORKFLOW_COVERAGE_SELECTOR,
         WORKSPACE_SYNC_V3_PLANNING_ORDER_COVERAGE_SELECTOR,
+        WORKSPACE_SYNC_V3_TASK_COVER_COVERAGE_SELECTOR,
     ]) {
         const contract = resolveWorkspaceSyncV3CombinedWireContract(coverage);
         if (exclusions.length === contract.excludedProjections.length

package/dist/sync/v3/workspaceSyncV3CoverageRegistry.js

@@ -2,6 +2,8 @@ import { WORKSPACE_SYNC_V3_COMBINED_COVERAGE_POLICY, WORKSPACE_SYNC_V3_COMBINED_
 import { WORKSPACE_SYNC_V3_NESTED_COVERAGE_POLICY, WORKSPACE_SYNC_V3_NESTED_COVERAGE_PROFILE, validateWorkspaceSyncV3NestedCoverageFeedEntry, } from './workspaceSyncV3NestedCoverage.js';
 import { WORKSPACE_SYNC_V3_WORKFLOW_COVERAGE_POLICY, WORKSPACE_SYNC_V3_WORKFLOW_COVERAGE_PROFILE, validateWorkspaceSyncV3WorkflowCoverageFeedEntry, } from './workspaceSyncV3WorkflowCoverage.js';
 import { WORKSPACE_SYNC_V3_PLANNING_ORDER_COVERAGE_POLICY, WORKSPACE_SYNC_V3_PLANNING_ORDER_COVERAGE_PROFILE, validateWorkspaceSyncV3PlanningOrderCoverageFeedEntry, } from './workspaceSyncV3PlanningOrderCoverage.js';
+import { WORKSPACE_SYNC_V3_TASK_COVER_COVERAGE_POLICY, WORKSPACE_SYNC_V3_TASK_COVER_COVERAGE_PROFILE, validateWorkspaceSyncV3TaskCoverCoverageFeedEntry, } from './workspaceSyncV3TaskCoverCoverage.js';
+import { WORKSPACE_SYNC_V3_WORKFLOW_TASK_COVER_COVERAGE_POLICY, WORKSPACE_SYNC_V3_WORKFLOW_TASK_COVER_COVERAGE_PROFILE, validateWorkspaceSyncV3WorkflowTaskCoverCoverageFeedEntry, } from './workspaceSyncV3WorkflowTaskCoverCoverage.js';
 export const WORKSPACE_SYNC_V3_REGISTERED_COVERAGES = Object.freeze([
     Object.freeze({
         profile: WORKSPACE_SYNC_V3_COMBINED_COVERAGE_PROFILE,
@@ -23,6 +25,16 @@ export const WORKSPACE_SYNC_V3_REGISTERED_COVERAGES = Object.freeze([
         policy: WORKSPACE_SYNC_V3_PLANNING_ORDER_COVERAGE_POLICY,
         validateEntry: validateWorkspaceSyncV3PlanningOrderCoverageFeedEntry,
     }),
+    Object.freeze({
+        profile: WORKSPACE_SYNC_V3_TASK_COVER_COVERAGE_PROFILE,
+        policy: WORKSPACE_SYNC_V3_TASK_COVER_COVERAGE_POLICY,
+        validateEntry: validateWorkspaceSyncV3TaskCoverCoverageFeedEntry,
+    }),
+    Object.freeze({
+        profile: WORKSPACE_SYNC_V3_WORKFLOW_TASK_COVER_COVERAGE_PROFILE,
+        policy: WORKSPACE_SYNC_V3_WORKFLOW_TASK_COVER_COVERAGE_POLICY,
+        validateEntry: validateWorkspaceSyncV3WorkflowTaskCoverCoverageFeedEntry,
+    }),
 ]);
 export function resolveWorkspaceSyncV3RegisteredCoverage(input) {
     const profileId = String(input.coverageProfileId || '').trim();

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

@@ -1,4 +1,4 @@
-export type WorkspaceSyncV3ProjectionDescriptor = 'initiative/full-v1' | 'workstream/full-v1' | 'task/root-v1' | 'task-comments/full-v1' | 'task-checklist/full-v1' | 'task-attachment-links/full-v1' | 'entity-event/full-v1' | 'task-relationship/full-v1' | 'taxonomy/full-v1' | 'workflow-published-definition/full-v2' | 'workflow-execution/root-v1' | 'workflow-execution-event/full-v1' | 'workstream-task-order/full-v1';
+export type WorkspaceSyncV3ProjectionDescriptor = 'initiative/full-v1' | 'workstream/full-v1' | 'task/root-v1' | 'task-comments/full-v1' | 'task-checklist/full-v1' | 'task-attachment-links/full-v1' | 'task-attachment-links/full-v2' | 'entity-event/full-v1' | 'task-relationship/full-v1' | 'taxonomy/full-v1' | 'workflow-published-definition/full-v2' | 'workflow-execution/root-v1' | 'workflow-execution-event/full-v1' | 'workstream-task-order/full-v1';
 export type WorkspaceSyncV3JournalProjectionDescriptor = WorkspaceSyncV3ProjectionDescriptor | 'task/taxonomy-remap-v1';
 export interface WorkspaceSyncV3ProjectionCoverageDescriptor {
     projectionId: WorkspaceSyncV3ProjectionDescriptor;

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

@@ -7,4 +7,5 @@ export declare function resolveWorkspaceSyncV3AttestedV2Exclusions(input: {
     coverage: unknown;
     excludedProjections: unknown;
     env?: NodeJS.ProcessEnv;
+    runtimeMode?: 'local' | 'cloud';
 }): readonly WorkspaceSyncV2ProjectionExclusion[] | null;

package/dist/sync/v3/workspaceSyncV3LegacyBoundaryAttestation.js

@@ -1,5 +1,5 @@
-import { isWorkspaceSyncV3CombinedLegacyFenceEnabled, normalizeWorkspaceSyncV2ProjectionExclusions, WORKSPACE_SYNC_V3_COMBINED_V2_EXCLUSIONS, } from './workspaceSyncV2ProjectionExclusions.js';
-import { resolveWorkspaceSyncV3CombinedWireContract, } from './workspaceSyncV3CombinedWireContract.js';
+import { isWorkspaceSyncV3CombinedLegacyFenceConfigured, isWorkspaceSyncV3CombinedLegacyFenceEnabled, normalizeWorkspaceSyncV2ProjectionExclusions, WORKSPACE_SYNC_V3_COMBINED_V2_EXCLUSIONS, } from './workspaceSyncV2ProjectionExclusions.js';
+import { WORKSPACE_SYNC_V3_COMBINED_COVERAGE_SELECTOR, resolveWorkspaceSyncV3CombinedWireContract, } from './workspaceSyncV3CombinedWireContract.js';
 import { resolveCombinedFeedCapability, resolveRequestedCombinedFeedCoverage } from './combinedFeedCapability.js';
 export function isWorkspaceSyncV3NestedLegacyFenceEnabled(env = process.env) {
     return /^(1|true|on|yes)$/i.test(String(env.TASKFORCE_SYNC_V3_NESTED_LEGACY_FENCE_ENABLED || '').trim());
@@ -17,17 +17,30 @@ export function resolveWorkspaceSyncV3RequiredCloudCoverage(env = process.env) {
 export const resolveWorkspaceSyncV3RequiredPushCoverage = resolveWorkspaceSyncV3RequiredCloudCoverage;
 export function resolveWorkspaceSyncV3AttestedV2Exclusions(input) {
     const env = input.env || process.env;
-    if (!isWorkspaceSyncV3CombinedLegacyFenceEnabled(env))
-        return input.coverage == null ? [] : null;
-    if (input.coverage == null)
-        return WORKSPACE_SYNC_V3_COMBINED_V2_EXCLUSIONS;
+    const runtimeMode = input.runtimeMode || 'cloud';
+    const localFenceEnabled = (coverage) => (isWorkspaceSyncV3CombinedLegacyFenceConfigured(env)
+        && resolveCombinedFeedCapability({ runtimeMode: 'local', env, coverage })
+            .combinedFeed.activationReady);
+    if (input.coverage == null) {
+        const fenceEnabled = runtimeMode === 'local'
+            ? localFenceEnabled(WORKSPACE_SYNC_V3_COMBINED_COVERAGE_SELECTOR)
+            : isWorkspaceSyncV3CombinedLegacyFenceEnabled(env);
+        return fenceEnabled ? WORKSPACE_SYNC_V3_COMBINED_V2_EXCLUSIONS : [];
+    }
     if (!input.coverage || typeof input.coverage !== 'object' || Array.isArray(input.coverage))
         return null;
     const contract = resolveWorkspaceSyncV3CombinedWireContract(input.coverage);
-    if (!contract || (contract.nestedWriterPrerequisitesRequired
-        && (!isWorkspaceSyncV3NestedLegacyFenceEnabled(env)
-            || !resolveCombinedFeedCapability({ runtimeMode: 'cloud', env, coverage: contract.coverage })
-                .combinedFeed.activationReady)))
+    if (!contract)
+        return null;
+    const fenceEnabled = runtimeMode === 'local'
+        ? localFenceEnabled(contract.coverage)
+        : isWorkspaceSyncV3CombinedLegacyFenceEnabled(env)
+            && (!contract.nestedWriterPrerequisitesRequired
+                || (isWorkspaceSyncV3NestedLegacyFenceEnabled(env)
+                    && resolveCombinedFeedCapability({
+                        runtimeMode: 'cloud', env, coverage: contract.coverage,
+                    }).combinedFeed.activationReady));
+    if (!fenceEnabled)
         return null;
     if (!Array.isArray(input.excludedProjections))
         return null;

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

@@ -23,6 +23,7 @@ export interface WorkspaceSyncV3NestedTaskApplyCore {
     resolveTaskAttachmentLinksForDurableSync(links: ReturnType<typeof serializeWorkspaceSyncV3TaskAttachmentLinksPayload>['links'], workspaceId: string, options?: {
         adoptAuthoritativeReferenceNumber?: boolean;
         ignoreAssetMetadataSnapshots?: boolean;
+        restoreDeletedExternalAssetForAuthoritativeSync?: boolean;
     }): AttachmentItem[];
     listTaskAttachmentLinksForDurableSync(taskId: string, workspaceId: string): ReturnType<typeof serializeWorkspaceSyncV3TaskAttachmentLinksPayload>['links'];
     getEntityEventForSync(input: {
@@ -71,12 +72,14 @@ export declare function resolveWorkspaceSyncV3AttachmentApplyObligations(input:
     } | {
         success: false;
         error: string;
+        disposition?: 'retryable' | 'terminal-unavailable';
     }>;
     onInstalled?: (taskId: string) => void;
 }): Promise<{
     attempted: number;
     resolved: number;
     remaining: number;
+    terminal: number;
     nextAttemptAt: string | null;
     resolvedTaskIds: string[];
     lastError: string | null;

package/dist/sync/v3/workspaceSyncV3NestedTaskApply.js

@@ -2,7 +2,7 @@ import { DurableTaskAttachmentLinksApplyError } from '../../core/TaskAttachmentL
 import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
 import { fingerprintWorkspaceSyncPayload, hasCompletedRecoveryForSupersededEntityEvent, WorkspaceSyncDurabilityStore, } from './syncDurabilityStore.js';
 import { calculateAttachmentApplyObligationRetryDelayMs, WorkspaceSyncV3AttachmentApplyObligationStore, } from './workspaceSyncV3AttachmentApplyObligationStore.js';
-import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload, serializeWorkspaceSyncV3TaskChecklistPayload, serializeWorkspaceSyncV3TaskCommentsPayload, serializeWorkspaceSyncV3EntityEventPayload, validateWorkspaceSyncV3EntityEventPayload, validateWorkspaceSyncV3TaskAttachmentLinksPayload, validateWorkspaceSyncV3TaskChecklistPayload, validateWorkspaceSyncV3TaskCommentAppendPayload, validateWorkspaceSyncV3TaskCommentsPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
+import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload, serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload, serializeWorkspaceSyncV3TaskChecklistPayload, serializeWorkspaceSyncV3TaskCommentsPayload, serializeWorkspaceSyncV3EntityEventPayload, validateWorkspaceSyncV3EntityEventPayload, validateWorkspaceSyncV3TaskAttachmentLinksPayload, validateWorkspaceSyncV3TaskAttachmentLinksV2Payload, validateWorkspaceSyncV3TaskChecklistPayload, validateWorkspaceSyncV3TaskCommentAppendPayload, validateWorkspaceSyncV3TaskCommentsPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
 import { validateWorkspaceSyncV3NestedTaskFeedEntry } from './workspaceSyncV3NestedTaskProjection.js';
 export class WorkspaceSyncV3TaskCommentAggregateDivergenceError extends Error {
     taskId;
@@ -50,6 +50,7 @@ function serializeTaskAttachmentLinkOwnership(payload) {
             order: link.order,
             ...(link.displayName !== undefined ? { displayName: link.displayName } : {}),
         })),
+        ...('cardCoverAssetId' in payload ? { cardCoverAssetId: payload.cardCoverAssetId } : {}),
     };
 }
 function applyEntry(core, workspaceId, entry, now, authoritativeEntityEventRecoveryIds) {
@@ -85,16 +86,22 @@ function applyEntry(core, workspaceId, entry, now, authoritativeEntityEventRecov
         assertInstalledFingerprint(serializeWorkspaceSyncV3TaskChecklistPayload({ taskId: task.id, items: installed.checklistItems || [] }), entry.canonicalFingerprint || '', 'Task checklist');
         return;
     }
-    if (entry.projection === 'task-attachment-links/full-v1') {
-        const payload = validateWorkspaceSyncV3TaskAttachmentLinksPayload(entry.payload);
+    if (entry.projection === 'task-attachment-links/full-v1'
+        || entry.projection === 'task-attachment-links/full-v2') {
+        const v2Payload = entry.projection === 'task-attachment-links/full-v2'
+            ? validateWorkspaceSyncV3TaskAttachmentLinksV2Payload(entry.payload)
+            : null;
+        const payload = v2Payload ?? validateWorkspaceSyncV3TaskAttachmentLinksPayload(entry.payload);
+        const cardCoverAssetId = v2Payload?.cardCoverAssetId;
         const task = taskOrThrow(core, payload.taskId, workspaceId);
         const ownershipFingerprint = fingerprintWorkspaceSyncPayload(serializeTaskAttachmentLinkOwnership(payload));
         const obligations = new WorkspaceSyncV3AttachmentApplyObligationStore(core.getDatabaseAdapter());
         let attachments;
         try {
-            attachments = core.resolveTaskAttachmentLinksForDurableSync(payload.links, workspaceId, {
+            attachments = core.getDatabaseAdapter().transaction(() => (core.resolveTaskAttachmentLinksForDurableSync(payload.links, workspaceId, {
                 ignoreAssetMetadataSnapshots: true,
-            });
+                restoreDeletedExternalAssetForAuthoritativeSync: true,
+            })))();
         }
         catch (error) {
             if (error instanceof DurableTaskAttachmentLinksApplyError
@@ -122,10 +129,19 @@ function applyEntry(core, workspaceId, entry, now, authoritativeEntityEventRecov
             }
             throw error;
         }
-        installTaskNestedFields(core, workspaceId, task, { attachments });
-        const installedPayload = serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
-            taskId: task.id, links: core.listTaskAttachmentLinksForDurableSync(task.id, workspaceId),
+        const installed = installTaskNestedFields(core, workspaceId, task, {
+            attachments,
+            ...(cardCoverAssetId !== undefined ? { cardCoverAssetId } : {}),
         });
+        const installedPayload = cardCoverAssetId !== undefined
+            ? serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload({
+                taskId: task.id,
+                links: core.listTaskAttachmentLinksForDurableSync(task.id, workspaceId),
+                cardCoverAssetId: installed.cardCoverAssetId ?? null,
+            })
+            : serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
+                taskId: task.id, links: core.listTaskAttachmentLinksForDurableSync(task.id, workspaceId),
+            });
         // Captions, original filenames, and readable references are snapshots of
         // asset-owned metadata. A historical link event must remain installable
         // after the asset is renamed or receives a new readable reference.
@@ -210,7 +226,14 @@ export async function resolveWorkspaceSyncV3AttachmentApplyObligations(input) {
     let lastError = null;
     for (const obligation of due) {
         try {
-            const payload = validateWorkspaceSyncV3TaskAttachmentLinksPayload(JSON.parse(obligation.payloadJson));
+            const rawPayload = JSON.parse(obligation.payloadJson);
+            const hasCardCover = Object.prototype.hasOwnProperty.call(rawPayload, 'cardCoverAssetId');
+            const payload = hasCardCover
+                ? validateWorkspaceSyncV3TaskAttachmentLinksV2Payload(rawPayload)
+                : validateWorkspaceSyncV3TaskAttachmentLinksPayload(rawPayload);
+            const cardCoverAssetId = hasCardCover
+                ? payload.cardCoverAssetId
+                : undefined;
             const installMutation = () => {
                 const task = input.core.getTask(payload.taskId, input.workspaceId);
                 if (!task) {
@@ -222,11 +245,22 @@ export async function resolveWorkspaceSyncV3AttachmentApplyObligations(input) {
                 }
                 const attachments = input.core.resolveTaskAttachmentLinksForDurableSync(payload.links, input.workspaceId, {
                     ignoreAssetMetadataSnapshots: true,
+                    restoreDeletedExternalAssetForAuthoritativeSync: true,
                 });
-                installTaskNestedFields(input.core, input.workspaceId, task, { attachments });
-                const installedPayload = serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
-                    taskId: task.id, links: input.core.listTaskAttachmentLinksForDurableSync(task.id, input.workspaceId),
+                const installed = installTaskNestedFields(input.core, input.workspaceId, task, {
+                    attachments,
+                    ...(cardCoverAssetId !== undefined ? { cardCoverAssetId } : {}),
                 });
+                const installedPayload = cardCoverAssetId !== undefined
+                    ? serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload({
+                        taskId: task.id,
+                        links: input.core.listTaskAttachmentLinksForDurableSync(task.id, input.workspaceId),
+                        cardCoverAssetId: installed.cardCoverAssetId ?? null,
+                    })
+                    : serializeWorkspaceSyncV3TaskAttachmentLinksPayload({
+                        taskId: task.id,
+                        links: input.core.listTaskAttachmentLinksForDurableSync(task.id, input.workspaceId),
+                    });
                 assertInstalledFingerprint(serializeTaskAttachmentLinkOwnership(installedPayload), fingerprintWorkspaceSyncPayload(serializeTaskAttachmentLinkOwnership(payload)), `Task attachment links for ${task.id}`);
                 obligationStore.resolve({
                     tenantId, workspaceId: input.workspaceId, taskId: obligation.taskId,
@@ -292,8 +326,20 @@ export async function resolveWorkspaceSyncV3AttachmentApplyObligations(input) {
                     if (!input.hydrateAsset || !assetId || hydratedAssetIds.has(assetId))
                         throw error;
                     const hydration = await input.hydrateAsset(assetId);
-                    if (!hydration.success)
+                    if (!hydration.success) {
+                        if (hydration.disposition === 'terminal-unavailable') {
+                            obligationStore.markTerminalUnavailable({
+                                tenantId,
+                                workspaceId: input.workspaceId,
+                                taskId: obligation.taskId,
+                                canonicalFingerprint: obligation.canonicalFingerprint,
+                                reason: hydration.error,
+                                now: input.now,
+                            });
+                            throw new TerminalAttachmentApplyObligationError(hydration.error);
+                        }
                         throw new Error(hydration.error);
+                    }
                     hydratedAssetIds.add(assetId);
                 }
             }
@@ -304,6 +350,8 @@ export async function resolveWorkspaceSyncV3AttachmentApplyObligations(input) {
         }
         catch (error) {
             lastError = error instanceof Error ? error.message : 'Deferred attachment-link retry failed.';
+            if (error instanceof TerminalAttachmentApplyObligationError)
+                continue;
             const nextAttemptAt = new Date(Date.parse(input.now) + calculateAttachmentApplyObligationRetryDelayMs(obligation.attempts + 1)).toISOString();
             obligationStore.recordAttemptFailure({
                 tenantId, workspaceId: input.workspaceId, taskId: obligation.taskId,
@@ -318,8 +366,11 @@ export async function resolveWorkspaceSyncV3AttachmentApplyObligations(input) {
         attempted: due.length,
         resolved,
         remaining: summary.open,
+        terminal: summary.terminal,
         nextAttemptAt: summary.nextAttemptAt,
         resolvedTaskIds,
         lastError: summary.lastError || lastError,
     };
 }
+class TerminalAttachmentApplyObligationError extends Error {
+}

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

@@ -18,6 +18,9 @@ export type WorkspaceSyncV3TaskAttachmentLinksPayload = {
     taskId: string;
     links: WorkspaceSyncV3TaskAttachmentLink[];
 };
+export type WorkspaceSyncV3TaskAttachmentLinksV2Payload = WorkspaceSyncV3TaskAttachmentLinksPayload & {
+    cardCoverAssetId: string | null;
+};
 export type WorkspaceSyncV3TaskAttachmentLink = {
     assetId: string;
     role: 'attachment' | 'image' | 'reference';
@@ -55,5 +58,11 @@ export declare function serializeWorkspaceSyncV3TaskAttachmentLinksPayload(input
     links: unknown;
 }): WorkspaceSyncV3TaskAttachmentLinksPayload;
 export declare function validateWorkspaceSyncV3TaskAttachmentLinksPayload(value: unknown): WorkspaceSyncV3TaskAttachmentLinksPayload;
+export declare function serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload(input: {
+    taskId: string;
+    links: unknown;
+    cardCoverAssetId: unknown;
+}): WorkspaceSyncV3TaskAttachmentLinksV2Payload;
+export declare function validateWorkspaceSyncV3TaskAttachmentLinksV2Payload(value: unknown): WorkspaceSyncV3TaskAttachmentLinksV2Payload;
 export declare function serializeWorkspaceSyncV3EntityEventPayload(event: EntityEvent): WorkspaceSyncEntityEventSnapshot;
 export declare function validateWorkspaceSyncV3EntityEventPayload(value: unknown): WorkspaceSyncEntityEventSnapshot;

package/dist/sync/v3/workspaceSyncV3NestedTaskCodecs.js

@@ -279,6 +279,32 @@ export function validateWorkspaceSyncV3TaskAttachmentLinksPayload(value) {
     }
     return canonical;
 }
+export function serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload(input) {
+    const canonical = serializeWorkspaceSyncV3TaskAttachmentLinksPayload(input);
+    const cardCoverAssetId = input.cardCoverAssetId == null
+        ? null
+        : requiredId(input.cardCoverAssetId, 'Task attachment links cardCoverAssetId');
+    if (cardCoverAssetId !== null && !canonical.links.some((link) => (link.assetId === cardCoverAssetId && link.role === 'image'))) {
+        throw new Error('Task attachment links cardCoverAssetId must reference an image link.');
+    }
+    return { ...canonical, cardCoverAssetId };
+}
+export function validateWorkspaceSyncV3TaskAttachmentLinksV2Payload(value) {
+    const source = record(value, 'Task attachment links v2 payload');
+    exactKeys(source, new Set(['taskId', 'links', 'cardCoverAssetId']), 'Task attachment links v2 payload');
+    if (!Object.prototype.hasOwnProperty.call(source, 'cardCoverAssetId')) {
+        throw new Error('Task attachment links v2 payload must explicitly carry cardCoverAssetId.');
+    }
+    const canonical = serializeWorkspaceSyncV3TaskAttachmentLinksV2Payload({
+        taskId: requiredId(source.taskId, 'Task attachment links taskId'),
+        links: source.links,
+        cardCoverAssetId: source.cardCoverAssetId,
+    });
+    if (canonicalWorkspaceSyncJson(canonical) !== canonicalWorkspaceSyncJson(value)) {
+        throw new Error('Task attachment links v2 payload is not canonically ordered or normalized.');
+    }
+    return canonical;
+}
 export function serializeWorkspaceSyncV3EntityEventPayload(event) {
     const serialized = serializeEntityActivityForSync(event);
     assertMetadataOnly(serialized.details, 'Entity event details');

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

@@ -33,15 +33,25 @@ export declare const WORKSPACE_SYNC_V3_NESTED_TASK_PROJECTIONS: readonly [Readon
     dependencies: readonly ["initiative/full-v1", "workstream/full-v1", "task/root-v1"];
     operationAtomic: true;
 }>];
+export declare const WORKSPACE_SYNC_V3_TASK_ATTACHMENT_LINKS_V2_PROJECTION: Readonly<{
+    readonly projectionId: "task-attachment-links/full-v2";
+    readonly domain: "task-attachment-links";
+    readonly schemaVersion: 2;
+    readonly mutationKinds: readonly string[];
+    readonly fields: readonly string[];
+    readonly dependencies: readonly ["task/root-v1"];
+    readonly operationAtomic: true;
+}>;
 export declare function projectWorkspaceSyncV3NestedTaskJournalRow(row: WorkspaceSyncJournalRow): WorkspaceSyncV3FeedEntry | null;
+export declare function projectWorkspaceSyncV3NestedTaskV2JournalRow(row: WorkspaceSyncJournalRow): WorkspaceSyncV3FeedEntry | null;
 export declare function validateWorkspaceSyncV3NestedTaskFeedEntry(entry: WorkspaceSyncV3FeedEntry): void;
-/**
- * Operation projector for nested/event coverage. Ordinary writers emit
- * parent-first operations; repair baselines and comment reconcile may emit
- * nested-only groups that still project when every row is a nested domain.
- */
 export declare function projectWorkspaceSyncV3NestedTaskOperation(input: {
     rows: readonly WorkspaceSyncJournalRow[];
     cycleHighWatermark: string;
     followingRow?: WorkspaceSyncJournalRow | null;
 }): WorkspaceSyncV3FeedEntry[] | null;
+export declare function projectWorkspaceSyncV3NestedTaskV2Operation(input: {
+    rows: readonly WorkspaceSyncJournalRow[];
+    cycleHighWatermark: string;
+    followingRow?: WorkspaceSyncJournalRow | null;
+}): WorkspaceSyncV3FeedEntry[] | null;

package/dist/sync/v3/workspaceSyncV3NestedTaskProjection.js

@@ -4,7 +4,7 @@ import { assertWorkspaceSyncV3OperationBoundary } from './workspaceSyncV3Operati
 import { projectWorkspaceSyncV3TaskRootJournalRow } from './workspaceSyncV3TaskRootProjection.js';
 import { projectWorkspaceSyncV3InitiativeJournalRow } from './workspaceSyncV3Feed.js';
 import { projectWorkspaceSyncV3WorkstreamJournalRow } from './workspaceSyncV3WorkstreamProjection.js';
-import { serializeWorkspaceSyncV3EntityEventPayload, validateWorkspaceSyncV3EntityEventPayload, validateWorkspaceSyncV3TaskAttachmentLinksPayload, validateWorkspaceSyncV3TaskChecklistPayload, validateWorkspaceSyncV3TaskCommentAppendPayload, validateWorkspaceSyncV3TaskCommentsPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
+import { serializeWorkspaceSyncV3EntityEventPayload, serializeWorkspaceSyncV3TaskAttachmentLinksPayload, validateWorkspaceSyncV3EntityEventPayload, validateWorkspaceSyncV3TaskAttachmentLinksPayload, validateWorkspaceSyncV3TaskAttachmentLinksV2Payload, validateWorkspaceSyncV3TaskChecklistPayload, validateWorkspaceSyncV3TaskCommentAppendPayload, validateWorkspaceSyncV3TaskCommentsPayload, } from './workspaceSyncV3NestedTaskCodecs.js';
 import { isLegacyEntityEventAdoptionIdentity } from './entityEventLegacyAdoptionContract.js';
 export const WORKSPACE_SYNC_V3_NESTED_TASK_PROJECTIONS = Object.freeze([
     Object.freeze({
@@ -46,6 +46,15 @@ export const WORKSPACE_SYNC_V3_NESTED_TASK_PROJECTIONS = Object.freeze([
         operationAtomic: true,
     }),
 ]);
+export const WORKSPACE_SYNC_V3_TASK_ATTACHMENT_LINKS_V2_PROJECTION = Object.freeze({
+    projectionId: 'task-attachment-links/full-v2',
+    domain: 'task-attachment-links',
+    schemaVersion: 2,
+    mutationKinds: Object.freeze(['replace']),
+    fields: Object.freeze(['taskId', 'links', 'cardCoverAssetId']),
+    dependencies: Object.freeze(['task/root-v1']),
+    operationAtomic: true,
+});
 const projectionByDomain = new Map(WORKSPACE_SYNC_V3_NESTED_TASK_PROJECTIONS.map((projection) => [projection.domain, projection.projectionId]));
 function sequence(value, label) {
     const text = String(value ?? '').trim();
@@ -68,7 +77,7 @@ function parsePayload(row) {
         throw new Error(`Nested task journal payload is malformed at ${row.sequence}.`);
     }
 }
-function canonicalPayload(row) {
+function canonicalPayload(row, attachmentProjection) {
     const raw = parsePayload(row);
     if (row.domain === 'task-comments') {
         if (row.mutationKind === 'append') {
@@ -91,7 +100,17 @@ function canonicalPayload(row) {
         return { payload, canonicalFingerprint: fingerprintWorkspaceSyncPayload(payload) };
     }
     if (row.domain === 'task-attachment-links' && row.mutationKind === 'replace') {
-        const payload = validateWorkspaceSyncV3TaskAttachmentLinksPayload(raw);
+        const payload = attachmentProjection === 'task-attachment-links/full-v2'
+            ? validateWorkspaceSyncV3TaskAttachmentLinksV2Payload(raw)
+            : (() => {
+                try {
+                    return validateWorkspaceSyncV3TaskAttachmentLinksPayload(raw);
+                }
+                catch {
+                    const v2 = validateWorkspaceSyncV3TaskAttachmentLinksV2Payload(raw);
+                    return serializeWorkspaceSyncV3TaskAttachmentLinksPayload(v2);
+                }
+            })();
         if (payload.taskId !== row.entityId)
             throw new Error(`Task attachment-link identity is invalid at ${row.sequence}.`);
         return { payload, canonicalFingerprint: fingerprintWorkspaceSyncPayload(payload) };
@@ -107,8 +126,10 @@ function canonicalPayload(row) {
 function canonicalEntityEventPayload(raw) {
     return validateWorkspaceSyncV3EntityEventPayload(serializeWorkspaceSyncV3EntityEventPayload(raw));
 }
-export function projectWorkspaceSyncV3NestedTaskJournalRow(row) {
-    const projection = projectionByDomain.get(row.domain);
+function projectNestedTaskJournalRow(row, attachmentProjection) {
+    const projection = row.domain === 'task-attachment-links'
+        ? attachmentProjection
+        : projectionByDomain.get(row.domain);
     if (!projection)
         return null;
     if (row.contractVersion !== WORKSPACE_SYNC_CONTRACT_VERSION) {
@@ -131,7 +152,7 @@ export function projectWorkspaceSyncV3NestedTaskJournalRow(row) {
         if (payload.action === 'sync-v3-repair-baseline')
             return null;
     }
-    const { payload, canonicalFingerprint } = canonicalPayload(row);
+    const { payload, canonicalFingerprint } = canonicalPayload(row, attachmentProjection);
     return {
         sequence: journalSequence,
         projection,
@@ -146,8 +167,17 @@ export function projectWorkspaceSyncV3NestedTaskJournalRow(row) {
         occurredAt,
     };
 }
+export function projectWorkspaceSyncV3NestedTaskJournalRow(row) {
+    return projectNestedTaskJournalRow(row, 'task-attachment-links/full-v1');
+}
+export function projectWorkspaceSyncV3NestedTaskV2JournalRow(row) {
+    return projectNestedTaskJournalRow(row, 'task-attachment-links/full-v2');
+}
 export function validateWorkspaceSyncV3NestedTaskFeedEntry(entry) {
-    const projected = projectWorkspaceSyncV3NestedTaskJournalRow({
+    const projector = entry.projection === 'task-attachment-links/full-v2'
+        ? projectWorkspaceSyncV3NestedTaskV2JournalRow
+        : projectWorkspaceSyncV3NestedTaskJournalRow;
+    const projected = projector({
         sequence: entry.sequence,
         contractVersion: WORKSPACE_SYNC_CONTRACT_VERSION,
         clientId: 'validation-client',
@@ -181,9 +211,9 @@ function assertNestedDependentOrder(rows) {
         throw new Error('Nested task operation dependents are duplicated or out of order.');
     }
 }
-function projectNestedDependentRows(rows) {
+function projectNestedDependentRows(rows, attachmentProjection) {
     return rows.flatMap((row) => {
-        const projected = projectWorkspaceSyncV3NestedTaskJournalRow(row);
+        const projected = projectNestedTaskJournalRow(row, attachmentProjection);
         if (!projected) {
             const payload = row.domain === 'entity-event'
                 ? canonicalEntityEventPayload(parsePayload(row))
@@ -217,7 +247,7 @@ function isSupportedNestedOnlyOperation(rows) {
  * root. Apply still requires referenced parents to exist on the receiver; feed
  * only needs to project the nested rows.
  */
-function projectNestedOnlyOperation(rows) {
+function projectNestedOnlyOperation(rows, attachmentProjection) {
     if (!isSupportedNestedOnlyOperation(rows)) {
         throw new Error('Nested-only task operation is not an allowed repair or reconciliation shape.');
     }
@@ -229,7 +259,7 @@ function projectNestedOnlyOperation(rows) {
             throw new Error('Nested task operation dependent identity does not match its task root.');
         }
     }
-    const projected = projectNestedDependentRows(rows);
+    const projected = projectNestedDependentRows(rows, attachmentProjection);
     const events = projected
         .filter((entry) => entry.domain === 'entity-event')
         .map((entry) => validateWorkspaceSyncV3EntityEventPayload(entry.payload));
@@ -256,14 +286,14 @@ function projectNestedOnlyOperation(rows) {
  * parent-first operations; repair baselines and comment reconcile may emit
  * nested-only groups that still project when every row is a nested domain.
  */
-export function projectWorkspaceSyncV3NestedTaskOperation(input) {
+function projectNestedTaskOperation(input, attachmentProjection) {
     if (!input.rows.some((row) => projectionByDomain.has(row.domain)))
         return null;
     assertWorkspaceSyncV3OperationBoundary(input);
     const [first, ...dependents] = input.rows;
     if (first && projectionByDomain.has(first.domain)
         && input.rows.every((row) => projectionByDomain.has(row.domain))) {
-        return projectNestedOnlyOperation(input.rows);
+        return projectNestedOnlyOperation(input.rows, attachmentProjection);
     }
     if (!first || !['task', 'initiative', 'workstream'].includes(first.domain)) {
         throw new Error('Nested task operation must begin with its v3-owned parent root.');
@@ -272,7 +302,7 @@ export function projectWorkspaceSyncV3NestedTaskOperation(input) {
         throw new Error('Nested task operation contains an unsupported dependent row.');
     }
     assertNestedDependentOrder(dependents);
-    const projectedDependents = projectNestedDependentRows(dependents);
+    const projectedDependents = projectNestedDependentRows(dependents, attachmentProjection);
     const eventRows = projectedDependents.filter((entry) => entry.domain === 'entity-event');
     const rawEventRows = dependents.filter((row) => row.domain === 'entity-event');
     const sentinelOnly = eventRows.length === 0 && rawEventRows.length > 0 && rawEventRows.every((row) => (canonicalEntityEventPayload(parsePayload(row)).action === 'sync-v3-repair-baseline'));
@@ -327,3 +357,9 @@ export function projectWorkspaceSyncV3NestedTaskOperation(input) {
     }
     return [parent, ...projectedDependents];
 }
+export function projectWorkspaceSyncV3NestedTaskOperation(input) {
+    return projectNestedTaskOperation(input, 'task-attachment-links/full-v1');
+}
+export function projectWorkspaceSyncV3NestedTaskV2Operation(input) {
+    return projectNestedTaskOperation(input, 'task-attachment-links/full-v2');
+}

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

@@ -2,7 +2,7 @@ import type { EntityEvent, TaskItem } from '../../types.js';
 import type { WorkspaceSyncV3ProjectionDescriptor } from './workspaceSyncV3FeedProfile.js';
 import { type WorkspaceSyncV3TaskAttachmentLink } from './workspaceSyncV3NestedTaskCodecs.js';
 export type WorkspaceSyncV3NestedTaskRepairCandidate = {
-    projection: Extract<WorkspaceSyncV3ProjectionDescriptor, 'task-comments/full-v1' | 'task-checklist/full-v1' | 'task-attachment-links/full-v1' | 'entity-event/full-v1'>;
+    projection: Extract<WorkspaceSyncV3ProjectionDescriptor, 'task-comments/full-v1' | 'task-checklist/full-v1' | 'task-attachment-links/full-v1' | 'task-attachment-links/full-v2' | 'entity-event/full-v1'>;
     domain: 'task-comments' | 'task-checklist' | 'task-attachment-links' | 'entity-event';
     entityId: string;
     mutationKind: 'replace' | 'append';
@@ -16,4 +16,5 @@ export declare function buildWorkspaceSyncV3NestedTaskRepairCandidates(input: {
     tasks: readonly TaskItem[];
     events: readonly EntityEvent[];
     attachmentLinksByTaskId?: ReadonlyMap<string, readonly WorkspaceSyncV3TaskAttachmentLink[]>;
+    attachmentProjection?: 'task-attachment-links/full-v1' | 'task-attachment-links/full-v2';
 }): WorkspaceSyncV3NestedTaskRepairCandidate[];