@taskforcehq/taskforce 0.3.326 → 0.3.327

package/dist/sync/engine/localWorkspaceContentManifestService.d.ts

@@ -0,0 +1,21 @@
+import type { BinaryAssetSyncIndexEntry, DocumentSyncIndexEntry } from '../contentSyncState.js';
+import { type WorkspaceContentManifestV1 } from '../workspaceContentManifest.js';
+export interface LocalWorkspaceContentManifestCore {
+    getPaths(): {
+        basePath: string;
+    };
+}
+export interface LocalWorkspaceContentManifestState {
+    listWorkspaceSyncDocumentIndex(basePath: string, workspaceId: string): Promise<DocumentSyncIndexEntry[]>;
+    listWorkspaceSyncBinaryAssetIndex(workspaceId: string): Promise<BinaryAssetSyncIndexEntry[]>;
+}
+export interface LocalWorkspaceContentManifestResult extends WorkspaceContentManifestV1 {
+    success: true;
+}
+interface ReadLocalWorkspaceContentManifestArgs {
+    core: LocalWorkspaceContentManifestCore;
+    contentSyncState: LocalWorkspaceContentManifestState;
+    workspaceId: string;
+}
+export declare function readLocalWorkspaceContentManifest({ core, contentSyncState, workspaceId, }: ReadLocalWorkspaceContentManifestArgs): Promise<LocalWorkspaceContentManifestResult>;
+export {};

package/dist/sync/engine/localWorkspaceContentManifestService.js

@@ -0,0 +1,44 @@
+import { WORKSPACE_CONTENT_MANIFEST_VERSION, createWorkspaceContentMetadataFingerprintV1, } from '../workspaceContentManifest.js';
+export async function readLocalWorkspaceContentManifest({ core, contentSyncState, workspaceId, }) {
+    const basePath = core.getPaths().basePath;
+    const [documents, assets] = await Promise.all([
+        contentSyncState.listWorkspaceSyncDocumentIndex(basePath, workspaceId),
+        contentSyncState.listWorkspaceSyncBinaryAssetIndex(workspaceId),
+    ]);
+    const entries = [
+        ...documents.map((entry) => ({
+            manifestVersion: WORKSPACE_CONTENT_MANIFEST_VERSION,
+            kind: 'document',
+            path: entry.path,
+            sha256: entry.contentSha256,
+            sizeBytes: entry.sizeBytes,
+            updatedAt: entry.updatedAt,
+            metadataFingerprint: createWorkspaceContentMetadataFingerprintV1({
+                kind: 'document',
+                metadata: {
+                    ...entry,
+                    linkRole: entry.linkRole === 'reference' ? 'reference' : 'attachment',
+                },
+            }),
+            existsLocally: entry.contentAvailable,
+        })),
+        ...assets.map((asset) => ({
+            manifestVersion: WORKSPACE_CONTENT_MANIFEST_VERSION,
+            kind: 'asset',
+            path: asset.path,
+            sha256: asset.contentSha256,
+            sizeBytes: asset.sizeBytes,
+            updatedAt: asset.updatedAt,
+            metadataFingerprint: createWorkspaceContentMetadataFingerprintV1({
+                kind: 'asset',
+                metadata: { ...asset, assetKind: asset.kind },
+            }),
+            existsLocally: asset.contentAvailable,
+        })),
+    ];
+    return {
+        success: true,
+        manifestVersion: WORKSPACE_CONTENT_MANIFEST_VERSION,
+        entries,
+    };
+}

package/dist/sync/engine/workspaceSyncAtomicLocalPublisher.d.ts

@@ -0,0 +1,36 @@
+export interface WorkspaceSyncAtomicLocalFileHandle {
+    write(buffer: Buffer, offset: number, length: number, position: number): number;
+    setTimes(atime: Date, mtime: Date): void;
+    sync(): void;
+    close(): void;
+}
+export interface WorkspaceSyncAtomicLocalFileOperations {
+    mkdir(directory: string): void;
+    openExclusive(filePath: string): WorkspaceSyncAtomicLocalFileHandle;
+    readFile(filePath: string): Buffer;
+    rename(source: string, destination: string): void;
+    unlink(filePath: string): void;
+    syncDirectory(directory: string): void;
+    cleanupAbandonedTemporaries(directory: string): number;
+}
+export declare class WorkspaceSyncAtomicLocalPublicationError extends Error {
+    readonly code: 'SYNC_LOCAL_CONTENT_INPUT_INVALID' | 'SYNC_LOCAL_CONTENT_VERIFICATION_FAILED' | 'SYNC_LOCAL_CONTENT_PUBLICATION_FAILED';
+    readonly boundary: 'input' | 'open' | 'write' | 'timestamp' | 'flush' | 'verify' | 'rename' | 'directory-sync';
+    readonly published: boolean;
+    constructor(code: 'SYNC_LOCAL_CONTENT_INPUT_INVALID' | 'SYNC_LOCAL_CONTENT_VERIFICATION_FAILED' | 'SYNC_LOCAL_CONTENT_PUBLICATION_FAILED', boundary: 'input' | 'open' | 'write' | 'timestamp' | 'flush' | 'verify' | 'rename' | 'directory-sync', published: boolean, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function cleanupAbandonedWorkspaceSyncTemporaryFiles(directory: string, options?: {
+    nowMs?: number;
+    minAgeMs?: number;
+    limit?: number;
+}): number;
+export interface WorkspaceSyncAtomicLocalPublicationInput {
+    targetPath: string;
+    body: Buffer;
+    expectedSha256: string;
+    expectedSizeBytes: number;
+    sourceUpdatedAt?: Date | null;
+}
+export declare function publishWorkspaceSyncLocalFileAtomically(input: WorkspaceSyncAtomicLocalPublicationInput, fileOperations?: WorkspaceSyncAtomicLocalFileOperations): void;

package/dist/sync/engine/workspaceSyncAtomicLocalPublisher.js

@@ -0,0 +1,203 @@
+import { createHash, randomUUID } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
+const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/;
+const TEMPORARY_FILE_PATTERN = /^\.taskforce-sync-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.tmp$/i;
+const DEFAULT_TEMPORARY_MIN_AGE_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_TEMPORARY_CLEANUP_LIMIT = 32;
+const TEMPORARY_CLEANUP_INTERVAL_MS = 60 * 60 * 1000;
+const lastTemporaryCleanupAtByDirectory = new Map();
+export class WorkspaceSyncAtomicLocalPublicationError extends Error {
+    code;
+    boundary;
+    published;
+    constructor(code, boundary, published, message, options) {
+        super(message, options);
+        this.code = code;
+        this.boundary = boundary;
+        this.published = published;
+        this.name = 'WorkspaceSyncAtomicLocalPublicationError';
+    }
+}
+function isMissingFileError(error) {
+    return Boolean(error
+        && typeof error === 'object'
+        && 'code' in error
+        && error.code === 'ENOENT');
+}
+function isUnsupportedDirectorySyncError(error) {
+    if (!error || typeof error !== 'object' || !('code' in error))
+        return false;
+    return ['EINVAL', 'ENOTSUP', 'EISDIR', 'EPERM'].includes(String(error.code));
+}
+export function cleanupAbandonedWorkspaceSyncTemporaryFiles(directory, options = {}) {
+    const nowMs = options.nowMs ?? Date.now();
+    const minAgeMs = options.minAgeMs ?? DEFAULT_TEMPORARY_MIN_AGE_MS;
+    const limit = Math.max(0, Math.floor(options.limit ?? DEFAULT_TEMPORARY_CLEANUP_LIMIT));
+    if (limit === 0)
+        return 0;
+    let entries;
+    try {
+        entries = fs.readdirSync(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isMissingFileError(error))
+            return 0;
+        throw error;
+    }
+    let deleted = 0;
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        if (deleted >= limit)
+            break;
+        if (!entry.isFile() || !TEMPORARY_FILE_PATTERN.test(entry.name))
+            continue;
+        const temporaryPath = path.join(directory, entry.name);
+        let stat;
+        try {
+            stat = fs.lstatSync(temporaryPath);
+        }
+        catch (error) {
+            if (isMissingFileError(error))
+                continue;
+            throw error;
+        }
+        if (!stat.isFile() || nowMs - stat.mtimeMs < minAgeMs)
+            continue;
+        try {
+            fs.unlinkSync(temporaryPath);
+            deleted += 1;
+        }
+        catch (error) {
+            if (!isMissingFileError(error))
+                throw error;
+        }
+    }
+    return deleted;
+}
+const defaultFileOperations = {
+    mkdir: (directory) => fs.mkdirSync(directory, { recursive: true }),
+    openExclusive: (filePath) => {
+        const descriptor = fs.openSync(filePath, 'wx');
+        return {
+            write: (buffer, offset, length, position) => fs.writeSync(descriptor, buffer, offset, length, position),
+            setTimes: (atime, mtime) => fs.futimesSync(descriptor, atime, mtime),
+            sync: () => fs.fsyncSync(descriptor),
+            close: () => fs.closeSync(descriptor),
+        };
+    },
+    readFile: (filePath) => fs.readFileSync(filePath),
+    rename: (source, destination) => fs.renameSync(source, destination),
+    unlink: (filePath) => fs.unlinkSync(filePath),
+    syncDirectory: (directory) => {
+        let descriptor = null;
+        try {
+            descriptor = fs.openSync(directory, 'r');
+            fs.fsyncSync(descriptor);
+        }
+        catch (error) {
+            if (!isUnsupportedDirectorySyncError(error))
+                throw error;
+        }
+        finally {
+            if (descriptor !== null)
+                fs.closeSync(descriptor);
+        }
+    },
+    cleanupAbandonedTemporaries: (directory) => {
+        const nowMs = Date.now();
+        const lastCleanupAt = lastTemporaryCleanupAtByDirectory.get(directory) ?? 0;
+        if (nowMs - lastCleanupAt < TEMPORARY_CLEANUP_INTERVAL_MS)
+            return 0;
+        const deleted = cleanupAbandonedWorkspaceSyncTemporaryFiles(directory, { nowMs });
+        lastTemporaryCleanupAtByDirectory.set(directory, nowMs);
+        return deleted;
+    },
+};
+function assertVerifiedBytes(body, expectedSha256, expectedSizeBytes, targetPath) {
+    const actualSha256 = createHash('sha256').update(body).digest('hex');
+    if (body.byteLength !== expectedSizeBytes || actualSha256 !== expectedSha256) {
+        throw new WorkspaceSyncAtomicLocalPublicationError('SYNC_LOCAL_CONTENT_VERIFICATION_FAILED', 'verify', false, `Atomic local content verification failed for ${targetPath}.`);
+    }
+}
+function validateInput(input) {
+    const targetPath = String(input.targetPath || '');
+    const expectedSha256 = String(input.expectedSha256 || '').trim().toLowerCase();
+    if (!path.isAbsolute(targetPath)
+        || !Buffer.isBuffer(input.body)
+        || !SHA256_HEX_PATTERN.test(expectedSha256)
+        || !Number.isSafeInteger(input.expectedSizeBytes)
+        || input.expectedSizeBytes < 0) {
+        throw new WorkspaceSyncAtomicLocalPublicationError('SYNC_LOCAL_CONTENT_INPUT_INVALID', 'input', false, 'Atomic local content publication requires an absolute target, bytes, SHA-256, and size.');
+    }
+    assertVerifiedBytes(input.body, expectedSha256, input.expectedSizeBytes, targetPath);
+    return { targetPath, expectedSha256 };
+}
+function writeFully(file, body) {
+    let offset = 0;
+    while (offset < body.byteLength) {
+        const bytesWritten = file.write(body, offset, body.byteLength - offset, offset);
+        if (!Number.isSafeInteger(bytesWritten) || bytesWritten <= 0) {
+            throw new Error('Atomic local content temporary write made no progress.');
+        }
+        offset += bytesWritten;
+    }
+}
+export function publishWorkspaceSyncLocalFileAtomically(input, fileOperations = defaultFileOperations) {
+    const { targetPath, expectedSha256 } = validateInput(input);
+    const parentPath = path.dirname(targetPath);
+    fileOperations.mkdir(parentPath);
+    try {
+        fileOperations.cleanupAbandonedTemporaries(parentPath);
+    }
+    catch {
+        // Cleanup is bounded maintenance and must not prevent a valid publication.
+    }
+    const temporaryPath = path.join(parentPath, `.taskforce-sync-${randomUUID()}.tmp`);
+    let temporaryFile = null;
+    let temporaryExists = false;
+    let published = false;
+    let boundary = 'open';
+    try {
+        temporaryFile = fileOperations.openExclusive(temporaryPath);
+        temporaryExists = true;
+        boundary = 'write';
+        writeFully(temporaryFile, input.body);
+        if (input.sourceUpdatedAt) {
+            boundary = 'timestamp';
+            temporaryFile.setTimes(input.sourceUpdatedAt, input.sourceUpdatedAt);
+        }
+        boundary = 'flush';
+        temporaryFile.sync();
+        temporaryFile.close();
+        temporaryFile = null;
+        boundary = 'verify';
+        assertVerifiedBytes(fileOperations.readFile(temporaryPath), expectedSha256, input.expectedSizeBytes, targetPath);
+        boundary = 'rename';
+        fileOperations.rename(temporaryPath, targetPath);
+        temporaryExists = false;
+        published = true;
+        boundary = 'directory-sync';
+        fileOperations.syncDirectory(parentPath);
+    }
+    catch (error) {
+        if (temporaryFile) {
+            try {
+                temporaryFile.close();
+            }
+            catch {
+                // Preserve the original publication failure.
+            }
+        }
+        if (temporaryExists) {
+            try {
+                fileOperations.unlink(temporaryPath);
+            }
+            catch {
+                // A later bounded cleanup can remove an abandoned temporary.
+            }
+        }
+        if (error instanceof WorkspaceSyncAtomicLocalPublicationError)
+            throw error;
+        throw new WorkspaceSyncAtomicLocalPublicationError('SYNC_LOCAL_CONTENT_PUBLICATION_FAILED', boundary, published, `Failed to publish atomic local content for ${targetPath}.`, { cause: error });
+    }
+}

package/dist/sync/engine/workspaceSyncContentLifecycleAdapter.d.ts

@@ -0,0 +1,21 @@
+import { type WorkspaceSyncContentHead, type WorkspaceSyncContentKind, type WorkspaceSyncContentScope, type WorkspaceSyncContentVersionStore } from './workspaceSyncContentVersionStore.js';
+export type WorkspaceSyncContentTombstoneInput = WorkspaceSyncContentScope & {
+    kind: WorkspaceSyncContentKind;
+    logicalPath: string;
+    sourceUpdatedAt: string;
+    publishedAt: string;
+    deletedAt: string;
+    retireGcAfter?: string | null;
+};
+export interface WorkspaceSyncContentLifecyclePort {
+    tombstone(input: WorkspaceSyncContentTombstoneInput): WorkspaceSyncContentHead;
+}
+/**
+ * Synchronous database-only lifecycle boundary for immutable workspace content.
+ * Physical provider deletion is intentionally owned by the post-commit GC path.
+ */
+export declare class WorkspaceSyncContentLifecycleAdapter implements WorkspaceSyncContentLifecyclePort {
+    private readonly versions;
+    constructor(versions: Pick<WorkspaceSyncContentVersionStore, 'tombstone'>);
+    tombstone(input: WorkspaceSyncContentTombstoneInput): WorkspaceSyncContentHead;
+}

package/dist/sync/engine/workspaceSyncContentLifecycleAdapter.js

@@ -0,0 +1,13 @@
+/**
+ * Synchronous database-only lifecycle boundary for immutable workspace content.
+ * Physical provider deletion is intentionally owned by the post-commit GC path.
+ */
+export class WorkspaceSyncContentLifecycleAdapter {
+    versions;
+    constructor(versions) {
+        this.versions = versions;
+    }
+    tombstone(input) {
+        return this.versions.tombstone(input);
+    }
+}

package/dist/sync/engine/workspaceSyncContentPullObligationStore.d.ts

@@ -0,0 +1,65 @@
+import type { DatabaseAdapter } from '../../storage/databaseAdapter.js';
+import type { WorkspaceContentManifestEntry, WorkspaceContentManifestKind } from '../workspaceContentManifest.js';
+export interface WorkspaceSyncContentPullObligation {
+    tenantId: string;
+    workspaceId: string;
+    kind: WorkspaceContentManifestKind;
+    path: string;
+    sourceWatermark: string;
+    metadataFingerprint: string;
+    expectedSha256: string;
+    expectedSizeBytes: number;
+    manifestUpdatedAt: string;
+    attempts: number;
+    lastError: string | null;
+    createdAt: string;
+    updatedAt: string;
+    resolvedAt: string | null;
+}
+export interface WorkspaceSyncContentPullObligationInput {
+    manifest: WorkspaceContentManifestEntry;
+    sourceWatermark: string;
+}
+export type WorkspaceSyncContentPullObligationResolutionClaim = {
+    kind: WorkspaceContentManifestKind;
+    path: string;
+    sourceWatermark: string;
+} & ({
+    resolution: 'exact-version';
+    metadataFingerprint: string;
+} | {
+    resolution: 'at-or-before-watermark';
+});
+export declare function workspaceSyncContentPullObligationId(value: Pick<WorkspaceSyncContentPullObligation, 'kind' | 'path'>): string;
+export declare class WorkspaceSyncContentPullObligationStore {
+    private readonly db;
+    constructor(db: DatabaseAdapter);
+    upsertMany(input: {
+        tenantId: string;
+        workspaceId: string;
+        obligations: readonly WorkspaceSyncContentPullObligationInput[];
+        now: string;
+    }): void;
+    listOpen(input: {
+        tenantId: string;
+        workspaceId: string;
+        limit?: number;
+    }): WorkspaceSyncContentPullObligation[];
+    resolveMany(input: {
+        tenantId: string;
+        workspaceId: string;
+        claims: readonly WorkspaceSyncContentPullObligationResolutionClaim[];
+        now: string;
+    }): void;
+    recordAttemptFailure(input: {
+        tenantId: string;
+        workspaceId: string;
+        obligationIds: readonly string[];
+        error: string;
+        now: string;
+    }): void;
+    countOpen(input: {
+        tenantId: string;
+        workspaceId: string;
+    }): number;
+}

package/dist/sync/engine/workspaceSyncContentPullObligationStore.js

@@ -0,0 +1,160 @@
+function requiredText(value, field) {
+    const normalized = String(value || '').trim();
+    if (!normalized)
+        throw new TypeError(`${field} is required.`);
+    return normalized;
+}
+function mapRow(row) {
+    return {
+        tenantId: row.tenant_id,
+        workspaceId: row.workspace_id,
+        kind: row.kind === 'document' ? 'document' : 'asset',
+        path: row.path,
+        sourceWatermark: row.source_watermark,
+        metadataFingerprint: row.metadata_fingerprint,
+        expectedSha256: row.expected_sha256,
+        expectedSizeBytes: Number(row.expected_size_bytes),
+        manifestUpdatedAt: row.manifest_updated_at,
+        attempts: Number(row.attempts),
+        lastError: row.last_error,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        resolvedAt: row.resolved_at,
+    };
+}
+export function workspaceSyncContentPullObligationId(value) {
+    return `${value.kind}:${value.path}`;
+}
+export class WorkspaceSyncContentPullObligationStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    upsertMany(input) {
+        const tenantId = requiredText(input.tenantId, 'tenantId');
+        const workspaceId = requiredText(input.workspaceId, 'workspaceId');
+        const now = requiredText(input.now, 'now');
+        for (const obligation of input.obligations) {
+            const manifest = obligation.manifest;
+            const kind = manifest.kind === 'document' ? 'document' : 'asset';
+            const path = requiredText(manifest.path, 'manifest.path');
+            const sourceWatermark = requiredText(obligation.sourceWatermark, 'sourceWatermark');
+            this.db.prepare(`
+                INSERT INTO workspace_sync_content_pull_obligations (
+                    tenant_id, workspace_id, kind, path, source_watermark,
+                    metadata_fingerprint, expected_sha256, expected_size_bytes,
+                    manifest_updated_at, attempts, last_error, created_at, updated_at, resolved_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 0, NULL, ?, ?, NULL)
+                ON CONFLICT (tenant_id, workspace_id, kind, path) DO UPDATE SET
+                    source_watermark = excluded.source_watermark,
+                    metadata_fingerprint = excluded.metadata_fingerprint,
+                    expected_sha256 = excluded.expected_sha256,
+                    expected_size_bytes = excluded.expected_size_bytes,
+                    manifest_updated_at = excluded.manifest_updated_at,
+                    attempts = CASE
+                        WHEN workspace_sync_content_pull_obligations.source_watermark = excluded.source_watermark
+                             AND workspace_sync_content_pull_obligations.metadata_fingerprint = excluded.metadata_fingerprint
+                             AND workspace_sync_content_pull_obligations.expected_sha256 = excluded.expected_sha256
+                             AND workspace_sync_content_pull_obligations.expected_size_bytes = excluded.expected_size_bytes
+                        THEN workspace_sync_content_pull_obligations.attempts
+                        ELSE 0
+                    END,
+                    last_error = CASE
+                        WHEN workspace_sync_content_pull_obligations.source_watermark = excluded.source_watermark
+                             AND workspace_sync_content_pull_obligations.metadata_fingerprint = excluded.metadata_fingerprint
+                             AND workspace_sync_content_pull_obligations.expected_sha256 = excluded.expected_sha256
+                             AND workspace_sync_content_pull_obligations.expected_size_bytes = excluded.expected_size_bytes
+                             AND workspace_sync_content_pull_obligations.resolved_at IS NULL
+                        THEN workspace_sync_content_pull_obligations.last_error
+                        ELSE NULL
+                    END,
+                    updated_at = CASE
+                        WHEN workspace_sync_content_pull_obligations.source_watermark = excluded.source_watermark
+                             AND workspace_sync_content_pull_obligations.metadata_fingerprint = excluded.metadata_fingerprint
+                             AND workspace_sync_content_pull_obligations.expected_sha256 = excluded.expected_sha256
+                             AND workspace_sync_content_pull_obligations.expected_size_bytes = excluded.expected_size_bytes
+                             AND workspace_sync_content_pull_obligations.resolved_at IS NULL
+                        THEN workspace_sync_content_pull_obligations.updated_at
+                        ELSE excluded.updated_at
+                    END,
+                    resolved_at = NULL
+                WHERE excluded.source_watermark >
+                        workspace_sync_content_pull_obligations.source_watermark
+                   OR (
+                        excluded.source_watermark =
+                            workspace_sync_content_pull_obligations.source_watermark
+                        AND workspace_sync_content_pull_obligations.resolved_at IS NULL
+                   )
+            `).run(tenantId, workspaceId, kind, path, sourceWatermark, String(manifest.metadataFingerprint || ''), String(manifest.sha256 || '').toLowerCase(), Math.max(0, Number(manifest.sizeBytes) || 0), requiredText(manifest.updatedAt, 'manifest.updatedAt'), now, now);
+        }
+    }
+    listOpen(input) {
+        const limit = Math.max(1, Math.min(100, Math.floor(Number(input.limit) || 100)));
+        const rows = this.db.prepare(`
+            SELECT *
+            FROM workspace_sync_content_pull_obligations
+            WHERE tenant_id = ? AND workspace_id = ? AND resolved_at IS NULL
+            ORDER BY attempts ASC, updated_at ASC, kind ASC, path ASC
+            LIMIT ?
+        `).all(input.tenantId, input.workspaceId, limit);
+        return rows.map(mapRow);
+    }
+    resolveMany(input) {
+        const seen = new Set();
+        for (const claim of input.claims) {
+            const kind = claim.kind === 'document' ? 'document' : claim.kind === 'asset' ? 'asset' : '';
+            const path = requiredText(claim.path, 'claim.path');
+            const sourceWatermark = requiredText(claim.sourceWatermark, 'claim.sourceWatermark');
+            if (!kind)
+                throw new TypeError('Invalid content-pull obligation kind.');
+            const dedupeKey = JSON.stringify(claim);
+            if (seen.has(dedupeKey))
+                continue;
+            seen.add(dedupeKey);
+            if (claim.resolution === 'exact-version') {
+                const metadataFingerprint = requiredText(claim.metadataFingerprint, 'claim.metadataFingerprint');
+                this.db.prepare(`
+                    UPDATE workspace_sync_content_pull_obligations
+                    SET resolved_at = ?, updated_at = ?, last_error = NULL
+                    WHERE tenant_id = ? AND workspace_id = ? AND kind = ? AND path = ?
+                      AND source_watermark = ? AND metadata_fingerprint = ?
+                      AND resolved_at IS NULL
+                `).run(input.now, input.now, input.tenantId, input.workspaceId, kind, path, sourceWatermark, metadataFingerprint);
+                continue;
+            }
+            if (claim.resolution !== 'at-or-before-watermark') {
+                throw new TypeError('Invalid content-pull obligation resolution mode.');
+            }
+            this.db.prepare(`
+                UPDATE workspace_sync_content_pull_obligations
+                SET resolved_at = ?, updated_at = ?, last_error = NULL
+                WHERE tenant_id = ? AND workspace_id = ? AND kind = ? AND path = ?
+                  AND source_watermark <= ?
+                  AND resolved_at IS NULL
+            `).run(input.now, input.now, input.tenantId, input.workspaceId, kind, path, sourceWatermark);
+        }
+    }
+    recordAttemptFailure(input) {
+        for (const obligationId of new Set(input.obligationIds)) {
+            const separator = obligationId.indexOf(':');
+            if (separator < 1)
+                continue;
+            const kind = obligationId.slice(0, separator);
+            const path = obligationId.slice(separator + 1);
+            this.db.prepare(`
+                UPDATE workspace_sync_content_pull_obligations
+                SET attempts = attempts + 1, last_error = ?, updated_at = ?
+                WHERE tenant_id = ? AND workspace_id = ? AND kind = ? AND path = ?
+                  AND resolved_at IS NULL
+            `).run(String(input.error || '').slice(0, 500), input.now, input.tenantId, input.workspaceId, kind, path);
+        }
+    }
+    countOpen(input) {
+        const row = this.db.prepare(`
+            SELECT COUNT(*) AS count
+            FROM workspace_sync_content_pull_obligations
+            WHERE tenant_id = ? AND workspace_id = ? AND resolved_at IS NULL
+        `).get(input.tenantId, input.workspaceId);
+        return Number(row?.count || 0);
+    }
+}