@ruso-0/nreki 8.3.0 → 8.6.1

package/README.md

@@ -147,6 +147,79 @@ True topological circuit rank via Union-Find on the type constraint graph. `beta
 
 ---
 
+## What's New in v8.6 (TFC-Ultra)
+
+**Topological Foveal Compression** — Hyper-causal context sculpting for frontier LLMs. Point TFC-Ultra at a specific method or function inside a file, and it extracts the target symbol at 100% resolution plus its causal dependencies (upstream callers, downstream deps, resolved imports, blast radius), while annihilating orthogonal "dark matter" code.
+
+```bash
+nreki_code action:"compress" path:"src/huge-file.ts" focus:"criticalMethod"
+```
+
+### Empirical results (benchmarked against NREKI src/ — 5 files, 15 focus probes + 15 boundary probes)
+
+**Operational case** (methods of medium-to-large size):
+
+| Metric | Value |
+|--------|-------|
+| **Avg compression** | **82.2%** (~5.6x) |
+| **p50 compression** | **84.8%** |
+| **p95 compression** | **89.9%** (~10x) |
+| **Advantage vs legacy tier-3** | **+9.8pp** (consistent) |
+| **Fovea fidelity** | **100%** — target symbol preserved verbatim for zero-loss reasoning |
+| **True LRU AST cache** | **34x avg speedup**, **137x in extreme cases** (1,819ms → 13.3ms on 82 KB file) |
+| **Fallback rate (Density Shield)** | **13.3%** — when TFC can't beat 15% compression, falls through to legacy aggressive |
+
+**Best case boundary** (theoretical ceiling — small focus inside large file):
+
+| Metric | Value |
+|--------|-------|
+| **Max compression observed** | **98.2%** (**55x**) |
+| **Context** | focus `isBooted` (3-line getter) inside `nreki-kernel.ts` (82 KB, 1,640 lines) |
+| **Boundary probes** | 15 (top-3 smallest symbols per file), **0 fallbacks**, compression range: **30x–55x** |
+
+### The Amdahl law of focused compression
+
+TFC compression ratio follows an asymptotic limit:
+
+```
+Ratio ≈ 1 − (Preamble + Fovea + Markov_Mantle_O(1)) / TotalFileSize
+```
+
+- When the Fovea is a small getter (3 lines) inside a 1,640-line file, the numerator is minuscule vs. the denominator. **Ratio approaches 100%. Empirical ceiling: 98.2% (55x).**
+- When the Fovea is a large operational method (500 lines), the numerator grows. **Ratio drops to 70-80%.** Still preserves 100% of the causal information the agent needs.
+- When the Fovea is a God Class (entire file), the numerator **exceeds** the denominator due to parafovea overhead. **The Density Shield detects this and falls through to legacy aggressive**, guaranteeing the output is never worse than baseline.
+
+**This is not marketing. This is physics.** See [BENCH-TFC.md](BENCH-TFC.md) for the raw dogfooding benchmark with per-file breakdowns.
+
+### How it works
+
+- **Fovea**: the target symbol is preserved byte-for-byte at 100% resolution
+- **Upstream vectorial collapse** (O(1)): N local callers condensed to a single line of names
+- **Downstream event horizon** (O(1)): top-10 local dependencies + `cleanSignature` to strip JSDoc waste
+- **External parafovea**: BM25-resolved signatures of imported symbols used inside the fovea
+- **Blast radius**: dependents from the project-wide import graph
+- **Dark matter**: everything else in the file is omitted as a single annotation line
+- **Density Shield 0.85**: if TFC can't achieve ≥15% real compression (e.g. when the agent aims at a God Class and pulls the entire file into the fovea), the compressor returns `null` and the system falls through to the legacy aggressive compressor — **mathematically guarantees you never perform worse than baseline**
+
+### TFC-Pro Enforcer (auto-guard on `read`)
+
+When a file exceeds 3,000 tokens and the agent tries to read it raw, NREKI's hook intercepts the call and instructs the agent to use outline + focus-driven compression instead. This eliminates context-window suicide before it happens.
+
+---
+
+## What's New in v8.5 (Engine Decomposition)
+
+The 878-line `engine.ts` God Object was decomposed into a clean facade pattern:
+
+- `engine-types.ts` — shared type definitions (SearchResult, EngineConfig, SessionReport, IndexStats)
+- `engine/indexer.ts` — `IndexPipeline` class (write side: AST parsing, embedding, batch storage)
+- `engine/searcher.ts` — `SearchEngine` class (read side: T-RAG Tectonic Relevance Scoring)
+- `engine.ts` — thin orchestrator facade (~520 lines)
+
+Zero API changes. All 28 public methods on `NrekiEngine` preserved. `sql.js` intentionally kept (migration to `node:sqlite` postponed to v9.0 to avoid breaking users on Node 20 LTS or forcing the `--experimental-sqlite` flag).
+
+---
+
 ## What's New in v8.3
 
 ### Kernel Decomposition (v8.1)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ruso-0/nreki",
-  "version": "8.3.0",
+  "version": "8.6.1",
   "description": "MCP plugin that validates AI agent edits in RAM before they touch disk. Spectral clustering, architecture diffs, bridge detection, dead code oracle, and cross-file semantic checks for TypeScript, Go (gopls), and Python (pyright). Zero cloud dependencies.",
   "main": "dist/index.js",
   "type": "module",