docs: define source timestamp normalization

docs/decisions/0004-source-timezone-normalization.md

@@ -0,0 +1,25 @@
+# ADR 0004: Interpret source timestamps as Asia/Tehran and normalize to UTC
+
+- Status: Accepted
+- Date: 2026-08-20
+
+## Context
+
+The challenge archive contains timezone-naive timestamp strings such as `2026-01-02 11:52:56`. It supplies no offset or timezone column. Analytics depend on consistent daily/hourly windows, retry durations, settlement timing, and period comparisons, so leaving interpretation implicit would make results environment-dependent.
+
+## Decision
+
+Interpret every valid timezone-naive source timestamp as local civil time in the IANA `Asia/Tehran` zone. Convert canonical persisted timestamps to UTC-backed PostgreSQL `timestamptz` values. API contracts expose ISO-8601 timestamps with an explicit UTC offset (`Z`); merchant-facing presentation converts them to `Asia/Tehran` and uses the Jalali calendar.
+
+The importer records the assumed zone and timezone-data/runtime version in its manifest. The raw archive remains immutable operational input identified by checksum, preserving the original textual values and allowing a new import version if authoritative source metadata later contradicts the assumption. A changed interpretation must never silently update an existing completed import.
+
+Missing or invalid timestamp values remain missing/rejected according to the import validation policy; they are not replaced with import time. Timestamp-order anomalies are reported as data-quality evidence and are not automatically “corrected.”
+
+## Consequences
+
+- Day/hour analytics have one documented merchant-relevant timezone.
+- Database comparisons and API interchange use explicit instants rather than server-local time.
+- The assumption is traceable and reversible through source checksum, immutable input, manifest metadata, and importer revision.
+- Tests must cover conversion around relevant timezone-rule boundaries and ensure host/container timezone does not change results.
+- Calendar conversion is a presentation concern; backend period boundaries are calculated from explicit `Asia/Tehran` local ranges and converted to UTC for querying.
+