docs: record production analytics decisions

docs/DATA-FOUNDATION-SPEC.md

@@ -165,6 +165,15 @@ This contract applies only to the one-time challenge-data bootstrap and explicit
 8. Populate and validate the approved calendar range, then build affected analytics projections idempotently after source promotion. Projection failure must not make an incomplete projection appear fresh.
 9. Never schedule, watch, or poll for another CSV. After bootstrap, production source-row creation is an external ZarinPal responsibility. Analytics freshness over those future rows has a separate read/refresh contract.
 
+## Production write and analytics freshness contract
+
+- ZarinPal is the authoritative writer of future production payment sessions/attempts in the normalized PostgreSQL schema.
+- This project owns the normalized schema contract, migrations, read models, and analytics; it does not recreate ZarinPal's payment-write workflow.
+- Live rows are distinguishable from bootstrap rows and include stable creation/update metadata for incremental analytics. Bootstrap-only import provenance is not forged for live rows.
+- Incremental analytics projections refresh within 15 minutes of an eligible source change.
+- A nightly idempotent reconciliation checks/recomputes the approved authoritative window and detects drift.
+- Failed refreshes never advance the API/UI freshness watermark.
+
 ## Synthetic merchant/account rules
 
 - Create exactly one initial demo user per distinct merchant unless the later identity spec explicitly changes cardinality.
@@ -186,6 +195,8 @@ This contract applies only to the one-time challenge-data bootstrap and explicit
 - Daily, Jalali-month, Persian-season, and approved calendar-event analytics reconcile to deterministic source queries for additive metrics.
 - Rates are recomputed from their numerator and denominator over the requested period rather than averaged from daily percentages.
 - Non-additive metrics such as unique payer-token counts are never produced by summing daily distinct counts.
+- Incremental projections become queryable within 15 minutes of eligible live writes, and nightly reconciliation detects/corrects drift without double counting.
+- Calendar rows covering the reporting period reconcile with reviewed official snapshots and record provenance/checksums.
 
 ## Approval gates / unresolved decisions
 
@@ -203,4 +214,10 @@ Resolved: peer benchmarks exclude the active merchant and require at least 10 ot
 
 Resolved: use normalized source-of-truth entities plus versioned calendar/event dimensions, rebuildable daily base summaries, and metric-specific projections for non-additive or measured high-cost period analytics. Monthly, Persian-season, and holiday results use explicit calendar definitions. Keep fact tables unpartitioned initially and introduce partitioning only from measured need. See ADR 0007.
 
+Resolved: ZarinPal writes future production rows directly to the normalized tables. Our backend owns schema/read/analytics contracts, refreshes projections within 15 minutes, and performs nightly reconciliation. CSV ingestion remains one-time only. See ADR 0008.
+
+Resolved: commit reviewed yearly Iranian calendar snapshots sourced from the University of Tehran Institute of Geophysics Calendar Center; do not call a calendar API at runtime. Official holidays and analytical campaign/event windows remain distinguishable and versioned. See ADR 0009.
+
+Resolved: only source session status `Verified` is a definitely successful payment. Keep `Paid` separate until an authoritative ZarinPal definition changes the metric catalogue. See `METRIC-CATALOGUE.md`.
+
 No broad architecture approval gates remain for this capability. Physical columns, indexes, constraints, calendar source, projection shapes, and migration details still require profiling evidence and acceptance in the implementation-ready revision of this spec.