@taskforcehq/taskforce 0.3.326 → 0.3.328

package/dist/sync/v3/workspaceSyncV3LegacyBoundaryAttestation.js

@@ -0,0 +1,45 @@
+import { isWorkspaceSyncV3CombinedLegacyFenceEnabled, normalizeWorkspaceSyncV2ProjectionExclusions, WORKSPACE_SYNC_V3_COMBINED_V2_EXCLUSIONS, } from './workspaceSyncV2ProjectionExclusions.js';
+import { 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());
+}
+export function resolveWorkspaceSyncV3RequiredCloudCoverage(env = process.env) {
+    const coverage = resolveRequestedCombinedFeedCoverage(env);
+    const contract = resolveWorkspaceSyncV3CombinedWireContract(coverage);
+    if (!contract?.nestedWriterPrerequisitesRequired)
+        return null;
+    return resolveCombinedFeedCapability({ runtimeMode: 'cloud', env, coverage })
+        .combinedFeed.activationReady
+        ? coverage
+        : null;
+}
+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;
+    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)))
+        return null;
+    if (!Array.isArray(input.excludedProjections))
+        return null;
+    const asserted = input.excludedProjections.map((projection) => String(projection || '').trim());
+    try {
+        normalizeWorkspaceSyncV2ProjectionExclusions(asserted);
+    }
+    catch {
+        return null;
+    }
+    return asserted.length === contract.excludedProjections.length
+        && contract.excludedProjections.every((projection, index) => asserted[index] === projection)
+        ? contract.excludedProjections
+        : null;
+}

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

@@ -0,0 +1,27 @@
+import type { DatabaseAdapter } from '../../storage/databaseAdapter.js';
+import { type WorkspaceSyncOutboxRecovery } from './syncDurabilityStore.js';
+import { type WorkspaceSyncV3AttachmentApplyObligationSummary } from './workspaceSyncV3AttachmentApplyObligationStore.js';
+export interface WorkspaceSyncV3LocalOutboxStatus {
+    activeDepth: number;
+    pending: number;
+    inFlight: number;
+    blocked: number;
+    operationStates: {
+        pending: number;
+        retryScheduled: number;
+        inFlight: number;
+        stale: number;
+        blocked: number;
+    };
+    oldestActiveCreatedAt: string | null;
+    oldestActionableAt?: string | null;
+    blockedErrorCode: string | null;
+    recovery: WorkspaceSyncOutboxRecovery | null;
+    attachmentApplyObligations?: WorkspaceSyncV3AttachmentApplyObligationSummary;
+}
+export declare function readWorkspaceSyncV3LocalOutboxStatus(input: {
+    db: DatabaseAdapter;
+    tenantId: string;
+    workspaceId: string;
+    now?: string;
+}): WorkspaceSyncV3LocalOutboxStatus;

package/dist/sync/v3/workspaceSyncV3LocalOutboxStatus.js

@@ -0,0 +1,83 @@
+import { resolveWorkspaceSyncActiveOperationState, WorkspaceSyncDurabilityStore, } from './syncDurabilityStore.js';
+import { WorkspaceSyncV3AttachmentApplyObligationStore, } from './workspaceSyncV3AttachmentApplyObligationStore.js';
+export function readWorkspaceSyncV3LocalOutboxStatus(input) {
+    const rows = input.db.prepare(`
+        SELECT status, next_attempt_at, lease_expires_at, created_at
+        FROM workspace_sync_outbox
+        WHERE tenant_id = ? AND workspace_id = ?
+          AND status IN ('pending', 'in_flight', 'blocked')
+    `).all(input.tenantId, input.workspaceId);
+    const status = {
+        activeDepth: 0,
+        pending: 0,
+        inFlight: 0,
+        blocked: 0,
+        operationStates: {
+            pending: 0,
+            retryScheduled: 0,
+            inFlight: 0,
+            stale: 0,
+            blocked: 0,
+        },
+        oldestActiveCreatedAt: null,
+        oldestActionableAt: null,
+        blockedErrorCode: null,
+        recovery: null,
+        attachmentApplyObligations: new WorkspaceSyncV3AttachmentApplyObligationStore(input.db)
+            .readSummary({
+            tenantId: input.tenantId,
+            workspaceId: input.workspaceId,
+            now: input.now || new Date().toISOString(),
+        }),
+    };
+    const now = input.now || new Date().toISOString();
+    for (const row of rows) {
+        if (row.status === 'pending')
+            status.pending += 1;
+        if (row.status === 'in_flight')
+            status.inFlight += 1;
+        if (row.status === 'blocked')
+            status.blocked += 1;
+        const operationState = resolveWorkspaceSyncActiveOperationState({
+            status: row.status,
+            nextAttemptAt: row.next_attempt_at,
+            leaseExpiresAt: row.lease_expires_at,
+            now,
+        });
+        if (operationState === 'pending')
+            status.operationStates.pending += 1;
+        if (operationState === 'retry-scheduled')
+            status.operationStates.retryScheduled += 1;
+        if (operationState === 'in-flight')
+            status.operationStates.inFlight += 1;
+        if (operationState === 'stale')
+            status.operationStates.stale += 1;
+        if (operationState === 'blocked')
+            status.operationStates.blocked += 1;
+        const oldest = typeof row.created_at === 'string' ? row.created_at.trim() : '';
+        if (oldest && (!status.oldestActiveCreatedAt || oldest < status.oldestActiveCreatedAt)) {
+            status.oldestActiveCreatedAt = oldest;
+        }
+        if (oldest
+            && (operationState === 'pending' || operationState === 'stale')
+            && (!status.oldestActionableAt || oldest < status.oldestActionableAt)) {
+            status.oldestActionableAt = oldest;
+        }
+    }
+    status.activeDepth = status.pending + status.inFlight + status.blocked;
+    const blocked = input.db.prepare(`
+        SELECT last_error_code
+        FROM workspace_sync_outbox
+        WHERE tenant_id = ? AND workspace_id = ? AND status = 'blocked'
+        ORDER BY updated_at DESC, enqueue_sequence ASC
+        LIMIT 1
+    `).get(input.tenantId, input.workspaceId);
+    status.blockedErrorCode = typeof blocked?.last_error_code === 'string'
+        ? blocked.last_error_code.trim() || null
+        : null;
+    status.recovery = new WorkspaceSyncDurabilityStore(input.db).readOpenOutboxRecovery({
+        tenantId: input.tenantId,
+        workspaceId: input.workspaceId,
+    });
+    return status;
+}

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

@@ -0,0 +1,10 @@
+import type { WorkspaceSyncV3FeedCoveragePolicy, WorkspaceSyncV3FeedEntry, WorkspaceSyncV3FeedOperationProjector } from './workspaceSyncV3Feed.js';
+import type { WorkspaceSyncV3CoverageProfile } from './workspaceSyncV3FeedProfile.js';
+/**
+ * Exact nested/event coverage activated for the named performance cohort.
+ * Coverage-v3 remains immutable as the explicit rollback contract.
+ */
+export declare const WORKSPACE_SYNC_V3_NESTED_COVERAGE_PROFILE: WorkspaceSyncV3CoverageProfile;
+export declare const projectWorkspaceSyncV3NestedCoverageOperation: WorkspaceSyncV3FeedOperationProjector;
+export declare const WORKSPACE_SYNC_V3_NESTED_COVERAGE_POLICY: WorkspaceSyncV3FeedCoveragePolicy;
+export declare function validateWorkspaceSyncV3NestedCoverageFeedEntry(entry: WorkspaceSyncV3FeedEntry): void;

package/dist/sync/v3/workspaceSyncV3NestedCoverage.js

@@ -0,0 +1,40 @@
+import { createHash } from 'crypto';
+import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
+import { projectWorkspaceSyncV3CombinedOperation, validateWorkspaceSyncV3CombinedFeedEntry, WORKSPACE_SYNC_V3_COMBINED_PROJECTIONS, } from './workspaceSyncV3CombinedCoverage.js';
+import { projectWorkspaceSyncV3NestedTaskOperation, validateWorkspaceSyncV3NestedTaskFeedEntry, WORKSPACE_SYNC_V3_NESTED_TASK_PROJECTIONS, } from './workspaceSyncV3NestedTaskProjection.js';
+const projections = Object.freeze([
+    ...WORKSPACE_SYNC_V3_COMBINED_PROJECTIONS,
+    ...WORKSPACE_SYNC_V3_NESTED_TASK_PROJECTIONS,
+]);
+const identity = Object.freeze({
+    coverageProfileId: 'task-planning-metadata',
+    coverageVersion: 4,
+    projections,
+});
+/**
+ * Exact nested/event coverage activated for the named performance cohort.
+ * Coverage-v3 remains immutable as the explicit rollback contract.
+ */
+export const WORKSPACE_SYNC_V3_NESTED_COVERAGE_PROFILE = Object.freeze({
+    ...identity,
+    coverageDigest: createHash('sha256').update(canonicalWorkspaceSyncJson(identity)).digest('hex'),
+});
+const NESTED_DOMAINS = new Set(['task-comments', 'task-checklist', 'task-attachment-links', 'entity-event']);
+export const projectWorkspaceSyncV3NestedCoverageOperation = (input) => {
+    if (input.rows.some((row) => NESTED_DOMAINS.has(row.domain))) {
+        const nested = projectWorkspaceSyncV3NestedTaskOperation(input);
+        if (!nested)
+            throw new Error('Nested/event coverage operation is incomplete.');
+        return nested;
+    }
+    return projectWorkspaceSyncV3CombinedOperation(input);
+};
+export const WORKSPACE_SYNC_V3_NESTED_COVERAGE_POLICY = Object.freeze({
+    profile: WORKSPACE_SYNC_V3_NESTED_COVERAGE_PROFILE,
+    projectOperation: projectWorkspaceSyncV3NestedCoverageOperation,
+});
+export function validateWorkspaceSyncV3NestedCoverageFeedEntry(entry) {
+    if (NESTED_DOMAINS.has(entry.domain))
+        return validateWorkspaceSyncV3NestedTaskFeedEntry(entry);
+    return validateWorkspaceSyncV3CombinedFeedEntry(entry);
+}

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

@@ -0,0 +1,83 @@
+import type { EntityEvent, InitiativeItem, TaskItem, WorkstreamItem } from '../../types.js';
+import type { AttachmentItem } from '../../core/Taskforce.js';
+import type { DatabaseAdapter } from '../../storage/databaseAdapter.js';
+import type { WorkspaceSyncV3FeedEntry } from './workspaceSyncV3Feed.js';
+import { serializeWorkspaceSyncV3TaskAttachmentLinksPayload } from './workspaceSyncV3NestedTaskCodecs.js';
+export interface WorkspaceSyncV3NestedTaskApplyCore {
+    getDatabaseAdapter(): DatabaseAdapter;
+    getTenantId(): string;
+    getTask(id: string, workspaceId?: string): TaskItem | null;
+    hasTaskDeletionMarkerForSync(id: string, workspaceId?: string): boolean;
+    getInitiative(id: string, workspaceId?: string): InitiativeItem | null;
+    getWorkstream(id: string, workspaceId?: string): WorkstreamItem | null;
+    updateTask(id: string, updates: Partial<TaskItem>, workspaceId?: string, options?: {
+        persistBackup?: boolean;
+        emitRealtime?: boolean;
+        syncUpdatedAt?: string;
+        skipTaskEvents?: boolean;
+        allowV3OwnedMetadataWrite?: boolean;
+        allowArchivedNestedContentSyncWrite?: boolean;
+        preferExplicitAttachmentRole?: boolean;
+        preferExplicitAttachmentAssetId?: boolean;
+    }): TaskItem | null;
+    resolveTaskAttachmentLinksForDurableSync(links: ReturnType<typeof serializeWorkspaceSyncV3TaskAttachmentLinksPayload>['links'], workspaceId: string, options?: {
+        adoptAuthoritativeReferenceNumber?: boolean;
+        ignoreAssetMetadataSnapshots?: boolean;
+    }): AttachmentItem[];
+    listTaskAttachmentLinksForDurableSync(taskId: string, workspaceId: string): ReturnType<typeof serializeWorkspaceSyncV3TaskAttachmentLinksPayload>['links'];
+    getEntityEventForSync(input: {
+        workspaceId?: string | null;
+        eventId: string;
+    }): EntityEvent | null;
+    upsertEntityEventForSync(event: EntityEvent, options?: {
+        allowAuthoritativeReplacement?: boolean;
+    }): EntityEvent;
+}
+export declare class WorkspaceSyncV3TaskCommentAggregateDivergenceError extends Error {
+    readonly taskId: string;
+    readonly code = "WORKSPACE_SYNC_TASK_COMMENTS_AGGREGATE_DIVERGENCE";
+    constructor(taskId: string);
+}
+/**
+ * Behavior-dark dependent apply. The caller must apply the parent root entries
+ * first and invoke this function inside the same combined page transaction.
+ */
+export declare function applyWorkspaceSyncV3NestedTaskEntries(input: {
+    core: WorkspaceSyncV3NestedTaskApplyCore;
+    workspaceId: string;
+    entries: readonly WorkspaceSyncV3FeedEntry[];
+    now: string;
+    authoritativeEntityEventRecoveryIds?: ReadonlySet<string>;
+}): {
+    state: 'applied' | 'deferred';
+};
+/**
+ * Bounded, independent retry of previously deferred task-attachment-links
+ * entries (see the `task-attachment-links/full-v1` branch of `applyEntry`).
+ * Each obligation is attempted and persisted independently so one still-
+ * blocked task cannot prevent others from converging once their asset
+ * becomes locally available. The server-owned runner invokes it after a
+ * successful combined-feed cycle and supplies targeted asset hydration. Each
+ * obligation retains its own persisted next-attempt deadline; it never moves
+ * the workspace-wide runner into retry-wait or blocks unrelated sync work.
+ */
+export declare function resolveWorkspaceSyncV3AttachmentApplyObligations(input: {
+    core: WorkspaceSyncV3NestedTaskApplyCore;
+    workspaceId: string;
+    now: string;
+    limit?: number;
+    hydrateAsset?: (assetId: string) => Promise<{
+        success: true;
+    } | {
+        success: false;
+        error: string;
+    }>;
+    onInstalled?: (taskId: string) => void;
+}): Promise<{
+    attempted: number;
+    resolved: number;
+    remaining: number;
+    nextAttemptAt: string | null;
+    resolvedTaskIds: string[];
+    lastError: string | null;
+}>;

package/dist/sync/v3/workspaceSyncV3NestedTaskApply.js

@@ -0,0 +1,325 @@
+import { DurableTaskAttachmentLinksApplyError } from '../../core/TaskAttachmentLinksDurableMutationService.js';
+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 { validateWorkspaceSyncV3NestedTaskFeedEntry } from './workspaceSyncV3NestedTaskProjection.js';
+export class WorkspaceSyncV3TaskCommentAggregateDivergenceError extends Error {
+    taskId;
+    code = 'WORKSPACE_SYNC_TASK_COMMENTS_AGGREGATE_DIVERGENCE';
+    constructor(taskId) {
+        super('Task comment append does not produce the authoritative aggregate fingerprint.');
+        this.taskId = taskId;
+        this.name = 'WorkspaceSyncV3TaskCommentAggregateDivergenceError';
+    }
+}
+function taskOrThrow(core, taskId, workspaceId) {
+    const task = core.getTask(taskId, workspaceId);
+    if (!task)
+        throw new Error(`Nested task projection ${taskId} is missing its v3-owned task root.`);
+    return task;
+}
+function installTaskNestedFields(core, workspaceId, task, patch) {
+    const updated = core.updateTask(task.id, patch, workspaceId, {
+        persistBackup: false,
+        emitRealtime: false,
+        skipTaskEvents: true,
+        // The task/root-v1 entry in the same operation owns updatedAt. Preserve
+        // that accepted coordinate while installing its dependent projection.
+        syncUpdatedAt: task.updatedAt,
+        allowV3OwnedMetadataWrite: true,
+        allowArchivedNestedContentSyncWrite: true,
+        preferExplicitAttachmentRole: patch.attachments !== undefined,
+        preferExplicitAttachmentAssetId: patch.attachments !== undefined,
+    });
+    if (!updated)
+        throw new Error(`Nested task projection ${task.id} disappeared during apply.`);
+    return updated;
+}
+function assertInstalledFingerprint(actual, expected, label) {
+    if (fingerprintWorkspaceSyncPayload(actual) !== expected) {
+        throw new Error(`${label} canonical fingerprint does not match the installed state.`);
+    }
+}
+function serializeTaskAttachmentLinkOwnership(payload) {
+    return {
+        taskId: payload.taskId,
+        links: payload.links.map((link) => ({
+            assetId: link.assetId,
+            role: link.role,
+            order: link.order,
+            ...(link.displayName !== undefined ? { displayName: link.displayName } : {}),
+        })),
+    };
+}
+function applyEntry(core, workspaceId, entry, now, authoritativeEntityEventRecoveryIds) {
+    if (entry.projection === 'task-comments/full-v1') {
+        const task = taskOrThrow(core, entry.entityId, workspaceId);
+        if (entry.mutationKind === 'append') {
+            const payload = validateWorkspaceSyncV3TaskCommentAppendPayload(entry.payload);
+            const existing = serializeWorkspaceSyncV3TaskCommentsPayload({ taskId: task.id, comments: task.comments || [] });
+            const collision = existing.comments.find((comment) => comment.id === payload.comment.id);
+            if (collision && canonicalWorkspaceSyncJson(collision) !== canonicalWorkspaceSyncJson(payload.comment)) {
+                throw new Error(`Task comment identity conflict: ${payload.comment.id}.`);
+            }
+            const aggregate = serializeWorkspaceSyncV3TaskCommentsPayload({
+                taskId: task.id,
+                comments: collision ? existing.comments : [...existing.comments, payload.comment],
+            });
+            if (fingerprintWorkspaceSyncPayload(aggregate) !== payload.canonicalFingerprint) {
+                throw new WorkspaceSyncV3TaskCommentAggregateDivergenceError(task.id);
+            }
+            const installed = installTaskNestedFields(core, workspaceId, task, { comments: aggregate.comments });
+            assertInstalledFingerprint(serializeWorkspaceSyncV3TaskCommentsPayload({ taskId: task.id, comments: installed.comments || [] }), payload.canonicalFingerprint, 'Task comments');
+            return;
+        }
+        const payload = validateWorkspaceSyncV3TaskCommentsPayload(entry.payload);
+        const installed = installTaskNestedFields(core, workspaceId, task, { comments: payload.comments });
+        assertInstalledFingerprint(serializeWorkspaceSyncV3TaskCommentsPayload({ taskId: task.id, comments: installed.comments || [] }), entry.canonicalFingerprint || '', 'Task comments');
+        return;
+    }
+    if (entry.projection === 'task-checklist/full-v1') {
+        const payload = validateWorkspaceSyncV3TaskChecklistPayload(entry.payload);
+        const task = taskOrThrow(core, payload.taskId, workspaceId);
+        const installed = installTaskNestedFields(core, workspaceId, task, { checklistItems: payload.items });
+        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);
+        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, {
+                ignoreAssetMetadataSnapshots: true,
+            });
+        }
+        catch (error) {
+            if (error instanceof DurableTaskAttachmentLinksApplyError
+                && error.code === 'TASK_ATTACHMENT_ASSET_NOT_READY') {
+                // The referenced asset has no local hydration metadata yet
+                // (it travels on the separate v2 content transport and may
+                // not have arrived). Defer this one entry as a bounded,
+                // deduplicated obligation instead of aborting the whole page:
+                // one attachment dependency must not starve every other
+                // unrelated entry in the feed, and repeated identical
+                // failures must not force a full re-scan on every retry.
+                obligations.recordDeferred({
+                    tenantId: core.getTenantId(), workspaceId, taskId: task.id,
+                    assetIds: error.assetId ? [error.assetId] : [],
+                    payloadJson: JSON.stringify(entry.payload),
+                    canonicalFingerprint: ownershipFingerprint,
+                    sourceSequence: entry.sequence,
+                    entityRevision: entry.entityRevision,
+                    lifecycleRevision: entry.lifecycleRevision,
+                    revisionFingerprint: entry.canonicalFingerprint || entry.payloadFingerprint,
+                    error: error.message,
+                    now,
+                });
+                return 'deferred';
+            }
+            throw error;
+        }
+        installTaskNestedFields(core, workspaceId, task, { attachments });
+        const installedPayload = 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.
+        // Verify only the relationship-owned fields after persistence.
+        assertInstalledFingerprint(serializeTaskAttachmentLinkOwnership(installedPayload), ownershipFingerprint, `Task attachment links for ${task.id}`);
+        obligations.resolveSuperseded({ tenantId: core.getTenantId(), workspaceId, taskId: task.id, now });
+        return;
+    }
+    if (entry.projection === 'entity-event/full-v1') {
+        const payload = validateWorkspaceSyncV3EntityEventPayload(entry.payload);
+        if (payload.workspaceId !== workspaceId) {
+            throw new Error(`Entity event ${payload.id} belongs to a different workspace.`);
+        }
+        const parentExists = payload.entityType === 'task'
+            ? Boolean(core.getTask(payload.entityId, workspaceId)
+                || core.hasTaskDeletionMarkerForSync(payload.entityId, workspaceId))
+            : payload.entityType === 'initiative'
+                ? Boolean(core.getInitiative(payload.entityId, workspaceId))
+                : Boolean(core.getWorkstream(payload.entityId, workspaceId));
+        if (!parentExists)
+            throw new Error(`Entity event ${payload.id} is missing its v3-owned parent root.`);
+        const existing = core.getEntityEventForSync({ workspaceId, eventId: payload.id });
+        if (existing) {
+            const canonicalExisting = serializeWorkspaceSyncV3EntityEventPayload(existing);
+            if (fingerprintWorkspaceSyncPayload(canonicalExisting) !== entry.canonicalFingerprint) {
+                if (!authoritativeEntityEventRecoveryIds?.has(payload.id)
+                    && !hasCompletedRecoveryForSupersededEntityEvent(core.getDatabaseAdapter(), {
+                        tenantId: core.getTenantId(),
+                        workspaceId,
+                        entityType: payload.entityType,
+                        entityId: payload.entityId,
+                        eventId: payload.id,
+                    })) {
+                    throw new Error(`Entity event identity conflict: ${payload.id}.`);
+                }
+                const replaced = core.upsertEntityEventForSync(payload, {
+                    allowAuthoritativeReplacement: true,
+                });
+                assertInstalledFingerprint(serializeWorkspaceSyncV3EntityEventPayload(replaced), entry.canonicalFingerprint || '', 'Entity event');
+            }
+            return;
+        }
+        const installed = core.upsertEntityEventForSync(payload);
+        assertInstalledFingerprint(serializeWorkspaceSyncV3EntityEventPayload(installed), entry.canonicalFingerprint || '', 'Entity event');
+        return;
+    }
+    throw new Error(`Unsupported nested task projection: ${entry.projection}.`);
+}
+/**
+ * Behavior-dark dependent apply. The caller must apply the parent root entries
+ * first and invoke this function inside the same combined page transaction.
+ */
+export function applyWorkspaceSyncV3NestedTaskEntries(input) {
+    input.entries.forEach(validateWorkspaceSyncV3NestedTaskFeedEntry);
+    return input.core.getDatabaseAdapter().transaction(() => {
+        let state = 'applied';
+        for (const entry of input.entries) {
+            if (applyEntry(input.core, input.workspaceId, entry, input.now, input.authoritativeEntityEventRecoveryIds) === 'deferred')
+                state = 'deferred';
+        }
+        return { state };
+    })();
+}
+/**
+ * Bounded, independent retry of previously deferred task-attachment-links
+ * entries (see the `task-attachment-links/full-v1` branch of `applyEntry`).
+ * Each obligation is attempted and persisted independently so one still-
+ * blocked task cannot prevent others from converging once their asset
+ * becomes locally available. The server-owned runner invokes it after a
+ * successful combined-feed cycle and supplies targeted asset hydration. Each
+ * obligation retains its own persisted next-attempt deadline; it never moves
+ * the workspace-wide runner into retry-wait or blocks unrelated sync work.
+ */
+export async function resolveWorkspaceSyncV3AttachmentApplyObligations(input) {
+    const tenantId = input.core.getTenantId();
+    const obligationStore = new WorkspaceSyncV3AttachmentApplyObligationStore(input.core.getDatabaseAdapter());
+    const due = obligationStore.listDue({
+        tenantId, workspaceId: input.workspaceId, now: input.now, limit: input.limit,
+    });
+    let resolved = 0;
+    const resolvedTaskIds = [];
+    let lastError = null;
+    for (const obligation of due) {
+        try {
+            const payload = validateWorkspaceSyncV3TaskAttachmentLinksPayload(JSON.parse(obligation.payloadJson));
+            const installMutation = () => {
+                const task = input.core.getTask(payload.taskId, input.workspaceId);
+                if (!task) {
+                    obligationStore.resolve({
+                        tenantId, workspaceId: input.workspaceId, taskId: obligation.taskId,
+                        canonicalFingerprint: obligation.canonicalFingerprint, now: input.now,
+                    });
+                    return { resolved: true, installed: false };
+                }
+                const attachments = input.core.resolveTaskAttachmentLinksForDurableSync(payload.links, input.workspaceId, {
+                    ignoreAssetMetadataSnapshots: true,
+                });
+                installTaskNestedFields(input.core, input.workspaceId, task, { attachments });
+                const installedPayload = 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,
+                    canonicalFingerprint: obligation.canonicalFingerprint, now: input.now,
+                });
+                input.onInstalled?.(obligation.taskId);
+                return { resolved: true, installed: true };
+            };
+            const attemptInstall = () => {
+                if (obligation.entityRevision && obligation.lifecycleRevision && obligation.revisionFingerprint) {
+                    const applied = new WorkspaceSyncDurabilityStore(input.core.getDatabaseAdapter())
+                        .applyReplicatedEntityRevision({
+                        tenantId,
+                        workspaceId: input.workspaceId,
+                        domain: 'task-attachment-links',
+                        entityId: obligation.taskId,
+                        sequence: obligation.sourceSequence,
+                        entityRevision: obligation.entityRevision,
+                        lifecycleRevision: obligation.lifecycleRevision,
+                        canonicalFingerprint: obligation.revisionFingerprint,
+                        now: input.now,
+                        applyMutation: installMutation,
+                    });
+                    if (applied.state === 'applied')
+                        return applied.result;
+                    input.core.getDatabaseAdapter().transaction(() => obligationStore.resolve({
+                        tenantId, workspaceId: input.workspaceId, taskId: obligation.taskId,
+                        canonicalFingerprint: obligation.canonicalFingerprint, now: input.now,
+                    }))();
+                    return { resolved: true, installed: false };
+                }
+                // Compatibility for obligations created by the brief pre-
+                // revision-carrier implementation. Those rows already wrote
+                // their revision ledger coordinate before deferring.
+                return input.core.getDatabaseAdapter().transaction(() => {
+                    const revision = input.core.getDatabaseAdapter().prepare(`
+                        SELECT CAST(last_sequence AS TEXT) AS last_sequence
+                        FROM workspace_sync_entity_revisions
+                        WHERE tenant_id = ? AND workspace_id = ?
+                          AND domain = 'task-attachment-links' AND entity_id = ?
+                    `).get(tenantId, input.workspaceId, obligation.taskId);
+                    if (String(revision?.last_sequence ?? '') !== obligation.sourceSequence) {
+                        obligationStore.resolve({
+                            tenantId, workspaceId: input.workspaceId, taskId: obligation.taskId,
+                            canonicalFingerprint: obligation.canonicalFingerprint, now: input.now,
+                        });
+                        return { resolved: true, installed: false };
+                    }
+                    return installMutation();
+                })();
+            };
+            let installed;
+            const hydratedAssetIds = new Set();
+            while (true) {
+                try {
+                    installed = attemptInstall();
+                    break;
+                }
+                catch (error) {
+                    const assetId = error instanceof DurableTaskAttachmentLinksApplyError
+                        ? String(error.assetId || '').trim()
+                        : '';
+                    if (!input.hydrateAsset || !assetId || hydratedAssetIds.has(assetId))
+                        throw error;
+                    const hydration = await input.hydrateAsset(assetId);
+                    if (!hydration.success)
+                        throw new Error(hydration.error);
+                    hydratedAssetIds.add(assetId);
+                }
+            }
+            if (installed.resolved)
+                resolved += 1;
+            if (installed.installed)
+                resolvedTaskIds.push(obligation.taskId);
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error.message : 'Deferred attachment-link retry failed.';
+            const nextAttemptAt = new Date(Date.parse(input.now) + calculateAttachmentApplyObligationRetryDelayMs(obligation.attempts + 1)).toISOString();
+            obligationStore.recordAttemptFailure({
+                tenantId, workspaceId: input.workspaceId, taskId: obligation.taskId,
+                canonicalFingerprint: obligation.canonicalFingerprint,
+                error: lastError,
+                nextAttemptAt, now: input.now,
+            });
+        }
+    }
+    const summary = obligationStore.readSummary({ tenantId, workspaceId: input.workspaceId, now: input.now });
+    return {
+        attempted: due.length,
+        resolved,
+        remaining: summary.open,
+        nextAttemptAt: summary.nextAttemptAt,
+        resolvedTaskIds,
+        lastError: summary.lastError || lastError,
+    };
+}