docs: approve analytics presentation defaults

docs/ANALYTICS-SPEC.md

@@ -55,11 +55,12 @@ Every section uses a versioned typed contract and has independent `queued`, `cal
 
 ## Metric and period contract
 
-- `METRIC-CATALOGUE.md` version `0.3.0` is canonical for formulas, units, grains, missing-data behavior, and peer direction.
+- `METRIC-CATALOGUE.md` version `0.4.0` is canonical for formulas, units, grains, missing-data behavior, and peer direction.
 - `Paid` and `Verified` both mean bank payment succeeded; only `Verified` is finalized. Never label `Paid` as failure.
 - Amount and fee calculations count each eligible payment session once. Attempt rows cannot multiply session values.
 - Rates are calculated from summed numerator and denominator components for the selected period, never averaged from daily percentages.
 - Timing percentiles exclude null values and expose sample size and non-null coverage; missing time never becomes zero.
+- `NoAttempt` markers create zero-attempt sessions and never count as attempts or retries. `InBank` is an observed attempt stage, not proof of rejection.
 - Every result states the exact Tehran-local half-open period, Jalali label, unit, sample/denominator, source revision, metric-definition version, and calculation timestamp.
 - Approved period types are one Tehran-local day, one Saturday–Friday week, one Jalali month, or one Persian season. Holiday/event dimensions do not exist in the MVP contract.
 
@@ -127,6 +128,7 @@ Every section uses a versioned typed contract and has independent `queued`, `cal
 - Timeouts, transient retry limits/backoff, failed-section isolation, manual retry, rate limits, heartbeat, replay, and snapshot fallback behave as specified.
 - Peer results exclude the active merchant, use equal merchant weighting, obey both suppression thresholds, and never expose individual peers.
 - Tenant-bound drill-downs reconcile to aggregates and cannot expose another merchant through parameter manipulation.
+- Read-only drill-downs cover unverified-paid, failed, and retried sessions. Failed-session filters may distinguish zero-attempt and reached-bank stages without exposing payer tokens or claiming undocumented causes.
 - No raw payer token, credential, cross-tenant row, or AvalAI secret enters results, logs, cache payloads, or browser data.
 
 ## Boundaries
@@ -143,11 +145,11 @@ Every section uses a versioned typed contract and has independent `queued`, `cal
 - Peer comparison uses same-category merchant-weighted medians and direction-aware percentiles with the approved suppression threshold.
 - Payment lifecycle, retry, timing, and real-fee definitions follow `METRIC-CATALOGUE.md` and ADR 0013.
 - Asynq `v0.26.0` is pinned and acknowledged as pre-1.0; jobs have bounded concurrency, timeouts, rate limits, and exponential-backoff retries.
+- Default first view is the latest complete Jalali month containing source data, avoiding an empty current month in the static demo.
+- Compare with the immediately previous equivalent complete period. If it is empty or unavailable, return an explicit unavailable comparison rather than silently substituting another baseline.
+- Overview priority is bank-paid amount, bank-paid session count, payment success rate, then verification completion. Retry, timing, and fee analysis follow below.
+- MVP read-only drill-downs cover unverified-paid, failed, and retried sessions; payer tokens and peer-level rows are excluded.
 
 ## Open product decisions
 
-- Default reporting period on first dashboard access, especially when the current period has no source data
-- Default previous-period comparison behavior when an equivalent baseline is empty or incomplete
-- Exact overview KPI order and which deterministic insight appears first
-- Which tenant-scoped drill-down tables are MVP-visible versus definition-only
 - Deterministic threshold/severity rules for surfacing actionable findings

docs/METRIC-CATALOGUE.md

@@ -1,7 +1,7 @@
 # Analytics Metric Catalogue
 
 - Status: Draft — listed definitions approved
-- Version: 0.3.0
+- Version: 0.4.0
 - Last updated: 2026-08-20
 
 Every merchant-facing number identifies its grain, formula, source fields, filters, Tehran-local period, unit, missing-data behavior, trace path, and definition version.
@@ -61,6 +61,14 @@ Every merchant-facing number identifies its grain, formula, source fields, filte
 - Grain/unit: distinct sessions
 - Traceability: ordered merchant-scoped attempt history; never depend on CSV row order
 
+## Payment-stage diagnostics
+
+- `no_attempt_sessions`: count sessions with zero normalized payment attempts. During challenge bootstrap this corresponds to the source marker `try_seq = 0 AND try_status = 'NoAttempt'`; the marker itself is not an attempt.
+- `reached_bank_sessions`: count distinct sessions containing at least one attempt with `try_status IN ('InBank', 'Paid', 'Verified', 'Reversed')`.
+- `in_bank_without_result_sessions`: count sessions whose latest positive-sequence attempt is `InBank` and which have no later `Paid`, `Verified`, `Failed`, or `Reversed` attempt.
+- `failed_sessions`: count sessions with final `session_status = 'Failed'`; drill-down may distinguish zero-attempt, reached-bank, and other observable stages without inventing undocumented failure causes.
+- Grain/unit: distinct payment sessions; attempt-stage counts must deduplicate by session when presented as sessions.
+
 ## Processing time
 
 - Report median (p50) and p95 separately for `init_time_ms` and `verify_time_ms`
@@ -83,6 +91,7 @@ Every merchant-facing number identifies its grain, formula, source fields, filte
 - Zero, undefined, missing, suppressed peer value, and calculation failure remain distinct states.
 - `Paid` and `Verified` are both bank-payment successes, but only `Verified` is finalized.
 - `Reversed` is not in the success numerator; display it separately when non-zero.
+- `NoAttempt` is a source session marker, not a failed payment attempt. `InBank` means the user reached a bank gateway but no later outcome was recorded for that attempt; do not call it a bank rejection.
 
 ## Peer comparison