feat(interchain-indexer): Stats zero-count chain visibility setting (#1662)

* Added `StatsSettings`. Introducing `include_zero_chains`.

* Added ENV validation step into the implementation-plan workflow

* Update memory bank

* Code review issues

* Fix issues

Author: EvgenKor

interchain-indexer/.memory-bank/research/config-loading-and-validation.md

@@ -71,8 +71,10 @@ Settings                              (deny_unknown_fields)
   ├─ jaeger: JaegerSettings
   ├─ database: DatabaseSettings
   ├─ api: ApiSettings                         (deny_unknown_fields)
-  ├─ stats_backfill_on_start: bool
-  └─ stats_chains_recalculation_period_secs: u64
+  └─ stats: StatsSettings                     (deny_unknown_fields)
+       ├─ backfill_on_start: bool
+       ├─ chains_recalculation_period_secs: u64
+       └─ include_zero_chains: bool
 ```
 
 ### JSON Config Structs

interchain-indexer/.memory-bank/research/stats-projection.md

@@ -108,8 +108,9 @@ increments `crosschain_messages.stats_processed` for the counted rows.
 
 There is also a startup backfill path for historical rows:
 
-- when `stats_backfill_on_start = true`, server startup triggers a stats
-  backfill pass
+- when `stats.backfill_on_start = true` (env:
+  `INTERCHAIN_INDEXER__STATS__BACKFILL_ON_START=true`), server startup triggers
+  a stats backfill pass
 - the backfill scans canonical rows with `stats_processed = 0`
 - it applies the same projection logic in batches until no eligible rows remain
 

interchain-indexer/.memory-bank/research/stats-subsystem.md

@@ -213,7 +213,8 @@ For detailed message-projection semantics, see `stats-projection.md`.
 
 ### 3. Startup backfill reuses the same projection rules
 
-When `stats_backfill_on_start = true`, startup calls
+When `stats.backfill_on_start = true` (env:
+`INTERCHAIN_INDEXER__STATS__BACKFILL_ON_START=true`), startup calls
 `backfill_stats_until_idle_with_token_enrichment()`.
 
 That method repeatedly runs `backfill_stats_projection_round(...)` until no
@@ -402,6 +403,23 @@ Then:
 - left join from `chains` ensures known chains without a stats row can still be
   returned as `0`
 
+Zero-chain visibility is service-wide and configurable:
+
+- `stats.include_zero_chains` (env:
+  `INTERCHAIN_INDEXER__STATS__INCLUDE_ZERO_CHAINS`), default `true`
+- when `true`: `/stats/chains` and message-path endpoints include known chains
+  from `chains` even when the aggregated stats row is missing or zero
+  - `/stats/chains` keeps its `chains LEFT JOIN stats_chains` shape
+  - message-path endpoints drive the query from `chains` (excluding the
+    selected chain) and left-join `stats_messages` / aggregated
+    `stats_messages_days`
+  - explicit `counterparty_chain_ids` still suppresses synthesized zero rows
+- when `false`: both families return only rows with positive aggregated stats
+  - `/stats/chains` filters
+    `COALESCE(sc.unique_transfer_users_count, 0) > 0 OR COALESCE(sc.unique_message_users_count, 0) > 0)`
+    inside the ranked SQL, preserving keyset pagination
+  - message-path endpoints keep their current stats-table-driven behavior
+
 ## Refresh and Recalculation Model
 
 ### Live request-time queries
@@ -456,16 +474,18 @@ Behavior:
 
 Main knob:
 
-- `INTERCHAIN_INDEXER__STATS_CHAINS_RECALCULATION_PERIOD_SECS`
+- `INTERCHAIN_INDEXER__STATS__CHAINS_RECALCULATION_PERIOD_SECS`
+  (`stats.chains_recalculation_period_secs`)
 - default: `3600`
 - `0` disables periodic refresh
 
 ## Backfill Semantics
 
 ### What startup backfill does
 
-`INTERCHAIN_INDEXER__STATS_BACKFILL_ON_START=true` triggers a startup catch-up
-pass that projects historical canonical rows whose stats were not yet built.
+`INTERCHAIN_INDEXER__STATS__BACKFILL_ON_START=true`
+(`stats.backfill_on_start = true`) triggers a startup catch-up pass that
+projects historical canonical rows whose stats were not yet built.
 
 It is useful when:
 

interchain-indexer/.memory-bank/workflows/implementation-plan.md

@@ -88,6 +88,7 @@ Produce `implementation-plan-X.md` (X - source solution number) describing:
 - affected layers and their responsibilities
 - end-to-end data flow and control flow changes
 - persistence, API, config, and runtime implications
+- README / generated env documentation implications when ENV or config keys change
 - invariants that must remain true
 - main risks, edge cases, and failure handling expectations
 - validation strategy
@@ -109,6 +110,7 @@ Requirements:
 Prepare the implementation breakdown:
 
 - exact files, modules, schemas, tests, and configs likely to change
+- `README.md` and generated env documentation impact when ENV or config surface changes
 - required migrations, backfills, or rollout ordering
 - dependencies between subtasks
 - validation commands and artifacts to update
@@ -139,6 +141,15 @@ Include:
 - known risks and watch-outs
 - any remaining blockers or questions
 
+If the approved design adds, removes, renames, or changes ENVs or config keys, the coding handoff
+must explicitly require the implementation agent to:
+
+- run `just check-envs`
+- if `just check-envs` fails, run `just generate-envs`
+- review any generated changes, especially in `README.md`
+- add or refine `README.md` descriptions for new or changed env fields when the generated output is
+  missing or insufficiently descriptive
+
 ### 7. Decide the Outcome Status
 
 End with one of these statuses inside both artifacts when relevant:
@@ -180,6 +191,14 @@ Verification guidance in both artifacts must follow the repo testing rules:
 - do not default to raw `cargo test` commands when a repo-native wrapper exists
 - only mention bare `cargo test` when no wrapper applies or when the command is specifically needed for a non-default case
 
+When the planned change affects ENVs or config keys, verification guidance in `coding-task-X.md`
+must also include:
+
+- `just check-envs`
+- `just generate-envs` as the required follow-up when `just check-envs` fails because generated env
+  docs are out of sync
+- a final `README.md` review to ensure new or changed env fields are described clearly when needed
+
 Use this structure:
 
 ### `implementation-plan-X.md`
@@ -279,3 +298,12 @@ Use this structure:
 
 [ready for coding | blocked on clarification | blocked on additional codebase research | blocked on product or architectural decision]
 ```
+
+When ENV or config surface changes are in scope, extend the generated `coding-task-X.md` with:
+
+- `README.md` in `Files And Components`
+- an ordered work item to run `just check-envs`, fall back to `just generate-envs` on failure, and
+  review the resulting `README.md` diff
+- a verification entry for `just check-envs`
+- an acceptance criterion that the main `README.md` env documentation is updated for any new or
+  changed fields when needed