docs: define bootstrap and schema proposal

docs/DATA-FOUNDATION-SPEC.md

@@ -6,11 +6,12 @@
 
 ## Objective
 
-Repeatably ingest the supplied payment-attempt archive into PostgreSQL, preserve provenance and data quality evidence, model business entities separately, and provide a trustworthy base for authentication and deterministic analytics.
+Perform a one-time, repeatable bootstrap of the supplied payment-attempt archive into PostgreSQL, preserve provenance and data quality evidence, model business entities separately, and provide a trustworthy base for authentication and deterministic analytics. Future production payment records are written to PostgreSQL by ZarinPal under an external upstream contract; recurring source ingestion is not owned by this project.
 
 ## In scope
 
 - Streamed `.csv.gz` ingestion from a local, Git-ignored input path
+- One-time administrative bootstrap/recovery execution; no ingestion scheduler or file watcher
 - Import runs, checksums, schema version, row counts, rejection/error reporting
 - Normalized merchant, category, terminal, payment-session, payment-attempt, and account/profile concepts
 - Versioned Gregorian/Jalali calendar dates and curated Iranian event/holiday periods
@@ -26,6 +27,7 @@ Repeatably ingest the supplied payment-attempt archive into PostgreSQL, preserve
 - Merchant-facing API endpoints
 - AI recommendations
 - Production backup mechanics (owned by platform operations)
+- Recurring CSV ingestion, polling, CDC, or ownership of ZarinPal's production payment-write path
 - Treating the challenge archive or local database as version-controlled source
 
 ## Proposed logical model (technology-neutral)
@@ -97,7 +99,7 @@ erDiagram
       timestamptz try_created_at
       timestamptz verified_at
       timestamptz settled_at
-      int expire_in
+      timestamptz expires_at
     }
     IMPORT_RUN {
       bigint id PK
@@ -151,6 +153,8 @@ This ERD is a logical baseline, not an approved physical schema. In particular,
 
 ## Import contract
 
+This contract applies only to the one-time challenge-data bootstrap and explicit recovery re-runs. It is not a periodic production pipeline.
+
 1. Accept an explicit path, defaulting locally to `data/incoming/challenge_data.csv.gz`.
 2. Calculate SHA-256 before import and identify an already completed import of the same schema/checksum.
 3. Validate headers and supported schema version before database writes.
@@ -158,7 +162,8 @@ This ERD is a logical baseline, not an approved physical schema. In particular,
 5. Validate uniqueness of `(session_key, try_seq)`, referential consistency, parseability, null rates, ranges, timestamp ordering, and merchant/terminal/category relationships.
 6. Promote accepted data transactionally or through a resumable, explicitly versioned workflow; a failed run cannot appear complete.
 7. Emit a machine-readable and human-readable import report. Do not log raw card keys or credentials.
-8. Populate and validate the approved calendar range, then rebuild affected analytics projections idempotently after source promotion. Projection failure must not make an incomplete projection appear fresh.
+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.
 
 ## Synthetic merchant/account rules