devchain-cli 0.22.0 → 0.23.0

package/dist/server/modules/epic-time/services/epic-estimate-logging.service.js

@@ -0,0 +1,716 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EpicEstimateLoggingService = void 0;
+const node_crypto_1 = require("node:crypto");
+const common_1 = require("@nestjs/common");
+const error_types_1 = require("../../../common/errors/error-types");
+const external_time_mutation_service_1 = require("../../external-integrations/my-work/external-time-mutation.service");
+const external_provider_models_1 = require("../../external-integrations/models/external-provider.models");
+const external_time_mutation_store_1 = require("../../external-integrations/sessions/external-time-mutation.store");
+const storage_interface_1 = require("../../storage/interfaces/storage.interface");
+const epic_time_models_1 = require("../models/epic-time.models");
+const epic_time_daily_allocator_1 = require("../models/epic-time-daily-allocator");
+const epic_time_local_day_1 = require("../models/epic-time-local-day");
+const epic_time_service_1 = require("./epic-time.service");
+const MILLIS_PER_MINUTE = 60_000;
+const MAX_ENTRIES_PER_REQUEST = 10;
+const MAX_DAILY_LEDGER_ENTRIES = 3_660;
+const REQUEST_KEY_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function dailyOperationId(keyHash, index) {
+    return `daily:${keyHash}:${index}`;
+}
+function settlementOutcomeForPhase(phase) {
+    switch (phase) {
+        case 'succeeded':
+            return 'logged';
+        case 'failed':
+        case 'not_applied':
+            return 'not_logged';
+        default:
+            return null;
+    }
+}
+function isOperationInProgress(phase) {
+    return phase === 'pending' || phase === 'dispatched';
+}
+let EpicEstimateLoggingService = class EpicEstimateLoggingService {
+    storage;
+    epicTime;
+    timeMutations;
+    constructor(storage, epicTime, timeMutations) {
+        this.storage = storage;
+        this.epicTime = epicTime;
+        this.timeMutations = timeMutations;
+    }
+    async getState(input) {
+        const context = await this.resolveContext(input);
+        const stored = await this.storage.getExternalEstimateLogState(context.identity);
+        const state = stored ? (await this.reconcilePending(context, stored)).state : null;
+        return this.snapshot(context, state);
+    }
+    async setLoggedMinutes(input) {
+        const context = await this.resolveContext(input);
+        const projection = this.epicTime.getDailyProjection(context.epic.id, input.timeZone);
+        const state = await this.storage.setExternalEstimateLoggedMinutes({
+            ...context.identity,
+            loggedMinutes: input.loggedMinutes,
+            expectedRevision: input.expectedRevision,
+            aggregationTimeZone: projection.canonicalTimeZone,
+            currentDailyTotals: projection.currentByDate,
+        });
+        return this.snapshot(context, state);
+    }
+    async createTimeEntry(input) {
+        const context = await this.resolveContext(input);
+        const requestKey = this.requireRequestKey(input.requestKey);
+        const dailySnapshot = this.requireDailySnapshot(input.dailySnapshot, input.estimateTotalMinutes);
+        this.requireNonnegativeInteger(input.estimateTotalMinutes, 'Estimate total minutes');
+        this.requireNonnegativeInteger(input.expectedRevision, 'Expected revision');
+        const projection = this.epicTime.getDailyProjection(context.epic.id, input.timeZone);
+        const checkpoint = await this.storage.getExternalEstimateLogDailyCheckpoint(context.identity);
+        const state = checkpoint?.state ?? null;
+        if (state?.pendingOperationId) {
+            throw new error_types_1.BusyError('An estimate operation is pending for this task.', {
+                reason: 'estimate_operation_pending',
+            });
+        }
+        if (input.expectedRevision !== (state?.revision ?? 0)) {
+            throw new error_types_1.OptimisticLockError('External estimate log state', context.identity.remoteTaskId, {
+                expectedRevision: input.expectedRevision,
+                actualRevision: state?.revision ?? 0,
+            });
+        }
+        const keyHash = (0, node_crypto_1.createHash)('sha256').update(requestKey).digest('hex');
+        for (let index = 0; index < MAX_ENTRIES_PER_REQUEST; index += 1) {
+            if (this.timeMutations.inspectOperation(dailyOperationId(keyHash, index))) {
+                throw new error_types_1.ConflictError('The request key was already used.', {
+                    reason: 'request_key_reused',
+                });
+            }
+        }
+        const liveMinutesByDate = new Map(projection.currentByDate.map((day) => [day.activityDate, day.minutes]));
+        for (const captured of dailySnapshot) {
+            if ((liveMinutesByDate.get(captured.activityDate) ?? 0) < captured.minutes) {
+                throw new error_types_1.ValidationError('Estimate snapshot exceeds the current estimate on a date.', {
+                    reason: 'estimate_snapshot_ahead',
+                });
+            }
+        }
+        const allocation = (0, epic_time_daily_allocator_1.allocateDailyEstimateExport)({
+            liveByDate: projection.currentByDate,
+            capturedByDate: dailySnapshot,
+            ledgerByDate: checkpoint?.days.map((day) => ({
+                activityDate: day.activityDate,
+                minutes: day.loggedMinutes,
+            })) ?? [],
+            unallocatedCreditMinutes: checkpoint?.unallocatedLoggedMinutes ?? 0,
+            storedCanonicalTimeZone: state?.aggregationTimeZone ?? null,
+            currentCanonicalTimeZone: projection.canonicalTimeZone,
+        });
+        if (allocation.status === 'zone_rebind_required' || allocation.status === 'real_shrink') {
+            throw new error_types_1.ValidationError('The estimate checkpoint requires a Set-logged rebaseline.', {
+                reason: 'rebaseline_required',
+            });
+        }
+        if (allocation.status === 'stale_capture') {
+            throw new error_types_1.ValidationError('The estimate snapshot is stale; recapture the current estimate.', {
+                reason: 'estimate_snapshot_stale',
+            });
+        }
+        if (allocation.entryChunks.length === 0) {
+            throw new error_types_1.ValidationError('There is no new estimate time to log.', {
+                reason: 'estimate_up_to_date',
+            });
+        }
+        const dispatchChunks = allocation.entryChunks.slice(0, MAX_ENTRIES_PER_REQUEST);
+        const hasMore = allocation.entryChunks.length > dispatchChunks.length;
+        let entriesLogged = 0;
+        let minutesLogged = 0;
+        let expectedRevision = input.expectedRevision;
+        for (const [index, chunk] of dispatchChunks.entries()) {
+            const operationId = dailyOperationId(keyHash, index);
+            if (chunk.durationMs > external_provider_models_1.MAX_TIME_ENTRY_DURATION_MS) {
+                throw new error_types_1.ValidationError('Estimate delta exceeds the maximum time-entry duration.', {
+                    reason: 'duration_limit',
+                });
+            }
+            const current = await this.storage.getExternalEstimateLogState(context.identity);
+            if ((current?.revision ?? 0) !== expectedRevision || current?.pendingOperationId) {
+                if (entriesLogged > 0) {
+                    return this.createOutcome('partially_logged', entriesLogged, minutesLogged, true, 'concurrent_write', context);
+                }
+                if (current?.pendingOperationId) {
+                    throw new error_types_1.BusyError('An estimate operation is pending for this task.', {
+                        reason: 'estimate_operation_pending',
+                    });
+                }
+                throw new error_types_1.OptimisticLockError('External estimate log state', context.identity.remoteTaskId, {
+                    expectedRevision,
+                    actualRevision: current?.revision ?? 0,
+                });
+            }
+            let prepared;
+            try {
+                prepared = this.requirePendingValue(await this.storage.prepareExternalEstimateLogOperation({
+                    ...context.identity,
+                    operationId,
+                    deltaMinutes: chunk.minutes,
+                    estimateTotalMinutes: input.estimateTotalMinutes,
+                    startedAt: chunk.startedAt,
+                    connectionId: context.connection.id,
+                    connectionGeneration: context.connection.generation,
+                    expectedRevision,
+                    activityDate: chunk.activityDate,
+                    aggregationTimeZone: projection.canonicalTimeZone,
+                    capturedDailyTotals: dailySnapshot,
+                }), operationId);
+            }
+            catch (error) {
+                if (error instanceof error_types_1.OptimisticLockError && entriesLogged > 0) {
+                    return this.createOutcome('partially_logged', entriesLogged, minutesLogged, true, 'concurrent_write', context);
+                }
+                throw error;
+            }
+            let result;
+            try {
+                result = await this.timeMutations.createEstimateTimeEntry(input.projectId, input.provider, input.remoteTaskId, {
+                    durationMs: chunk.durationMs,
+                    startedAt: chunk.startedAt,
+                    note: epic_time_models_1.EXTERNAL_ESTIMATE_TIME_ENTRY_NOTE,
+                }, operationId, input.expectedEpoch);
+            }
+            catch (error) {
+                await this.clearKnownFailureFromCurrentCall(context, prepared, operationId);
+                if (entriesLogged > 0) {
+                    return this.createOutcome('partially_logged', entriesLogged, minutesLogged, true, 'provider_error', context);
+                }
+                throw error;
+            }
+            const inspection = this.requireMatchingInspection(prepared, operationId);
+            if (result.outcome === 'created') {
+                if (inspection.phase !== 'succeeded') {
+                    throw new error_types_1.ConflictError('Provider receipt did not confirm the estimate operation.', {
+                        reason: 'receipt_phase_mismatch',
+                    });
+                }
+                try {
+                    const confirmed = await this.storage.confirmExternalEstimateLogOperation({
+                        ...context.identity,
+                        operationId,
+                        expectedRevision: prepared.revision,
+                    });
+                    expectedRevision = confirmed.revision;
+                }
+                catch (error) {
+                    if (!(error instanceof error_types_1.OptimisticLockError))
+                        throw error;
+                    return this.createOutcome('partially_logged', entriesLogged, minutesLogged, true, 'concurrent_write', context);
+                }
+                entriesLogged += 1;
+                minutesLogged += chunk.minutes;
+                continue;
+            }
+            const unknown = await this.markOutcomeUnknown(context, prepared, inspection);
+            return this.createOutcome('outcome_unknown', entriesLogged, minutesLogged, true, 'outcome_unknown', context, unknown);
+        }
+        return this.createOutcome('logged', entriesLogged, minutesLogged, hasMore, hasMore ? 'entry_cap' : 'completed', context);
+    }
+    async createOutcome(outcome, entriesLogged, minutesLogged, hasMore, stoppedReason, context, state) {
+        const finalState = state ?? (await this.storage.getExternalEstimateLogState(context.identity));
+        return {
+            outcome,
+            entriesLogged,
+            minutesLogged,
+            hasMore,
+            stoppedReason,
+            snapshot: await this.snapshot(context, finalState),
+        };
+    }
+    async resolveOperation(input) {
+        const context = await this.resolveContext(input);
+        const state = await this.requirePendingState(context.identity, input.operationId);
+        this.assertExpectedRevision(state, input.expectedRevision);
+        if (input.action === 'verify') {
+            return this.verify(context, state);
+        }
+        return this.resolveManually(context, state, input.action);
+    }
+    async verify(context, state) {
+        if (state.pendingResolution !== null) {
+            const resumed = await this.resumeStoredResolution(context, state);
+            if (resumed.outcome === null) {
+                throw new error_types_1.BusyError('The estimate operation is still in progress.', {
+                    reason: 'operation_in_progress',
+                });
+            }
+            return {
+                outcome: resumed.outcome,
+                snapshot: await this.snapshot(context, resumed.state),
+            };
+        }
+        const inspection = this.timeMutations.inspectOperation(state.pendingOperationId);
+        if (!inspection) {
+            return { outcome: 'unresolved', snapshot: await this.snapshot(context, state) };
+        }
+        this.assertInspectionMatches(state, inspection);
+        const terminalOutcome = settlementOutcomeForPhase(inspection.phase);
+        if (terminalOutcome !== null) {
+            const reconciled = await this.reconcilePending(context, state);
+            return {
+                outcome: reconciled.outcome ?? terminalOutcome,
+                snapshot: await this.snapshot(context, reconciled.state),
+            };
+        }
+        if (isOperationInProgress(inspection.phase)) {
+            throw new error_types_1.BusyError('The estimate operation is still in progress.', {
+                reason: 'operation_in_progress',
+            });
+        }
+        if (inspection.phase !== 'outcome_unknown') {
+            return { outcome: 'unresolved', snapshot: await this.snapshot(context, state) };
+        }
+        if (!this.isCurrentPendingEpoch(context, state)) {
+            throw new error_types_1.ConflictError('Provider verification is unavailable after connection replacement.', {
+                reason: 'connection_superseded',
+            });
+        }
+        await this.timeMutations.verifyOperation(context.request.projectId, context.request.provider, state.pendingOperationId, context.connection.generation);
+        const reconciled = await this.reconcilePending(context, state);
+        if (reconciled.state.pendingOperationId === null) {
+            const after = this.timeMutations.inspectOperation(state.pendingOperationId);
+            return {
+                outcome: reconciled.outcome ??
+                    (after ? settlementOutcomeForPhase(after.phase) : null) ??
+                    'not_logged',
+                snapshot: await this.snapshot(context, reconciled.state),
+            };
+        }
+        return { outcome: 'unresolved', snapshot: await this.snapshot(context, reconciled.state) };
+    }
+    async resolveManually(context, state, resolution) {
+        const inspection = this.timeMutations.inspectOperation(state.pendingOperationId);
+        if (inspection) {
+            this.assertInspectionMatches(state, inspection);
+            const terminal = await this.settleExactTerminalReceipt(context, state, inspection);
+            if (terminal) {
+                return {
+                    outcome: terminal.outcome,
+                    snapshot: await this.snapshot(context, terminal.state),
+                };
+            }
+            if (isOperationInProgress(inspection.phase)) {
+                throw new error_types_1.BusyError('The estimate operation is still in progress.', {
+                    reason: 'operation_in_progress',
+                });
+            }
+            if (inspection.phase !== 'outcome_unknown' &&
+                inspection.phase !== 'abandoned_unknown' &&
+                this.isCurrentPendingEpoch(context, state)) {
+                throw new error_types_1.ConflictError('The estimate operation is not eligible for manual resolution.', {
+                    reason: 'manual_resolution_unavailable',
+                });
+            }
+        }
+        const storedState = await this.storage.storeExternalEstimateLogResolution({
+            ...context.identity,
+            operationId: state.pendingOperationId,
+            resolution,
+            expectedRevision: state.revision,
+        });
+        const stored = this.requirePendingValue(storedState, state.pendingOperationId);
+        const applied = await this.resumeStoredResolution(context, stored);
+        if (applied.outcome === null) {
+            throw new error_types_1.BusyError('The estimate operation is still in progress.', {
+                reason: 'operation_in_progress',
+            });
+        }
+        return { outcome: applied.outcome, snapshot: await this.snapshot(context, applied.state) };
+    }
+    async reconcilePending(context, state) {
+        if (state.pendingOperationId === null) {
+            return { state, outcome: null };
+        }
+        const inspection = this.timeMutations.inspectOperation(state.pendingOperationId);
+        if (!inspection) {
+            if (state.pendingResolution === null) {
+                return { state, outcome: null };
+            }
+            return this.resumeStoredResolution(context, state);
+        }
+        this.assertInspectionMatches(state, inspection);
+        const terminal = await this.settleExactTerminalReceipt(context, state, inspection);
+        if (terminal) {
+            return terminal;
+        }
+        if (inspection.phase === 'outcome_unknown' && state.pendingPhase === 'prepared') {
+            const marked = await this.storage.markExternalEstimateLogOperationOutcomeUnknown({
+                ...context.identity,
+                operationId: state.pendingOperationId,
+                expectedRevision: state.revision,
+            });
+            if (marked.pendingOperationId !== null && marked.pendingResolution !== null) {
+                return this.resumeStoredResolution(context, marked);
+            }
+            return { state: marked, outcome: null };
+        }
+        if (state.pendingResolution !== null) {
+            return this.resumeStoredResolution(context, state);
+        }
+        return { state, outcome: null };
+    }
+    async resumeStoredResolution(context, state) {
+        const inspection = this.timeMutations.inspectOperation(state.pendingOperationId);
+        if (inspection) {
+            this.assertInspectionMatches(state, inspection);
+            const terminal = await this.settleExactTerminalReceipt(context, state, inspection);
+            if (terminal) {
+                return terminal;
+            }
+            if (isOperationInProgress(inspection.phase)) {
+                return { state, outcome: null };
+            }
+            if (inspection.phase === 'outcome_unknown' && this.isCurrentPendingEpoch(context, state)) {
+                await this.timeMutations.acknowledgeOperation(context.request.projectId, context.request.provider, state.pendingOperationId, context.connection.generation);
+                const afterAcknowledgement = this.timeMutations.inspectOperation(state.pendingOperationId);
+                if (afterAcknowledgement) {
+                    this.assertInspectionMatches(state, afterAcknowledgement);
+                    const terminalAfterAcknowledgement = await this.settleExactTerminalReceipt(context, state, afterAcknowledgement);
+                    if (terminalAfterAcknowledgement) {
+                        return terminalAfterAcknowledgement;
+                    }
+                    if (isOperationInProgress(afterAcknowledgement.phase)) {
+                        return { state, outcome: null };
+                    }
+                }
+            }
+        }
+        const applied = await this.storage.applyExternalEstimateLogResolution({
+            ...context.identity,
+            operationId: state.pendingOperationId,
+            expectedRevision: state.revision,
+        });
+        return { state: applied, outcome: state.pendingResolution };
+    }
+    async settleExactTerminalReceipt(context, state, inspection) {
+        const outcome = settlementOutcomeForPhase(inspection.phase);
+        if (outcome === null)
+            return null;
+        let current = state;
+        while (true) {
+            try {
+                let settled;
+                if (outcome === 'logged') {
+                    settled = await this.storage.confirmExternalEstimateLogOperation({
+                        ...context.identity,
+                        operationId: state.pendingOperationId,
+                        expectedRevision: current.revision,
+                    });
+                }
+                else {
+                    settled = await this.storage.clearExternalEstimateLogOperation({
+                        ...context.identity,
+                        operationId: state.pendingOperationId,
+                        expectedRevision: current.revision,
+                    });
+                }
+                return { state: settled, outcome };
+            }
+            catch (error) {
+                if (!(error instanceof error_types_1.OptimisticLockError))
+                    throw error;
+                const refreshed = await this.storage.getExternalEstimateLogState(context.identity);
+                if (!refreshed || refreshed.pendingOperationId === null) {
+                    if (refreshed)
+                        return { state: refreshed, outcome };
+                    throw error;
+                }
+                if (refreshed.pendingOperationId !== state.pendingOperationId ||
+                    refreshed.revision === current.revision) {
+                    throw error;
+                }
+                current = refreshed;
+            }
+        }
+    }
+    async clearKnownFailureFromCurrentCall(context, prepared, operationId) {
+        const inspection = this.timeMutations.inspectOperation(operationId);
+        if (inspection) {
+            this.assertInspectionMatches(prepared, inspection);
+            if (inspection.phase === 'outcome_unknown') {
+                await this.markOutcomeUnknown(context, prepared, inspection);
+                return;
+            }
+            if (inspection.phase !== 'failed' && inspection.phase !== 'not_applied') {
+                return;
+            }
+        }
+        await this.storage.clearExternalEstimateLogOperation({
+            ...context.identity,
+            operationId,
+            expectedRevision: prepared.revision,
+        });
+    }
+    async markOutcomeUnknown(context, prepared, inspection) {
+        this.assertInspectionMatches(prepared, inspection);
+        if (inspection.phase !== 'outcome_unknown') {
+            throw new error_types_1.ConflictError('Provider receipt is not outcome-unknown.', {
+                reason: 'receipt_phase_mismatch',
+            });
+        }
+        if (prepared.pendingPhase === 'outcome_unknown') {
+            return prepared;
+        }
+        return this.storage.markExternalEstimateLogOperationOutcomeUnknown({
+            ...context.identity,
+            operationId: prepared.pendingOperationId,
+            expectedRevision: prepared.revision,
+        });
+    }
+    async snapshot(context, state) {
+        if (!state) {
+            return {
+                state: null,
+                initialized: false,
+                revision: 0,
+                loggedMinutes: 0,
+                aggregationTimeZone: null,
+                days: [],
+                unallocatedLoggedMinutes: 0,
+                pendingDisposition: 'none',
+                canVerify: false,
+                verifyExpiresAt: null,
+            };
+        }
+        const checkpoint = await this.storage.getExternalEstimateLogDailyCheckpoint(context.identity);
+        if (!checkpoint) {
+            throw new error_types_1.NotFoundError('External estimate log state');
+        }
+        return {
+            state: checkpoint.state,
+            initialized: true,
+            revision: checkpoint.state.revision,
+            loggedMinutes: checkpoint.state.loggedMinutes,
+            aggregationTimeZone: checkpoint.state.aggregationTimeZone,
+            days: checkpoint.days,
+            unallocatedLoggedMinutes: checkpoint.unallocatedLoggedMinutes,
+            ...this.pendingDispositionFields(context, checkpoint.state),
+        };
+    }
+    pendingDispositionFields(context, state) {
+        if (state.pendingOperationId === null) {
+            return {
+                pendingDisposition: 'none',
+                canVerify: false,
+                verifyExpiresAt: null,
+            };
+        }
+        const inspection = this.timeMutations.inspectOperation(state.pendingOperationId);
+        if (inspection) {
+            this.assertInspectionMatches(state, inspection);
+        }
+        if (inspection?.phase === 'pending' || inspection?.phase === 'dispatched') {
+            return {
+                pendingDisposition: 'busy',
+                canVerify: false,
+                verifyExpiresAt: null,
+            };
+        }
+        if (state.pendingResolution !== null) {
+            return {
+                pendingDisposition: 'finishing',
+                canVerify: false,
+                verifyExpiresAt: null,
+            };
+        }
+        const currentEpoch = this.isCurrentPendingEpoch(context, state);
+        const disposition = inspection?.phase === 'outcome_unknown' && currentEpoch ? 'outcome_unknown' : 'manual_review';
+        return {
+            pendingDisposition: disposition,
+            canVerify: inspection?.canVerify === true && currentEpoch,
+            verifyExpiresAt: inspection?.canVerify === true && currentEpoch ? inspection.expiresAt : null,
+        };
+    }
+    requireMatchingInspection(state, operationId) {
+        const inspection = this.timeMutations.inspectOperation(operationId);
+        if (!inspection) {
+            throw new error_types_1.ConflictError('Provider receipt is unavailable.', {
+                reason: 'receipt_missing',
+            });
+        }
+        this.assertInspectionMatches(state, inspection);
+        return inspection;
+    }
+    assertInspectionMatches(state, inspection) {
+        const tuple = inspection.tuple;
+        if (inspection.operationId !== state.pendingOperationId ||
+            inspection.kind !== 'create' ||
+            tuple.provider !== state.provider ||
+            tuple.remoteTaskId !== state.remoteTaskId ||
+            tuple.connectionId !== state.pendingConnectionId ||
+            tuple.connectionGeneration !== state.pendingConnectionGeneration ||
+            tuple.effectiveStartedAt !== state.pendingStartedAt ||
+            tuple.durationMs !== state.pendingDeltaMinutes * MILLIS_PER_MINUTE ||
+            tuple.noteFingerprint !== (0, external_time_mutation_store_1.timeEntryNoteFingerprint)(epic_time_models_1.EXTERNAL_ESTIMATE_TIME_ENTRY_NOTE)) {
+            throw new error_types_1.ConflictError('Provider receipt does not match the pending estimate operation.', {
+                reason: 'receipt_tuple_mismatch',
+            });
+        }
+    }
+    async requirePendingState(identity, operationId) {
+        const state = await this.storage.getExternalEstimateLogState(identity);
+        if (!state || state.pendingOperationId === null) {
+            throw new error_types_1.NotFoundError('Pending estimate operation');
+        }
+        if (state.pendingOperationId !== operationId) {
+            throw new error_types_1.ConflictError('A different estimate operation is pending.', {
+                reason: 'estimate_operation_mismatch',
+            });
+        }
+        return state;
+    }
+    requirePendingValue(state, operationId) {
+        if (state.pendingOperationId !== operationId) {
+            throw new error_types_1.ConflictError('Estimate operation state changed unexpectedly.', {
+                reason: 'estimate_operation_mismatch',
+            });
+        }
+        return state;
+    }
+    async resolveContext(input) {
+        const request = this.normalizeContext(input);
+        const identity = {
+            provider: request.provider,
+            remoteScopeKey: request.remoteScopeKey,
+            remoteTaskId: request.remoteTaskId,
+        };
+        const [link, connection] = await Promise.all([
+            this.storage.findExternalTaskLink(identity.provider, identity.remoteScopeKey, identity.remoteTaskId),
+            this.storage.getIntegrationConnection({
+                projectId: request.projectId,
+                provider: request.provider,
+            }),
+        ]);
+        if (!link) {
+            throw new error_types_1.NotFoundError('External task link');
+        }
+        if (connection?.projectId !== request.projectId || connection.provider !== request.provider) {
+            throw new error_types_1.ValidationError('Connect the integration before changing estimate time.', {
+                reason: 'not_connected',
+            });
+        }
+        if (connection.generation !== request.expectedEpoch) {
+            throw new error_types_1.ConflictError('The connection changed; reload with the current epoch.', {
+                reason: 'connection_epoch_mismatch',
+            });
+        }
+        if (link.connectionId !== connection.id) {
+            throw new error_types_1.ConflictError('The external task link does not belong to the current connection.', {
+                reason: 'link_connection_mismatch',
+            });
+        }
+        const epic = await this.storage.getEpic(link.epicId);
+        if (epic.projectId !== request.projectId) {
+            throw new error_types_1.NotFoundError('External task link');
+        }
+        return { request, identity, link, epic, connection };
+    }
+    normalizeContext(input) {
+        const projectId = this.requireIdentifier(input.projectId, 'Project');
+        const remoteScopeKey = this.requireIdentifier(input.remoteScopeKey, 'Remote scope');
+        const remoteTaskId = this.requireIdentifier(input.remoteTaskId, 'Remote task');
+        if (input.provider !== 'clickup' && input.provider !== 'jira') {
+            throw new error_types_1.ValidationError('Integration provider is invalid.');
+        }
+        if (!Number.isSafeInteger(input.expectedEpoch) || input.expectedEpoch < 1) {
+            throw new error_types_1.ValidationError('Connection epoch must be a positive whole number.');
+        }
+        return {
+            projectId,
+            provider: input.provider,
+            remoteScopeKey,
+            remoteTaskId,
+            expectedEpoch: input.expectedEpoch,
+        };
+    }
+    isCurrentPendingEpoch(context, state) {
+        return (context.connection.id === state.pendingConnectionId &&
+            context.connection.generation === state.pendingConnectionGeneration);
+    }
+    assertExpectedRevision(state, expectedRevision) {
+        this.requireNonnegativeInteger(expectedRevision, 'Expected revision');
+        if (state.revision !== expectedRevision) {
+            throw this.optimisticLock(state, expectedRevision);
+        }
+    }
+    optimisticLock(state, expectedRevision) {
+        return new error_types_1.OptimisticLockError('External estimate log state', state.remoteTaskId, {
+            expectedRevision,
+            actualRevision: state.revision,
+        });
+    }
+    requireRequestKey(value) {
+        const normalized = value?.trim();
+        if (!normalized || !REQUEST_KEY_PATTERN.test(normalized)) {
+            throw new error_types_1.ValidationError('Estimate request key must be a fresh UUID.');
+        }
+        return normalized.toLowerCase();
+    }
+    requireDailySnapshot(entries, estimateTotalMinutes) {
+        if (!Array.isArray(entries) || entries.length > MAX_DAILY_LEDGER_ENTRIES) {
+            throw new error_types_1.ValidationError(`The daily snapshot may carry at most ${MAX_DAILY_LEDGER_ENTRIES} activity dates.`);
+        }
+        let previousDate = null;
+        let total = 0;
+        for (const entry of entries) {
+            if (!(0, epic_time_local_day_1.isValidActivityDate)(entry?.activityDate ?? '')) {
+                throw new error_types_1.ValidationError('The daily snapshot contains an invalid activity date.');
+            }
+            if (!Number.isSafeInteger(entry?.minutes) || entry.minutes < 0) {
+                throw new error_types_1.ValidationError('Daily snapshot minutes must be nonnegative whole numbers.');
+            }
+            if (previousDate !== null && entry.activityDate.localeCompare(previousDate) <= 0) {
+                throw new error_types_1.ValidationError('Daily snapshot dates must be unique and ascending.');
+            }
+            previousDate = entry.activityDate;
+            total += entry.minutes;
+        }
+        if (total !== estimateTotalMinutes) {
+            throw new error_types_1.ValidationError('The daily snapshot must sum to the estimate total.', {
+                reason: 'snapshot_sum_mismatch',
+            });
+        }
+        return [...entries];
+    }
+    requireIdentifier(value, label) {
+        const normalized = value?.trim();
+        if (!normalized) {
+            throw new error_types_1.ValidationError(`${label} identifier is required.`);
+        }
+        return normalized;
+    }
+    requireNonnegativeInteger(value, label) {
+        if (!Number.isSafeInteger(value) || value < 0) {
+            throw new error_types_1.ValidationError(`${label} must be a nonnegative whole number.`);
+        }
+    }
+};
+exports.EpicEstimateLoggingService = EpicEstimateLoggingService;
+exports.EpicEstimateLoggingService = EpicEstimateLoggingService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(storage_interface_1.STORAGE_SERVICE)),
+    __metadata("design:paramtypes", [Object, epic_time_service_1.EpicTimeService,
+        external_time_mutation_service_1.ExternalTimeMutationService])
+], EpicEstimateLoggingService);
+//# sourceMappingURL=epic-estimate-logging.service.js.map