# KẾ HOẠCH 08 — Context Compression / Token Optimizer (nén đầu vào/đầu ra)

> Năng lực **nén prompt/context để giảm token · latency · cost** — nhưng **không phá governance**.
>
> Status 2026-07-06: **🟡 Track 3 MVP implemented + tested (CASAN-native token-killer).**
> `packages/casan-harness/scripts/bash/context-compress.py` — compressor deterministic của CASAN
> (KHÔNG dùng lại RTK): modes `dedup`/`extractive`/`structural`, must-keep luôn giữ,
> tee raw-passthrough khi lệnh fail, báo `token_saved`/`ratio`, và gate must-keep
> fail-able. Test `packages/casan-harness/tests/phase08-compression-tests.sh` **7/0 (WSL)**; đã nối
> vào `ci-harness-gate.sh` (`phase08-compression`). Còn: Track 1 nén INPUT + Track 2
> nén VIEW liên-bước + Track 4 abstractive (gated) + nối H4/H5 scan/hash trong pipeline thật.
>
> Nhãn: [có] tồn tại thật · [đo] đã kiểm chứng · [mới] cần làm · [chưa tự động] có đo/người quyết.
> Phụ thuộc: **01** (đường dẫn sau restructure) · **07** (thứ tự scan/audit an toàn, V19/V5) · **03** (chế độ abstractive dùng model).

## 1. Bối cảnh & câu hỏi
- Ngoài thị trường có thật: **LLMLingua / LongLLMLingua / LLMLingua-2** (Microsoft Research), **PromptFlow** LLMLingua tool, **LangChain ContextualCompressionRetriever** (nén tài liệu RAG trước khi vào LLM).
- **RTK — Rust Token Killer** ([rtk-ai/rtk](https://github.com/rtk-ai/rtk)): CLI proxy nén **output của lệnh** (git/test/log/build…) trước khi vào context, giảm 60–90% token bằng 4 chiến lược deterministic: **Smart Filtering · Grouping · Truncation · Deduplication**, có `tee` (lưu raw đầy đủ khi lệnh fail) và analytics `rtk gain`. **Chỉ dùng làm reference ý tưởng** — CASAN **TỰ XÂY module tương tự**, **KHÔNG dùng lại binary RTK**, để giữ chủ quyền + đưa vào đúng luồng governance (scan raw → hash → nén → scan compressed).
- **Repo hiện tại [đo — grep toàn repo]:** *chưa có* module nén prompt/context. Chỉ có truncation tên nhánh + vài gợi ý "summarize" trong prompt speckit + `max_tokens` trong 1 test. → Đây là **năng lực mới**.

## 2. Quyết định kiến trúc — **KHÔNG tạo H8**
Nén là **capability cắt ngang**, không phải harness thứ 8 (tránh phình kiến trúc 7 harness):

> **H1.5 Context Compression / Token Optimizer** — cross-cutting capability, **chủ sở hữu H1 (context) + H6 (budget)**, được **verify bởi H3/H4/H5**, dùng **H2** cho tool-output và **H7** cho chunk/retry.

### 2.1 Map phần → harness
| Phần | Harness chính | Vai trò |
|---|---|---|
| Chọn/rút gọn/dedup/summarize context đầu vào | **H1** | owner nén input |
| Nén output "view cho bước sau" (KHÔNG nén artifact cuối) | **H1** (context memory) | giảm token liên-bước |
| Nén tool-output dài (log/search/terminal) | **H2 + H1** | H2 kiểm quyền, H1 nén phần liên quan |
| Kiểm nén **không mất ý** (faithfulness) | **H3** | gate ngữ nghĩa |
| Scan raw **và** bản nén (injection/secret/PII) | **H4** | trước & sau nén |
| Audit raw + compressed + ratio + policy | **H5** | bằng chứng bất biến |
| Token/cost budget: khi nào nén, ratio, token saved | **H6** | chính sách chi phí |
| Chunk/retry/resume khi quá dài / nén fail | **H7** | điều phối |

**Lớp chính nếu phải chọn một:** **H1 Context**, dưới kiểm soát **H6 budget**, verify bởi **H3/H4/H5**.

## 3. Nguyên tắc AN TOÀN (bắt buộc — tinh chỉnh so với bản thảo)
1. **Scan + audit RAW TRƯỚC khi nén.** Nén trước có thể **xoá dấu injection** hoặc **mất bằng chứng gốc**. Thứ tự: `H4 scan raw → H5 hash raw → H1 nén → H3 faithfulness → H4 scan compressed → H5 audit compressed+ratio → model`.
2. **Scan LẠI sau khi nén.** Bản nén có thể *vô tình sinh* hoặc *che* nội dung độc → H4 phải quét cả bản nén.
3. **Must-keep invariants (điểm mới quan trọng):** một tập **mệnh đề bắt buộc giữ** — đặc biệt **yêu cầu phủ định / ràng buộc bảo mật** (vd *"Không gửi dữ liệu người dùng lên cloud model"*). Nén **cấm** làm rớt các mệnh đề này; H3 REJECT nếu mất.
4. **Không dùng nén để NÉ H4.** Vì luôn scan-after-compress, nén không thể là đường lách bảo mật.
5. **Abstractive = một model-call** → chịu **H4** (compressor có thể bị inject), **H6** (tốn token), **H3** (có thể ảo). Do đó abstractive phải gated, không mặc định.
6. **Artifact cuối KHÔNG nén.** Code/spec/plan/audit/test-log chính thức giữ **full** để review/rollback/audit; chỉ tạo **compressed view** cho bước kế.

## 4. Bốn chế độ nén
| Mode | Dùng khi | Rủi ro |
|---|---|---|
| `extractive` | giữ nguyên câu/đoạn quan trọng | thấp nhất — **ưu tiên** |
| `structural` | log/spec dài → JSON/table ngắn | thấp — **ưu tiên** |
| `semantic-dedup` | loại trùng giữa nhiều artifact/history | trung |
| `abstractive` | tóm tắt bằng model, tiết kiệm mạnh | **cao** (mất ý/ảo) → gated |

> **Khuyến nghị:** bắt đầu **extractive + structural**; **hoãn abstractive** cho requirement/spec (dễ mất chi tiết), chỉ bật sau khi H3 faithfulness + must-keep vững.

## 5. Luồng chuẩn
```
1. Nhận raw (input / artifact / tool-output)
2. H4 scan raw            (injection/secret/PII)
3. H5 ghi hash raw        (bằng chứng gốc)
4. H6 check token budget  → nếu KHÔNG vượt: dùng raw, bỏ qua nén
5. Nếu vượt budget:
   a. H1 nén (mode phù hợp) + giữ must-keep invariants
   b. H3 kiểm faithfulness (không mất ý / không rớt must-keep)
   c. H4 scan bản nén
   d. H5 audit: hash raw + hash compressed + ratio + mode + policy
6. Đưa bản nén vào model
7. Lưu artifact FULL riêng (không mất dữ liệu gốc)
```

## 6. Module layout (đề xuất)
Trước restructure (hiện tại):
```
packages/casan-harness/scripts/bash/compress-context.sh        # H1 owner
packages/casan-harness/scripts/python/context-compress.py       # extractive/structural/dedup
packages/casan-harness/scripts/bash/token-budget-check.sh        # H6
packages/casan-harness/scripts/python/verify-compression.py      # H3 faithfulness + must-keep
.specify/level5/compression-policy.yaml            # mode, ratio, must-keep, budget
```
Sau restructure (khớp Plan 01):
```
src/gates/h1-context/compress-context.sh
src/gates/h1-context/context-compress.py
src/gates/h6-agentops/token-budget-check.sh
src/gates/h3-eval/verify-compression-faithfulness.py
config/compression-policy.yaml
```

## 7. Tasks theo track

### Track 1 — MVP: nén INPUT (extractive + structural)
| Task | Việc | Verify | Done |
|---|---|---|---|
| 1.1 | `compression-policy.yaml`: mode, ratio target, **must-keep patterns**, token budget | policy load được | có policy |
| 1.2 | `token-budget-check.sh` (H6): tính token input; vượt → bật nén | input dài → trả `NEED_COMPRESS` | H6 quyết định |
| 1.3 | `context-compress.py` extractive + structural (giữ must-keep) | nén ra ≤ budget, giữ must-keep | có bản nén |
| 1.4 | Chèn đúng thứ tự an toàn: scan-raw → hash-raw → nén → H3 → scan-compressed → audit | log đúng trình tự | thứ tự an toàn |
| 1.5 | `verify-compression-faithfulness.py` (H3): REJECT nếu rớt must-keep | test rớt must-keep → REJECT | H3 gate |
| 1.6 | H5 audit raw+compressed+ratio+mode | sửa 1 bên → `AUDIT_HASH_MISMATCH` | bằng chứng |
| 1.7 | H4 scan bản nén | payload trong bản nén → BLOCK | scan-after |

**Cổng ra Track 1:** input dài được nén an toàn, giữ must-keep, có audit ratio; 35/35 + 43/43 không tụt.

### Track 2 — Nén VIEW liên-bước (artifact full giữ nguyên)
| Task | Việc | Verify | Done |
|---|---|---|---|
| 2.1 | STEP sinh artifact dài → lưu **full** + tạo **compressed view** cho bước sau | full + view cùng tồn tại | không mất gốc |
| 2.2 | H3 kiểm view không mất yêu cầu quan trọng | rớt yêu cầu → REJECT | faithfulness |
| 2.3 | H5 audit cả full + view | hash cả hai | truy vết |

### Track 3 — Nén TOOL-OUTPUT (H2 + H1)
| Task | Việc | Verify | Done |
|---|---|---|---|
| 3.1 | Tool trả log/output dài → H4 scan raw → H5 hash → H1 nén phần liên quan → H4 scan nén | tool-output dài → nén qua đúng flow | không đưa thẳng vào model |
| 3.2 | Nối với Plan-07 C1/V7 (tool authorization + tool-output scan) | tool-output độc → BLOCK trước nén | an toàn |

#### Track 3 — tự xây token-killer tương tự RTK (KHÔNG dùng lại RTK)
Xây **module CASAN-native** lấy ý tưởng từ RTK, nhưng là code của CASAN, để giữ chủ
quyền và nhúng đúng luồng governance. **Không phụ thuộc binary RTK, không auto-
rewrite hook** (pipeline CASAN chạy bash script, không phải agent tool-call):

| Ý tưởng từ RTK | CASAN tự xây (module riêng) | Ràng buộc governance |
|---|---|---|
| Smart Filtering / Grouping / Truncation | `context-compress.py` mode `structural`/`extractive` cho tool-output (git/test/lint/log) | luôn deterministic; không cần model |
| Deduplication (gộp dòng log lặp + đếm) | `semantic-dedup` cho log dài | giữ dòng unique |
| `tee` — lưu raw đầy đủ khi lệnh **fail** | bắt buộc giữ artifact FULL + hash RAW (đã là nguyên tắc mục 3) | fail ⇒ không nén, giữ raw để debug |
| `rtk gain` analytics (token saved/ratio) | metric `token_saved`/`ratio` tự tính → H6 telemetry + dashboard | nguồn số liệu cho Control Plane (Plan-13) |
| `config.toml` (exclude_commands, tee mode) | `compression-policy.yaml` | **settings quản lý qua Control Plane (Plan-13)**, đổi phải H5 audit |

| Task | Việc | Verify | Done |
|---|---|---|---|
| 3.3 | Thư viện filter tool-output CASAN-native theo loại (git/test/lint/log/build) — đặt SAU `H4 scan raw → H5 hash raw`, trước `H4 scan compressed` | log 200 dòng test → còn ~20 dòng failures-only, đúng thứ tự scan/audit | có filter deterministic (code CASAN) |
| 3.4 | Coverage filter cho ≥N loại lệnh (git/test/lint/build/log/pkg-manager), mở rộng dần như RTK — **không** phụ thuộc binary ngoài | mỗi loại có filter + test benign giữ đúng thông tin | self-contained, không external dep |
| 3.5 | Bật/tắt + cấu hình filter qua `compression-policy.yaml` (managed bởi Plan-13) | đổi policy → hành vi nén đổi, có audit | policy-driven |

### Track 4 — Abstractive + semantic-dedup (gated, làm sau)
| Task | Việc | Verify | Done |
|---|---|---|---|
| 4.1 | `abstractive` qua model-router (chịu H4/H6) | bật sau cờ; đo token saved | gated |
| 4.2 | H3 faithfulness nghiêm cho abstractive (must-keep 100%) | rớt bất kỳ must-keep → REJECT | an toàn ngữ nghĩa |
| 4.3 | `semantic-dedup` giữa history/artifact | loại trùng, giữ unique | dedup đúng |

## 8. Test faithfulness & must-keep (red-team)
| Test | Kỳ vọng |
|---|---|
| `adv-compression-drops-negative-requirement` (rớt *"Không gửi dữ liệu lên cloud"*) | H3 **REJECT** |
| `adv-compression-drops-edge-case` (mất điều kiện biên) | H3 REJECT |
| `adv-compression-drops-security-instruction` | H3 REJECT |
| `adv-compressed-carries-injection` (bản nén chứa payload) | H4 **BLOCK** (scan-after) |
| `adv-abstractive-hallucinated-summary` (nghe đúng nhưng sai) | H3 REJECT |
| `benign-compression-ratio` (nén hợp lệ) | PASS + đo token saved |

## 9. Rủi ro
| Rủi ro | Giảm thiểu |
|---|---|
| Nén mất requirement/edge/security | must-keep invariants + H3 faithfulness bắt buộc |
| Nén che injection | luôn scan-after-compress (H4) |
| Abstractive ảo | gated + H3 nghiêm + ưu tiên extractive |
| Mất bằng chứng gốc | scan/hash RAW trước nén; lưu artifact full |
| Nén thành đường né H4 | scan cả raw & compressed |
| Compressor model bị inject (V5) | H4 quét input của compressor + tách tiêu chí/nội dung |

## 10. Liên kết Plan-07
- **V19 Data exfil:** nén có thể *giúp* (strip secret trước cloud) hoặc *hại* (lộ qua summary) → phải qua C3 data-exfil check.
- **V5 classifier/compressor injection:** abstractive compressor là model → gia cố như judge.
- **H6 budget (V12/V13):** compression feed `token_saved`, `ratio` vào telemetry; nén là công cụ giữ ngân sách.

## 11. Tiêu chí HOÀN THÀNH
- [ ] Track 1: input nén extractive+structural, giữ must-keep, đúng thứ tự scan/audit, có H3 gate.
- [ ] Artifact cuối KHÔNG bị nén; chỉ có compressed view cho bước sau (Track 2).
- [ ] Tool-output nén qua H2+H1+H4 (Track 3), không đưa thẳng vào model.
- [ ] Abstractive gated sau cờ, H3 must-keep 100% (Track 4).
- [ ] Red-team faithfulness (mục 8) xanh; benign đo được `token_saved`/`ratio`.
- [ ] 35/35 + 43/43 không tụt.

## 12. Ghi chú trung thực
- Toàn bộ Plan 08 là **[mới]** — repo hiện chưa có module nén ([đo] grep xác nhận).
- Không tạo H8; đây là **capability dưới H1/H6**, verify bởi H3/H4/H5.
- Giá trị: giảm token/cost **và** giúp CASAN giống một **AI-SDLC platform** thật, nhưng chỉ đáng làm **sau khi Plan-07 core (Track A + C-MVP) vững** — nén thêm bề mặt rủi ro nên phải có governance trước.

---

_Liên quan: `CASAN_PLAN_07_PRODUCTION_HARDENING.md` (thứ tự an toàn, V19/V5) · `CASAN_PLAN_01_RESTRUCTURE.md` (đường dẫn) · `CASAN_PLAN_03_CLOUD_PATCH.md` (abstractive dùng model) · `CASAN_PLAN_13_CONTROL_PLANE.md` (compression-policy là settings quản lý qua Control Plane) · reference: [rtk-ai/rtk](https://github.com/rtk-ai/rtk)._