Skip to content

A self-hosted UPI & COD payment gateway with zero per-transaction platform fees, universal JavaScript checkout integration, dynamic QR payments, WhatsApp OTP authentication, and automated payment verification.

JavaScript
47.6 KB
Raw Blame
import { PaymentStatus, ObservationAttributionStatus, TicketStatus, SenderType, isTerminalStatus, calculateObservationFingerprint } from '@youpi/common';

export function getChannelFamily(source) {
  const normalized = String(source || '').trim().toUpperCase();
  if (normalized === 'GMAIL') return 'GMAIL';
  if (['SMS', 'SMS_GATEWAY', 'GOOGLE_MESSAGES', 'ANDROID_OBSERVER'].includes(normalized)) {
    return 'SMS';
  }
  return normalized || 'SMS';
}

export class AttributionEngine {
  /**
   * @param {{
   *   sessionRepo: import('@youpi/db').PaymentSessionRepository,
   *   obsRepo: import('@youpi/db').ObservationRepository,
   *   ticketRepo?: import('@youpi/db').SupportTicketRepository,
   *   auditRepo?: import('@youpi/db').AuditLogRepository,
   *   eventEmitter?: { emit: (event: string, payload: any) => void }
   * }} options
   */
  constructor(options) {
    this.sessionRepo = options.sessionRepo;
    this.obsRepo = options.obsRepo;
    this.ticketRepo = options.ticketRepo;
    this.auditRepo = options.auditRepo;
    this.eventEmitter = options.eventEmitter || { emit: () => {} };
    const isTestExecution = process.env.NODE_ENV === 'test' ||
      Boolean(process.env.NODE_TEST_CONTEXT) ||
      (process.execArgv && process.execArgv.some(a => a.includes('test'))) ||
      (process.argv && process.argv.some(a => a.includes('test')));

    this.gracePeriodMs = options.gracePeriodMs !== undefined
      ? options.gracePeriodMs
      : (process.env.PAYMENT_GRACE_PERIOD_MS !== undefined
        ? Number(process.env.PAYMENT_GRACE_PERIOD_MS)
        : (isTestExecution ? 0 : 5000));
    /** @type {Map<string, NodeJS.Timeout>} */
    this.pendingGraceTimers = new Map();
  }

  destroy() {
    for (const timer of this.pendingGraceTimers.values()) {
      clearTimeout(timer);
    }
    this.pendingGraceTimers.clear();
  }

  /**
   * More than one session could explain this alert. Do not pick one.
   * Live sessions move to MANUAL_REVIEW. The observation is kept as evidence.
   */
  holdAmbiguous(savedObs, sessions, reason) {
    this.obsRepo.markAmbiguous(savedObs.id);
    const ids = [];
    for (const session of sessions) {
      if (!session?.id) continue;
      ids.push(session.id);
      const live = session.status === PaymentStatus.ACTIVE
        || session.status === PaymentStatus.PROCESSING
        || session.status === PaymentStatus.OBSERVED_SUCCESS;
      if (!live) continue;
      try {
        this.sessionRepo.transitionToTerminal(session.id, PaymentStatus.MANUAL_REVIEW, { reason });
        this.eventEmitter.emit('PAYMENT.MANUAL_REVIEW', {
          paymentId: session.id,
          orderId: session.orderId || session.order_id,
          merchantId: session.merchantId || session.merchant_id,
          observationId: savedObs.id,
          reason
        });
      } catch (err) {
        if (this.auditRepo) {
          this.auditRepo.log({
            merchantId: session.merchantId || session.merchant_id,
            entityType: 'PAYMENT_SESSION',
            entityId: session.id,
            action: 'AMBIGUOUS_MATCH_TRANSITION_FAILED',
            actorType: 'SYSTEM',
            details: { reason, error: err.message, observationId: savedObs.id }
          });
        }
      }
    }
    if (this.auditRepo && sessions[0]) {
      this.auditRepo.log({
        merchantId: sessions[0].merchantId || sessions[0].merchant_id,
        entityType: 'PAYMENT_OBSERVATION',
        entityId: savedObs.id,
        action: 'AMBIGUOUS_MATCH_MANUAL_REVIEW',
        actorType: 'SYSTEM',
        details: {
          reason,
          observationId: savedObs.id,
          sessionIds: ids,
          amountPaise: savedObs.amountPaise?.toString?.() || String(savedObs.amount_paise || '')
        }
      });
    }
    return {
      attributed: false,
      duplicate: false,
      lateMatch: false,
      ambiguous: true,
      observationId: savedObs.id,
      outcomeStatus: PaymentStatus.MANUAL_REVIEW,
      reason
    };
  }

  /**
   * Processes a normalized canonical observation through the attribution pipeline.
   * @param {ReturnType<typeof import('./normalizer.js').ObservationNormalizer.normalize>} normalizedObs
   * @returns {{
   *   attributed: boolean,
   *   duplicate: boolean,
   *   lateMatch: boolean,
   *   paymentSessionId?: string,
   *   observationId: string,
   *   outcomeStatus: string,
   *   verificationLevel?: number,
   *   verificationTag?: string,
   *   verificationSources?: string[]
   * }}
   */
  processObservation(normalizedObs) {
    if (normalizedObs && normalizedObs.amountPaise !== undefined && typeof normalizedObs.amountPaise !== 'bigint') {
      normalizedObs = { ...normalizedObs, amountPaise: BigInt(normalizedObs.amountPaise) };
    }
    if (normalizedObs && !(normalizedObs.observedAt instanceof Date)) {
      const parsedDate = normalizedObs.observedAt ? new Date(normalizedObs.observedAt) : new Date();
      normalizedObs = {
        ...normalizedObs,
        observedAt: Number.isNaN(parsedDate.getTime()) ? new Date() : parsedDate
      };
    }
    if (normalizedObs && !normalizedObs.fingerprintHash) {
      normalizedObs = {
        ...normalizedObs,
        fingerprintHash: calculateObservationFingerprint({
          receivingAccountId: normalizedObs.receivingAccountId,
          amountPaise: normalizedObs.amountPaise,
          source: normalizedObs.source,
          bankReferenceNumber: normalizedObs.bankReferenceNumber,
          observedAt: normalizedObs.observedAt
        })
      };
    }

    const incomingFamily = getChannelFamily(normalizedObs.source);

    // Tier 1: Check fingerprint for deduplication
    // Look up this channel family first: once a second channel family has upgraded the payment, the
    // fingerprint has one row per channel family and the unfiltered lookup may return the other one.
    const existingSameFamily = this.obsRepo.findByFingerprintOrFamily
      ? this.obsRepo.findByFingerprintOrFamily(normalizedObs.fingerprintHash, normalizedObs.source)
      : this.obsRepo.findByFingerprint(normalizedObs.fingerprintHash, normalizedObs.source);
    const existing = existingSameFamily || this.obsRepo.findByFingerprint(normalizedObs.fingerprintHash);
    if (existing) {
      // If observation came from the SAME channel family (e.g. SMS_GATEWAY + ANDROID_OBSERVER or GOOGLE_MESSAGES),
      // drop as a redundant duplicate so same-channel-family events never falsely upgrade to Level 2.
      if (existing.source === normalizedObs.source || getChannelFamily(existing.source) === incomingFamily) {
        if (this.auditRepo) {
          this.auditRepo.log({
            entityType: 'PAYMENT_OBSERVATION',
            entityId: existing.id,
            action: 'DUPLICATE_OBSERVATION_DROPPED',
            actorType: 'OBSERVER',
            details: {
              fingerprintHash: normalizedObs.fingerprintHash,
              source: normalizedObs.source,
              existingSource: existing.source,
              channelFamily: incomingFamily
            }
          });
        }
        return {
          attributed: false,
          duplicate: true,
          lateMatch: false,
          paymentSessionId: existing.attributedPaymentId || undefined,
          observationId: existing.id,
          outcomeStatus: ObservationAttributionStatus.DUPLICATE_IGNORED
        };
      }

      // If observation came from a NEW, INDEPENDENT channel family (SMS vs GMAIL) and payment was already attributed:
      // Upgrade verification tier to Level 2 (Dual Verification)!
      if (existing.attributedPaymentId) {
        const targetSession = this.sessionRepo.findById(existing.attributedPaymentId);
        // Keep MANUAL_REVIEW sessions held until verified by authoritative bank statement
        if (targetSession && targetSession.status === PaymentStatus.MANUAL_REVIEW) {
          return {
            attributed: false,
            duplicate: false,
            lateMatch: false,
            ambiguous: true,
            paymentSessionId: targetSession.id,
            observationId: existing.id,
            outcomeStatus: PaymentStatus.MANUAL_REVIEW,
            reason: 'SESSION_HELD_IN_MANUAL_REVIEW'
          };
        }
        // If target session already has a verification source from this channel family, drop as duplicate
        if (
          targetSession &&
          Array.isArray(targetSession.verificationSources) &&
          targetSession.verificationSources.some(s => getChannelFamily(s) === incomingFamily)
        ) {
          return {
            attributed: false,
            duplicate: true,
            lateMatch: false,
            paymentSessionId: targetSession.id,
            observationId: existing.id,
            outcomeStatus: ObservationAttributionStatus.DUPLICATE_IGNORED
          };
        }
        const closedWithoutUpgrade = targetSession
          && isTerminalStatus(targetSession.status)
          && targetSession.status !== PaymentStatus.SUCCESS
          && targetSession.status !== PaymentStatus.OBSERVED_SUCCESS
          && targetSession.status !== PaymentStatus.RECONCILED;
        if (closedWithoutUpgrade) {
          const savedObs = this.obsRepo.create(normalizedObs);
          this.obsRepo.markLateUnmatched(savedObs.id, targetSession.id);
          if (this.auditRepo) {
            this.auditRepo.log({
              merchantId: targetSession.merchantId,
              entityType: 'PAYMENT_SESSION',
              entityId: targetSession.id,
              action: 'LATE_OBSERVATION_DETECTED',
              actorType: 'SYSTEM',
              details: {
                observationId: savedObs.id,
                source: normalizedObs.source,
                sessionStatus: targetSession.status
              }
            });
          }
          if (this.ticketRepo && targetSession.customerId) {
            this.ticketRepo.createTicket({
              merchantId: targetSession.merchantId,
              customerId: targetSession.customerId,
              paymentId: targetSession.id,
              subject: `[LATE PAYMENT DETECTED] Order #${targetSession.orderId}`,
              status: TicketStatus.OPEN,
              initialMessage: {
                senderType: SenderType.ADMIN,
                senderId: targetSession.merchantId,
                message: `A delayed payment observation of ${normalizedObs.amountPaise / 100n} INR was detected after session ${targetSession.id} ended with status ${targetSession.status}. Flagged for manual merchant reconciliation.`
              }
            });
          }
          this.eventEmitter.emit('PAYMENT.LATE_DETECTED', {
            paymentId: targetSession.id,
            orderId: targetSession.orderId,
            merchantId: targetSession.merchantId,
            amountPaise: normalizedObs.amountPaise,
            observationId: savedObs.id
          });
          return {
            attributed: false,
            duplicate: false,
            lateMatch: true,
            paymentSessionId: targetSession.id,
            observationId: savedObs.id,
            outcomeStatus: ObservationAttributionStatus.LATE_UNMATCHED
          };
        }

        // Cancel pending 5-second grace timer if any
        const pendingTimer = this.pendingGraceTimers.get(existing.attributedPaymentId);
        if (pendingTimer) {
          clearTimeout(pendingTimer);
          this.pendingGraceTimers.delete(existing.attributedPaymentId);
        }

        const savedObs = this.obsRepo.create(normalizedObs);
        let verifyResult;
        try {
          verifyResult = this.sessionRepo.recordVerificationSource(
            existing.attributedPaymentId,
            normalizedObs.source,
            savedObs.id,
            { finalizeSuccess: true }
          );
          if (existing.bankReferenceNumber && savedObs.bankReferenceNumber && String(existing.bankReferenceNumber).trim() === String(savedObs.bankReferenceNumber).trim()) {
            this.obsRepo.db.execute(`
              UPDATE payment_observations
              SET attribution_status = ?
              WHERE id = ?
            `, [ObservationAttributionStatus.ATTRIBUTED, savedObs.id]);
          } else {
            this.obsRepo.markAttributed(savedObs.id, existing.attributedPaymentId);
          }
        } catch (dbErr) {
          const errMsg = dbErr?.message || '';
          if (errMsg.includes('UNIQUE constraint failed') || errMsg.includes('duplicate key value') || errMsg.includes('idx_observations_unique_attributed_bank_ref') || errMsg.includes('idx_payment_sessions_attributed_obs')) {
            return {
              attributed: false,
              duplicate: true,
              lateMatch: false,
              observationId: savedObs.id,
              outcomeStatus: 'REFERENCE_ALREADY_USED'
            };
          }
          throw dbErr;
        }

        if (this.auditRepo) {
          this.auditRepo.log({
            entityType: 'PAYMENT_SESSION',
            entityId: existing.attributedPaymentId,
            action: 'PAYMENT_VERIFICATION_UPGRADED',
            actorType: 'SYSTEM',
            details: {
              source: normalizedObs.source,
              level: verifyResult.level,
              tag: verifyResult.tag,
              sources: verifyResult.sources
            }
          });
        }

        if (verifyResult.isFirstSuccess) {
          this.eventEmitter.emit('PAYMENT.OBSERVED_SUCCESS', {
            paymentId: existing.attributedPaymentId,
            orderId: verifyResult.session.orderId,
            merchantId: verifyResult.session.merchantId,
            amountPaise: verifyResult.session.amountPaise,
            observationId: savedObs.id,
            verificationLevel: verifyResult.level,
            verificationTag: verifyResult.tag,
            sources: verifyResult.sources
          });
        }

        this.eventEmitter.emit('PAYMENT.VERIFICATION_UPGRADED', {
          paymentId: existing.attributedPaymentId,
          verificationLevel: verifyResult.level,
          verificationTag: verifyResult.tag,
          sources: verifyResult.sources
        });

        return {
          attributed: true,
          duplicate: false,
          lateMatch: false,
          paymentSessionId: existing.attributedPaymentId,
          observationId: savedObs.id,
          outcomeStatus: PaymentStatus.OBSERVED_SUCCESS,
          verificationLevel: verifyResult.level,
          verificationTag: verifyResult.tag,
          verificationSources: verifyResult.sources
        };
      }
    }

    // Persist new observation as UNATTRIBUTED first
    const savedObs = this.obsRepo.create(normalizedObs);

    // Tier 2: Check currently active session on receiving account
    let currentSession = null;
    if (normalizedObs.rawPayload?.targetSessionId) {
      currentSession = this.sessionRepo.findById(normalizedObs.rawPayload.targetSessionId);
      if (currentSession && currentSession.status === PaymentStatus.MANUAL_REVIEW) {
        this.obsRepo.markAmbiguous(savedObs.id);
        return {
          attributed: false,
          duplicate: false,
          lateMatch: false,
          ambiguous: true,
          paymentSessionId: currentSession.id,
          observationId: savedObs.id,
          outcomeStatus: PaymentStatus.MANUAL_REVIEW,
          reason: 'SESSION_HELD_IN_MANUAL_REVIEW'
        };
      }
    }
    if (currentSession?.method === 'MANUAL_UPI') {
      if (this.auditRepo) this.auditRepo.log({
        merchantId: currentSession.merchantId,
        entityType: 'PAYMENT_SESSION',
        entityId: currentSession.id,
        action: 'AUTOMATIC_OBSERVATION_IGNORED_FOR_MANUAL_UPI',
        actorType: 'OBSERVER',
        details: { observationId: savedObs.id, source: normalizedObs.source }
      });
      return {
        attributed: false,
        duplicate: false,
        lateMatch: false,
        observationId: savedObs.id,
        outcomeStatus: ObservationAttributionStatus.UNATTRIBUTED,
        reason: 'MANUAL_UPI_REQUIRES_ADMIN_BANK_VERIFICATION'
      };
    }
    if (!currentSession || (currentSession.amountPaise !== normalizedObs.amountPaise)) {
      const matchRows = this.sessionRepo.db.query(`
        SELECT * FROM payment_sessions
        WHERE receiving_account_id = ? AND status IN ('ACTIVE', 'PROCESSING') AND method <> 'MANUAL_UPI' AND amount_paise = ?
      `, [normalizedObs.receivingAccountId, Number(normalizedObs.amountPaise)]);
      if (matchRows.length > 1) {
        return this.holdAmbiguous(
          savedObs,
          matchRows.map(row => this.sessionRepo.mapRow(row)),
          'MULTIPLE_LIVE_AMOUNT_MATCHES'
        );
      }
      if (matchRows.length === 1) {
        currentSession = this.sessionRepo.mapRow(matchRows[0]);
      } else if (!currentSession) {
        currentSession = this.sessionRepo.findCurrentActiveOrProcessing(normalizedObs.receivingAccountId);
      }
    } else if (!normalizedObs.rawPayload?.targetSessionId) {
      // Even if targetSessionId was not specified and currentSession matched amount, verify no other live session shares this amount
      const matchRows = this.sessionRepo.db.query(`
        SELECT * FROM payment_sessions
        WHERE receiving_account_id = ? AND status IN ('ACTIVE', 'PROCESSING') AND amount_paise = ?
      `, [normalizedObs.receivingAccountId, Number(normalizedObs.amountPaise)]);
      if (matchRows.length > 1) {
        return this.holdAmbiguous(
          savedObs,
          matchRows.map(row => this.sessionRepo.mapRow(row)),
          'MULTIPLE_LIVE_AMOUNT_MATCHES'
        );
      }
    }

    if (currentSession) {
      // Invariant Check 1: Must be in ACTIVE or PROCESSING status
      const isEligibleStatus = [PaymentStatus.ACTIVE, PaymentStatus.PROCESSING].includes(currentSession.status);

      // Invariant Check 2: Exact Amount Match (in integer paise)
      const isAmountMatch = currentSession.amountPaise === normalizedObs.amountPaise;

      // Invariant Check 3: Temporal Window (with 5-minute clock skew tolerance, strictly preventing hijacking of prior expired sessions)
      let isPriorExpiredSession = false;
      if (currentSession.slotAcquiredAt && normalizedObs.observedAt < currentSession.slotAcquiredAt) {
        const thirtyMinutesAgo = new Date(Date.now() - 30 * 60 * 1000);
        const recentExpired = this.sessionRepo.findRecentlyExpiredOrFailed(
          normalizedObs.receivingAccountId,
          thirtyMinutesAgo
        );
        isPriorExpiredSession = recentExpired.some(s => s.amountPaise === normalizedObs.amountPaise);
      }

      const slotStart = currentSession.slotAcquiredAt
        ? new Date(currentSession.slotAcquiredAt.getTime() - 300000)
        : new Date(currentSession.createdAt.getTime() - 300000);

      const isTimeValid = !isPriorExpiredSession && (normalizedObs.observedAt >= slotStart);

      // Invariant Check 0a: Transaction Reference Already Used Check
      let isUtrAlreadyUsed = false;
      const trimmedUtr = normalizedObs.bankReferenceNumber ? String(normalizedObs.bankReferenceNumber).trim() : '';
      if (trimmedUtr.length > 0) {
        const priorUsedSession = this.sessionRepo.db.queryOne(`
          SELECT ps.id, ps.order_id
          FROM payment_sessions ps
          JOIN payment_observations po ON (ps.attributed_observation_id = po.id OR po.attributed_payment_id = ps.id)
          WHERE ps.status NOT IN ('FAILED', 'EXPIRED', 'CANCELLED')
            AND ps.id != ?
            AND po.bank_reference_number = ?
          LIMIT 1
        `, [currentSession.id, trimmedUtr]);

        if (priorUsedSession) {
          isUtrAlreadyUsed = true;
          if (this.auditRepo) {
            this.auditRepo.log({
              merchantId: currentSession.merchantId,
              entityType: 'PAYMENT_SESSION',
              entityId: currentSession.id,
              action: 'REUSED_UTR_REJECTED',
              actorType: 'SYSTEM',
              details: {
                bankReferenceNumber: trimmedUtr,
                consumedByOrderId: priorUsedSession.order_id,
                consumedBySessionId: priorUsedSession.id
              }
            });
          }
        }
      }

      // Invariant Check 0b: Check if SMS is from personal numeric phone number (10-15 digits E.164, no letters)
      let isPersonalSms = false;
      const senderStr = (normalizedObs.rawPayload?.sender || normalizedObs.rawPayload?.from || '').toString().trim();
      if ((normalizedObs.source === 'SMS' || normalizedObs.source === 'ANDROID_OBSERVER') && senderStr) {
        const digitsOnly = senderStr.replace(/[\s+-]/g, '');
        if (digitsOnly.length >= 10 && /^\d+$/.test(digitsOnly) && !/[a-zA-Z]/.test(senderStr)) {
          isPersonalSms = true;
        }
      }

      if (isPriorExpiredSession && isEligibleStatus && isAmountMatch) {
        return this.holdAmbiguous(savedObs, [currentSession], 'LIVE_AND_RECENT_SAME_AMOUNT');
      }

      if (isUtrAlreadyUsed) {
        return {
          attributed: false,
          duplicate: true,
          lateMatch: false,
          observationId: savedObs.id,
          outcomeStatus: 'REFERENCE_ALREADY_USED'
        };
      }

      if (isPersonalSms) {
        return {
          attributed: false,
          duplicate: false,
          lateMatch: false,
          observationId: savedObs.id,
          outcomeStatus: 'PERSONAL_SMS_REJECTED'
        };
      }

      if (isEligibleStatus && isAmountMatch && isTimeValid) {
        const wasActive = currentSession.status === PaymentStatus.ACTIVE;

        // Check if currentSession already has an attributed primary observation (e.g. during grace window or REQUIRE_DUAL_CHANNEL)
        const primaryObs = currentSession.attributedObservationId
          ? this.obsRepo.findById(currentSession.attributedObservationId)
          : null;

        if (primaryObs) {
          const hasConflictingUtr = Boolean(
            primaryObs.bankReferenceNumber &&
            savedObs.bankReferenceNumber &&
            String(primaryObs.bankReferenceNumber).trim() !== String(savedObs.bankReferenceNumber).trim()
          );
          if (hasConflictingUtr) {
            const pendingGrace = this.pendingGraceTimers.get(currentSession.id);
            if (pendingGrace) {
              clearTimeout(pendingGrace);
              this.pendingGraceTimers.delete(currentSession.id);
            }
            return this.holdAmbiguous(savedObs, [currentSession], 'CONFLICTING_UTR_ON_SESSION');
          }

          if (getChannelFamily(primaryObs.source) === incomingFamily) {
            this.obsRepo.markDuplicate(savedObs.id);
            return {
              attributed: false,
              duplicate: true,
              lateMatch: false,
              paymentSessionId: currentSession.id,
              observationId: savedObs.id,
              outcomeStatus: ObservationAttributionStatus.DUPLICATE_IGNORED
            };
          }
        }

        // Check if there is already an active grace period awaiting second source for this session
        const pendingGrace = this.pendingGraceTimers.get(currentSession.id);
        if (pendingGrace) {
          clearTimeout(pendingGrace);
          this.pendingGraceTimers.delete(currentSession.id);

          // Second independent source confirmed within 5-second grace window -> LEVEL 2 DUAL VERIFICATION!
          let verifyResult;
          try {
            verifyResult = this.sessionRepo.recordVerificationSource(
              currentSession.id,
              normalizedObs.source,
              savedObs.id,
              { finalizeSuccess: true }
            );

            const sameUtrAsPrimary = Boolean(
              primaryObs &&
              primaryObs.bankReferenceNumber &&
              savedObs.bankReferenceNumber &&
              String(primaryObs.bankReferenceNumber).trim() === String(savedObs.bankReferenceNumber).trim()
            );

            if (!sameUtrAsPrimary) {
              this.obsRepo.markAttributed(savedObs.id, currentSession.id);
            } else {
              // Secondary dual-verification observation corroborates existing attributed UTR
              this.obsRepo.db.execute(`
                UPDATE payment_observations
                SET attribution_status = ?
                WHERE id = ?
              `, [ObservationAttributionStatus.ATTRIBUTED, savedObs.id]);
            }
          } catch (dbErr) {
            const errMsg = dbErr?.message || '';
            if (errMsg.includes('UNIQUE constraint failed') || errMsg.includes('duplicate key value') || errMsg.includes('idx_observations_unique_attributed_bank_ref') || errMsg.includes('idx_payment_sessions_attributed_obs')) {
              return {
                attributed: false,
                duplicate: true,
                lateMatch: false,
                observationId: savedObs.id,
                outcomeStatus: 'REFERENCE_ALREADY_USED'
              };
            }
            throw dbErr;
          }

          if (this.auditRepo) {
            this.auditRepo.log({
              merchantId: currentSession.merchantId,
              entityType: 'PAYMENT_SESSION',
              entityId: currentSession.id,
              action: 'PAYMENT_VERIFICATION_UPGRADED_L2',
              actorType: 'SYSTEM',
              details: {
                observationId: savedObs.id,
                source: normalizedObs.source,
                verificationLevel: 2,
                verificationTag: verifyResult.tag,
                sources: verifyResult.sources
              }
            });
          }

          this.eventEmitter.emit('PAYMENT.OBSERVED_SUCCESS', {
            paymentId: currentSession.id,
            orderId: currentSession.orderId,
            merchantId: currentSession.merchantId,
            amountPaise: currentSession.amountPaise,
            observationId: savedObs.id,
            verificationLevel: 2,
            verificationTag: verifyResult.tag,
            sources: verifyResult.sources
          });

          this.eventEmitter.emit('PAYMENT.VERIFICATION_UPGRADED', {
            paymentId: currentSession.id,
            orderId: currentSession.orderId,
            verificationLevel: 2,
            verificationTag: verifyResult.tag,
            sources: verifyResult.sources
          });

          return {
            attributed: true,
            duplicate: false,
            lateMatch: false,
            wasActive,
            paymentSessionId: currentSession.id,
            observationId: savedObs.id,
            outcomeStatus: PaymentStatus.OBSERVED_SUCCESS,
            verificationLevel: 2,
            verificationTag: verifyResult.tag,
            verificationSources: verifyResult.sources
          };
        }

        // FIRST SOURCE CONFIRMATION:
        // Record Level 1 verification source without immediate finalization (start 5-second grace window)
        let verifyResult;
        try {
          verifyResult = this.sessionRepo.recordVerificationSource(
            currentSession.id,
            normalizedObs.source,
            savedObs.id,
            { finalizeSuccess: false }
          );

          this.obsRepo.markAttributed(savedObs.id, currentSession.id);
        } catch (dbErr) {
          const errMsg = dbErr.message || '';
          if (errMsg.includes('UNIQUE constraint failed') || errMsg.includes('duplicate key value') || errMsg.includes('idx_observations_unique_attributed_bank_ref') || errMsg.includes('idx_payment_sessions_attributed_obs')) {
            if (this.auditRepo) {
              this.auditRepo.log({
                merchantId: currentSession.merchantId,
                entityType: 'PAYMENT_SESSION',
                entityId: currentSession.id,
                action: 'REUSED_UTR_REJECTED',
                actorType: 'SYSTEM',
                details: {
                  bankReferenceNumber: trimmedUtr,
                  error: 'Concurrent UTR or observation attribution race prevented by database unique constraint.'
                }
              });
            }
            return {
              attributed: false,
              duplicate: true,
              lateMatch: false,
              observationId: savedObs.id,
              outcomeStatus: 'REFERENCE_ALREADY_USED'
            };
          }
          throw dbErr;
        }

        if (this.auditRepo) {
          this.auditRepo.log({
            merchantId: currentSession.merchantId,
            entityType: 'PAYMENT_SESSION',
            entityId: currentSession.id,
            action: 'PAYMENT_LEVEL1_VERIFIED',
            actorType: 'SYSTEM',
            details: {
              observationId: savedObs.id,
              source: normalizedObs.source,
              amountPaise: normalizedObs.amountPaise.toString(),
              verificationLevel: 1,
              verificationTag: verifyResult.tag,
              sources: verifyResult.sources
            }
          });
        }

        this.eventEmitter.emit('PAYMENT.LEVEL1_VERIFIED', {
          paymentId: currentSession.id,
          orderId: currentSession.orderId,
          merchantId: currentSession.merchantId,
          amountPaise: currentSession.amountPaise,
          observationId: savedObs.id,
          verificationLevel: 1,
          verificationTag: verifyResult.tag,
          sources: verifyResult.sources
        });

        // If grace period is 0 (e.g. in instant tests), finalize immediately unless dual channel is required
        if (this.verificationPolicy !== 'REQUIRE_DUAL_CHANNEL' && (this.verificationPolicy === 'SINGLE_CHANNEL_VALIDATED_GMAIL' || this.gracePeriodMs <= 0)) {
          const finalResult = this.sessionRepo.recordVerificationSource(
            currentSession.id,
            normalizedObs.source,
            savedObs.id,
            { finalizeSuccess: true }
          );
          this.eventEmitter.emit('PAYMENT.OBSERVED_SUCCESS', {
            paymentId: currentSession.id,
            orderId: currentSession.orderId,
            merchantId: currentSession.merchantId,
            amountPaise: currentSession.amountPaise,
            observationId: savedObs.id,
            verificationLevel: finalResult.level,
            verificationTag: finalResult.tag,
            sources: finalResult.sources
          });

          return {
            attributed: true,
            duplicate: false,
            lateMatch: false,
            wasActive,
            paymentSessionId: currentSession.id,
            observationId: savedObs.id,
            outcomeStatus: PaymentStatus.OBSERVED_SUCCESS,
            verificationLevel: finalResult.level,
            verificationTag: finalResult.tag,
            verificationSources: finalResult.sources
          };
        }

        if (this.verificationPolicy === 'REQUIRE_DUAL_CHANNEL') {
          return {
            attributed: true,
            duplicate: false,
            lateMatch: false,
            wasActive,
            paymentSessionId: currentSession.id,
            observationId: savedObs.id,
            outcomeStatus: PaymentStatus.PROCESSING,
            verificationLevel: verifyResult.level,
            verificationTag: verifyResult.tag,
            verificationSources: verifyResult.sources
          };
        }

        // Start 5-second grace window awaiting second poller
        const targetSessionId = currentSession.id;
        const targetObsId = savedObs.id;
        const targetSource = normalizedObs.source;
        const targetOrderId = currentSession.orderId;
        const targetMerchantId = currentSession.merchantId;
        const targetAmountPaise = currentSession.amountPaise;

        const graceTimer = setTimeout(() => {
          this.pendingGraceTimers.delete(targetSessionId);
          // Check if session became terminal during the grace window
          const latestSession = this.sessionRepo.findById(targetSessionId);
          const alreadyObserved = latestSession && (
            latestSession.status === PaymentStatus.SUCCESS
            || latestSession.status === PaymentStatus.OBSERVED_SUCCESS
            || latestSession.status === PaymentStatus.RECONCILED
          );
          if (!latestSession || (isTerminalStatus(latestSession.status) && !alreadyObserved)) {
            const sessionStatus = latestSession ? latestSession.status : 'EXPIRED';
            this.obsRepo.markLateUnmatched(targetObsId);
            if (this.auditRepo) {
              this.auditRepo.log({
                merchantId: targetMerchantId,
                entityType: 'PAYMENT_SESSION',
                entityId: targetSessionId,
                action: 'LATE_OBSERVATION_DETECTED',
                actorType: 'SYSTEM',
                details: {
                  observationId: targetObsId,
                  source: targetSource,
                  sessionStatus
                }
              });
            }
            if (this.ticketRepo && latestSession?.customerId) {
              this.ticketRepo.createTicket({
                merchantId: targetMerchantId,
                customerId: latestSession.customerId,
                paymentId: targetSessionId,
                subject: `[LATE PAYMENT DETECTED] Order #${targetOrderId}`,
                status: TicketStatus.OPEN,
                initialMessage: {
                  senderType: SenderType.ADMIN,
                  senderId: targetMerchantId,
                  message: `A delayed payment observation of ${targetAmountPaise / 100n} INR was detected after session ${targetSessionId} ended with status ${sessionStatus}. Flagged for manual merchant reconciliation.`
                }
              });
            }
            this.eventEmitter.emit('PAYMENT.LATE_DETECTED', {
              paymentId: targetSessionId,
              orderId: targetOrderId,
              merchantId: targetMerchantId,
              amountPaise: targetAmountPaise,
              observationId: targetObsId
            });
            return;
          }

          if (alreadyObserved) {
            return;
          }

          // 5 seconds elapsed without second source: finalize as Level 1
          const finalResult = this.sessionRepo.recordVerificationSource(
            targetSessionId,
            targetSource,
            targetObsId,
            { finalizeSuccess: true }
          );

          if (this.auditRepo) {
            this.auditRepo.log({
              merchantId: targetMerchantId,
              entityType: 'PAYMENT_SESSION',
              entityId: targetSessionId,
              action: 'PAYMENT_ATTRIBUTED_SUCCESS_L1',
              actorType: 'SYSTEM',
              details: {
                observationId: targetObsId,
                source: targetSource,
                verificationLevel: finalResult.level,
                verificationTag: finalResult.tag
              }
            });
          }

          this.eventEmitter.emit('PAYMENT.OBSERVED_SUCCESS', {
            paymentId: targetSessionId,
            orderId: targetOrderId,
            merchantId: targetMerchantId,
            amountPaise: targetAmountPaise,
            observationId: targetObsId,
            verificationLevel: finalResult.level,
            verificationTag: finalResult.tag,
            sources: finalResult.sources
          });
        }, this.gracePeriodMs);

        if (graceTimer.unref) graceTimer.unref();
        this.pendingGraceTimers.set(targetSessionId, graceTimer);

        return {
          attributed: true,
          duplicate: false,
          lateMatch: false,
          wasActive,
          paymentSessionId: currentSession.id,
          observationId: savedObs.id,
          outcomeStatus: 'VERIFYING',
          verificationLevel: 1,
          verificationTag: verifyResult.tag,
          verificationSources: verifyResult.sources
        };
      }
    }

    // Check if observation confirms a recently successful session on this receiving account (within 60s)
    // Upgrades verification level (e.g. from Level 1 -> Level 2 -> Level 3)
    const sixtySecsAgo = new Date(Date.now() - 60000).toISOString();
    const recentSuccessSession = this.sessionRepo.db.queryOne(`
      SELECT * FROM payment_sessions
      WHERE receiving_account_id = ? AND status IN ('SUCCESS', 'OBSERVED_SUCCESS')
        AND amount_paise = ? AND completed_at >= ?
      ORDER BY completed_at DESC LIMIT 1
    `, [normalizedObs.receivingAccountId, Number(normalizedObs.amountPaise), sixtySecsAgo]);

    if (recentSuccessSession) {
      // Check if this session's attributed observation had a UTR
      const existingObs = recentSuccessSession.attributed_observation_id
        ? this.obsRepo.findById(recentSuccessSession.attributed_observation_id)
        : null;

      // If both have UTRs and they do NOT match, this is NOT the same transaction!
      const isUtrConflict = normalizedObs.bankReferenceNumber &&
        existingObs?.bankReferenceNumber &&
        normalizedObs.bankReferenceNumber !== existingObs.bankReferenceNumber;

      if (isUtrConflict) {
        if (this.auditRepo) {
          this.auditRepo.log({
            merchantId: recentSuccessSession.merchant_id,
            entityType: 'PAYMENT_SESSION',
            entityId: recentSuccessSession.id,
            action: 'DUPLICATE_PAYMENT_UTR_CONFLICT',
            actorType: 'SYSTEM',
            details: {
              observationId: savedObs.id,
              existingUtr: existingObs?.bankReferenceNumber,
              newUtr: normalizedObs.bankReferenceNumber,
              amountPaise: normalizedObs.amountPaise.toString()
            }
          });
        }
        if (this.ticketRepo && recentSuccessSession.customer_id) {
          this.ticketRepo.createTicket({
            merchantId: recentSuccessSession.merchant_id,
            customerId: recentSuccessSession.customer_id,
            paymentId: recentSuccessSession.id,
            subject: `[DUPLICATE PAYMENT DETECTED] Order #${recentSuccessSession.order_id}`,
            status: TicketStatus.OPEN,
            initialMessage: {
              senderType: SenderType.ADMIN,
              senderId: recentSuccessSession.merchant_id,
              message: `A duplicate payment of ${normalizedObs.amountPaise / 100n} INR with reference ${normalizedObs.bankReferenceNumber} was received within 60s of completed order #${recentSuccessSession.order_id} (reference ${existingObs?.bankReferenceNumber || 'N/A'}). Flagged for merchant refund reconciliation.`
            }
          });
        }
        this.eventEmitter.emit('PAYMENT.DUPLICATE_DETECTED', {
          paymentId: recentSuccessSession.id,
          orderId: recentSuccessSession.order_id,
          merchantId: recentSuccessSession.merchant_id,
          observationId: savedObs.id,
          existingUtr: existingObs?.bankReferenceNumber,
          newUtr: normalizedObs.bankReferenceNumber,
          amountPaise: normalizedObs.amountPaise
        });
      }

      const sessionSlotStart = recentSuccessSession.slot_acquired_at
        ? new Date(new Date(recentSuccessSession.slot_acquired_at).getTime() - 30000)
        : new Date(new Date(recentSuccessSession.created_at).getTime() - 30000);
      const sessionCompleted = recentSuccessSession.completed_at
        ? new Date(new Date(recentSuccessSession.completed_at).getTime() + 30000)
        : new Date();

      // Temporal check: observation must have been observed during this session's window
      if (!isUtrConflict && normalizedObs.observedAt >= sessionSlotStart && normalizedObs.observedAt <= sessionCompleted) {
        const mappedRecentSession = this.sessionRepo.mapRow(recentSuccessSession);
        if (
          Array.isArray(mappedRecentSession.verificationSources) &&
          mappedRecentSession.verificationSources.some(s => getChannelFamily(s) === incomingFamily)
        ) {
          this.obsRepo.markDuplicate(savedObs.id);
          return {
            attributed: false,
            duplicate: true,
            lateMatch: false,
            paymentSessionId: recentSuccessSession.id,
            observationId: savedObs.id,
            outcomeStatus: ObservationAttributionStatus.DUPLICATE_IGNORED
          };
        }

        const verifyResult = this.sessionRepo.recordVerificationSource(
          recentSuccessSession.id,
          normalizedObs.source,
          savedObs.id
        );

        this.obsRepo.markAttributed(savedObs.id, recentSuccessSession.id);

        if (this.auditRepo) {
          this.auditRepo.log({
            merchantId: recentSuccessSession.merchant_id,
            entityType: 'PAYMENT_SESSION',
            entityId: recentSuccessSession.id,
            action: 'PAYMENT_VERIFICATION_UPGRADED',
            actorType: 'SYSTEM',
            details: {
              observationId: savedObs.id,
              source: normalizedObs.source,
              amountPaise: normalizedObs.amountPaise.toString(),
              verificationLevel: verifyResult.level,
              verificationTag: verifyResult.tag,
              sources: verifyResult.sources
            }
          });
        }

        this.eventEmitter.emit('PAYMENT.VERIFICATION_UPGRADED', {
          paymentId: recentSuccessSession.id,
          orderId: recentSuccessSession.order_id,
          verificationLevel: verifyResult.level,
          verificationTag: verifyResult.tag,
          sources: verifyResult.sources
        });

        return {
          attributed: true,
          duplicate: false,
          lateMatch: false,
          paymentSessionId: recentSuccessSession.id,
          observationId: savedObs.id,
          outcomeStatus: PaymentStatus.OBSERVED_SUCCESS,
          verificationLevel: verifyResult.level,
          verificationTag: verifyResult.tag,
          verificationSources: verifyResult.sources
        };
      }
    }

    // Tier 3: Late Observation Handling
    // Check if observation matches a recently expired or failed session on this receiving account (< 30 mins)
    const thirtyMinutesAgo = new Date(Date.now() - 30 * 60 * 1000);
    const recentExpired = this.sessionRepo.findRecentlyExpiredOrFailed(
      normalizedObs.receivingAccountId,
      thirtyMinutesAgo
    );

    const lateMatches = recentExpired.filter(s => s.amountPaise === normalizedObs.amountPaise);
    if (lateMatches.length > 1) {
      return this.holdAmbiguous(savedObs, lateMatches, 'MULTIPLE_LATE_AMOUNT_MATCHES');
    }
    const lateMatchedSession = lateMatches[0];

    if (lateMatchedSession) {
      // Mark observation as LATE_UNMATCHED and preserve candidate session ID in raw_payload
      this.obsRepo.markLateUnmatched(savedObs.id, lateMatchedSession.id);

      if (this.auditRepo) {
        this.auditRepo.log({
          merchantId: lateMatchedSession.merchantId,
          entityType: 'PAYMENT_SESSION',
          entityId: lateMatchedSession.id,
          action: 'LATE_OBSERVATION_DETECTED',
          actorType: 'SYSTEM',
          details: {
            observationId: savedObs.id,
            source: normalizedObs.source,
            amountPaise: normalizedObs.amountPaise.toString(),
            sessionStatus: lateMatchedSession.status
          }
        });
      }

      // Automatically create a high-priority reconciliation support ticket if customer exists
      if (this.ticketRepo && lateMatchedSession.customerId) {
        this.ticketRepo.createTicket({
          merchantId: lateMatchedSession.merchantId,
          customerId: lateMatchedSession.customerId,
          paymentId: lateMatchedSession.id,
          subject: `[LATE PAYMENT DETECTED] Order #${lateMatchedSession.orderId}`,
          status: TicketStatus.OPEN,
          initialMessage: {
            senderType: SenderType.ADMIN,
            senderId: lateMatchedSession.merchantId,
            message: `A delayed payment observation of ${normalizedObs.amountPaise / 100n} INR was detected after session ${lateMatchedSession.id} ended with status ${lateMatchedSession.status}. Flagged for manual merchant reconciliation.`
          }
        });
      }

      // Emit LATE_DETECTED event
      this.eventEmitter.emit('PAYMENT.LATE_DETECTED', {
        paymentId: lateMatchedSession.id,
        orderId: lateMatchedSession.orderId,
        merchantId: lateMatchedSession.merchantId,
        amountPaise: normalizedObs.amountPaise,
        observationId: savedObs.id
      });

      return {
        attributed: false,
        duplicate: false,
        lateMatch: true,
        paymentSessionId: lateMatchedSession.id,
        observationId: savedObs.id,
        outcomeStatus: ObservationAttributionStatus.LATE_UNMATCHED
      };
    }

    // Unattributed observation
    return {
      attributed: false,
      duplicate: false,
      lateMatch: false,
      observationId: savedObs.id,
      outcomeStatus: ObservationAttributionStatus.UNATTRIBUTED
    };
  }

  /**
   * Re-evaluates unmatched (UNATTRIBUTED / LATE_UNMATCHED) observations for a receiving account
   * against eligible sessions to surface late-payment correlation or manual review holds.
   * Never auto-confirms an immutable terminal session (EXPIRED/FAILED/CANCELLED).
   * @param {string} receivingAccountId
   */
  reconcileUnmatchedObservations(receivingAccountId) {
    const unattributed = this.obsRepo.findUnattributed(receivingAccountId);
    const results = [];

    for (const obs of unattributed) {
      // 1. Check live sessions with matching amount
      const liveRows = this.sessionRepo.db.query(`
        SELECT * FROM payment_sessions
        WHERE receiving_account_id = ? AND status IN ('ACTIVE', 'PROCESSING') AND amount_paise = ?
      `, [receivingAccountId, Number(obs.amountPaise)]);

      if (liveRows.length > 1) {
        const held = this.holdAmbiguous(
          obs,
          liveRows.map(r => this.sessionRepo.mapRow(r)),
          'MULTIPLE_LIVE_AMOUNT_MATCHES'
        );
        results.push({ observationId: obs.id, action: 'HELD_AMBIGUOUS', ...held });
        continue;
      }

      // 2. Check recently expired or failed sessions (< 30 mins)
      const thirtyMinutesAgo = new Date(Date.now() - 30 * 60 * 1000);
      const recentExpired = this.sessionRepo.findRecentlyExpiredOrFailed(receivingAccountId, thirtyMinutesAgo);
      const lateMatches = recentExpired.filter(s => s.amountPaise === obs.amountPaise);

      if (lateMatches.length > 1) {
        const held = this.holdAmbiguous(obs, lateMatches, 'MULTIPLE_LATE_AMOUNT_MATCHES');
        results.push({ observationId: obs.id, action: 'HELD_AMBIGUOUS', ...held });
        continue;
      }

      if (lateMatches.length === 1) {
        const lateSession = lateMatches[0];
        this.obsRepo.markLateUnmatched(obs.id, lateSession.id);
        if (this.auditRepo) {
          this.auditRepo.log({
            merchantId: lateSession.merchantId,
            entityType: 'PAYMENT_SESSION',
            entityId: lateSession.id,
            action: 'LATE_OBSERVATION_RECONCILED_TO_TICKET',
            actorType: 'SYSTEM',
            details: {
              observationId: obs.id,
              source: obs.source,
              amountPaise: obs.amountPaise.toString(),
              sessionStatus: lateSession.status
            }
          });
        }
        if (this.ticketRepo && lateSession.customerId) {
          this.ticketRepo.createTicket({
            merchantId: lateSession.merchantId,
            customerId: lateSession.customerId,
            paymentId: lateSession.id,
            subject: `[LATE PAYMENT DETECTED] Order #${lateSession.orderId}`,
            status: TicketStatus.OPEN,
            initialMessage: {
              senderType: SenderType.ADMIN,
              senderId: lateSession.merchantId,
              message: `A delayed payment observation of ${obs.amountPaise / 100n} INR was matched during unmatched reconciliation after session ${lateSession.id} ended with status ${lateSession.status}.`
            }
          });
        }
        this.eventEmitter.emit('PAYMENT.LATE_DETECTED', {
          paymentId: lateSession.id,
          orderId: lateSession.orderId,
          merchantId: lateSession.merchantId,
          amountPaise: obs.amountPaise,
          observationId: obs.id
        });
        results.push({
          observationId: obs.id,
          action: 'MARKED_LATE_UNMATCHED',
          paymentSessionId: lateSession.id,
          outcomeStatus: ObservationAttributionStatus.LATE_UNMATCHED
        });
        continue;
      }

      results.push({
        observationId: obs.id,
        action: 'REMAINS_UNATTRIBUTED',
        outcomeStatus: ObservationAttributionStatus.UNATTRIBUTED
      });
    }

    return {
      processed: unattributed.length,
      reconciledCount: results.filter(r => r.action !== 'REMAINS_UNATTRIBUTED').length,
      results
    };
  }
}