# Matryca Plumber v1.8.0 — Edge Software Optimization Plan

**Status:** Shipped in **1.8.0** (see [`CHANGELOG.md`](../CHANGELOG.md) `[1.8.0]`).  
**Baseline:** [`v1.8-OPTIMIZATION-PLAN.md`](v1.8-OPTIMIZATION-PLAN.md) (KV-cache sessions, memory budget, cooperative yield).  
**OpenSpec:** [`openspec/llm-performance.md`](openspec/llm-performance.md)

**Constraint:** CPU-only, 16 GB RAM, ≤10k Markdown pages — Python orchestration only (no model quantization).

**I/O timing:** Cooperative **micro-yields** (2 ms batch pauses, `yield_host`) live in the optimization plan — they are **not** thermal pauses. Thermal sleeps are ≥ 1 s and run only after LLM turns; see [`v1.8-OPTIMIZATION-PLAN.md`](v1.8-OPTIMIZATION-PLAN.md#thermal-pauses-vs-cooperative-micro-yield).

---

## TRIZ framing

| Directive | TRIZ principle | Mechanism |
|-----------|----------------|-----------|
| 1 CPU sandbox | Extraction | Isolate Plumber on 1–2 cores; leave L3 for LLM tensor ops |
| 2 Frozen prefix | Prior Action | Immutable `[SYSTEM]+[STABLE_CONTEXT]` + SHA-256 before each call |
| 3 Adaptive LLM | Mechanical substitution + nested fallback | Logits grammar when available; else 3-try self-correction |
| 3b Resilient JSON | Separation in space + prior action + self-service | `max_tokens`, balanced-brace extract, Gemma tail repair, compression/history prose sanitize, stateless insights — [`resilience-llm-json-triz.md`](resilience-llm-json-triz.md) |
| 4 mmap reads | Parameter change | Kernel paging instead of heap strings during Phase 1 |

---

## Directive 1 — L3 cache isolation

**Module:** [`src/agent/process_priority.py`](../src/agent/process_priority.py)

- `probe_cpu_topology()` — physical vs logical core counts
- `resolve_cpu_sandbox_config()` — env `MATRYCA_CPU_SANDBOX`, `MATRYCA_PLUMBER_CPU_AFFINITY`
- `apply_cpu_sandbox()` — `cpu_affinity`, `nice(19)`, `IOPRIO_CLASS_IDLE`, Windows idle class
- Degrades to `apply_plumber_priority()` when `psutil` is missing

**Operator:** Pin Ollama/LM Studio to the *other* cores manually; Plumber must not share the LLM mask.

---

## Directive 2 — Deterministic KV prefix

**Modules:** [`page_prompt_session.py`](../src/agent/page_prompt_session.py), [`prompt_layout.py`](../src/agent/prompt_layout.py)

- `FrozenPromptPrefix` — frozen dataclass, `prefix_sha256`, `verify_unchanged()`, `append_task()`
- Canonical delimiter `CANONICAL_TASK_HEADER` — no `.strip()` on stable body
- `PagePromptSession.frozen` — telemetry `kv_prefix_hash` on LLM turns

---

## Directive 3 — Adaptive structured output

**Module:** [`src/agent/llm_client.py`](../src/agent/llm_client.py)

**Product rule:** Graph quality > CPU speed.

| Path | When | Behavior |
|------|------|----------|
| **A** | `GrammarCapability.LOGITS_JSON_SCHEMA` | Single request, strict `json_schema`, zero validation retries |
| **B** | Legacy / `JSON_OBJECT` / probe miss | Up to 3 self-correction turns with `ValidationError` feedback; `parse_llm_json` once per attempt |
| **Degrade** | Exhausted retries | `StructuredOutputExhaustedError` → page `status=error` |

- `probe_backend()` at first completion / daemon start
- `InstructorLLMClient` base in `llm_client.py`; `index_page` subclass hook in `maintenance_daemon.py`
- **Resilience layer:** `resolve_llm_max_completion_tokens()`; `sanitize_llm_completion_text()`; [`json_repair.py`](../src/utils/json_repair.py) (first-delimiter extract, string-aware trailing trim, nesting-stack bracket balance) — documented in [`resilience-llm-json-triz.md`](resilience-llm-json-triz.md)

---

## Directive 4 — mmap graph reads

**Module:** [`src/graph/markdown_io.py`](../src/graph/markdown_io.py)

- `mmap_graph_page()` context manager, `MmapTextView`
- Bootstrap regex path: `extract_catalog_fields_from_mmap()` in [`master_catalog.py`](../src/graph/master_catalog.py)
- Env: `MATRYCA_GRAPH_READ_MMAP`, `MATRYCA_MMAP_MIN_BYTES`

---

## Verification

```bash
uv run pytest tests/test_llm_client_adaptive.py tests/test_page_prompt_session.py \
  tests/test_process_priority.py tests/test_markdown_io.py -q
make perf   # slow soak
```

---

## Related

- [`v1.8-OPTIMIZATION-PLAN.md`](v1.8-OPTIMIZATION-PLAN.md)
- [`openspec/llm-performance.md`](openspec/llm-performance.md)
