docs/CLAIM_TO_CODE_MAP.md

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 src/blocks.py	TTLinear.set_rank 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 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 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 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
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 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 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.