@taskforcehq/taskforce 0.3.326 → 0.3.327

package/dist/sync/v3/workspaceSyncLocalOwnershipSnapshot.js

@@ -0,0 +1,81 @@
+import { WorkspaceSyncDurabilityStore } from './syncDurabilityStore.js';
+import { WorkspaceSyncV3CombinedProjectionStateStore } from './workspaceSyncV3CombinedProjectionState.js';
+export function readWorkspaceSyncLocalOwnershipSnapshot(input) {
+    const { core, workspaceId } = input;
+    const tenantId = core.getTenantId();
+    const database = core.getDatabaseAdapter();
+    const store = new WorkspaceSyncDurabilityStore(database);
+    const initiativeProjection = store.readInitiativeProjectionOwnership({
+        tenantId,
+        workspaceId,
+    });
+    const combinedProjectionState = new WorkspaceSyncV3CombinedProjectionStateStore(database).read({
+        tenantId,
+        workspaceId,
+    });
+    const combinedProjection = {
+        owner: combinedProjectionState.owner,
+        epoch: combinedProjectionState.epoch,
+        coverageProfileId: combinedProjectionState.coverageProfileId,
+        coverageVersion: combinedProjectionState.coverageVersion,
+        coverageDigest: combinedProjectionState.coverageDigest,
+    };
+    const tasks = store.listTaskMetadataOwnership({
+        tenantId,
+        workspaceId,
+    });
+    const activeTaskRelationshipIds = store.listActiveTaskRelationshipOperationIds({
+        tenantId,
+        workspaceId,
+    });
+    const taxonomyOwnership = store.readWorkspaceDomainOwnership({
+        tenantId,
+        workspaceId,
+        domain: 'taxonomy',
+        entityId: '__taxonomy_config__',
+    });
+    const initiativeIds = core.listInitiatives(workspaceId)
+        .map((initiative) => String(initiative.id || '').trim())
+        .filter(Boolean)
+        .sort();
+    const initiatives = [];
+    for (let offset = 0; offset < initiativeIds.length; offset += 100) {
+        initiatives.push(...store.listWorkspaceDomainOwnership({
+            tenantId,
+            workspaceId,
+            domain: 'initiative',
+            entityIds: initiativeIds.slice(offset, offset + 100),
+        }).filter((entry) => entry.activeOperation || entry.owned));
+    }
+    const workstreamIds = core.listWorkstreams(workspaceId)
+        .map((workstream) => String(workstream.id || '').trim())
+        .filter(Boolean)
+        .sort();
+    const workstreams = [];
+    for (let offset = 0; offset < workstreamIds.length; offset += 100) {
+        workstreams.push(...store.listWorkspaceDomainOwnership({
+            tenantId,
+            workspaceId,
+            domain: 'workstream',
+            entityIds: workstreamIds.slice(offset, offset + 100),
+        }).filter((entry) => entry.activeOperation || entry.owned));
+    }
+    return {
+        success: true,
+        contractVersion: 3,
+        workspaceId,
+        tasks,
+        activeTaskRelationshipIds,
+        initiatives,
+        workstreams,
+        initiativeProjection,
+        combinedProjection,
+        taxonomy: {
+            activeOperation: taxonomyOwnership.activeOperation,
+            owned: taxonomyOwnership.owned,
+            entityRevision: taxonomyOwnership.entityRevision,
+            lifecycleRevision: taxonomyOwnership.lifecycleRevision,
+            lastSequence: taxonomyOwnership.lastSequence,
+        },
+    };
+}

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

@@ -0,0 +1 @@
+export declare function fingerprintWorkspaceSyncPayload(value: unknown): string;

package/dist/sync/v3/workspaceSyncPayloadFingerprint.js

@@ -0,0 +1,5 @@
+import { createHash } from 'crypto';
+import { canonicalWorkspaceSyncJson } from './canonicalWorkspaceSyncJson.js';
+export function fingerprintWorkspaceSyncPayload(value) {
+    return createHash('sha256').update(canonicalWorkspaceSyncJson(value), 'utf8').digest('hex');
+}

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

@@ -0,0 +1,16 @@
+import type { WorkspaceSyncIncomingTaskApplyModel } from '../syncApplyHandlers.js';
+import type { WorkspaceSyncChange } from '../workspaceSyncModel.js';
+export declare const WORKSPACE_SYNC_V2_EXCLUDABLE_PROJECTIONS: readonly ["task/root-v1", "task-relationship/full-v1", "taxonomy/full-v1", "initiative/full-v1", "workstream/full-v1", "task-comments/full-v1", "task-checklist/full-v1", "task-attachment-links/full-v1", "entity-event/full-v1", "workstream-task-order/full-v1"];
+export type WorkspaceSyncV2ProjectionExclusion = typeof WORKSPACE_SYNC_V2_EXCLUDABLE_PROJECTIONS[number];
+export declare const WORKSPACE_SYNC_V3_COMBINED_V2_EXCLUSIONS: readonly WorkspaceSyncV2ProjectionExclusion[];
+export declare function normalizeWorkspaceSyncV2ProjectionExclusions(values: Iterable<unknown> | null | undefined): WorkspaceSyncV2ProjectionExclusion[];
+export declare function parseWorkspaceSyncV2ProjectionExclusions(raw: string | null | undefined): WorkspaceSyncV2ProjectionExclusion[];
+export declare function workspaceSyncV2ProjectionExclusionsEqual(left: Iterable<unknown> | null | undefined, right: Iterable<unknown> | null | undefined): boolean;
+export declare function prepareWorkspaceSyncV2TaskCarriers(taskMutations: WorkspaceSyncIncomingTaskApplyModel, excludedProjections: ReadonlySet<WorkspaceSyncV2ProjectionExclusion>, readExistingTask?: (taskId: string) => WorkspaceSyncIncomingTaskApplyModel['upserts'][number]['task'] | null): WorkspaceSyncIncomingTaskApplyModel;
+export declare function assertWorkspaceSyncV2TaskCarrierRootsExist(taskMutations: WorkspaceSyncIncomingTaskApplyModel, taskExists: (taskId: string) => boolean): void;
+export declare function isWorkspaceSyncV3CombinedLegacyFenceConfigured(env?: NodeJS.ProcessEnv): boolean;
+export declare function isWorkspaceSyncV3CombinedLegacyFenceEnabled(env?: NodeJS.ProcessEnv): boolean;
+export declare function partitionWorkspaceSyncV2LegacyChanges(changes: readonly WorkspaceSyncChange[], excludedProjections: ReadonlySet<WorkspaceSyncV2ProjectionExclusion>): {
+    changes: WorkspaceSyncChange[];
+    suppressedCounts: Partial<Record<WorkspaceSyncV2ProjectionExclusion, number>>;
+};

package/dist/sync/v3/workspaceSyncV2ProjectionExclusions.js

@@ -0,0 +1,161 @@
+import { areWorkspaceSyncV3CombinedCloudWritersReady } from './combinedFeedPrerequisites.js';
+export const WORKSPACE_SYNC_V2_EXCLUDABLE_PROJECTIONS = Object.freeze([
+    'task/root-v1',
+    'task-relationship/full-v1',
+    'taxonomy/full-v1',
+    'initiative/full-v1',
+    'workstream/full-v1',
+    'task-comments/full-v1',
+    'task-checklist/full-v1',
+    'task-attachment-links/full-v1',
+    'entity-event/full-v1',
+    'workstream-task-order/full-v1',
+]);
+export const WORKSPACE_SYNC_V3_COMBINED_V2_EXCLUSIONS = Object.freeze([
+    'task/root-v1',
+    'task-relationship/full-v1',
+    'taxonomy/full-v1',
+    'initiative/full-v1',
+    'workstream/full-v1',
+]);
+const allowed = new Set(WORKSPACE_SYNC_V2_EXCLUDABLE_PROJECTIONS);
+export function normalizeWorkspaceSyncV2ProjectionExclusions(values) {
+    const requested = new Set();
+    for (const value of values || []) {
+        const projection = String(value || '').trim();
+        if (!projection || !allowed.has(projection) || requested.has(projection)) {
+            throw new Error('Workspace sync v2 projection exclusions are invalid.');
+        }
+        requested.add(projection);
+    }
+    return WORKSPACE_SYNC_V2_EXCLUDABLE_PROJECTIONS.filter((projection) => requested.has(projection));
+}
+export function parseWorkspaceSyncV2ProjectionExclusions(raw) {
+    const value = String(raw || '').trim();
+    return value ? normalizeWorkspaceSyncV2ProjectionExclusions(value.split(',')) : [];
+}
+export function workspaceSyncV2ProjectionExclusionsEqual(left, right) {
+    try {
+        const a = normalizeWorkspaceSyncV2ProjectionExclusions(left);
+        const b = normalizeWorkspaceSyncV2ProjectionExclusions(right);
+        return a.length === b.length && a.every((projection, index) => projection === b[index]);
+    }
+    catch {
+        return false;
+    }
+}
+export function prepareWorkspaceSyncV2TaskCarriers(taskMutations, excludedProjections, readExistingTask) {
+    if (!excludedProjections.has('task/root-v1'))
+        return taskMutations;
+    const commentsOwned = excludedProjections.has('task-comments/full-v1');
+    const checklistOwned = excludedProjections.has('task-checklist/full-v1');
+    const attachmentsOwned = excludedProjections.has('task-attachment-links/full-v1');
+    if (commentsOwned && checklistOwned && attachmentsOwned) {
+        return { upserts: [], deletes: taskMutations.deletes };
+    }
+    return {
+        upserts: taskMutations.upserts.map(({ archived, task }) => {
+            const existing = readExistingTask?.(String(task.id || '').trim());
+            if ((commentsOwned || checklistOwned || attachmentsOwned) && !existing) {
+                throw new Error(`V2 task carrier ${task.id} is missing its v3-owned task root.`);
+            }
+            return {
+                archived,
+                task: {
+                    ...task,
+                    ...(commentsOwned ? { comments: existing.comments || [] } : {}),
+                    ...(checklistOwned ? { checklistItems: existing.checklistItems || [] } : {}),
+                    ...(attachmentsOwned ? { attachments: existing.attachments || [] } : {}),
+                },
+            };
+        }),
+        deletes: taskMutations.deletes,
+    };
+}
+export function assertWorkspaceSyncV2TaskCarrierRootsExist(taskMutations, taskExists) {
+    const taskIds = Array.from(new Set(taskMutations.upserts
+        .map((mutation) => String(mutation.task.id || '').trim())
+        .filter(Boolean)))
+        .sort();
+    const missingTaskId = taskIds.find((taskId) => !taskExists(taskId));
+    if (!missingTaskId)
+        return;
+    throw Object.assign(new Error(`V2 task carrier ${missingTaskId} is missing its v3-owned task root.`), { code: 'SYNC_V2_TASK_CARRIER_ROOT_MISSING', statusCode: 409 });
+}
+export function isWorkspaceSyncV3CombinedLegacyFenceConfigured(env = process.env) {
+    const enabled = (value) => /^(1|true|on|yes)$/i.test(String(value || '').trim());
+    return enabled(env.TASKFORCE_SYNC_V3_FEED_ENABLED)
+        && enabled(env.TASKFORCE_SYNC_V3_FEED_REPAIR_ENABLED)
+        && enabled(env.TASKFORCE_SYNC_V3_COMBINED_FEED_ENABLED)
+        && enabled(env.TASKFORCE_SYNC_V3_COMBINED_LEGACY_FENCE_ENABLED);
+}
+export function isWorkspaceSyncV3CombinedLegacyFenceEnabled(env = process.env) {
+    return isWorkspaceSyncV3CombinedLegacyFenceConfigured(env)
+        && areWorkspaceSyncV3CombinedCloudWritersReady(env);
+}
+export function partitionWorkspaceSyncV2LegacyChanges(changes, excludedProjections) {
+    const accepted = [];
+    const suppressedCounts = {};
+    const suppress = (projection) => {
+        suppressedCounts[projection] = (suppressedCounts[projection] || 0) + 1;
+    };
+    for (const change of changes) {
+        if (change.op === 'upsert') {
+            const commentsOwned = excludedProjections.has('task-comments/full-v1');
+            const checklistOwned = excludedProjections.has('task-checklist/full-v1');
+            const attachmentsOwned = excludedProjections.has('task-attachment-links/full-v1');
+            if (excludedProjections.has('task/root-v1') && commentsOwned && checklistOwned && attachmentsOwned) {
+                suppress('task/root-v1');
+                suppress('task-comments/full-v1');
+                suppress('task-checklist/full-v1');
+                suppress('task-attachment-links/full-v1');
+                continue;
+            }
+            if (commentsOwned || checklistOwned || attachmentsOwned) {
+                const task = { ...change.task };
+                if (commentsOwned) {
+                    delete task.comments;
+                    suppress('task-comments/full-v1');
+                }
+                if (checklistOwned) {
+                    delete task.checklistItems;
+                    suppress('task-checklist/full-v1');
+                }
+                if (attachmentsOwned) {
+                    delete task.attachments;
+                    suppress('task-attachment-links/full-v1');
+                }
+                accepted.push({ ...change, task });
+                continue;
+            }
+        }
+        if (excludedProjections.has('task/root-v1') && change.op === 'delete') {
+            suppress('task/root-v1');
+            continue;
+        }
+        if (excludedProjections.has('task-relationship/full-v1')
+            && (change.op === 'task-relationship-upsert' || change.op === 'task-relationship-delete')) {
+            suppress('task-relationship/full-v1');
+            continue;
+        }
+        if (excludedProjections.has('taxonomy/full-v1') && change.op === 'taxonomy-upsert') {
+            suppress('taxonomy/full-v1');
+            continue;
+        }
+        if (excludedProjections.has('initiative/full-v1') && change.op === 'initiative-upsert') {
+            suppress('initiative/full-v1');
+            continue;
+        }
+        if (excludedProjections.has('workstream/full-v1') && change.op === 'workstream-upsert') {
+            suppress('workstream/full-v1');
+            continue;
+        }
+        if (excludedProjections.has('entity-event/full-v1')
+            && (change.op === 'task-event-upsert' || change.op === 'entity-event-upsert')) {
+            suppress('entity-event/full-v1');
+            continue;
+        }
+        accepted.push(change);
+    }
+    return { changes: accepted, suppressedCounts };
+}

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

@@ -0,0 +1,83 @@
+import type { DatabaseAdapter } from '../../storage/databaseAdapter.js';
+export interface WorkspaceSyncV3AttachmentApplyObligation {
+    tenantId: string;
+    workspaceId: string;
+    taskId: string;
+    assetIds: string[];
+    payloadJson: string;
+    canonicalFingerprint: string;
+    sourceSequence: string;
+    entityRevision: string | null;
+    lifecycleRevision: string | null;
+    revisionFingerprint: string | null;
+    attempts: number;
+    lastError: string | null;
+    createdAt: string;
+    updatedAt: string;
+    nextAttemptAt: string;
+    resolvedAt: string | null;
+}
+export interface WorkspaceSyncV3AttachmentApplyObligationSummary {
+    open: number;
+    due: number;
+    oldestOpenCreatedAt: string | null;
+    nextAttemptAt: string | null;
+    totalAttempts: number;
+    lastError: string | null;
+}
+export declare class WorkspaceSyncV3AttachmentApplyObligationStore {
+    private readonly db;
+    constructor(db: DatabaseAdapter);
+    recordDeferred(input: {
+        tenantId: string;
+        workspaceId: string;
+        taskId: string;
+        assetIds: readonly string[];
+        payloadJson: string;
+        canonicalFingerprint: string;
+        sourceSequence: string;
+        entityRevision?: string;
+        lifecycleRevision?: string;
+        revisionFingerprint?: string;
+        error: string;
+        now: string;
+    }): void;
+    listDue(input: {
+        tenantId: string;
+        workspaceId: string;
+        now: string;
+        limit?: number;
+    }): WorkspaceSyncV3AttachmentApplyObligation[];
+    countOpen(input: {
+        tenantId: string;
+        workspaceId: string;
+    }): number;
+    readSummary(input: {
+        tenantId: string;
+        workspaceId: string;
+        now: string;
+    }): WorkspaceSyncV3AttachmentApplyObligationSummary;
+    resolve(input: {
+        tenantId: string;
+        workspaceId: string;
+        taskId: string;
+        canonicalFingerprint: string;
+        now: string;
+    }): void;
+    resolveSuperseded(input: {
+        tenantId: string;
+        workspaceId: string;
+        taskId: string;
+        now: string;
+    }): void;
+    recordAttemptFailure(input: {
+        tenantId: string;
+        workspaceId: string;
+        taskId: string;
+        canonicalFingerprint: string;
+        error: string;
+        nextAttemptAt: string;
+        now: string;
+    }): void;
+}
+export declare function calculateAttachmentApplyObligationRetryDelayMs(attempts: number): number;

package/dist/sync/v3/workspaceSyncV3AttachmentApplyObligationStore.js

@@ -0,0 +1,161 @@
+function requiredText(value, field) {
+    const normalized = String(value || '').trim();
+    if (!normalized)
+        throw new TypeError(`${field} is required.`);
+    return normalized;
+}
+function mapRow(row) {
+    let assetIds = [];
+    try {
+        const parsed = JSON.parse(row.asset_ids_json);
+        if (Array.isArray(parsed))
+            assetIds = parsed.map((value) => String(value));
+    }
+    catch { /* malformed rows surface as an empty asset list, not a crash */ }
+    return {
+        tenantId: row.tenant_id,
+        workspaceId: row.workspace_id,
+        taskId: row.task_id,
+        assetIds,
+        payloadJson: row.payload_json,
+        canonicalFingerprint: row.canonical_fingerprint,
+        sourceSequence: String(row.source_sequence),
+        entityRevision: row.entity_revision == null ? null : String(row.entity_revision),
+        lifecycleRevision: row.lifecycle_revision == null ? null : String(row.lifecycle_revision),
+        revisionFingerprint: row.revision_fingerprint,
+        attempts: Number(row.attempts),
+        lastError: row.last_error,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        nextAttemptAt: row.next_attempt_at,
+        resolvedAt: row.resolved_at,
+    };
+}
+export class WorkspaceSyncV3AttachmentApplyObligationStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    // Upserts the deferred entry keyed by task, so a newer authoritative
+    // attachment-links payload for the same task supersedes a stale deferred
+    // one instead of accumulating duplicate recovery debt. A payload with an
+    // older-or-equal source sequence than an already-open obligation is
+    // ignored (out-of-order/duplicate delivery of the same or older state).
+    recordDeferred(input) {
+        const tenantId = requiredText(input.tenantId, 'tenantId');
+        const workspaceId = requiredText(input.workspaceId, 'workspaceId');
+        const taskId = requiredText(input.taskId, 'taskId');
+        const sourceSequence = requiredText(input.sourceSequence, 'sourceSequence');
+        const now = requiredText(input.now, 'now');
+        this.db.prepare(`
+            INSERT INTO workspace_sync_v3_attachment_apply_obligations (
+                tenant_id, workspace_id, task_id, asset_ids_json, payload_json,
+                canonical_fingerprint, source_sequence, attempts, last_error,
+                entity_revision, lifecycle_revision, revision_fingerprint,
+                created_at, updated_at, next_attempt_at, resolved_at
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, NULL)
+            ON CONFLICT (tenant_id, workspace_id, task_id) DO UPDATE SET
+                asset_ids_json = excluded.asset_ids_json,
+                payload_json = excluded.payload_json,
+                canonical_fingerprint = excluded.canonical_fingerprint,
+                source_sequence = excluded.source_sequence,
+                entity_revision = excluded.entity_revision,
+                lifecycle_revision = excluded.lifecycle_revision,
+                revision_fingerprint = excluded.revision_fingerprint,
+                attempts = 0,
+                last_error = excluded.last_error,
+                updated_at = excluded.updated_at,
+                next_attempt_at = excluded.next_attempt_at,
+                resolved_at = NULL
+            WHERE workspace_sync_v3_attachment_apply_obligations.resolved_at IS NOT NULL
+               OR CAST(excluded.source_sequence AS ${this.db.provider === 'postgres' ? 'BIGINT' : 'INTEGER'})
+                    > CAST(workspace_sync_v3_attachment_apply_obligations.source_sequence AS ${this.db.provider === 'postgres' ? 'BIGINT' : 'INTEGER'})
+        `).run(tenantId, workspaceId, taskId, JSON.stringify([...new Set(input.assetIds.map((value) => String(value)))]), input.payloadJson, requiredText(input.canonicalFingerprint, 'canonicalFingerprint'), sourceSequence, String(input.error || '').slice(0, 500) || null, input.entityRevision == null ? null : requiredText(input.entityRevision, 'entityRevision'), input.lifecycleRevision == null ? null : requiredText(input.lifecycleRevision, 'lifecycleRevision'), input.revisionFingerprint == null ? null : requiredText(input.revisionFingerprint, 'revisionFingerprint'), now, now, now);
+    }
+    listDue(input) {
+        const limit = Math.max(1, Math.min(50, Math.floor(Number(input.limit) || 5)));
+        const rows = this.db.prepare(`
+            SELECT *
+            FROM workspace_sync_v3_attachment_apply_obligations
+            WHERE tenant_id = ? AND workspace_id = ? AND resolved_at IS NULL AND next_attempt_at <= ?
+            ORDER BY next_attempt_at ASC, task_id ASC
+            LIMIT ?
+        `).all(input.tenantId, input.workspaceId, input.now, limit);
+        return rows.map(mapRow);
+    }
+    countOpen(input) {
+        const row = this.db.prepare(`
+            SELECT COUNT(*) AS count
+            FROM workspace_sync_v3_attachment_apply_obligations
+            WHERE tenant_id = ? AND workspace_id = ? AND resolved_at IS NULL
+        `).get(input.tenantId, input.workspaceId);
+        return Number(row?.count || 0);
+    }
+    readSummary(input) {
+        const aggregate = this.db.prepare(`
+            SELECT COUNT(*) AS open,
+                   SUM(CASE WHEN next_attempt_at <= ? THEN 1 ELSE 0 END) AS due,
+                   MIN(created_at) AS oldest_open_created_at,
+                   MIN(next_attempt_at) AS next_attempt_at,
+                   SUM(attempts) AS total_attempts
+            FROM workspace_sync_v3_attachment_apply_obligations
+            WHERE tenant_id = ? AND workspace_id = ? AND resolved_at IS NULL
+        `).get(input.now, input.tenantId, input.workspaceId);
+        const latest = this.db.prepare(`
+            SELECT last_error
+            FROM workspace_sync_v3_attachment_apply_obligations
+            WHERE tenant_id = ? AND workspace_id = ? AND resolved_at IS NULL
+              AND last_error IS NOT NULL
+            ORDER BY updated_at DESC, task_id ASC
+            LIMIT 1
+        `).get(input.tenantId, input.workspaceId);
+        return {
+            open: Number(aggregate?.open || 0),
+            due: Number(aggregate?.due || 0),
+            oldestOpenCreatedAt: aggregate?.oldest_open_created_at || null,
+            nextAttemptAt: aggregate?.next_attempt_at || null,
+            totalAttempts: Number(aggregate?.total_attempts || 0),
+            lastError: latest?.last_error || null,
+        };
+    }
+    // Resolved on success (the deferred entry finally installed) or when the
+    // obligation becomes moot (e.g. the task was deleted). Fenced on the
+    // exact canonical fingerprint so a concurrently-upserted newer deferred
+    // payload for the same task is never silently resolved out from under
+    // its own retry.
+    resolve(input) {
+        this.db.prepare(`
+            UPDATE workspace_sync_v3_attachment_apply_obligations
+            SET resolved_at = ?, updated_at = ?
+            WHERE tenant_id = ? AND workspace_id = ? AND task_id = ?
+              AND canonical_fingerprint = ? AND resolved_at IS NULL
+        `).run(input.now, input.now, input.tenantId, input.workspaceId, input.taskId, input.canonicalFingerprint);
+    }
+    // Clears any open obligation for this task regardless of fingerprint. A
+    // task-attachment-links entry that just installed successfully is, by
+    // construction, the newest applied state for that task's aggregate, so
+    // any still-open deferred entry for the same task is moot.
+    resolveSuperseded(input) {
+        this.db.prepare(`
+            UPDATE workspace_sync_v3_attachment_apply_obligations
+            SET resolved_at = ?, updated_at = ?
+            WHERE tenant_id = ? AND workspace_id = ? AND task_id = ? AND resolved_at IS NULL
+        `).run(input.now, input.now, input.tenantId, input.workspaceId, input.taskId);
+    }
+    recordAttemptFailure(input) {
+        this.db.prepare(`
+            UPDATE workspace_sync_v3_attachment_apply_obligations
+            SET attempts = attempts + 1, last_error = ?, updated_at = ?, next_attempt_at = ?
+            WHERE tenant_id = ? AND workspace_id = ? AND task_id = ?
+              AND canonical_fingerprint = ? AND resolved_at IS NULL
+        `).run(String(input.error || '').slice(0, 500), input.now, input.nextAttemptAt, input.tenantId, input.workspaceId, input.taskId, input.canonicalFingerprint);
+    }
+}
+// Bounded exponential backoff for a still-unresolved obligation: starts near
+// a minute (hydration is often fast once the dependency actually settles)
+// and caps at 30 minutes so a permanently-missing asset cannot make this
+// obligation spin, but still gets periodically rechecked.
+export function calculateAttachmentApplyObligationRetryDelayMs(attempts) {
+    const attempt = Math.max(1, Math.min(20, Math.floor(attempts || 1)));
+    return Math.min(30 * 60_000, 60_000 * (2 ** (attempt - 1)));
+}

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

@@ -0,0 +1,16 @@
+import type { WorkspaceSyncEngineLocalServices } from '../engine/workspaceSyncEngineLocalServices.js';
+import type { WorkspaceSyncEngineRemoteServices } from '../engine/workspaceSyncEngineRemoteServices.js';
+export type WorkspaceSyncV3AttachmentAssetHydrationResult = {
+    success: true;
+    appliedChanges: number;
+    emittedEventIds: string[];
+} | {
+    success: false;
+    error: string;
+};
+export declare function hydrateWorkspaceSyncV3AttachmentAsset(input: {
+    workspaceId: string;
+    assetId: string;
+    remoteServices: Pick<WorkspaceSyncEngineRemoteServices, 'pullWorkspaceContent' | 'abandonTransferReceipts' | 'buildV2ApplyCompletionGroup'>;
+    localServices: Pick<WorkspaceSyncEngineLocalServices, 'applyV2Batch'>;
+}): Promise<WorkspaceSyncV3AttachmentAssetHydrationResult>;

package/dist/sync/v3/workspaceSyncV3AttachmentAssetHydration.js

@@ -0,0 +1,90 @@
+import { decryptWorkspaceSyncContentChangeInPlace } from '../workspaceSyncContentDecryption.js';
+import { fingerprintWorkspaceContentBody } from '../workspaceContentManifest.js';
+export async function hydrateWorkspaceSyncV3AttachmentAsset(input) {
+    const remoteServices = input.remoteServices;
+    const applyV2Batch = input.localServices.applyV2Batch;
+    const response = await remoteServices.pullWorkspaceContent({
+        workspaceId: input.workspaceId,
+        requests: [{ kind: 'asset', assetId: input.assetId }],
+        previousCursor: null,
+    });
+    const receipt = response.transferReceipt;
+    let transferCommitted = false;
+    try {
+        if (!response.ok) {
+            return { success: false, error: `Workspace attachment asset hydration failed (${response.status || 0}).` };
+        }
+        const data = response.data || {};
+        if ((data.missing?.length || 0) > 0 || (data.remaining?.length || 0) > 0) {
+            return { success: false, error: `Workspace attachment asset is unavailable in cloud content: ${input.assetId}` };
+        }
+        const rawChanges = Array.isArray(data.changes) ? data.changes : [];
+        const changes = rawChanges.filter((change) => ((change.op === 'document-upsert' || change.op === 'asset-upsert')
+            && String(change.assetId || '').trim() === input.assetId));
+        if (rawChanges.length !== 1 || changes.length !== 1) {
+            return { success: false, error: `Workspace attachment asset hydration returned an unexpected payload: ${input.assetId}` };
+        }
+        try {
+            await decryptWorkspaceSyncContentChangeInPlace(changes[0], typeof process !== 'undefined' ? process.env?.TASKFORCE_SYNC_KEY : undefined);
+        }
+        catch {
+            return { success: false, error: `Workspace attachment asset hydration decryption failed: ${input.assetId}` };
+        }
+        const contentMetadata = Array.isArray(data.contentMetadata)
+            ? data.contentMetadata
+            : [];
+        const expectedContentKind = changes[0].op === 'document-upsert'
+            ? 'document'
+            : 'asset';
+        const matchingMetadata = contentMetadata.filter((entry) => (entry.kind === expectedContentKind
+            && entry.assetId === input.assetId
+            && entry.path === changes[0].path));
+        if (contentMetadata.length !== 1 || matchingMetadata.length !== 1) {
+            return { success: false, error: `Workspace attachment asset hydration metadata is unavailable: ${input.assetId}` };
+        }
+        const metadata = matchingMetadata[0];
+        const actual = changes[0].op === 'document-upsert'
+            ? await fingerprintWorkspaceContentBody('document', changes[0].content)
+            : await fingerprintWorkspaceContentBody('asset', changes[0].contentBase64);
+        if (actual.sha256 !== metadata.sha256.toLowerCase() || actual.sizeBytes !== metadata.sizeBytes) {
+            return { success: false, error: `Workspace attachment asset hydration verification failed: ${input.assetId}` };
+        }
+        const completionGroup = receipt
+            ? remoteServices.buildV2ApplyCompletionGroup({
+                workspaceId: input.workspaceId,
+                previousCursor: null,
+                nextCursor: null,
+                receipts: [receipt],
+            })
+            : undefined;
+        if (receipt && !completionGroup) {
+            return {
+                success: false,
+                error: 'Workspace attachment asset hydration could not bind its transfer to local apply.',
+            };
+        }
+        const applyResult = completionGroup
+            ? await applyV2Batch(input.workspaceId, changes, { completionGroup })
+            : await applyV2Batch(input.workspaceId, changes);
+        if (!applyResult.ok) {
+            return { success: false, error: `Workspace attachment asset hydration apply failed (${applyResult.status || 0}).` };
+        }
+        transferCommitted = true;
+        const applyData = applyResult.data && typeof applyResult.data === 'object'
+            ? applyResult.data
+            : {};
+        const emittedEventIds = Array.isArray(applyData.emittedEventIds)
+            ? applyData.emittedEventIds.map((value) => String(value || '').trim()).filter(Boolean)
+            : [];
+        return { success: true, appliedChanges: changes.length, emittedEventIds };
+    }
+    finally {
+        if (receipt && !transferCommitted) {
+            await remoteServices.abandonTransferReceipts({
+                workspaceId: input.workspaceId,
+                receipts: [receipt],
+                errorCode: 'WORKSPACE_SYNC_V3_ATTACHMENT_HYDRATION_NOT_COMMITTED',
+            });
+        }
+    }
+}