Mopati123 · Mopati123 · May 6, 2026 · May 6, 2026
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 A production-grade trading bot that models financial markets as curved physical space and finds optimal trades using Feynman's path integral — the same mathematics that governs how particles move through quantum fields.
 
-Every trade decision is authorized by a cryptographic governance protocol, signed with Ed25519, and stored in an immutable Merkle-chained audit trail.
+Every trade decision is authorized by a cryptographic governance protocol and stored in a SHA-256 runtime evidence hash chain. Optional evidence bundles support Merkle roots and Ed25519 signatures where that path is used.
 
 ---
 
@@ -23,7 +23,8 @@ Instead of simple indicators (RSI, MACD), this system:
 
 | Guide | Description |
 |-------|-------------|
-| [Architecture Guide](docs/ARCHITECTURE.md) | System design — physics core, 20-stage pipeline, manifold geometry |
+| [Architecture Guide](docs/ARCHITECTURE.md) | System design — physics core, canonical pipeline, manifold geometry |
+| [Rootfile Hamiltonian Canon](docs/ROOTFILE_HAMILTONIAN_CANON.md) | One-to-one map from the lawful-collapse canon to the current rootfile runtime |
 | [API Reference](docs/API.md) | Complete class and method reference for all modules |
 | [Tutorials](docs/TUTORIAL.md) | Step-by-step guides: paper trading, dashboard, Telegram bot, brokers |
 | [Examples](docs/examples/README.md) | Working Python code snippets |
@@ -38,7 +39,7 @@ Instead of simple indicators (RSI, MACD), this system:
 RAW MARKET DATA (MT5 / Deriv / TradingView)
         ↓
 ┌─────────────────────────────────────────┐
-│         20-STAGE PIPELINE               │
+│         CANONICAL PIPELINE              │
 │  1. Data Ingestion                      │
 │  2. State Construction (microstructure) │
 │  3. ICT Extraction (OB, FVG, BOS)       │
@@ -56,7 +57,7 @@ RAW MARKET DATA (MT5 / Deriv / TradingView)
 │ 15. Scheduler Collapse ← CIRCUIT BREAKER│
 │ 16. Execution (paper / live)            │
 │ 17. Reconciliation ← PnL DIVERGENCE    │
-│ 18. Evidence Emission (Ed25519+Merkle)  │
+│ 18. Evidence Emission (SHA-256 chain)   │
 │ 19. Weight Update (PPO + backward law)  │
 │ 20. Completed                           │
 └─────────────────────────────────────────┘
@@ -75,7 +76,7 @@ The repository now includes a non-breaking rootfile overlay that makes the archi
 | `core.orchestration` | Select admissible paths and mint execution authority | `trading.kernel.scheduler`, `trading.kernel.apex_engine`, constraints |
 | `core.authority` | Canonical `ExecutionToken` facade and token validation | TAEP scheduler tokens plus trading scheduler token compatibility |
 | `core.execution` | Shadow/live/broker execution boundaries | `trading.shadow`, `apps.telegram.trading_live`, broker adapters |
-| `tachyonic_chain` | Evidence and Merkle audit-chain exports | `trading.evidence.evidence_chain` |
+| `tachyonic_chain` | Runtime SHA-256 audit-chain exports; optional bundle adapters | `tachyonic_chain.audit_log`, `trading.evidence.evidence_chain` |
 | `backend_api` | Telegram, dashboard, and read/control surfaces | `apps.telegram`, `trading.dashboard` |
 
 The law of motion is: data prepares state, simulation proposes, orchestration authorizes, execution acts, and evidence records. Shadow and live execution boundaries now validate scheduler-issued authority through `core.authority.validate_token(...)`; proposal modules remain token-free so analysis stays cheap and safe.

diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
@@ -6,6 +6,8 @@ ApexQuantumICT treats financial markets as a curved Riemannian manifold and sele
 
 The rootfile-first overlay makes that contract explicit without breaking the existing engine. Current modules stay in place, while canonical namespaces describe the architecture in first-order layers: state preparation, proposal generation, authorization, execution, evidence, validation, and API observation.
 
+For the one-to-one mathematical canon, see [Rootfile Hamiltonian Canon](ROOTFILE_HAMILTONIAN_CANON.md). It maps the thirteen lawful-collapse laws to the current pipeline, broker settlement, evidence, and ML feedback paths.
+
 ---
 
 ## Rootfile-First Overlay
@@ -295,7 +297,9 @@ O1-O18 remain the legacy ICT/SMC operator contract. O19-O25 are analytics-only o
 
 ---
 
-## 20-Stage Canonical Pipeline
+## Canonical Pipeline
+
+The active decision loop has nineteen stage handlers plus completion/failure bookkeeping. Older docs may call this a 20-stage pipeline because `COMPLETED` is represented as a terminal stage result.
 
 ```
 RAW MARKET DATA (MT5 / Deriv / TradingView)
@@ -337,22 +341,39 @@ ROOTFILE AUDIT CHAIN (SHA-256 JSONL HASH CHAIN)
 | 3. ICT_EXTRACTION | Identify order blocks, FVGs, BOS/CHOCH, liquidity zones, session |
 | 4. GEOMETRY_COMPUTATION | Compute ϕ(p,t) → metric g_ij → Γⁱⱼₖ → curvature K → regime |
 | 5. TRAJECTORY_GENERATION | RK4 integration → N candidate paths with geodesic-seeded initial conditions |
-| 6. RAMANUJAN_COMPRESSION | Cluster paths into behavioral families; reduce redundancy |
+| 6. RAMANUJAN_COMPRESSION | Deterministically cluster paths by liquidity/time/entry/risk/topology signatures |
 | 7. ADMISSIBILITY_FILTERING | Π_total gate: discard paths violating constraints |
 | 8. ACTION_EVALUATION | Compute S[γ] = w_L·S_L + w_T·S_T + w_E·S_E + w_R·S_R (+ optional S_HFT) for each path |
 | 9. PATH_INTEGRAL | Weight each path: P ∝ exp(−S/ℏ); calibrate ℏ for ESS≈0.5 |
 | 10. INTERFERENCE_SELECTION | Destructive interference cancels high-action paths |
 | 11. PATH_SELECTION | γ* = argmax weight = argmin action |
 | 12. PROPOSAL_GENERATION | Extract (direction, entry, stop, target, size, predicted_pnl) from γ* |
 | 13. ADMISSIBILITY_CHECK | Final risk gate: check_all_limits() from risk manager |
-| 14. ENTROPY_GATE | ΔS < threshold: reject if trajectory variance too high |
+| 14. ENTROPY_GATE | Measure posterior path uncertainty and information gain; reject if uncertainty is too high |
 | 15. SCHEDULER_COLLAPSE | Issue ExecutionToken or REFUSE; **circuit breaker** wraps this call |
 | 16. EXECUTION | Submit to shadow/paper/live broker via ExecutionToken |
 | 17. RECONCILIATION | PnL divergence: \|predicted − realized\| / max(\|predicted\|, 1) |
 | 18. EVIDENCE_EMISSION | Append a canonical SHA-256 hash-chained evidence record |
 | 19. WEIGHT_UPDATE | PPO reward + backward law: w_new ← Π_simplex(w_old + η·J) |
 | 20. COMPLETED | Update state, log metrics, prepare for next cycle |
 
+### Lawful-Collapse Stage Map
+
+```text
+raw state -> geometry -> paths -> action -> projectors -> entropy
+-> scheduler -> execution -> reconciliation -> evidence -> ML feedback
+```
+
+| Runtime group | Canon coverage | Primary implementation |
+|---------------|----------------|------------------------|
+| Raw state | H1 state space | `PipelineContext`, data ingestion, state construction |
+| Geometry | H2-H4 geometry, connection, curvature | `trading/geometry/*` |
+| Paths | H5-H6 path space and compression | `trading/path_integral/*`, Ramanujan compression stage |
+| Action/projectors | H7-H8 scoring and admissibility | `trading/action/*`, `trading/risk/risk_manager.py` |
+| Entropy/authority | H9-H10 delta-S and scheduler collapse | entropy gate, `trading/kernel/scheduler.py` |
+| Collapse/reconciliation | H11-H12 broker execution and reality check | execution/reconciliation stages, MT5 and Deriv settlement CLIs |
+| Evidence/learning | H13 evidence plus ML feedback | `tachyonic_chain/audit_log.py`, PPO pending state, refusal-risk rebuild |
+
 ---
 
 ## Production Hardening (T3-A)

diff --git a/docs/ROOTFILE_HAMILTONIAN_CANON.md b/docs/ROOTFILE_HAMILTONIAN_CANON.md
@@ -0,0 +1,105 @@
+# Rootfile Hamiltonian Canon
+
+## Summary
+
+The rootfile trading runtime is best described as lawful collapse of possible
+market futures into auditable state.
+
+The original canon uses the phrase "nine Hamiltonians", but the working system
+maps more accurately to thirteen operational laws. Those thirteen laws are the
+canonical architecture layer for this repository. They sit above the active
+pipeline stages, broker settlement modules, evidence chain, and ML feedback
+path.
+
+The practical runtime flow is:
+
+```text
+raw state -> geometry -> paths -> action -> projectors -> entropy
+-> scheduler -> execution -> reconciliation -> evidence -> ML feedback
+```
+
+## One-To-One Rootfile Map
+
+| Canon law | Existing rootfile home | Current implementation meaning |
+|---|---|---|
+| H1 State space | `PipelineContext`, data ingestion, state construction | MT5, Deriv, and replay inputs become market state, OHLCV, microstructure, symbol, source, and stage context. |
+| H2 Geometry | `trading/geometry/liquidity_field.py`, `metric.py` | ICT and microstructure features become liquidity field `phi` and the conformal metric. |
+| H3 Connection | `trading/geometry/connection.py` | Christoffel symbols bend candidate trajectories through liquidity gradients. |
+| H4 Curvature | `trading/geometry/curvature.py` | Gaussian curvature classifies basin, flat, saddle, and transition regimes. |
+| H5 Path space | `trading/path_integral/trajectory_generator.py` | Candidate futures are generated as trajectories through market state space. |
+| H6 Ramanujan compression | Pipeline Ramanujan compression stage | Trajectories are grouped into deterministic behavior families using liquidity, time, entry, risk, and topology signatures. |
+| H7 Action | Pipeline action evaluation and `trading/action/*` | Paths receive weighted liquidity, time, entry, risk, and curvature-aware costs. |
+| H8 Admissibility | Pipeline admissibility stages and `trading/risk/risk_manager.py` | Illegal paths and unsafe proposals are refused before execution. |
+| H9 Entropy / delta S | Pipeline entropy gate and scheduler `delta_s` input | The gate measures prior path uncertainty, posterior action-weight uncertainty, and information gain before scheduler collapse. |
+| H10 Scheduler authority | `trading/kernel/scheduler.py` and scheduler-collapse stage | The scheduler is the sole authority that may issue an execution token. |
+| H11 Collapse / execution | Pipeline execution stage, broker modules, demo runner | Authorized proposals become paper fills, MT5 demo orders, or Deriv demo contracts. |
+| H12 Reconciliation | Pipeline reconciliation plus MT5 and Deriv settlement modules | Intended vs actual execution is checked; realized closed-trade PnL feeds settlement and learning. |
+| H13 Evidence | `tachyonic_chain/audit_log.py`, `trading/evidence/evidence_chain.py`, audit CLIs | Runtime evidence is a SHA-256 JSONL hash chain; the separate evidence bundle path supports Merkle roots and Ed25519 signatures where used. |
+
+## Active Pipeline Alignment
+
+The active `PipelineOrchestrator` runs nineteen decision stage handlers plus
+completion or failure bookkeeping. Older summaries call this a 20-stage pipeline
+because `COMPLETED` is counted as a terminal stage result.
+
+| Runtime stage group | Canon coverage |
+|---|---|
+| Data ingestion and state construction | H1 |
+| ICT extraction, liquidity field, metric, connection, curvature | H2, H3, H4 |
+| Trajectory generation and path-family compression | H5, H6 |
+| Action evaluation, path integral, interference, path selection | H7 |
+| Proposal generation and admissibility checks | H8 |
+| Entropy gate | H9 |
+| Scheduler collapse | H10 |
+| Execution | H11 |
+| Reconciliation | H12 |
+| Evidence emission and weight update | H13 plus ML feedback |
+
+Broker settlement is deliberately outside the immediate tick-loop collapse
+because MT5 positions and Deriv contracts close asynchronously. Settlement is
+the bridge from broker reality back into learning:
+
+| Broker path | Settlement path | Learning rule |
+|---|---|---|
+| MT5 demo order | `scripts.trading.settle_demo_trades` | Use realized position history, not floating open PnL. |
+| Deriv demo contract | `scripts.trading.settle_deriv_contracts` | Use closed contract profit/loss, not proposal-time payout estimates. |
+
+## Evidence And Anchoring
+
+There are two evidence layers, and they should not be conflated:
+
+| Layer | Implementation | What it proves |
+|---|---|---|
+| Runtime execution evidence | `tachyonic_chain/audit_log.py` | Each JSONL record stores `previous_hash`, canonical payload data, and `record_hash` using SHA-256. |
+| Optional evidence bundles | `trading/evidence/evidence_chain.py` | Bundle-level Merkle roots and Ed25519 signatures where that path is used. |
+
+GitHub commits then publicly anchor the code and curated reports. That is not a
+public blockchain transaction; it is public source-control anchoring layered on
+top of the local evidence hash chain.
+
+## What We Have Now
+
+The merged rootfile system has proven:
+
+- MT5 demo execution, settlement, evidence, and offline ML rebuild from a closed
+  take-profit trade.
+- Deriv demo execution, settlement, evidence, and offline ML rebuild from a
+  closed one-contract canary.
+- Scheduler-token enforcement before broker execution.
+- Durable Deriv PPO pending-state persistence before the canary runner stops.
+- V1 Ramanujan path-family signatures in the active pipeline.
+- Measured entropy and information-gain reporting into scheduler collapse.
+- Post-outcome falsification scoring for closed MT5 and Deriv demo settlements.
+
+The next proof target is a second guarded Deriv demo contract where settlement
+returns PPO feedback as `updated` or `transition_stored` instead of
+`missing_pending_state`.
+
+## Known Weak Spots
+
+- Ramanujan compression now has deterministic v1 signatures. Future work can
+  deepen the signatures with richer ICT lineage and empirical family scoring.
+- The entropy gate now measures prior/posterior uncertainty. Future work should
+  calibrate the threshold empirically against the 300-shadow/forward proof set.
+- Runtime evidence is SHA-256 hash chained; public-chain notarization would be a
+  separate explicit feature.
diff --git a/tests/rootfile/test_demo_trade_settlement.py b/tests/rootfile/test_demo_trade_settlement.py
@@ -122,13 +122,17 @@ def test_settle_demo_trades_writes_ledger_evidence_and_ml_artifacts(tmp_path: Pa
     assert report.scanned == 1
     assert report.closed == 1
     assert report.records[0].ppo_feedback_status == "missing_pending_state"
+    assert report.records[0].falsification_status == "correct_authorization"
+    assert report.records[0].falsification_hash is not None
     assert ledger_path.exists()
     assert evidence_path.exists()
     assert dataset_path.exists()
     assert model_path.exists()
     rows = read_refusal_risk_dataset(dataset_path)
     assert rows[0]["realized_pnl"] == 0.9
     assert rows[0]["close_reason"] == "tp"
+    assert rows[1]["event_type"] == "falsification_score"
+    assert rows[1]["outcome"] == "correct_authorization"
     assert json.loads(model_path.read_text(encoding="utf-8"))["runtime_integration"] == "offline_only"
 
 

diff --git a/tests/rootfile/test_deriv_contract_settlement.py b/tests/rootfile/test_deriv_contract_settlement.py
@@ -221,12 +221,16 @@ def test_settle_deriv_contracts_writes_ledger_evidence_and_ml_artifacts(tmp_path
     assert report.closed == 1
     assert report.records[0].status == "closed"
     assert report.records[0].ppo_feedback_status == "missing_pending_state"
+    assert report.records[0].falsification_status == "correct_authorization"
+    assert report.records[0].falsification_hash is not None
     assert ledger_path.exists()
     assert verify_execution_evidence_chain(evidence_path).valid
     rows = read_refusal_risk_dataset(dataset_path)
-    assert len(rows) == 1
+    assert len(rows) == 2
     assert rows[0]["broker"] == "deriv"
     assert rows[0]["realized_pnl"] == 0.95
+    assert rows[1]["event_type"] == "falsification_score"
+    assert rows[1]["outcome"] == "correct_authorization"
     assert json.loads(model_path.read_text(encoding="utf-8"))["runtime_integration"] == "offline_only"