Merge pull request #28 from t81dev/phase-19-data-driven-adaptation-16839316173144384857

Phase 19: Data-Driven Adaptation (Cost-Aware Fabric)

Author: t81dev

USER_MANUAL.md

@@ -30,7 +30,11 @@ Welcome to the **Ternary Fabric** user manual. This documentation is designed to
     Details on multi-tile topology and masking.
 13. **[PyTorch Integration](docs/12_PYTORCH.md)**
     Using the Ternary Fabric within the PyTorch deep learning framework.
-14. **[Strategy Roadmap](docs/ROADMAP.md)**
+14. **[GGUF Model Optimizations](docs/14_GGUF.md)**
+    Optimizing llama.cpp and GGUF workflows.
+15. **[Data-Driven Adaptation](docs/19_DATA_DRIVEN_ADAPTATION.md)**
+    Details on Phase 19 cost-aware scheduling and adaptive residency.
+16. **[Strategy Roadmap](docs/ROADMAP.md)**
     The project roadmap detailing completed and future phases.
 
 ---

docs/19_DATA_DRIVEN_ADAPTATION.md

@@ -0,0 +1,46 @@
+# Phase 19: Data-Driven Adaptation (Cost-Aware Fabric)
+
+Phase 19 focuses on transforming the Fabric from a passive executor into an active, economically-driven co-processor. It leverages the telemetry established in Phase 18 to make autonomous decisions about scheduling, residency, and optimization.
+
+## 1. Cost-Aware Scheduler
+
+The scheduler now selects tiles based on **projected cost** rather than fixed or round-robin assignment.
+
+### projected_cost(tile, kernel, tensors)
+- **Residency Hits:** Prefers tiles where weights or inputs are already resident.
+- **Broadcast Reuse:** Accounts for the cost of moving data between tiles.
+- **Memory Reads/Writes:** Estimates the I/O cost for the specific kernel.
+- **Tile Local Reuse:** Favors tiles that have previously processed similar data.
+
+## 2. Residency Policy Engine
+
+Adaptive memory management replaces static LRU.
+
+### Scoring Heuristic
+Blocks are scored based on:
+- **Recency:** Time since last access.
+- **Frequency:** Total number of accesses.
+- **Semantic Efficiency:** How much "meaning" (active ops) the block contributes per cost unit.
+
+### Policies
+- `keep_hot_state`: Prevents eviction of frequently used activation/state buffers.
+- `evict_cold_weights`: Prioritizes eviction of weights with long reuse distances.
+- `adaptive_pinning`: Automatically pins blocks that show high temporal locality.
+
+## 3. Sparse-Regime Optimization
+
+Reduces overhead for workloads where Zero-Skip is highly active.
+
+- **Micro-kernel Fusion:** Fuses adjacent operations (e.g., GEMV + Bias + Activation) to reduce memory round-trips.
+- **Control Flow Collapse:** Batches small asynchronous tasks to minimize worker thread wake-up overhead.
+
+## 4. Temporal Pipelines
+
+Optimizes recurrent and agentic workloads (LSTM, RNN).
+
+- **Asynchronous Hydration:** Prefetches the next step's inputs/weights while the current step is computing.
+- **State Persistence:** Keeps hidden states local to tiles to minimize fabric-wide broadcasts.
+
+## 5. Metric-Driven Auto-Tuning
+
+Rolling averages and baseline comparisons allow the fabric to "learn" the optimal configuration for a given workload over time.

docs/ROADMAP.md

@@ -130,15 +130,24 @@ Promotion of reference kernels to full hardware acceleration.
 *   **Deliverables:** Updated `frame_controller.v` and `ternary_lane_alu.v` with native support for 3D Convolution, LSTM, and Attention kernels.
 *   **Features:** Squared-stride memory addressing for CONV3D and `BIAS_EN` driven state persistence for recurrent/attention workloads.
 
-### Phase 18 — Ternary Workload Maturation & Measurement Plane ⏳
+### Phase 18 — Ternary Workload Maturation & Measurement Plane ✅
 Anchoring the fabric with workload realism and a formal programming model.
-*   **Status:** In Progress.
+*   **Status:** Complete.
 *   **Deliverables:**
     *   **Three-Tier Benchmark Suite:** Synthetic, Kernel, and Application-level measurement.
     *   **T-LSTM Promotion:** Native kernel path for recurrent stateful workloads.
     *   **Host API Surface:** Formal C/C++ primitives for fabric orchestration.
     *   **Cost Model:** Cycle-aware emulator tracking "fabric_cost" (ops + memory weighted).
 
+### Phase 19 — Data-Driven Adaptation (Cost-Aware Fabric) ⏳
+Using Phase 18 metrics to drive autonomous fabric behavior and scheduling.
+*   **Status:** In Progress.
+*   **Deliverables:**
+    *   **Cost-Aware Scheduler:** Economic tile selection based on residency and projected cost.
+    *   **Residency Policy Engine:** Adaptive pinning and scoring-based eviction (Scoring: Recency + Frequency).
+    *   **Sparse-Regime Optimization:** Micro-kernel fusion and reduced control-flow overhead.
+    *   **Temporal Pipelines:** Overlapping memory hydration with compute for recurrent workloads.
+
 ---
 
 # 🔑 What This Strategy Gives You

include/tfmbs.h

@@ -78,6 +78,7 @@ typedef struct {
 #define TFMBS_HINT_ZERO_SKIP_EN    (1 << 17)
 #define TFMBS_HINT_FREE_NEG_EN     (1 << 18)
 #define TFMBS_HINT_WEIGHT_BRDCST   (1 << 19)
+#define TFMBS_HINT_FUSED           (1 << 20)
 
 /* T-CONV Specific Hints */
 #define TFMBS_HINT_STRIDE_MASK     0x00300000 // Bits 21:20