Discount Eligibility Engines

Discount eligibility engines operate as the deterministic decision layer within Fare Rule Validation & Calculation Engines, translating policy mandates into auditable fare adjustments at the point of validation. For transit operations teams and revenue analysts, these systems must reconcile static entitlement registries with dynamic rider behavior while preserving fare equity and revenue integrity. Mobility tech developers and Python automation builders require predictable, idempotent execution paths that scale across high-throughput AFC streams without introducing latency at fare gates or mobile validators.

Pipeline Architecture & Memory-Efficient Ingestion

Real-world AFC architectures frequently deliver fragmented payloads: incomplete rider profiles, delayed third-party verification callbacks, or GTFS-RT service alerts that temporarily suspend fare capping. A resilient eligibility pipeline applies strict schema validation upstream, normalizes timestamp precision to the millisecond, and flags anomalous sequences before they enter the calculation graph.

To maintain memory efficiency under sustained tap volumes, ingestion layers should process events as bounded generators rather than materializing full datasets. Schema validation must reject malformed payloads at the edge, preventing cascading failures in downstream state machines. Python builders typically leverage Pydantic v2 for fast, compiled validation, combined with decimal.Decimal to eliminate floating-point drift in monetary calculations. Every tap event is hashed into an idempotency key, ensuring that network retries or backfilled logs never trigger duplicate discount applications.

Stateful Evaluation & Fallback Chains

Eligibility evaluation rarely executes in isolation. When a rider taps within a defined Transfer Window Logic, the engine must determine whether a discounted fare applies to the subsequent leg or if a transfer exemption supersedes the base discount. This requires synchronized state tracking across vehicles, modes, and fare media.

Concurrent validation introduces race conditions: two validators reading the same rider session simultaneously may both apply a transfer discount. Production engines resolve this via distributed locks or optimistic concurrency control, falling back to a deterministic tie-breaker based on tap timestamp and validator ID. When primary discount predicates fail to resolve—due to missing entitlement data, expired verification tokens, or conflicting policy flags—the engine routes execution through fallback calculation chains. These chains apply conservative defaults (typically base fare), log the deviation with structured metadata, and queue the transaction for manual reconciliation rather than blocking validation or silently defaulting to full fare.

The eligibility decision flow below mirrors the evaluator’s predicate ordering, where each unresolved check routes to reconciliation rather than blocking the tap:

Threshold Management & Policy Versioning

Policy shifts, regulatory updates, and subsidy program renewals demand rigorous change management. Rule versioning and rollback strategies ensure that every discount matrix, eligibility criterion, and exception handler is tracked as an immutable artifact. When a new fare relief mandate takes effect, the engine loads the updated configuration atomically, preserving active sessions under the previous version until they naturally expire.

Threshold Tuning Frameworks enable revenue teams to adjust income-based, age-based, or frequency-based discount triggers without redeploying core calculation services. By externalizing thresholds to configuration stores or feature flags, operators can pilot fare relief programs while maintaining strict audit trails. Demographic-specific programs, such as those detailed in Automating Senior and Student Fare Validation Rules, require periodic entitlement refreshes. The engine must gracefully handle expired credentials by routing riders to a grace-period evaluation path before enforcing full fare, minimizing customer friction while protecting subsidy compliance.

Production-Grade Python Implementation

The following implementation demonstrates a stateless, memory-bounded eligibility evaluator with explicit error handling, deterministic reconciliation routing, and idempotent execution guarantees.

import logging
import hashlib
from decimal import Decimal, ROUND_HALF_UP
from datetime import datetime, timedelta, timezone
from typing import Optional, Dict, Any
from functools import lru_cache
from pydantic import BaseModel, Field, ValidationError
from enum import Enum

logger = logging.getLogger(__name__)

class TapStatus(str, Enum):
    ELIGIBLE = "eligible"
    PARTIAL_FALLBACK = "partial_fallback"
    RECONCILIATION_REQUIRED = "reconciliation_required"
    REJECTED = "rejected"

class TapEvent(BaseModel):
    tap_id: str
    rider_id: str
    timestamp: datetime
    fare_media_type: str
    route_id: Optional[str] = None
    validator_id: str
    raw_payload: Dict[str, Any] = Field(default_factory=dict)

class EntitlementProfile(BaseModel):
    rider_id: str
    program_code: Optional[str] = None
    verification_expiry: Optional[datetime] = None
    discount_pct: Decimal = Decimal("0.00")

class ReconciliationRecord(BaseModel):
    tap_id: str
    status: TapStatus
    applied_fare: Decimal
    reason: str
    audit_hash: str
    timestamp: datetime

# Bounded in-memory cache for recent tap states (memory-efficient)
@lru_cache(maxsize=50_000)
def get_recent_transfer_state(rider_id: str, validator_id: str) -> Optional[datetime]:
    """Simulates bounded state lookup. In production, replace with Redis/DB with TTL."""
    return None

def generate_idempotency_key(tap: TapEvent) -> str:
    return hashlib.sha256(f"{tap.tap_id}:{tap.rider_id}:{tap.timestamp.isoformat()}".encode()).hexdigest()

def evaluate_discount(
    tap: TapEvent,
    entitlement: Optional[EntitlementProfile],
    base_fare: Decimal,
    transfer_window_minutes: int = 90
) -> Dict[str, Any]:
    """
    Deterministic eligibility evaluation with explicit fallback routing.
    """
    audit_log = []
    applied_fare = base_fare
    status = TapStatus.REJECTED

    try:
        # 1. Validate base fare precision
        if base_fare <= Decimal("0.00"):
            raise ValueError("Base fare must be positive")

        # 2. Check entitlement existence & expiry
        if not entitlement:
            status = TapStatus.RECONCILIATION_REQUIRED
            audit_log.append("Missing entitlement profile")
            applied_fare = base_fare
            return _build_result(tap, status, applied_fare, audit_log)

        if entitlement.verification_expiry and entitlement.verification_expiry < tap.timestamp:
            status = TapStatus.RECONCILIATION_REQUIRED
            audit_log.append("Expired verification token")
            applied_fare = base_fare
            return _build_result(tap, status, applied_fare, audit_log)

        # 3. Transfer window override check
        last_transfer = get_recent_transfer_state(tap.rider_id, tap.validator_id)
        if last_transfer and (tap.timestamp - last_transfer) < timedelta(minutes=transfer_window_minutes):
            status = TapStatus.ELIGIBLE
            applied_fare = Decimal("0.00")
            audit_log.append("Transfer exemption applied")
            return _build_result(tap, status, applied_fare, audit_log)

        # 4. Apply program discount
        discount_amount = base_fare * (entitlement.discount_pct / Decimal("100"))
        applied_fare = (base_fare - discount_amount).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)
        status = TapStatus.ELIGIBLE
        audit_log.append(f"Discount {entitlement.discount_pct}% applied")

    except ValidationError as ve:
        logger.error(f"Schema validation failed for tap {tap.tap_id}: {ve}")
        status = TapStatus.REJECTED
        audit_log.append("Invalid payload schema")
    except Exception as e:
        logger.exception(f"Unexpected evaluation error for tap {tap.tap_id}")
        status = TapStatus.RECONCILIATION_REQUIRED
        audit_log.append(f"Runtime exception: {str(e)}")
        applied_fare = base_fare  # Conservative default

    return _build_result(tap, status, applied_fare, audit_log)

def _build_result(tap: TapEvent, status: TapStatus, fare: Decimal, audit_log: list) -> Dict[str, Any]:
    reason = "; ".join(audit_log)
    audit_hash = hashlib.md5(f"{tap.tap_id}{status}{fare}{reason}".encode()).hexdigest()
    return {
        "tap_id": tap.tap_id,
        "rider_id": tap.rider_id,
        "status": status,
        "applied_fare": fare,
        "audit_hash": audit_hash,
        "reason": reason,
        "timestamp": datetime.now(timezone.utc)
    }

Scalable Reconciliation & Operational Guardrails

The reconciliation layer must operate asynchronously to avoid blocking fare gate validation. Transactions flagged as RECONCILIATION_REQUIRED are serialized to a dead-letter queue with structured metadata, including the original payload, evaluation trace, and deterministic audit hash. Revenue analysts consume this queue via batch reconciliation jobs that cross-reference delayed subsidy callbacks, correct entitlement mismatches, and issue retroactive fare adjustments.

The lifecycle below shows how a tap moves between evaluation states, with reconciliation feeding corrected entitlements back into a re-evaluation:

Idempotency is enforced at every stage. Backfilling missing entitlement records or reprocessing corrected AFC logs uses the same tap_id + timestamp hash to guarantee exactly-once execution. Memory pressure is managed through bounded caches, TTL-based session stores, and streaming aggregation for threshold counters. When deploying new discount matrices, canary releases route a percentage of traffic through the updated policy while maintaining parallel audit trails, enabling instant rollback without state corruption.

By decoupling validation, evaluation, and reconciliation, transit operators achieve sub-50ms gate latency, zero revenue leakage from duplicate discounts, and fully auditable compliance trails. Python orchestration layers that prioritize deterministic hashing, explicit fallback routing, and memory-bounded state tracking scale predictably across multi-agency AFC deployments.