docs: adopt CTO dataset semantics

docs/DATA-FOUNDATION-SPEC.md

@@ -40,7 +40,7 @@ erDiagram
     MERCHANT ||--o{ MERCHANT_USER : authenticates_as
     MERCHANT ||--o{ PAYMENT_SESSION : receives
     TERMINAL ||--o{ PAYMENT_SESSION : handles
-    PAYMENT_SESSION ||--|{ PAYMENT_ATTEMPT : contains
+    PAYMENT_SESSION ||--o{ PAYMENT_ATTEMPT : contains
     IMPORT_RUN ||--o{ PAYMENT_SESSION : introduced_by
     IMPORT_RUN ||--o{ PAYMENT_ATTEMPT : introduced_by
     IMPORT_RUN ||--o{ IMPORT_ISSUE : reports
@@ -84,7 +84,7 @@ erDiagram
     PAYMENT_ATTEMPT {
       bigint id PK
       bigint payment_session_id FK
-      int try_seq
+      int try_seq "positive"
       text try_status
       text switch_response_code
       text psp_code
@@ -139,6 +139,7 @@ This contract applies only to the one-time challenge-data bootstrap and explicit
 3. Validate headers and supported schema version before database writes.
 4. Stream/decompress and load into a staging boundary using bounded memory and PostgreSQL bulk-loading facilities.
 5. Validate uniqueness of `(session_key, try_seq)`, referential consistency, parseability, null rates, ranges, timestamp ordering, and merchant/terminal/category relationships.
+   A source `(try_seq = 0, try_status = 'NoAttempt')` record creates the session but no `payment_attempt` row; all normalized attempts require `try_seq >= 1`.
 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 reporting-date range, then initialize merchant/cohort analytics revisions. Do not eagerly calculate dashboard results; first relevant access starts lazy section jobs.
@@ -178,7 +179,7 @@ This contract applies only to the one-time challenge-data bootstrap and explicit
 - Re-running the same archive is safe and does not duplicate business rows.
 - Source row count and accepted/rejected counts reconcile exactly.
 - Every attempt maps to one session, terminal, merchant, category, and import run according to validated source relationships.
-- `(source_session_key, try_seq)` is unique.
+- Source `(session_key, try_seq)` records are unique. Normalized attempts require `try_seq >= 1` and are unique by `(payment_session_id, try_seq)`; a `NoAttempt` marker produces a session with zero attempts.
 - Missing values remain missing rather than being silently replaced with factual-looking defaults.
 - The import report captures checksum, importer revision, timings, counts, validation failures, and quality metrics.
 - Raw data and database state remain ignored by Git; code, schema, rules, docs, and safe templates are tracked.
@@ -211,7 +212,7 @@ Resolved: use Ent for application persistence/modeling, pgx/PostgreSQL `COPY` fo
 
 Resolved: interpret timezone-naive source timestamps as `Asia/Tehran`, normalize canonical timestamps to UTC, expose ISO-8601 timestamps through APIs, and retain the immutable source/import provenance needed to reproduce the conversion. See ADR 0004.
 
-Resolved: retain `payer_card_key` unchanged as a restricted, merchant-scoped opaque source token for internal repeat-payer analytics. Do not HMAC it, expose it, log it, export it, or send it to AI providers. Its upstream semantics remain unverified. See ADR 0005.
+Resolved: retain `payer_card_key` unchanged as a restricted pseudonymous card identifier whose equality is authoritative only within one merchant. It may support covered repeat-card analytics but cannot identify a person or link merchants. Do not HMAC it, expose it, log it, export it, or send it to AI providers. See ADR 0005.
 
 Resolved: peer benchmarks use other merchants in the active merchant's category for the same selected period, excluding the active merchant. Each peer contributes one independently calculated value to a merchant-weighted median, and the response includes a direction-aware merchant performance percentile. This represents a typical peer despite the dataset's extreme merchant-volume skew. At least 10 other merchants and 1,000 combined peer sessions are required; otherwise the benchmark is suppressed while the merchant's own analytics remain available. See ADR 0006.