# Claim-to-Code Mapping: Architectural Consistency & Empirical Traceability

This document establishes 1-to-1 traceability between every architectural, mathematical, systems, and performance claim in **Q-TensorFormer** and the underlying codebase implementation and empirical benchmark runners.

---

## 1. Traceability Matrix

| # | Major Claim | Source File(s) | Class / Function | Exact Implementation Mechanism | Experiment Verifying Claim | Empirical Result File | Confidence & Classification |
|---|---|---|---|---|---|---|---|
| **1** | **Dynamic Per-Token Tensor Rank Adaptation** | `src/tensor_layers.py`<br>`src/blocks.py` | `TTLinear.set_rank`<br>`TTLinear.forward_token_grouped` | Zero-SVD nested tensor core slicing $\mathcal{G}[1:r, :, :, 1:r]$ for $r \in \{1, 2, 4, 8\}$ with token-grouped batching. | `experiments/run_adaptive_rank_validation.py` | `outputs/adaptive_rank_results.json` | **MEASURED** (High) |
| **2** | **Continuous 8D Information State Vector** | `src/information_state.py` | `TokenInformationState.forward` | Real-time computation of $[S_t, H_t, U_t, A_t, R_t, L_t, M_t, B_t]$ with EMA running variance normalization. | `experiments/run_information_state_ablation.py` | `outputs/information_state_ablation.json` | **MEASURED** (High) |
| **3** | **Marginal Value Resource Allocation** | `src/resource_allocator.py` | `InformationValueAllocator`<br>`MarginalValueModel` | Evaluates $\text{Value}(a \mid \mathbf{z}_t) = \Delta \hat{Q} / (\Delta C_{\text{eff}} + \epsilon)$ across combinatorial action space. | `experiments/run_marginal_value_model.py` | `outputs/marginal_value_results.json` | **MEASURED** (High) |
| **4** | **Closed-Loop PID Dual Multiplier Control** | `src/resource_allocator.py` | `PIDDualSubgradientController.update` | Proportional-integral-derivative tuning of $\boldsymbol{\lambda} = [\lambda_l, \lambda_m, \lambda_e, \lambda_b]^T$ on constraint error $e(t) = \mathcal{C}(t) - \mathcal{B}$. | `experiments/run_controller_convergence.py` | `outputs/controller_convergence.json` | **MEASURED** (High) |
| **5** | **Anti-Chattering Hysteresis Stabilization** | `src/resource_allocator.py` | `InformationValueAllocator.forward` | Dual-threshold switching logic: suppresses route changes unless $\Delta U \ge \tau_{\text{hyst}}$ and cooldown elapsed. | `experiments/run_hysteresis_validation.py` | `outputs/hysteresis_results.json` | **MEASURED** (High) |
| **6** | **Nested TT Slicing Correctness** | `src/tensor_layers.py` | `TTLinear.get_active_cores` | Slices pre-allocated cores along bond dimensions without re-decomposition or runtime SVD. | `experiments/run_nested_tt_analysis.py` | `outputs/nested_tt_analysis.json` | **MEASURED** (High) |
| **7** | **Grouped-Query Attention (GQA) Memory Savings** | `src/attention.py` | `MultiHeadAttention.forward` | Decoupled $N_q / N_{kv}$ with zero-copy view broadcasting, reducing KV cache entries by up to 75%. | `experiments/run_gqa_audit.py` | `outputs/gqa_audit.json` | **MEASURED** (High) |
| **8** | **Multi-Precision Adaptive KV Cache** | `src/kv_cache.py` | `AdaptiveKVCache`<br>`QuantizedKVTensor` | Dynamic switching between FP16, symmetric INT8, and asymmetric packed INT4 with attention-sink eviction. | `experiments/run_kv_rate_distortion.py` | `outputs/kv_rate_distortion.json` | **MEASURED** (High) |
| **9** | **Quantum Kernel Self-Attention (QKSAM)** | `src/quantum_backend.py`<br>`src/attention.py` | `QuantumBackend.compute_kernel_matrix` | Evaluates $K(\mathbf{q}, \mathbf{k}) = \text{Tr}[\rho(\mathbf{q})\rho(\mathbf{k})]$ via parameterized quantum circuits with PennyLane. | `experiments/run_quantum_utility.py` | `outputs/quantum_utility.json` | **SIMULATED** (Disclosed Classical Overhead) |
| **10** | **Meyer-Wallach Entanglement Metric** | `src/quantum_backend.py` | `compute_meyer_wallach_entanglement` | Exact state entanglement capacity $Q(|\psi\rangle) = \frac{8}{n}\sum \det(\rho_k) \in [0, 1]$. | `tests/test_advanced_features.py` | PyTest Suite Report | **MEASURED** (Mathematical Definition) |
| **11** | **Calibrated Early-Exit Depth Routing** | `src/blocks.py` | `HybridBlock.forward` | Evaluates epistemic uncertainty $U_t < \gamma_{\text{exit}}$ to bypass downstream blocks via identity residual addition. | `experiments/run_comprehensive_comparison.py` | `outputs/comprehensive_comparison.json` | **MEASURED** (High) |
| **12** | **Hardware Roofline Model Analysis** | `src/hardware_cost_model.py` | `HardwareRooflineAnalyzer` | Computes arithmetic intensity $I = \text{FLOPs} / \text{Byte}$, ridge points, and memory/compute bound boundaries across devices. | `src/hardware_cost_model.py` | `outputs/comprehensive_comparison.json` | **ESTIMATED** (Level 2 Calibrated Model) |
| **13** | **Memory Traffic per Token (Bytes/tok)** | `src/tensor_layers.py`<br>`src/attention.py` | `get_memory_traffic` | Tracks physical bytes read (weights + activations) and written per forward pass. | `experiments/run_detailed_latency_profiling.py` | `outputs/detailed_latency_results.json` | **MEASURED** (High) |
| **14** | **Multi-Level Energy Profiling** | `src/hardware_cost_model.py` | `HardwareCostModel.estimate_energy_uj` | Multi-level hierarchy (Level 1: Analytical, Level 2: Calibrated Device Power $\times$ Wall-Clock Time, Level 3: Sensors). | `experiments/run_comprehensive_comparison.py` | `outputs/comprehensive_comparison.json` | **ESTIMATED** (Level 2 Clearly Disclosed) |
| **15** | **Multi-Baseline Comparison (11 Models)** | `src/baselines.py`<br>`experiments/` | `DenseBaseline`, `StaticTT`, `INT8/INT4 PTQ`, `H2O`, `GQA` | Standardized evaluation of 11 models under identical sequence lengths, batch sizes, and token budgets. | `experiments/run_comprehensive_comparison.py` | `outputs/comprehensive_comparison.json` | **MEASURED** (High) |
| **16** | **Multi-Dimensional Pareto Dominance** | `experiments/run_pareto_frontiers.py` | `compute_pareto_hypervolume` | Multi-point trade-offs across Quality vs Latency, Memory, Energy, Bandwidth, and KV size. | `experiments/run_pareto_frontiers.py` | `outputs/pareto_frontiers.json` | **MEASURED** (High) |

---

## 2. Key Code-Architecture Consistency Resolutions

### A. Per-Token Rank Execution in Sequences
- **Previous state**: In multi-token prefill sequences, `TTLinear.set_rank()` set a single global rank for the layer based on sequence-averaged utility.
- **Resolution**: Implemented `forward_token_grouped()` in `TTLinear` allowing each token in a sequence to be routed to its selected rank $r_t \in \{1, 2, 4, 8\}$, contracted through the sliced core, and scattered back in order.

### B. Removal of Theoretical Convergence Guarantees
- **Previous state**: README claimed "guarantees asymptotic convergence to KKT boundary".
- **Resolution**: Reformulated to "empirically stable closed-loop tracking". Created `experiments/run_controller_convergence.py` measuring actual settling time ($t_{\text{settle}}$), maximum overshoot ($M_p$), and steady-state error ($e_{\text{ss}}$) under workload step changes.

### C. Removal of "Zero Overhead" Claims
- **Previous state**: Slicing previously cited as zero-latency extraction (0.00 ms).
- **Corrected status**: Empirically measured tensor slicing pointer arithmetic overhead (~20-50 µs per layer on CPU/GPU) is explicitly disclosed and included in all latency breakdowns in `experiments/run_adaptive_rank_validation.py` and reported accurately.

### D. Quantum Simulation Overhead Disclosure
- **Previous state**: Emphasized theoretical quantum expressibility without stating classical CPU simulation penalty.
- **Resolution**: Full disclosure in documentation: running PennyLane statevector simulation on classical CPUs/GPUs incurs $+100\%\text{–}300\%$ latency overhead. Documented the exact epistemic uncertainty threshold required to justify quantum pathway activation.