devchain-cli 0.22.0 → 0.23.0

package/dist/server/modules/storage/local/delegates/external-estimate-log.delegate.js

@@ -0,0 +1,659 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExternalEstimateLogStorageDelegate = void 0;
+const drizzle_orm_1 = require("drizzle-orm");
+const error_types_1 = require("../../../../common/errors/error-types");
+const schema_1 = require("../../db/schema");
+const base_storage_delegate_1 = require("./base-storage.delegate");
+const MAX_TIME_ENTRY_DURATION_MS = 7 * 24 * 60 * 60 * 1_000;
+const MAX_BATCH_IDENTITIES = 1_000;
+const MAX_DAILY_LEDGER_ROWS = 3_660;
+const OPERATION_ID_PATTERN = /^[A-Za-z0-9:_.-]{1,128}$/;
+const ACTIVITY_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+const MAX_ZONE_LENGTH = 128;
+const LIST_LOGGED_MINUTES_SQL = `
+  WITH input(remote_scope_key, remote_task_id) AS MATERIALIZED (
+    SELECT
+      json_extract(value, '$.remoteScopeKey'),
+      json_extract(value, '$.remoteTaskId')
+    FROM json_each(?)
+  )
+  SELECT
+    states.remote_scope_key AS "remoteScopeKey",
+    states.remote_task_id AS "remoteTaskId",
+    states.logged_minutes AS "loggedMinutes"
+  FROM input
+  CROSS JOIN external_estimate_log_states AS states
+    ON states.provider = ?
+   AND states.remote_scope_key = input.remote_scope_key
+   AND states.remote_task_id = input.remote_task_id
+  ORDER BY states.remote_scope_key, states.remote_task_id`;
+const UPSERT_DAY_SQL = `
+  INSERT INTO external_estimate_log_days
+    (provider, remote_scope_key, remote_task_id, activity_date,
+     logged_minutes, created_at, updated_at)
+  VALUES (?, ?, ?, ?, ?, ?, ?)
+  ON CONFLICT(provider, remote_scope_key, remote_task_id, activity_date) DO UPDATE SET
+    logged_minutes = logged_minutes + excluded.logged_minutes,
+    updated_at = excluded.updated_at`;
+const LIST_BY_REMOTE_TASK_SQL = `
+  SELECT
+    states.provider AS "provider",
+    states.remote_scope_key AS "remoteScopeKey",
+    states.remote_task_id AS "remoteTaskId",
+    states.logged_minutes AS "loggedMinutes",
+    states.revision AS "revision",
+    states.pending_operation_id AS "pendingOperationId",
+    states.pending_delta_minutes AS "pendingDeltaMinutes",
+    states.pending_estimate_total_minutes AS "pendingEstimateTotalMinutes",
+    states.pending_started_at AS "pendingStartedAt",
+    states.pending_connection_id AS "pendingConnectionId",
+    states.pending_connection_generation AS "pendingConnectionGeneration",
+    states.pending_phase AS "pendingPhase",
+    states.pending_resolution AS "pendingResolution",
+    states.aggregation_time_zone AS "aggregationTimeZone",
+    states.pending_activity_date AS "pendingActivityDate",
+    states.created_at AS "createdAt",
+    states.updated_at AS "updatedAt",
+    COALESCE((
+      SELECT SUM(days.logged_minutes)
+      FROM external_estimate_log_days AS days
+      WHERE days.provider = states.provider
+        AND days.remote_scope_key = states.remote_scope_key
+        AND days.remote_task_id = states.remote_task_id
+    ), 0) AS "daySum"
+  FROM external_estimate_log_states AS states
+  WHERE states.provider = ? AND states.remote_task_id = ?
+  ORDER BY states.remote_scope_key`;
+class ExternalEstimateLogStorageDelegate extends base_storage_delegate_1.BaseStorageDelegate {
+    constructor(context) {
+        super(context);
+    }
+    async get(identity) {
+        const normalized = this.normalizeIdentity(identity);
+        const row = this.getRow(normalized);
+        if (!row) {
+            return null;
+        }
+        this.assertDaysWithinScalar(normalized, row.loggedMinutes);
+        return this.mapState(row);
+    }
+    async getDailyCheckpoint(identity) {
+        const normalized = this.normalizeIdentity(identity);
+        const row = this.getRow(normalized);
+        if (!row) {
+            return null;
+        }
+        const days = this.listDayRows(normalized);
+        if (days.length > MAX_DAILY_LEDGER_ROWS) {
+            throw new error_types_1.StorageError(`External estimate log dated ledger exceeds ${MAX_DAILY_LEDGER_ROWS} rows.`);
+        }
+        const daySum = days.reduce((total, day) => total + day.loggedMinutes, 0);
+        if (daySum > row.loggedMinutes) {
+            throw this.ledgerExceedsScalar();
+        }
+        return {
+            state: this.mapState(row),
+            days,
+            unallocatedLoggedMinutes: row.loggedMinutes - daySum,
+        };
+    }
+    async listByRemoteTask(provider, remoteTaskId) {
+        const normalizedProvider = this.requireProvider(provider);
+        const normalizedTaskId = this.requireIdentifier(remoteTaskId, 'Remote task');
+        const rows = this.rawClient
+            .prepare(LIST_BY_REMOTE_TASK_SQL)
+            .all(normalizedProvider, normalizedTaskId);
+        return rows.map((row) => {
+            if (row.daySum > row.loggedMinutes) {
+                throw this.ledgerExceedsScalar();
+            }
+            return this.mapState(row);
+        });
+    }
+    listLoggedMinutes(provider, identities) {
+        if (identities.length === 0) {
+            return [];
+        }
+        const normalizedProvider = this.requireProvider(provider);
+        const unique = new Map();
+        for (const identity of identities) {
+            const remoteScopeKey = this.requireIdentifier(identity.remoteScopeKey, 'Remote scope');
+            const remoteTaskId = this.requireIdentifier(identity.remoteTaskId, 'Remote task');
+            unique.set(`${remoteScopeKey}\u0000${remoteTaskId}`, { remoteScopeKey, remoteTaskId });
+        }
+        if (unique.size > MAX_BATCH_IDENTITIES) {
+            throw new error_types_1.ValidationError(`At most ${MAX_BATCH_IDENTITIES} estimate checkpoint identities may be read at once.`);
+        }
+        const seed = JSON.stringify([...unique.values()]);
+        return this.rawClient
+            .prepare(LIST_LOGGED_MINUTES_SQL)
+            .all(seed, normalizedProvider);
+    }
+    async setLoggedMinutes(data) {
+        const normalized = this.normalizeIdentity(data);
+        this.requireNonnegativeInteger(data.loggedMinutes, 'Logged minutes');
+        this.requireExpectedRevision(data.expectedRevision);
+        const aggregationTimeZone = data.aggregationTimeZone === null
+            ? null
+            : this.requireAggregationZone(data.aggregationTimeZone);
+        const currentTotals = this.requireDailyTotals(data.currentDailyTotals, 'Current daily totals');
+        return this.txRunner.runImmediateQueuedOrJoin(() => {
+            this.assertCurrentLink(normalized);
+            const existing = this.getRow(normalized);
+            this.assertExpectedRevision(existing, data.expectedRevision, normalized);
+            if (existing?.pendingOperationId) {
+                throw new error_types_1.ConflictError('Estimate log state has a pending operation.', {
+                    operationId: existing.pendingOperationId,
+                });
+            }
+            this.assertDaysWithinScalar(normalized, existing?.loggedMinutes ?? 0);
+            const now = new Date().toISOString();
+            const boundZone = aggregationTimeZone ?? existing?.aggregationTimeZone ?? null;
+            if (!existing) {
+                this.db
+                    .insert(schema_1.externalEstimateLogStates)
+                    .values({
+                    ...normalized,
+                    loggedMinutes: data.loggedMinutes,
+                    revision: 1,
+                    aggregationTimeZone: boundZone,
+                    createdAt: now,
+                    updatedAt: now,
+                })
+                    .run();
+            }
+            else {
+                this.updateByRevision(normalized, existing.revision, {
+                    loggedMinutes: data.loggedMinutes,
+                    aggregationTimeZone: boundZone,
+                    revision: existing.revision + 1,
+                    updatedAt: now,
+                });
+            }
+            this.clearDays(normalized);
+            const currentTotal = currentTotals.reduce((total, day) => total + day.minutes, 0);
+            const placements = this.computeCreditPlacements(Math.min(data.loggedMinutes, currentTotal), currentTotals, []);
+            this.applyDayPlacements(normalized, placements, now);
+            return this.requireState(normalized);
+        });
+    }
+    async prepare(data) {
+        const normalized = this.normalizeIdentity(data);
+        const operationId = this.requireOperationId(data.operationId);
+        this.requireExpectedRevision(data.expectedRevision);
+        const activityDate = data.activityDate === null ? null : this.requireActivityDate(data.activityDate);
+        const aggregationTimeZone = data.aggregationTimeZone === null
+            ? null
+            : this.requireAggregationZone(data.aggregationTimeZone);
+        const capturedTotals = this.requireDailyTotals(data.capturedDailyTotals, 'Captured daily totals');
+        return this.txRunner.runImmediateQueuedOrJoin(() => {
+            this.requirePositiveDelta(data.deltaMinutes);
+            this.requireNonnegativeInteger(data.estimateTotalMinutes, 'Estimate total minutes');
+            const startedAt = this.requireTimestamp(data.startedAt);
+            const connectionId = this.requireIdentifier(data.connectionId, 'Connection');
+            this.requirePositiveInteger(data.connectionGeneration, 'Connection generation');
+            this.assertCurrentLink(normalized);
+            this.assertConnectionEpoch(normalized.provider, connectionId, data.connectionGeneration);
+            const existing = this.getRow(normalized);
+            this.assertExpectedRevision(existing, data.expectedRevision, normalized);
+            if (existing?.pendingOperationId) {
+                throw new error_types_1.ConflictError('Estimate log state has a pending operation.', {
+                    operationId: existing.pendingOperationId,
+                });
+            }
+            const now = new Date().toISOString();
+            const existingDays = this.listDayRows(normalized);
+            const daySum = existingDays.reduce((total, day) => total + day.loggedMinutes, 0);
+            const creditMinutes = Math.max(0, (existing?.loggedMinutes ?? 0) - daySum);
+            const placements = this.computeCreditPlacements(creditMinutes, capturedTotals, existingDays);
+            this.applyDayPlacements(normalized, placements, now);
+            const boundZone = aggregationTimeZone ?? existing?.aggregationTimeZone ?? null;
+            const pending = {
+                pendingOperationId: operationId,
+                pendingDeltaMinutes: data.deltaMinutes,
+                pendingEstimateTotalMinutes: data.estimateTotalMinutes,
+                pendingStartedAt: startedAt,
+                pendingConnectionId: connectionId,
+                pendingConnectionGeneration: data.connectionGeneration,
+                pendingPhase: 'prepared',
+                pendingResolution: null,
+                pendingActivityDate: activityDate,
+            };
+            if (!existing) {
+                this.db
+                    .insert(schema_1.externalEstimateLogStates)
+                    .values({
+                    ...normalized,
+                    loggedMinutes: 0,
+                    revision: 1,
+                    aggregationTimeZone: boundZone,
+                    ...pending,
+                    createdAt: now,
+                    updatedAt: now,
+                })
+                    .run();
+            }
+            else {
+                this.updateByRevision(normalized, existing.revision, {
+                    ...pending,
+                    aggregationTimeZone: boundZone,
+                    revision: existing.revision + 1,
+                    updatedAt: now,
+                });
+            }
+            return this.requireState(normalized);
+        });
+    }
+    async markOutcomeUnknown(data) {
+        const normalized = this.normalizeIdentity(data);
+        const operationId = this.requireOperationId(data.operationId);
+        this.requireExpectedRevision(data.expectedRevision);
+        return this.txRunner.runImmediateQueuedOrJoin(() => {
+            this.assertCurrentLink(normalized);
+            const state = this.requirePending(normalized, operationId);
+            this.assertExpectedRevision(state, data.expectedRevision, normalized);
+            if (state.pendingPhase === 'outcome_unknown') {
+                return this.mapState(state);
+            }
+            this.updateByRevision(normalized, state.revision, {
+                pendingPhase: 'outcome_unknown',
+                revision: state.revision + 1,
+                updatedAt: new Date().toISOString(),
+            });
+            return this.requireState(normalized);
+        });
+    }
+    async confirm(data) {
+        return this.settle(data, 'logged');
+    }
+    async clear(data) {
+        return this.settle(data, 'not_logged');
+    }
+    async storeResolution(data) {
+        const normalized = this.normalizeIdentity(data);
+        const operationId = this.requireOperationId(data.operationId);
+        this.requireExpectedRevision(data.expectedRevision);
+        if (data.resolution !== 'logged' && data.resolution !== 'not_logged') {
+            throw new error_types_1.ValidationError('Estimate operation resolution is invalid.');
+        }
+        return this.txRunner.runImmediateQueuedOrJoin(() => {
+            this.assertCurrentLink(normalized);
+            const state = this.requirePending(normalized, operationId);
+            this.assertExpectedRevision(state, data.expectedRevision, normalized);
+            if (state.pendingResolution === data.resolution) {
+                return this.mapState(state);
+            }
+            if (state.pendingResolution !== null) {
+                throw new error_types_1.ConflictError('Estimate operation already has a different resolution.', {
+                    operationId,
+                });
+            }
+            this.updateByRevision(normalized, state.revision, {
+                pendingResolution: data.resolution,
+                revision: state.revision + 1,
+                updatedAt: new Date().toISOString(),
+            });
+            return this.requireState(normalized);
+        });
+    }
+    async applyResolution(data) {
+        const normalized = this.normalizeIdentity(data);
+        const operationId = this.requireOperationId(data.operationId);
+        this.requireExpectedRevision(data.expectedRevision);
+        return this.txRunner.runImmediateQueuedOrJoin(() => {
+            this.assertCurrentLink(normalized);
+            const state = this.requireState(normalized);
+            if (state.pendingOperationId === null) {
+                return state;
+            }
+            if (state.pendingOperationId !== operationId) {
+                throw new error_types_1.ConflictError('A different estimate operation is pending.', {
+                    operationId: state.pendingOperationId,
+                });
+            }
+            this.assertExpectedRevision(state, data.expectedRevision, normalized);
+            if (state.pendingResolution === null) {
+                throw new error_types_1.ConflictError('Estimate operation has no stored resolution.', { operationId });
+            }
+            return this.applySettlement(normalized, state, state.pendingResolution === 'logged');
+        });
+    }
+    settle(data, resolution) {
+        const normalized = this.normalizeIdentity(data);
+        const operationId = this.requireOperationId(data.operationId);
+        this.requireExpectedRevision(data.expectedRevision);
+        return this.txRunner.runImmediateQueuedOrJoin(() => {
+            this.assertCurrentLink(normalized);
+            const state = this.requireState(normalized);
+            if (state.pendingOperationId === null) {
+                return state;
+            }
+            if (state.pendingOperationId !== operationId) {
+                throw new error_types_1.ConflictError('A different estimate operation is pending.', {
+                    operationId: state.pendingOperationId,
+                });
+            }
+            this.assertExpectedRevision(state, data.expectedRevision, normalized);
+            return this.applySettlement(normalized, state, resolution === 'logged');
+        });
+    }
+    applySettlement(identity, state, addDelta) {
+        const nextLoggedMinutes = addDelta
+            ? state.loggedMinutes + state.pendingDeltaMinutes
+            : state.loggedMinutes;
+        if (!Number.isSafeInteger(nextLoggedMinutes)) {
+            throw new error_types_1.ValidationError('Logged minutes exceed the supported numeric range.');
+        }
+        const now = new Date().toISOString();
+        this.updateByRevision(identity, state.revision, {
+            loggedMinutes: nextLoggedMinutes,
+            revision: state.revision + 1,
+            pendingOperationId: null,
+            pendingDeltaMinutes: null,
+            pendingEstimateTotalMinutes: null,
+            pendingStartedAt: null,
+            pendingConnectionId: null,
+            pendingConnectionGeneration: null,
+            pendingPhase: null,
+            pendingResolution: null,
+            pendingActivityDate: null,
+            updatedAt: now,
+        });
+        if (addDelta && state.pendingActivityDate !== null) {
+            this.upsertDayIncrement(identity, state.pendingActivityDate, state.pendingDeltaMinutes, now);
+        }
+        return this.requireState(identity);
+    }
+    listDayRows(identity) {
+        return this.db
+            .select({
+            provider: schema_1.externalEstimateLogDays.provider,
+            remoteScopeKey: schema_1.externalEstimateLogDays.remoteScopeKey,
+            remoteTaskId: schema_1.externalEstimateLogDays.remoteTaskId,
+            activityDate: schema_1.externalEstimateLogDays.activityDate,
+            loggedMinutes: schema_1.externalEstimateLogDays.loggedMinutes,
+        })
+            .from(schema_1.externalEstimateLogDays)
+            .where(this.dayPredicate(identity))
+            .orderBy((0, drizzle_orm_1.asc)(schema_1.externalEstimateLogDays.activityDate))
+            .all();
+    }
+    sumDayMinutes(identity) {
+        const row = this.rawClient
+            .prepare(`SELECT COALESCE(SUM(logged_minutes), 0) AS total
+         FROM external_estimate_log_days
+         WHERE provider = ? AND remote_scope_key = ? AND remote_task_id = ?`)
+            .get(identity.provider, identity.remoteScopeKey, identity.remoteTaskId);
+        return row.total;
+    }
+    assertDaysWithinScalar(identity, loggedMinutes) {
+        if (this.sumDayMinutes(identity) > loggedMinutes) {
+            throw this.ledgerExceedsScalar();
+        }
+    }
+    ledgerExceedsScalar() {
+        return new error_types_1.StorageError('External estimate log dated ledger exceeds the scalar checkpoint.');
+    }
+    clearDays(identity) {
+        this.db.delete(schema_1.externalEstimateLogDays).where(this.dayPredicate(identity)).run();
+    }
+    upsertDayIncrement(identity, activityDate, minutes, now) {
+        this.rawClient
+            .prepare(UPSERT_DAY_SQL)
+            .run(identity.provider, identity.remoteScopeKey, identity.remoteTaskId, activityDate, minutes, now, now);
+    }
+    applyDayPlacements(identity, placements, now) {
+        for (const placement of placements) {
+            this.upsertDayIncrement(identity, placement.activityDate, placement.minutes, now);
+        }
+    }
+    computeCreditPlacements(creditMinutes, dailyTotals, existingDays) {
+        const coveredByDate = new Map(existingDays.map((day) => [day.activityDate, day.loggedMinutes]));
+        let remainingMinutes = creditMinutes;
+        const placements = [];
+        for (const total of dailyTotals) {
+            if (remainingMinutes <= 0) {
+                break;
+            }
+            const covered = coveredByDate.get(total.activityDate) ?? 0;
+            const uncovered = Math.max(0, total.minutes - covered);
+            const placed = Math.min(remainingMinutes, uncovered);
+            if (placed > 0) {
+                placements.push({ activityDate: total.activityDate, minutes: placed });
+                remainingMinutes -= placed;
+            }
+        }
+        return placements;
+    }
+    dayPredicate(identity) {
+        return (0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema_1.externalEstimateLogDays.provider, identity.provider), (0, drizzle_orm_1.eq)(schema_1.externalEstimateLogDays.remoteScopeKey, identity.remoteScopeKey), (0, drizzle_orm_1.eq)(schema_1.externalEstimateLogDays.remoteTaskId, identity.remoteTaskId));
+    }
+    requireDailyTotals(entries, label) {
+        const totalsByDate = new Map();
+        for (const entry of entries ?? []) {
+            const activityDate = this.requireActivityDate(entry?.activityDate, label);
+            if (!Number.isSafeInteger(entry?.minutes) || entry.minutes < 0) {
+                throw new error_types_1.ValidationError(`${label} minutes must be nonnegative whole numbers.`);
+            }
+            totalsByDate.set(activityDate, (totalsByDate.get(activityDate) ?? 0) + entry.minutes);
+        }
+        if (totalsByDate.size > MAX_DAILY_LEDGER_ROWS) {
+            throw new error_types_1.ValidationError(`${label} may carry at most ${MAX_DAILY_LEDGER_ROWS} unique activity dates.`);
+        }
+        return [...totalsByDate.entries()]
+            .map(([activityDate, minutes]) => ({ activityDate, minutes }))
+            .sort((left, right) => left.activityDate.localeCompare(right.activityDate));
+    }
+    requireActivityDate(value, label = 'Daily totals') {
+        const normalized = value?.trim();
+        if (!normalized || !ACTIVITY_DATE_PATTERN.test(normalized)) {
+            throw new error_types_1.ValidationError(`${label} activity date is invalid.`);
+        }
+        const [year, month, day] = normalized.split('-').map(Number);
+        const calendar = new Date(Date.UTC(year, month - 1, day));
+        if (calendar.getUTCFullYear() !== year ||
+            calendar.getUTCMonth() !== month - 1 ||
+            calendar.getUTCDate() !== day) {
+            throw new error_types_1.ValidationError(`${label} activity date is invalid.`);
+        }
+        return normalized;
+    }
+    requireAggregationZone(value) {
+        const normalized = value?.trim();
+        if (!normalized || normalized.length > MAX_ZONE_LENGTH) {
+            throw new error_types_1.ValidationError('Aggregation time zone is invalid.');
+        }
+        return normalized;
+    }
+    getRow(identity) {
+        return this.db
+            .select()
+            .from(schema_1.externalEstimateLogStates)
+            .where(this.identityPredicate(identity))
+            .limit(1)
+            .get();
+    }
+    requireState(identity) {
+        const row = this.getRow(identity);
+        if (!row) {
+            throw new error_types_1.NotFoundError('External estimate log state');
+        }
+        this.assertDaysWithinScalar(identity, row.loggedMinutes);
+        return this.mapState(row);
+    }
+    requirePending(identity, operationId) {
+        const state = this.getRow(identity);
+        if (!state) {
+            throw new error_types_1.NotFoundError('External estimate log state');
+        }
+        if (state.pendingOperationId === null) {
+            throw new error_types_1.ConflictError('Estimate log state has no pending operation.');
+        }
+        if (state.pendingOperationId !== operationId) {
+            throw new error_types_1.ConflictError('A different estimate operation is pending.', {
+                operationId: state.pendingOperationId,
+            });
+        }
+        return state;
+    }
+    updateByRevision(identity, revision, values) {
+        const result = this.db
+            .update(schema_1.externalEstimateLogStates)
+            .set(values)
+            .where((0, drizzle_orm_1.and)(this.identityPredicate(identity), (0, drizzle_orm_1.eq)(schema_1.externalEstimateLogStates.revision, revision)))
+            .run();
+        if (result.changes !== 1) {
+            throw this.optimisticLock(identity, revision);
+        }
+    }
+    assertCurrentLink(identity) {
+        const row = this.db
+            .select({ remoteTaskId: schema_1.externalTaskLinks.remoteTaskId })
+            .from(schema_1.externalTaskLinks)
+            .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema_1.externalTaskLinks.provider, identity.provider), (0, drizzle_orm_1.eq)(schema_1.externalTaskLinks.remoteScopeKey, identity.remoteScopeKey), (0, drizzle_orm_1.eq)(schema_1.externalTaskLinks.remoteTaskId, identity.remoteTaskId)))
+            .limit(1)
+            .get();
+        if (!row) {
+            throw new error_types_1.NotFoundError('Current external task link');
+        }
+    }
+    assertConnectionEpoch(provider, connectionId, generation) {
+        const connection = this.db
+            .select({ id: schema_1.integrationConnections.id })
+            .from(schema_1.integrationConnections)
+            .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema_1.integrationConnections.id, connectionId), (0, drizzle_orm_1.eq)(schema_1.integrationConnections.provider, provider), (0, drizzle_orm_1.eq)(schema_1.integrationConnections.generation, generation)))
+            .limit(1)
+            .get();
+        if (!connection) {
+            throw new error_types_1.ConflictError('Integration connection epoch is stale.');
+        }
+    }
+    identityPredicate(identity) {
+        return (0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(schema_1.externalEstimateLogStates.provider, identity.provider), (0, drizzle_orm_1.eq)(schema_1.externalEstimateLogStates.remoteScopeKey, identity.remoteScopeKey), (0, drizzle_orm_1.eq)(schema_1.externalEstimateLogStates.remoteTaskId, identity.remoteTaskId));
+    }
+    assertExpectedRevision(state, expectedRevision, identity) {
+        const actualRevision = state?.revision ?? 0;
+        if (actualRevision !== expectedRevision) {
+            throw this.optimisticLock(identity, expectedRevision, actualRevision);
+        }
+    }
+    optimisticLock(identity, expectedRevision, actualRevision) {
+        return new error_types_1.OptimisticLockError('External estimate log state', `${identity.provider}:${identity.remoteScopeKey}:${identity.remoteTaskId}`, { expectedRevision, ...(actualRevision === undefined ? {} : { actualRevision }) });
+    }
+    normalizeIdentity(identity) {
+        const remoteScopeKey = this.requireIdentifier(identity.remoteScopeKey, 'Remote scope');
+        const remoteTaskId = this.requireIdentifier(identity.remoteTaskId, 'Remote task');
+        const provider = this.requireProvider(identity.provider);
+        return { provider, remoteScopeKey, remoteTaskId };
+    }
+    requireProvider(provider) {
+        if (provider !== 'clickup' && provider !== 'jira') {
+            throw new error_types_1.ValidationError('Integration provider is invalid.');
+        }
+        return provider;
+    }
+    requireIdentifier(value, label) {
+        const normalized = value?.trim();
+        if (!normalized) {
+            throw new error_types_1.ValidationError(`${label} identifier is required.`);
+        }
+        return normalized;
+    }
+    requireOperationId(value) {
+        const normalized = value?.trim();
+        if (!normalized || !OPERATION_ID_PATTERN.test(normalized)) {
+            throw new error_types_1.ValidationError('Estimate operation ID is invalid.');
+        }
+        return normalized;
+    }
+    requireExpectedRevision(value) {
+        this.requireNonnegativeInteger(value, 'Expected revision');
+    }
+    requireNonnegativeInteger(value, label) {
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new error_types_1.ValidationError(`${label} must be a nonnegative whole number.`);
+        }
+    }
+    requirePositiveInteger(value, label) {
+        if (!Number.isSafeInteger(value) || value < 1) {
+            throw new error_types_1.ValidationError(`${label} must be a positive whole number.`);
+        }
+    }
+    requirePositiveDelta(deltaMinutes) {
+        if (!Number.isSafeInteger(deltaMinutes) || deltaMinutes === 0) {
+            throw new error_types_1.ValidationError('Estimate delta must be a nonzero whole number.');
+        }
+        if (deltaMinutes < 0) {
+            throw new error_types_1.ValidationError('Estimate delta must be positive.');
+        }
+        if (deltaMinutes * 60_000 > MAX_TIME_ENTRY_DURATION_MS) {
+            throw new error_types_1.ValidationError('Estimate delta exceeds the maximum time-entry duration.');
+        }
+    }
+    requireTimestamp(value) {
+        const normalized = value?.trim();
+        if (!normalized || !Number.isFinite(Date.parse(normalized))) {
+            throw new error_types_1.ValidationError('Estimate operation start time is invalid.');
+        }
+        return normalized;
+    }
+    mapState(row) {
+        const common = {
+            provider: row.provider,
+            remoteScopeKey: row.remoteScopeKey,
+            remoteTaskId: row.remoteTaskId,
+            loggedMinutes: row.loggedMinutes,
+            revision: row.revision,
+            aggregationTimeZone: row.aggregationTimeZone,
+            createdAt: row.createdAt,
+            updatedAt: row.updatedAt,
+        };
+        if (row.pendingOperationId === null) {
+            if (row.pendingDeltaMinutes !== null ||
+                row.pendingEstimateTotalMinutes !== null ||
+                row.pendingStartedAt !== null ||
+                row.pendingConnectionId !== null ||
+                row.pendingConnectionGeneration !== null ||
+                row.pendingPhase !== null ||
+                row.pendingResolution !== null ||
+                row.pendingActivityDate !== null) {
+                throw new error_types_1.StorageError('External estimate log state has incomplete pending fields.');
+            }
+            return {
+                ...common,
+                pendingOperationId: null,
+                pendingDeltaMinutes: null,
+                pendingEstimateTotalMinutes: null,
+                pendingStartedAt: null,
+                pendingConnectionId: null,
+                pendingConnectionGeneration: null,
+                pendingPhase: null,
+                pendingResolution: null,
+                pendingActivityDate: null,
+            };
+        }
+        if (row.pendingDeltaMinutes === null ||
+            row.pendingEstimateTotalMinutes === null ||
+            row.pendingStartedAt === null ||
+            row.pendingConnectionId === null ||
+            row.pendingConnectionGeneration === null ||
+            row.pendingPhase === null) {
+            throw new error_types_1.StorageError('External estimate log state has incomplete pending fields.');
+        }
+        return {
+            ...common,
+            pendingOperationId: row.pendingOperationId,
+            pendingDeltaMinutes: row.pendingDeltaMinutes,
+            pendingEstimateTotalMinutes: row.pendingEstimateTotalMinutes,
+            pendingStartedAt: row.pendingStartedAt,
+            pendingConnectionId: row.pendingConnectionId,
+            pendingConnectionGeneration: row.pendingConnectionGeneration,
+            pendingPhase: row.pendingPhase,
+            pendingResolution: row.pendingResolution,
+            pendingActivityDate: row.pendingActivityDate,
+        };
+    }
+}
+exports.ExternalEstimateLogStorageDelegate = ExternalEstimateLogStorageDelegate;
+//# sourceMappingURL=external-estimate-log.delegate.js.map