@taskforcehq/taskforce 0.3.326 → 0.3.327

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

@@ -0,0 +1,50 @@
+export type 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: {
+        recoveryBatchId: string;
+        state: 'awaiting_baseline' | 'baseline_ready' | 'replay_queued' | 'completed';
+        replayTotal: number;
+        replayPending: number;
+        replayInFlight: number;
+        replayBlocked: number;
+        replayAccepted: number;
+        createdAt: string;
+        updatedAt: string;
+        completedAt: string | null;
+    } | null;
+    attachmentApplyObligations?: {
+        open: number;
+        due: number;
+        oldestOpenCreatedAt: string | null;
+        nextAttemptAt: string | null;
+        totalAttempts: number;
+        lastError: string | null;
+    };
+};
+export type LocalOutboxDrainResult = {
+    processed: number;
+    retryRecommended: boolean;
+    budgetExhausted: boolean;
+    outbox?: WorkspaceSyncV3LocalOutboxStatus;
+};
+export declare function drainLocalOutbox(input: {
+    workspaceId: string;
+    fetchImpl?: typeof fetch;
+    operationBudget?: number;
+    requestTimeoutMs?: number;
+    signal?: AbortSignal;
+    hydrateAsset?: (assetId: string) => Promise<boolean>;
+}): Promise<LocalOutboxDrainResult>;

package/dist/sync/v3/localOutboxDrainClient.js

@@ -0,0 +1,250 @@
+const DISPATCH_PATH = '/api/taskforce/sync/v3/local/dispatch';
+const DEFAULT_OPERATION_BUDGET = 20;
+// The local route owns an upstream transport budget of 90 seconds. Leave
+// enough room for it to persist the retry disposition and return the updated
+// queue instead of aborting the browser at the same deadline.
+const DEFAULT_REQUEST_TIMEOUT_MS = 100_000;
+function parseOutboxStatus(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Local outbox dispatch returned an invalid outbox status.');
+    }
+    const row = value;
+    const integer = (key) => {
+        const parsed = Number(row[key]);
+        return Number.isInteger(parsed) && parsed >= 0 ? parsed : null;
+    };
+    const activeDepth = integer('activeDepth');
+    const pending = integer('pending');
+    const inFlight = integer('inFlight');
+    const blocked = integer('blocked');
+    let operationStates;
+    if (row.operationStates !== undefined) {
+        if (!row.operationStates || typeof row.operationStates !== 'object' || Array.isArray(row.operationStates)) {
+            throw new Error('Local outbox dispatch returned invalid operation states.');
+        }
+        const states = row.operationStates;
+        const stateInteger = (key) => {
+            const parsed = Number(states[key]);
+            return Number.isInteger(parsed) && parsed >= 0 ? parsed : null;
+        };
+        const normalized = {
+            pending: stateInteger('pending'),
+            retryScheduled: stateInteger('retryScheduled'),
+            inFlight: stateInteger('inFlight'),
+            stale: stateInteger('stale'),
+            blocked: stateInteger('blocked'),
+        };
+        if (Object.values(normalized).some((value) => value === null)
+            || pending === null || inFlight === null || blocked === null
+            || normalized.pending + normalized.retryScheduled !== pending
+            || normalized.inFlight + normalized.stale !== inFlight
+            || normalized.blocked !== blocked) {
+            throw new Error('Local outbox dispatch returned inconsistent operation states.');
+        }
+        operationStates = {
+            pending: normalized.pending,
+            retryScheduled: normalized.retryScheduled,
+            inFlight: normalized.inFlight,
+            stale: normalized.stale,
+            blocked: normalized.blocked,
+        };
+    }
+    const nullableString = (key) => (row[key] === null || typeof row[key] === 'string' ? row[key] : undefined);
+    const oldestActiveCreatedAt = nullableString('oldestActiveCreatedAt');
+    const oldestActionableAt = nullableString('oldestActionableAt');
+    const blockedErrorCode = nullableString('blockedErrorCode');
+    const recoveryValue = row.recovery;
+    let recovery = null;
+    if (recoveryValue !== null) {
+        if (!recoveryValue || typeof recoveryValue !== 'object' || Array.isArray(recoveryValue)) {
+            throw new Error('Local outbox dispatch returned an invalid recovery status.');
+        }
+        const item = recoveryValue;
+        const recoveryInteger = (key) => {
+            const parsed = Number(item[key]);
+            return Number.isInteger(parsed) && parsed >= 0 ? parsed : null;
+        };
+        const state = String(item.state || '');
+        const replayTotal = recoveryInteger('replayTotal');
+        const replayPending = recoveryInteger('replayPending');
+        const replayInFlight = recoveryInteger('replayInFlight');
+        const replayBlocked = recoveryInteger('replayBlocked');
+        const replayAccepted = recoveryInteger('replayAccepted');
+        if (typeof item.recoveryBatchId !== 'string'
+            || !['awaiting_baseline', 'baseline_ready', 'replay_queued', 'completed'].includes(state)
+            || replayTotal === null || replayPending === null || replayInFlight === null
+            || replayBlocked === null || replayAccepted === null
+            || replayTotal < replayPending + replayInFlight + replayBlocked + replayAccepted
+            || typeof item.createdAt !== 'string' || typeof item.updatedAt !== 'string'
+            || (item.completedAt !== null && typeof item.completedAt !== 'string')) {
+            throw new Error('Local outbox dispatch returned an invalid recovery status.');
+        }
+        recovery = {
+            recoveryBatchId: item.recoveryBatchId,
+            state: state,
+            replayTotal,
+            replayPending,
+            replayInFlight,
+            replayBlocked,
+            replayAccepted,
+            createdAt: item.createdAt,
+            updatedAt: item.updatedAt,
+            completedAt: item.completedAt,
+        };
+    }
+    let attachmentApplyObligations;
+    if (row.attachmentApplyObligations !== undefined) {
+        if (!row.attachmentApplyObligations
+            || typeof row.attachmentApplyObligations !== 'object'
+            || Array.isArray(row.attachmentApplyObligations)) {
+            throw new Error('Local outbox dispatch returned invalid attachment apply obligations.');
+        }
+        const item = row.attachmentApplyObligations;
+        const open = Number(item.open);
+        const due = Number(item.due);
+        const totalAttempts = Number(item.totalAttempts);
+        if (![open, due, totalAttempts].every((value) => Number.isInteger(value) && value >= 0)
+            || due > open
+            || (item.oldestOpenCreatedAt !== null && typeof item.oldestOpenCreatedAt !== 'string')
+            || (item.nextAttemptAt !== null && typeof item.nextAttemptAt !== 'string')
+            || (item.lastError !== null && typeof item.lastError !== 'string')) {
+            throw new Error('Local outbox dispatch returned invalid attachment apply obligations.');
+        }
+        attachmentApplyObligations = {
+            open,
+            due,
+            totalAttempts,
+            oldestOpenCreatedAt: item.oldestOpenCreatedAt,
+            nextAttemptAt: item.nextAttemptAt,
+            lastError: item.lastError,
+        };
+    }
+    if (activeDepth === null || pending === null || inFlight === null || blocked === null
+        || activeDepth !== pending + inFlight + blocked
+        || oldestActiveCreatedAt === undefined || blockedErrorCode === undefined
+        || !Object.prototype.hasOwnProperty.call(row, 'recovery')) {
+        throw new Error('Local outbox dispatch returned an invalid outbox status.');
+    }
+    return {
+        activeDepth,
+        pending,
+        inFlight,
+        blocked,
+        ...(operationStates ? { operationStates } : {}),
+        oldestActiveCreatedAt,
+        ...(oldestActionableAt !== undefined ? { oldestActionableAt } : {}),
+        blockedErrorCode,
+        recovery,
+        ...(attachmentApplyObligations ? { attachmentApplyObligations } : {}),
+    };
+}
+function parseDispatchResponse(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Local outbox dispatch returned an invalid response.');
+    }
+    const body = value;
+    const claimed = Number(body.claimed);
+    const outcomes = Array.isArray(body.outcomes) ? body.outcomes : [];
+    const validDependency = (entry) => {
+        if (entry.retryDependency === undefined)
+            return true;
+        if (entry.disposition !== 'retry' || !entry.retryDependency
+            || typeof entry.retryDependency !== 'object' || Array.isArray(entry.retryDependency))
+            return false;
+        const dependency = entry.retryDependency;
+        return Object.keys(dependency).sort().join(',') === 'assetId,kind'
+            && dependency.kind === 'asset'
+            && typeof dependency.assetId === 'string'
+            && /^[A-Za-z0-9._:-]+$/.test(dependency.assetId);
+    };
+    if (body.success !== true || !Number.isInteger(claimed) || claimed < 0 || claimed > 1
+        || outcomes.length !== claimed
+        || outcomes.some((entry) => !entry || typeof entry !== 'object'
+            || !['accepted', 'retry', 'blocked', 'lease-lost'].includes(String(entry.disposition || '')))) {
+        throw new Error('Local outbox dispatch returned an invalid response.');
+    }
+    if (outcomes.some((entry) => !validDependency(entry))) {
+        throw new Error('Local outbox dispatch returned an invalid retry dependency.');
+    }
+    return {
+        success: true,
+        claimed,
+        outcomes: outcomes,
+        outbox: parseOutboxStatus(body.outbox),
+    };
+}
+export async function drainLocalOutbox(input) {
+    const workspaceId = String(input.workspaceId || '').trim();
+    if (!workspaceId)
+        throw new Error('Workspace id is required to drain the local outbox.');
+    const fetchImpl = input.fetchImpl || fetch;
+    const operationBudget = Math.max(1, Math.min(100, Math.floor(input.operationBudget ?? DEFAULT_OPERATION_BUDGET)));
+    const requestTimeoutMs = Math.max(1, Math.floor(input.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS));
+    let processed = 0;
+    const hydratedDependencies = new Set();
+    let outbox;
+    while (processed < operationBudget) {
+        const controller = new AbortController();
+        let timeoutId;
+        let rejectCancellation;
+        const cancellation = new Promise((_resolve, reject) => {
+            rejectCancellation = reject;
+            timeoutId = setTimeout(() => {
+                controller.abort();
+                reject(new Error('Local outbox dispatch timed out.'));
+            }, requestTimeoutMs);
+        });
+        const abortFromCaller = () => {
+            controller.abort(input.signal?.reason);
+            rejectCancellation?.(new DOMException('Local outbox dispatch aborted.', 'AbortError'));
+        };
+        if (input.signal?.aborted)
+            abortFromCaller();
+        else
+            input.signal?.addEventListener('abort', abortFromCaller, { once: true });
+        try {
+            const dispatch = (async () => {
+                const response = await fetchImpl(DISPATCH_PATH, {
+                    method: 'POST',
+                    credentials: 'include',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ workspaceId, limit: 1 }),
+                    signal: controller.signal,
+                });
+                if (!response.ok)
+                    throw new Error(`Local outbox dispatch failed (${response.status}).`);
+                return parseDispatchResponse(await response.json());
+            })();
+            const result = await Promise.race([dispatch, cancellation]);
+            outbox = result.outbox;
+            if (result.claimed === 0) {
+                return { processed, retryRecommended: false, budgetExhausted: false, ...(outbox ? { outbox } : {}) };
+            }
+            processed += result.claimed;
+            const outcome = result.outcomes[0];
+            const disposition = outcome?.disposition;
+            if (disposition === 'retry' && outcome.retryDependency?.kind === 'asset') {
+                const dependencyKey = `${outcome.retryDependency.kind}:${outcome.retryDependency.assetId}`;
+                if (hydratedDependencies.has(dependencyKey)) {
+                    return { processed, retryRecommended: true, budgetExhausted: false, ...(outbox ? { outbox } : {}) };
+                }
+                if (!input.hydrateAsset || !await input.hydrateAsset(outcome.retryDependency.assetId)) {
+                    return { processed, retryRecommended: true, budgetExhausted: false, ...(outbox ? { outbox } : {}) };
+                }
+                hydratedDependencies.add(dependencyKey);
+                continue;
+            }
+            if (disposition === 'retry' || disposition === 'lease-lost') {
+                return { processed, retryRecommended: true, budgetExhausted: false, ...(outbox ? { outbox } : {}) };
+            }
+        }
+        finally {
+            if (timeoutId !== undefined)
+                clearTimeout(timeoutId);
+            input.signal?.removeEventListener('abort', abortFromCaller);
+        }
+    }
+    return { processed, retryRecommended: true, budgetExhausted: true, ...(outbox ? { outbox } : {}) };
+}

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

@@ -0,0 +1,31 @@
+import type { WorkspaceSyncOperationIdentity, WorkspaceSyncOutboxRecord } from './syncDurabilityStore.js';
+import type { WorkspaceSyncV3OperationEnvelope } from './workspaceSyncV3OperationProtocol.js';
+export type LocalOutboxAuthoritativeApplyInput = {
+    record?: WorkspaceSyncOutboxRecord;
+    identity: WorkspaceSyncOperationIdentity;
+    leaseOwner: string;
+    response: unknown;
+    now: string;
+};
+export type LocalOutboxDispatchReadiness = {
+    ready: true;
+} | {
+    ready: false;
+    retryable: boolean;
+    errorCode: string;
+    errorMessage: string;
+};
+export type LocalOutboxRetryDependency = {
+    kind: 'asset';
+    assetId: string;
+};
+export interface LocalOutboxOperationHandler {
+    readonly key: string;
+    supports(record: WorkspaceSyncOutboxRecord): boolean;
+    buildEnvelope(record: WorkspaceSyncOutboxRecord): WorkspaceSyncV3OperationEnvelope;
+    resolveDispatchReadiness?(record: WorkspaceSyncOutboxRecord): LocalOutboxDispatchReadiness;
+    applyAuthoritative(input: LocalOutboxAuthoritativeApplyInput): void;
+    isPermanentApplyError(error: unknown): boolean;
+    resolveRetryDependency?(error: unknown): LocalOutboxRetryDependency | null;
+}
+export declare function resolveLocalOutboxOperationHandler(handlers: readonly LocalOutboxOperationHandler[], record: WorkspaceSyncOutboxRecord): LocalOutboxOperationHandler;

package/dist/sync/v3/localOutboxOperationHandler.js

@@ -0,0 +1,10 @@
+export function resolveLocalOutboxOperationHandler(handlers, record) {
+    const matches = handlers.filter((handler) => handler.supports(record));
+    if (matches.length === 0) {
+        throw new Error(`Unsupported local outbox operation: ${record.domain}/${record.mutationKind}.`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`Ambiguous local outbox operation handler: ${record.domain}/${record.mutationKind}.`);
+    }
+    return matches[0];
+}

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

@@ -0,0 +1,14 @@
+export type LocalOutboxRecoveryPreparation = {
+    kind: 'none';
+    needsAuthoritativeRepair: false;
+    recoveryBatchId: null;
+} | {
+    kind: 'recovery';
+    needsAuthoritativeRepair: boolean;
+    recoveryBatchId: string;
+    state: 'awaiting_baseline' | 'baseline_ready' | 'replay_queued' | 'completed';
+};
+export declare function prepareLocalTaskRootOutboxRecovery(input: {
+    workspaceId: string;
+    fetchImpl?: typeof fetch;
+}): Promise<LocalOutboxRecoveryPreparation>;

package/dist/sync/v3/localOutboxRecoveryClient.js

@@ -0,0 +1,45 @@
+const RECOVERY_PATH = '/api/taskforce/sync/v3/local/recovery';
+export async function prepareLocalTaskRootOutboxRecovery(input) {
+    const workspaceId = String(input.workspaceId || '').trim();
+    if (!workspaceId)
+        throw new Error('Workspace id is required to prepare local recovery.');
+    const response = await (input.fetchImpl || fetch)(RECOVERY_PATH, {
+        method: 'POST',
+        credentials: 'include',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ workspaceId }),
+    });
+    const body = await response.json().catch(() => null);
+    if (!response.ok || body?.success !== true) {
+        const error = String(body?.error || `Local workspace sync recovery failed (${response.status}).`);
+        const code = typeof body?.code === 'string' ? body.code.trim() : '';
+        let responseOrigin = 'unknown-origin';
+        try {
+            responseOrigin = new URL(response.url).origin;
+        }
+        catch { /* mocked response */ }
+        throw new Error(`${error} [${code || 'UNKNOWN_RECOVERY_ERROR'}; HTTP ${response.status}; ${responseOrigin}]`);
+    }
+    if (body.kind === 'none' && body.needsAuthoritativeRepair === false && body.recovery === null) {
+        return { kind: 'none', needsAuthoritativeRepair: false, recoveryBatchId: null };
+    }
+    if (body.kind !== 'recovery'
+        || typeof body.needsAuthoritativeRepair !== 'boolean'
+        || !body.recovery || typeof body.recovery !== 'object' || Array.isArray(body.recovery)) {
+        throw new Error('Local workspace sync recovery returned an invalid response.');
+    }
+    const recovery = body.recovery;
+    const recoveryBatchId = String(recovery.recoveryBatchId || '').trim();
+    const state = String(recovery.state || '');
+    if (!/^recovery-[A-Za-z0-9-]{1,200}$/.test(recoveryBatchId)
+        || !['awaiting_baseline', 'baseline_ready', 'replay_queued', 'completed'].includes(state)
+        || (body.needsAuthoritativeRepair === true && state !== 'awaiting_baseline')) {
+        throw new Error('Local workspace sync recovery returned an invalid state.');
+    }
+    return {
+        kind: 'recovery',
+        needsAuthoritativeRepair: body.needsAuthoritativeRepair,
+        recoveryBatchId,
+        state: state,
+    };
+}

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

@@ -0,0 +1,12 @@
+import type { LocalOutboxRecoveryPreparation } from './localOutboxRecoveryClient.js';
+import { WorkspaceSyncDurabilityStore, type WorkspaceSyncOutboxRecovery } from './syncDurabilityStore.js';
+export type PreparedLocalOutboxRecovery = LocalOutboxRecoveryPreparation & {
+    recovery: WorkspaceSyncOutboxRecovery | null;
+};
+export declare function prepareLocalOutboxRecovery(input: {
+    store: WorkspaceSyncDurabilityStore;
+    tenantId: string;
+    workspaceId: string;
+    now: string;
+    createRecoveryBatchId: () => string;
+}): PreparedLocalOutboxRecovery;

package/dist/sync/v3/localOutboxRecoveryPreparationService.js

@@ -0,0 +1,151 @@
+function resumeRecovery(input) {
+    let recovery = input.recovery;
+    if (recovery.state === 'replay_queued') {
+        recovery = input.store.completeOutboxRecoveryIfSettled({
+            tenantId: input.tenantId,
+            workspaceId: input.workspaceId,
+            now: input.now,
+        }) || recovery;
+    }
+    if (recovery.state === 'replay_queued') {
+        input.store.restartOutboxRecoveryAfterRebaseConflict({
+            tenantId: input.tenantId,
+            workspaceId: input.workspaceId,
+            recoveryBatchId: recovery.recoveryBatchId,
+            now: input.now,
+        });
+        recovery = input.store.readOutboxRecovery({
+            tenantId: input.tenantId,
+            workspaceId: input.workspaceId,
+            recoveryBatchId: recovery.recoveryBatchId,
+        });
+    }
+    if (recovery.state === 'baseline_ready') {
+        input.store.prepareTaskRootOutboxRecoveryReplay({
+            tenantId: input.tenantId,
+            workspaceId: input.workspaceId,
+            recoveryBatchId: recovery.recoveryBatchId,
+            now: input.now,
+        });
+    }
+    return input.store.readOutboxRecovery({
+        tenantId: input.tenantId,
+        workspaceId: input.workspaceId,
+        recoveryBatchId: recovery.recoveryBatchId,
+    });
+}
+function appendEligibleBlockedChains(input) {
+    if (input.recovery.state !== 'awaiting_baseline') {
+        return input.recovery;
+    }
+    for (const identity of input.store.listBlockedOutboxIdentities({
+        tenantId: input.tenantId,
+        workspaceId: input.workspaceId,
+    })) {
+        try {
+            input.store.supersedeBlockedOutboxChain({
+                identity,
+                recoveryBatchId: input.recovery.recoveryBatchId,
+                now: input.now,
+                replayPolicy: 'task-root',
+                appendToExistingRecovery: true,
+            });
+        }
+        catch (error) {
+            const message = String(error?.message || '');
+            const expectedIneligibleChain = (/Workspace sync recovery replay currently supports/i.test(message)
+                || /semantic history reconciliation/i.test(message)
+                || /still owns an active lease/i.test(message)
+                || /authoritative entity-event adoption to settle first/i.test(message));
+            if (!expectedIneligibleChain)
+                throw error;
+            // Unsupported or actively leased chains remain blocked and fail closed.
+        }
+    }
+    return input.store.readOutboxRecovery({
+        tenantId: input.tenantId,
+        workspaceId: input.workspaceId,
+        recoveryBatchId: input.recovery.recoveryBatchId,
+    });
+}
+function preparedRecovery(recovery) {
+    return {
+        kind: 'recovery',
+        needsAuthoritativeRepair: recovery.state === 'awaiting_baseline',
+        recoveryBatchId: recovery.recoveryBatchId,
+        state: recovery.state,
+        recovery,
+    };
+}
+export function prepareLocalOutboxRecovery(input) {
+    let recovery = input.store.readOpenOutboxRecovery({
+        tenantId: input.tenantId,
+        workspaceId: input.workspaceId,
+    });
+    if (recovery) {
+        recovery = resumeRecovery({ ...input, recovery });
+        recovery = appendEligibleBlockedChains({ ...input, recovery });
+        return preparedRecovery(recovery);
+    }
+    const blockedRoots = input.store.listBlockedOutboxIdentities({
+        tenantId: input.tenantId,
+        workspaceId: input.workspaceId,
+    });
+    if (blockedRoots.length === 0) {
+        return {
+            kind: 'none',
+            needsAuthoritativeRepair: false,
+            recoveryBatchId: null,
+            recovery: null,
+        };
+    }
+    let recoveryBatchId = '';
+    let firstBlockedError = null;
+    for (const root of blockedRoots) {
+        const candidateBatchId = input.createRecoveryBatchId();
+        try {
+            input.store.supersedeBlockedOutboxChain({
+                identity: root,
+                recoveryBatchId: candidateBatchId,
+                now: input.now,
+                replayPolicy: 'task-root',
+            });
+            recoveryBatchId = candidateBatchId;
+            break;
+        }
+        catch (error) {
+            const concurrent = input.store.readOpenOutboxRecovery({
+                tenantId: input.tenantId,
+                workspaceId: input.workspaceId,
+            });
+            if (concurrent) {
+                recovery = appendEligibleBlockedChains({ ...input, recovery: concurrent });
+                recovery = resumeRecovery({ ...input, recovery });
+                return preparedRecovery(recovery);
+            }
+            firstBlockedError ??= error;
+        }
+    }
+    if (!recoveryBatchId) {
+        const message = String(firstBlockedError?.message || '');
+        if (/authoritative entity-event adoption to settle first/i.test(message)) {
+            return {
+                kind: 'none',
+                needsAuthoritativeRepair: false,
+                recoveryBatchId: null,
+                recovery: null,
+            };
+        }
+        throw firstBlockedError
+            || new Error('No blocked workspace sync operation is eligible for automatic recovery.');
+    }
+    recovery = input.store.readOutboxRecovery({
+        tenantId: input.tenantId,
+        workspaceId: input.workspaceId,
+        recoveryBatchId,
+    });
+    if (!recovery)
+        throw new Error('Workspace sync recovery was not persisted.');
+    recovery = appendEligibleBlockedChains({ ...input, recovery });
+    return preparedRecovery(recovery);
+}

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

@@ -0,0 +1,9 @@
+import type { DatabaseAdapter } from '../../storage/databaseAdapter.js';
+export declare class LocalSyncIdentityStore {
+    private readonly db;
+    private readonly generateId;
+    constructor(db: DatabaseAdapter, generateId?: () => string);
+    getOrCreateClientId(now?: string): string;
+    getClientId(): string | null;
+    createOperationId(): string;
+}

package/dist/sync/v3/localSyncIdentityStore.js

@@ -0,0 +1,43 @@
+import { randomUUID } from 'crypto';
+const INSTALLATION_KEY = 'local-runtime';
+function requireIsoTimestamp(value) {
+    if (!Number.isFinite(Date.parse(value)))
+        throw new Error('Identity timestamp must be an ISO timestamp.');
+    return new Date(value).toISOString();
+}
+export class LocalSyncIdentityStore {
+    db;
+    generateId;
+    constructor(db, generateId = randomUUID) {
+        this.db = db;
+        this.generateId = generateId;
+    }
+    getOrCreateClientId(now = new Date().toISOString()) {
+        const timestamp = requireIsoTimestamp(now);
+        return this.db.transaction(() => {
+            const candidate = `installation-${this.generateId()}`;
+            this.db.prepare(`
+                INSERT INTO workspace_sync_installation (installation_key, client_id, created_at, updated_at)
+                VALUES (?, ?, ?, ?)
+                ON CONFLICT (installation_key) DO NOTHING
+            `).run(INSTALLATION_KEY, candidate, timestamp, timestamp);
+            const row = this.db.prepare(`
+                SELECT client_id FROM workspace_sync_installation WHERE installation_key = ?
+            `).get(INSTALLATION_KEY);
+            const clientId = String(row?.client_id || '').trim();
+            if (!clientId)
+                throw new Error('Local sync installation identity was not persisted.');
+            return clientId;
+        })();
+    }
+    getClientId() {
+        const row = this.db.prepare(`
+            SELECT client_id FROM workspace_sync_installation WHERE installation_key = ?
+        `).get(INSTALLATION_KEY);
+        const clientId = String(row?.client_id || '').trim();
+        return clientId || null;
+    }
+    createOperationId() {
+        return `operation-${this.generateId()}`;
+    }
+}

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

@@ -0,0 +1,10 @@
+import { type LocalTaskAttachmentLinksOutboxCore } from './localTaskAttachmentLinksOutboxService.js';
+import type { LocalOutboxOperationHandler } from './localOutboxOperationHandler.js';
+import { WorkspaceSyncDurabilityStore, type WorkspaceSyncOutboxRecord } from './syncDurabilityStore.js';
+import type { WorkspaceSyncV3TaskAttachmentLinksEnvelope } from './workspaceSyncV3OperationProtocol.js';
+export declare function buildTaskAttachmentLinksEnvelope(record: WorkspaceSyncOutboxRecord): WorkspaceSyncV3TaskAttachmentLinksEnvelope;
+export declare function createLocalTaskAttachmentLinksOutboxHandler(input: {
+    store: WorkspaceSyncDurabilityStore;
+    core: LocalTaskAttachmentLinksOutboxCore;
+    onPostCommitError?: (error: unknown) => void;
+}): LocalOutboxOperationHandler;