@ruso-0/nreki 8.0.2 → 8.6.1

package/README.md

@@ -2,7 +2,7 @@
 
 <p align="center">
   <img src="https://img.shields.io/npm/v/@ruso-0/nreki?style=for-the-badge&color=blue" alt="npm version">
-  <img src="https://img.shields.io/badge/Tests-712-brightgreen?style=for-the-badge" alt="712 Tests">
+  <img src="https://img.shields.io/badge/Tests-713-brightgreen?style=for-the-badge" alt="713 Tests">
   <img src="https://img.shields.io/badge/AHI-9.7%2F10-brightgreen?style=for-the-badge" alt="AHI 9.7/10">
   <img src="https://img.shields.io/badge/Languages-TS%20%7C%20JS%20%7C%20Go%20%7C%20Python-blue?style=for-the-badge" alt="Multi-language">
   <img src="https://img.shields.io/badge/Cloud-Zero-orange?style=for-the-badge" alt="Zero Cloud">
@@ -24,7 +24,7 @@ AI proposes edit -> NREKI intercepts in RAM -> Compiler/LSP validates
   |              Some remain? ------> Full rollback. Disk untouched. Errors returned to agent.
 ```
 
-3 tools. 712 tests. 4 languages. Works with any MCP-compatible agent. Apache 2.0.
+3 tools. 713 tests. 4 languages. Works with any MCP-compatible agent. Apache 2.0.
 
 ---
 
@@ -147,6 +147,120 @@ 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)
+
+The 2,080-line God Object `nreki-kernel.ts` was decomposed into 4 focused modules:
+
+- `mutex.ts` — AsyncMutex FIFO with timeout protection
+- `types.ts` — All interfaces + IoC contracts (`TsHealingContext`, `LspHealingContext`)
+- `ttrd.ts` — Pure functions: `extractRawSignatures`, `detectSignatureRegression`, `isToxicType`
+- `healer.ts` — Both healers rewritten with Inversion of Control — healers no longer touch VFS, vfsClock, or tsBackend directly. Testable in isolation.
+
+### Production Hardening (v8.2)
+
+- **Token Drift Heartbeat** — Replaced call-count heuristic (15 calls) with token-physics (15,000 tokens default). ENV override: `NREKI_DRIFT_THRESHOLD`. Telemetry injected into header: `(Drift: X tokens | Limit: Y)`.
+- **Search Engine Segregation** — `VectorIndex` and `KeywordIndex` extracted to `src/search/`. Pure JavaScript, zero SQLite coupling. Ready for `node:sqlite` migration in v9.0.
+- **Handler Barrel Pattern** — 1,119-line `handlers/code.ts` split into `code/kernel-bridge.ts`, `code/read.ts`, `code/edit.ts`, `code/utils.ts`. Rate limiter stays in router (correct layer separation).
+- **WASM Deps Frozen** — `sql.js` and `tree-sitter-wasms` pinned to exact versions. No silent breakage from upstream updates.
+
+### Rayleigh Residual Guard (v8.3)
+
+Added a 4th defense layer to the spectral power iteration. Post-convergence, the solver computes `||Mv - μv||∞` and dies with `NaN` if the residual exceeds `1e-3`. This traps silent IEEE 754 drift that slips past the 3 existing guards (thermal, divergence, numerical sanity firewall).
+
+### interceptAtomicBatch Phase Extraction (v8.3)
+
+The 520-line ACID orchestrator was flattened into 3 private methods within `NrekiKernel`:
+
+- `phase1_injectVfs` — Path jail + VFS injection
+- `phase2_validateSidecars` — Go/Python LSP validation
+- `phase4_healingCascade` — Dual healer cascade (TS CodeFix API + LSP codeAction)
+
+Catch path untouched. ACID rollback semantics intact. The orchestrator now reads like a document.
+
+### engine.ts Flattening (v8.3)
+
+- **SessionTracker class** — Session state (`sessionSavings`) encapsulated. Saves one `Embedder.estimateTokens(content)` call per compression.
+- **`indexFile` split** — 124-line method → 28-line orchestrator + `indexPlaintextFallback` + `indexAstChunks`.
+- **`search` split** — 93-line method → 27-line orchestrator + `applyTectonicRelevanceScoring`.
+- **DB Facade grouping** — Delegation wrappers visually grouped under explicit `Facade` section headers.
+
+---
+
 ## The Architecture
 
 NREKI has 3 validation layers with multi-language support:
@@ -324,7 +438,7 @@ Re-injects 4-layer session state every ~15 tool calls to survive context compact
 
 | Metric | Value |
 |--------|-------|
-| Tests | 712 (44 suites) |
+| Tests | 713 (44 suites) |
 | Architecture Health Index | 9.7/10 (self-scored) |
 | Languages | 4 (TypeScript, JavaScript, Go, Python) |
 | Failure modes sealed | 32 (P1-P32) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ruso-0/nreki",
-  "version": "8.0.2",
+  "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",
@@ -60,8 +60,8 @@
     "@modelcontextprotocol/sdk": "^1.12.1",
     "chokidar": "^4.0.3",
     "picomatch": "^4.0.3",
-    "sql.js": "^1.12.0",
-    "tree-sitter-wasms": "^0.1.13",
+    "sql.js": "1.14.1",
+    "tree-sitter-wasms": "0.1.13",
     "web-tree-sitter": "^0.24.7",
     "zod": "^3.24.2"
   },