Merge branch 'main' into issue/435-578-idempotency-recovery

Author: Inkman007

.env.example

@@ -1,3 +1,9 @@
+# Which of these vars are actually required depends on which entry point
+# you're running (the REST API, the streaming pipeline, on-chain submission,
+# training, ...). See config/contracts.py for the per-runtime-mode contract,
+# and run `make check-env MODE=<mode>` to check your .env against one before
+# starting the service.
+
 # Stellar Horizon API endpoint used for ingestion.
 # Default: https://horizon.stellar.org
 # Optional.

.github/CODEOWNERS

@@ -0,0 +1,90 @@
+# LedgerLens CODEOWNERS
+# Each line is a file pattern followed by one or more owners.
+# Order matters: later rules override earlier ones for matching files.
+# See https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
+# ── Default owners for everything ────────────────────────────────────────────
+*                               @Ledger-Lenz/core-maintainers
+
+# ── Data ingestion pipeline ──────────────────────────────────────────────────
+/ingestion/                     @Ledger-Lenz/data-team
+/ingestion/horizon_streamer.py  @Ledger-Lenz/data-team @Ledger-Lenz/infra-team
+/ingestion/kafka_producer.py    @Ledger-Lenz/data-team @Ledger-Lenz/streaming-team
+/ingestion/rate_limiter.py      @Ledger-Lenz/infra-team
+
+# ── Detection engine ─────────────────────────────────────────────────────────
+/detection/                     @Ledger-Lenz/ml-team
+/detection/benford_engine.py    @Ledger-Lenz/ml-team
+/detection/feature_engineering.py @Ledger-Lenz/ml-team
+/detection/model_training.py    @Ledger-Lenz/ml-team
+/detection/model_inference.py   @Ledger-Lenz/ml-team
+/detection/wallet_graph.py      @Ledger-Lenz/ml-team
+/detection/gnn_encoder.py       @Ledger-Lenz/ml-team
+/detection/shap_explainer.py    @Ledger-Lenz/ml-team
+/detection/differential_privacy.py @Ledger-Lenz/ml-team @Ledger-Lenz/security-team
+/detection/adversarial/         @Ledger-Lenz/ml-team @Ledger-Lenz/security-team
+/detection/persistence.py       @Ledger-Lenz/data-team
+/detection/risk_score_store.py  @Ledger-Lenz/data-team
+
+# ── Streaming / real-time pipeline ───────────────────────────────────────────
+/streaming/                     @Ledger-Lenz/streaming-team
+/streaming/pipeline.py          @Ledger-Lenz/streaming-team
+/streaming/kafka_worker.py      @Ledger-Lenz/streaming-team @Ledger-Lenz/infra-team
+/streaming/ws_server.py         @Ledger-Lenz/streaming-team
+/streaming/alert_dispatcher.py  @Ledger-Lenz/streaming-team
+
+# ── Integrations / smart contracts ───────────────────────────────────────────
+/integrations/                  @Ledger-Lenz/contract-team
+/integrations/contract_client.py @Ledger-Lenz/contract-team
+/integrations/soroban/          @Ledger-Lenz/contract-team
+/integrations/zk_attestor.py    @Ledger-Lenz/contract-team
+
+# ── Monitoring & observability ───────────────────────────────────────────────
+/monitoring/                    @Ledger-Lenz/infra-team
+/monitoring/prometheus.yml      @Ledger-Lenz/infra-team
+/monitoring/alert_rules.yml     @Ledger-Lenz/infra-team
+
+# ── Configuration ────────────────────────────────────────────────────────────
+/config.py                      @Ledger-Lenz/core-maintainers
+/config/                        @Ledger-Lenz/core-maintainers
+/.env.example                   @Ledger-Lenz/core-maintainers
+
+# ── Reporting ────────────────────────────────────────────────────────────────
+/reporting/                     @Ledger-Lenz/data-team
+/reporting/fatf_exporter.py     @Ledger-Lenz/data-team @Ledger-Lenz/compliance-team
+
+# ── Privacy & differential privacy ───────────────────────────────────────────
+/privacy/                       @Ledger-Lenz/ml-team @Ledger-Lenz/security-team
+
+# ── CI/CD & build ───────────────────────────────────────────────────────────
+/.github/                       @Ledger-Lenz/core-maintainers
+/.github/workflows/             @Ledger-Lenz/infra-team
+/Dockerfile                     @Ledger-Lenz/infra-team
+/docker-compose.yml             @Ledger-Lenz/infra-team
+/Makefile                       @Ledger-Lenz/core-maintainers
+
+# ── Testing ──────────────────────────────────────────────────────────────────
+/tests/                         @Ledger-Lenz/core-maintainers
+/tests/integration/             @Ledger-Lenz/core-maintainers @Ledger-Lenz/infra-team
+/tests/fuzz/                    @Ledger-Lenz/ml-team
+
+# ── Scripts ──────────────────────────────────────────────────────────────────
+/scripts/                       @Ledger-Lenz/core-maintainers
+/scripts/stream.py              @Ledger-Lenz/streaming-team
+/scripts/retrain_if_drifted.py  @Ledger-Lenz/ml-team
+/scripts/testnet_setup.py       @Ledger-Lenz/contract-team
+
+# ── Utilities ────────────────────────────────────────────────────────────────
+/utils/                         @Ledger-Lenz/core-maintainers
+/utils/logging.py               @Ledger-Lenz/infra-team
+/utils/tracing.py               @Ledger-Lenz/infra-team
+
+# ── Models & data artifacts ──────────────────────────────────────────────────
+/models/                        @Ledger-Lenz/ml-team
+/data/                          @Ledger-Lenz/data-team
+
+# ── Documentation ────────────────────────────────────────────────────────────
+/docs/                          @Ledger-Lenz/core-maintainers
+/README.md                      @Ledger-Lenz/core-maintainers
+/CONTRIBUTING.md                @Ledger-Lenz/core-maintainers
+/CHANGELOG.md                   @Ledger-Lenz/core-maintainers

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,11 +2,66 @@
 
 What does this PR change and why?
 
+## Type of change
+
+<!-- Check all that apply -->
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Data/schema change (affects feature columns, data models, Avro schema)
+- [ ] Model change (affects training, inference, or evaluation metrics)
+- [ ] Infrastructure / CI change
+- [ ] Documentation only
+- [ ] Security fix
+
+## Changelog
+
+<!-- REQUIRED: paste the entry you added to CHANGELOG.md under [Unreleased] -->
+<!-- If this PR touches detection/feature_engineering.py, detection/model_*.py, -->
+<!-- ingestion/data_models.py, data/*, or models/* an entry is mandatory.       -->
+
+```
+### Added / Changed / Fixed / ...
+- <your entry here>
+```
+
+## Impact assessment
+
+### Data / feature schema changes
+<!-- If feature_engineering.py, data_models.py, or data/trade_avro_schema.json changed: -->
+- [ ] No schema changes
+- [ ] New feature columns added (update data/feature_dictionary.md)
+- [ ] Feature columns removed or renamed (update feature_schema_hash; note downstream impact)
+- [ ] Avro schema evolved (backward-compatible / breaking)
+
+### Model changes
+<!-- If model_training.py, model_inference.py, or models/* changed: -->
+- [ ] No model changes
+- [ ] Model retrained — include before/after AUC-ROC / F1 in the summary above
+- [ ] Inference API changed — update ledgerlens-core if RiskScore shape changed
+- [ ] Feature schema hash will change — all consumers need to reload models
+
+### Downstream impact
+<!-- Check any systems affected by this change -->
+- [ ] `ledgerlens-api` — REST API response shape may change
+- [ ] `ledgerlens-dashboard` — visualization or SHAP field names may change
+- [ ] `ledgerlens-contract` — on-chain RiskScore struct may change
+- [ ] `ledgerlens-core` — shared types or thresholds may change
+- [ ] None
+
 ## Checklist
 
 - [ ] `make test` passes locally
 - [ ] `make lint` and `make format` are clean
 - [ ] New/changed behavior has test coverage
-- [ ] `CHANGELOG.md` updated under "Unreleased"
+- [ ] `CHANGELOG.md` updated under `[Unreleased]`
 - [ ] If a shared contract changed (`RiskScore`, asset pair format, feature
       schema), linked issues/PRs in `ledgerlens-core` and downstream repos
+
+<!--
+If this PR touches a high-risk path (wire schema, shared contracts, feature
+or training code, DB schema, tenant config, model metadata), CI will ask you
+to add a short note under a specific heading. See
+.github/review-checklists.md — or run `make check-review-gates` to see which
+apply before you push.
+-->
+