Merge pull request #29 from t81dev/phase-19-hardening-13781412227940955739

Harden Phase 19: Cost-Aware Fabric & Economic Introspection

Author: t81dev

.gitignore

@@ -47,6 +47,7 @@ venv/
 # --- Ternary Data & Logs ---
 *.tfrm
 *.tfd
+*.csv
 weights.txt
 trace.vcd
 waveform.vcd

Makefile

@@ -39,7 +39,7 @@ OBJ_DIR = obj_dir
 VERILATOR_FLAGS = --cc $(HW_DIR)/ternary_fabric_top.v -I$(HW_DIR) --Mdir $(OBJ_DIR) -Wno-fatal
 
 # Targets
-ALL_C_BINS = $(BIN_DIR)/mediator_mock $(BIN_DIR)/pt5_example $(BIN_DIR)/reference_tfmbs $(BIN_DIR)/test_device $(BIN_DIR)/mock_llama $(BIN_DIR)/test_dynamic_detection $(BIN_DIR)/test_phase10 $(BIN_DIR)/test_multi_tile $(BIN_DIR)/test_eviction
+ALL_C_BINS = $(BIN_DIR)/mediator_mock $(BIN_DIR)/pt5_example $(BIN_DIR)/reference_tfmbs $(BIN_DIR)/test_device $(BIN_DIR)/mock_llama $(BIN_DIR)/test_dynamic_detection $(BIN_DIR)/test_phase10 $(BIN_DIR)/test_multi_tile $(BIN_DIR)/test_eviction $(BIN_DIR)/sparse_stress $(BIN_DIR)/test_convergence
 ALL_LIBS = $(BIN_DIR)/libtfmbs_device$(SHLIB_EXT) $(BIN_DIR)/libtfmbs_intercept$(SHLIB_EXT)
 ALL_HW_SIM = $(BIN_DIR)/fabric_tb.vvp
 
@@ -85,6 +85,12 @@ $(BIN_DIR)/test_multi_tile: tests/test_multi_tile.c $(BIN_DIR)/libtfmbs_device$(
 $(BIN_DIR)/test_eviction: tests/test_eviction.c $(BIN_DIR)/libtfmbs_device$(SHLIB_EXT)
 	$(CC) $(CFLAGS) -o $@ $< -L$(BIN_DIR) -ltfmbs_device
 
+$(BIN_DIR)/sparse_stress: benchmarks/synthetic/sparse_stress.c $(BIN_DIR)/libtfmbs_device$(SHLIB_EXT)
+	$(CC) $(CFLAGS) -o $@ $< -L$(BIN_DIR) -ltfmbs_device
+
+$(BIN_DIR)/test_convergence: tests/test_convergence.c $(BIN_DIR)/libtfmbs_device$(SHLIB_EXT)
+	$(CC) $(CFLAGS) -o $@ $< -L$(BIN_DIR) -ltfmbs_device
+
 run_mock_llama: $(BIN_DIR)/mock_llama $(ALL_LIBS)
 	export FABRIC_SHORT_CIRCUIT=1; \
 	$(LIBPATH_ENV)=$(BIN_DIR) $(PRELOAD_ENV)=$(BIN_DIR)/libtfmbs_intercept$(SHLIB_EXT) ./$(BIN_DIR)/mock_llama

README.md

@@ -159,26 +159,26 @@ LD_PRELOAD=./libtfmbs_intercept.so ./llama-cli -m model.gguf
 ### Telemetry Insights
 
 ```text
-[TFMBS-Telemetry] GEMV Completed
-  - Zero-Skips: 172,401 (65.8% reduction in total operations)
-  - Pool Usage: 84.2 MB / 128 MB (LRU Managed)
-  - Async Queue: 0 in-flight (Non-blocking execution)
+[TFMBS-Telemetry] Batch of 8 GEMV(s) Completed
+  - Zero-Skips: 497,990 (95.0% reduction)
+  - Cycles:     7,427 (Cost: 568023.0, Sem-Eff: 0.05, Econ-Eff: 0.05)
+  - Residency:  Hits: 54, Misses: 0
+  - Pool Usage: 0.5 MB / 128 MB (0.4%)
+  - Evictions:  0
 ```
 
-Telemetry exposes sparsity, residency, and queue pressure in real time.
+Telemetry exposes sparsity, residency, economic cost, and semantic efficiency in real time.
 
 ---
 
 ## 🏗️ Project State & Architecture
 
-The project is currently in **Phase 15**, representing full-stack operation:
+The project is currently in **Phase 19**, representing a **Cost-Aware Economic Fabric**:
 
-* PyTorch frontends
-* GGUF ingestion
-* Multi-tile emulation
-* IOCTL device layer
-* Interposition illusion
-* RTL kernel parity
+* **Economic Introspection:** Decisions are driven by projected cost and residency rebates.
+* **Hysteresis Scheduling:** Stabilized tile selection to prevent state thrashing.
+* **Sparse-Stress Hardening:** Verified performance at 99%+ sparsity.
+* **Temporal Pipelining:** Overlapping memory hydration with compute.
 
 ### Architecture Layers
 

USER_MANUAL.md

@@ -71,8 +71,10 @@ If you want to avoid the overhead of the "First Scan" heuristic, you can explici
 When running with the interposer or Python API, the Fabric provides real-time telemetry:
 
 *   **Zero-Skips:** The number of operations eliminated because an operand was zero. Typically 50-75% for LLM workloads.
+*   **Semantic Efficiency:** The ratio of useful operations (`active_ops`) to total operations.
+*   **Economic Efficiency:** The ratio of useful operations to total `fabric_cost` (weighted sum of ops, memory, and residency misses).
 *   **Pool Usage:** Current consumption of the 128MB emulation pool.
-*   **Eviction Events:** Increments when the LRU policy frees space for new weight frames.
+*   **Eviction Events:** Increments when the policy (Recency + Frequency) frees space for new weight frames.
 *   **Async Queue:** Shows in-flight GEMVs being processed by the background worker thread.
 
 ---

benchmarks/density_metrics.csv

@@ -0,0 +1,65 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <time.h>
+#include "tfmbs_device.h"
+#include "tfmbs_api.h"
+
+void run_stress(float sparsity, int use_batching) {
+    int rows = 512;
+    int cols = 1024;
+    int size = rows * cols;
+    int num_steps = 10;
+
+    void* w = fabric_alloc(size);
+    void* i = fabric_alloc(cols);
+    void* o = fabric_alloc(rows * sizeof(int32_t));
+
+    int8_t* host_w = malloc(size);
+    int8_t* host_i = malloc(cols);
+    memset(host_i, 1, cols);
+
+    // Initialize with high sparsity
+    for (int j = 0; j < size; j++) {
+        host_w[j] = ((float)rand() / RAND_MAX < (1.0 - sparsity)) ? 1 : 0;
+    }
+    fabric_memcpy_to(w, host_w, size, 1);
+    fabric_memcpy_to(i, host_i, cols, 1);
+
+    printf("\n[Sparse-Stress] Sparsity: %.1f%%, Batching: %s\n", sparsity * 100.0, use_batching ? "ON" : "OFF");
+
+    fabric_handle_t handles[num_steps];
+
+    for (int s = 0; s < num_steps; s++) {
+        handles[s] = fabric_exec_gemv_async(w, i, o, rows, cols);
+        if (!use_batching) {
+            fabric_wait(handles[s]);
+            fabric_dump_economic_csv("sparse_stress_economic.csv");
+            fabric_dump_metrics_csv("sparse_stress_metrics.csv");
+        }
+    }
+
+    if (use_batching) {
+        for (int s = 0; s < num_steps; s++) {
+            fabric_wait(handles[s]);
+            fabric_dump_economic_csv("sparse_stress_economic.csv");
+            fabric_dump_metrics_csv("sparse_stress_metrics.csv");
+        }
+    }
+
+    fabric_free(w); fabric_free(i); fabric_free(o);
+    free(host_w); free(host_i);
+}
+
+int main() {
+    srand(42);
+    // Sparsity levels: 95%, 98%, 99%
+    float levels[] = {0.95, 0.98, 0.99};
+
+    for (int l = 0; l < 3; l++) {
+        run_stress(levels[l], 0); // Batching OFF
+        run_stress(levels[l], 1); // Batching ON
+    }
+
+    return 0;
+}