# RTK Compression (Igbo)

🌐 **Languages:** 🇺🇸 [English](../../../../compression/RTK_COMPRESSION.md) · 🇪🇹 [am](../../../am/docs/compression/RTK_COMPRESSION.md) · 🇸🇦 [ar](../../../ar/docs/compression/RTK_COMPRESSION.md) · 🇦🇿 [az](../../../az/docs/compression/RTK_COMPRESSION.md) · 🇧🇬 [bg](../../../bg/docs/compression/RTK_COMPRESSION.md) · 🇧🇩 [bn](../../../bn/docs/compression/RTK_COMPRESSION.md) · 🇧🇦 [bs](../../../bs/docs/compression/RTK_COMPRESSION.md) · 🇨🇿 [cs](../../../cs/docs/compression/RTK_COMPRESSION.md) · 🇩🇰 [da](../../../da/docs/compression/RTK_COMPRESSION.md) · 🇩🇪 [de](../../../de/docs/compression/RTK_COMPRESSION.md) · 🇬🇷 [el](../../../el/docs/compression/RTK_COMPRESSION.md) · 🇪🇸 [es](../../../es/docs/compression/RTK_COMPRESSION.md) · 🇪🇪 [et](../../../et/docs/compression/RTK_COMPRESSION.md) · 🇮🇷 [fa](../../../fa/docs/compression/RTK_COMPRESSION.md) · 🇫🇮 [fi](../../../fi/docs/compression/RTK_COMPRESSION.md) · 🇫🇷 [fr](../../../fr/docs/compression/RTK_COMPRESSION.md) · 🇮🇪 [ga](../../../ga/docs/compression/RTK_COMPRESSION.md) · 🇮🇳 [gu](../../../gu/docs/compression/RTK_COMPRESSION.md) · 🇳🇬 [ha](../../../ha/docs/compression/RTK_COMPRESSION.md) · 🇮🇱 [he](../../../he/docs/compression/RTK_COMPRESSION.md) · 🇮🇳 [hi](../../../hi/docs/compression/RTK_COMPRESSION.md) · 🇭🇷 [hr](../../../hr/docs/compression/RTK_COMPRESSION.md) · 🇭🇺 [hu](../../../hu/docs/compression/RTK_COMPRESSION.md) · 🇦🇲 [hy](../../../hy/docs/compression/RTK_COMPRESSION.md) · 🇮🇩 [id](../../../id/docs/compression/RTK_COMPRESSION.md) · 🇮🇹 [it](../../../it/docs/compression/RTK_COMPRESSION.md) · 🇯🇵 [ja](../../../ja/docs/compression/RTK_COMPRESSION.md) · 🇬🇪 [ka](../../../ka/docs/compression/RTK_COMPRESSION.md) · 🇰🇭 [km](../../../km/docs/compression/RTK_COMPRESSION.md) · 🇮🇳 [kn](../../../kn/docs/compression/RTK_COMPRESSION.md) · 🇰🇷 [ko](../../../ko/docs/compression/RTK_COMPRESSION.md) · 🇱🇹 [lt](../../../lt/docs/compression/RTK_COMPRESSION.md) · 🇱🇻 [lv](../../../lv/docs/compression/RTK_COMPRESSION.md) · 🇮🇳 [ml](../../../ml/docs/compression/RTK_COMPRESSION.md) · 🇮🇳 [mr](../../../mr/docs/compression/RTK_COMPRESSION.md) · 🇲🇾 [ms](../../../ms/docs/compression/RTK_COMPRESSION.md) · 🇲🇹 [mt](../../../mt/docs/compression/RTK_COMPRESSION.md) · 🇲🇲 [my](../../../my/docs/compression/RTK_COMPRESSION.md) · 🇳🇵 [ne](../../../ne/docs/compression/RTK_COMPRESSION.md) · 🇳🇱 [nl](../../../nl/docs/compression/RTK_COMPRESSION.md) · 🇳🇴 [no](../../../no/docs/compression/RTK_COMPRESSION.md) · 🇮🇳 [or](../../../or/docs/compression/RTK_COMPRESSION.md) · 🇮🇳 [pa](../../../pa/docs/compression/RTK_COMPRESSION.md) · 🇵🇭 [phi](../../../phi/docs/compression/RTK_COMPRESSION.md) · 🇵🇱 [pl](../../../pl/docs/compression/RTK_COMPRESSION.md) · 🇵🇹 [pt](../../../pt/docs/compression/RTK_COMPRESSION.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/compression/RTK_COMPRESSION.md) · 🇷🇴 [ro](../../../ro/docs/compression/RTK_COMPRESSION.md) · 🇷🇺 [ru](../../../ru/docs/compression/RTK_COMPRESSION.md) · 🇱🇰 [si](../../../si/docs/compression/RTK_COMPRESSION.md) · 🇸🇰 [sk](../../../sk/docs/compression/RTK_COMPRESSION.md) · 🇸🇮 [sl](../../../sl/docs/compression/RTK_COMPRESSION.md) · 🇷🇸 [sr](../../../sr/docs/compression/RTK_COMPRESSION.md) · 🇸🇪 [sv](../../../sv/docs/compression/RTK_COMPRESSION.md) · 🇰🇪 [sw](../../../sw/docs/compression/RTK_COMPRESSION.md) · 🇮🇳 [ta](../../../ta/docs/compression/RTK_COMPRESSION.md) · 🇮🇳 [te](../../../te/docs/compression/RTK_COMPRESSION.md) · 🇹🇭 [th](../../../th/docs/compression/RTK_COMPRESSION.md) · 🇹🇷 [tr](../../../tr/docs/compression/RTK_COMPRESSION.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/compression/RTK_COMPRESSION.md) · 🇵🇰 [ur](../../../ur/docs/compression/RTK_COMPRESSION.md) · 🇺🇿 [uz](../../../uz/docs/compression/RTK_COMPRESSION.md) · 🇻🇳 [vi](../../../vi/docs/compression/RTK_COMPRESSION.md) · 🇳🇬 [yo](../../../yo/docs/compression/RTK_COMPRESSION.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/compression/RTK_COMPRESSION.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/compression/RTK_COMPRESSION.md)

---

Mkpokọta RTK bụ injin mkpokọta OmniRoute nke maara iwu, maka nsonaazụ terminal na ngwaọrụ. E
mepụtara ya maka nnọkọ coding-agent ebe ọtụtụ uto context si na ndekọ ule, nsonaazụ build,
mkpọtụ package manager, transcript shell, nsonaazụ Docker, nsonaazụ git, na stack trace.

RTK nwere ike iji `defaultMode: "rtk"` rụọ ọrụ ozugbo ma ọ bụ bụrụ nzọụkwụ mbụ na pipeline e jikọtara ọnụ, nke na-abụkarị:

```txt
rtk -> caveman
```

Usoro ahụ na-ebu ụzọ chịkọta nsonaazụ igwe nwere mkpọtụ, wee kwe ka Caveman chịkọta prose fọdụrụ.

RTK upstream na-akọ na a na-echekwa `60-90%` nke nsonaazụ iwu. Nnọkọ atụ dị na README ya si na
token ọkọlọtọ `~118,000` gbadaa na token RTK `~23,900`, nke pụtara na echekwara `79.7%` (`~80%`). OmniRoute na-eji
nkezi upstream ahụ maka mgbakọ ego echekwara site na nchịkọta e jikọtara ọnụ ya na mkpokọta input Caveman:

```txt
Nkezi RTK:      echekwara 80%
Input Caveman:  echekwara 46%
Ejikọtara ọnụ: 1 - (1 - 0.80) * (1 - 0.46) = echekwara 89.2%
Oke:           1 - (1 - 0.60..0.90) * (1 - 0.46) = 78.4-94.6%
```

## Ihe Ọ Na-akpakọ

Ndepụta arụnyere ugbu a na-ebufe ihe nzacha 56 n'ofe otú ndị a:

| Ụdị       | Ihe atụ                                                        |
| --------- | -------------------------------------------------------------- |
| `git`     | `git status`, `git branch`, `git diff`, `git log`              |
| `test`    | Vitest, Jest, Pytest, PHPUnit, Playwright, Go, ule Cargo       |
| `build`   | TypeScript, ESLint, Biome, Prettier, Vite, Webpack, Turbo, Nx  |
| `package` | `npm install`, `npm audit`, `pip`, `uv sync`, Poetry, Bundler  |
| `shell`   | `ls`, `find`, `grep`, ndekọ shell izugbe                       |
| `docker`  | `docker ps`, ndekọ Docker                                      |
| `infra`   | Terraform, OpenTofu, `systemctl status`                        |
| `generic` | mmepụta JSON, nleba stack, ihe ndabere azụ maka mmepụta izugbe |

Ihe nchọpụta dị na `open-sse/services/compression/engines/rtk/commandDetector.ts` na-ekewa mmepụta
tupu a họrọ ihe nzacha. Ihe nzacha nwekwara ike ịkwekọ site na ụkpụrụ iwu ma ọ bụ regex mmepụta
mgbe klaasị iwu na-ezughị.

## Mkpebi Filter

RTK na-ebunye filter n'usoro a:

1. Filter project sitere na `.rtk/filters.toml` na `.rtk/filters.json`, naanị mgbe a tụkwasịrị ha obi.
2. Filter global sitere na `DATA_DIR/rtk/filters.toml` na `DATA_DIR/rtk/filters.json`.
3. Filter e wuru n'ime ya sitere na `open-sse/services/compression/engines/rtk/filters/`.

N'ime scope otu, filter RTK TOML schema v1 na-ebute filter OmniRoute JSON ụzọ. A na-enyocha expression TOML
`match_command` tupu command-type matching ka filter a bubatara nke metụtara otu iwu kpọmkwem nwee ike dochie
filter sara mbara n'ime scope ahụ. Scope project ka na-ebute scope global ụzọ,
n'agbanyeghị format faịlụ.

A na-ama ụma achọ ntụkwasị obi maka filter project n'ihi na filter regex nwere ike ịgbanwe otu esi
egosi agent nsonaazụ ngwaọrụ. A na-anabata faịlụ filter project mgbe otu n'ime ihe ndị a bụ eziokwu:

- `rtkConfig.trustProjectFilters` bụ `true`.
- Etinyere `OMNIROUTE_RTK_TRUST_PROJECT_FILTERS=1`.
- `.rtk/trust.json` nwere hash SHA-256 kwekọrọ na faịlụ filter project ahụ.

Ihe atụ faịlụ ntụkwasị obi:

```json
{
  "filtersSha256": "0123456789abcdef...",
  "filtersTomlSha256": "fedcba9876543210..."
}
```

Hash ndị ahụ dị iche: `filtersSha256` tụkwasịrị `.rtk/filters.json` obi, ebe `filtersTomlSha256`
tụkwasịrị `.rtk/filters.toml` obi. Idezi nke ọ bụla n'ime faịlụ ndị ahụ na-eme ka naanị ntinye ntụkwasị obi nke ya ghara ịdị irè. Faịlụ global
bụ ndị administrator wụnyere ma na-eji omume ntụkwasị obi filter global dịbu adị.

Filter omenala nwere ike ịbụ otu object filter ma ọ bụ array nke object filter. A na-amafere filter omenala na-adịghị irè
ma `/api/context/rtk/filters` diagnostics na-akọ ha. Filter e wuru n'ime ya na-adịghị irè na-eme ka usoro ahụ daa ozugbo.

## Ndakọrịta RTK TOML schema v1

OmniRoute nwere ike ịgụ, nyochaa, nwalee, ma wụnye faịlụ nzacha ndị e kọwara n'ụzọ nkwupụta site na iji RTK TOML schema v1.
Ubi ndị a na-akwado bụ `description`, `match_command`, `strip_ansi`, `filter_stderr`,
`strip_lines_matching`, `keep_lines_matching`, `replace`, `match_output`, `truncate_lines_at`,
`head_lines`, `tail_lines`, `max_lines`, `on_empty`, na nnwale inline `[[tests.<filter>]]`.
A na-ajụ ubi ndị a na-amaghị, regular expressions ndị na-ezighi ezi ma ọ bụ na-adịghị nchebe, iwu strip/keep ndị e tinyere n'otu oge, faịlụ karịrị
1 MiB, na ntụaka na nzacha ndị a na-amaghị. Enwere ike inyocha faịlụ nke nnwale inline ya dara maka nyocha, mana enweghị ike
ịwụnye ma ọ bụ budata ya. Ọdịda n'ịbudata faịlụ omenala ka na-eji usoro
fail-open: a na-amafe faịlụ na-ezighi ezi, ebe nzacha ndị ọzọ na-aga n'ihu na-arụ ọrụ.

OmniRoute na-anata nsonaazụ ngwá ọrụ mgbe client ahụ nwụcharala ya, ya mere `filter_stderr = true`
enweghị ike ịgbanwe otu e si ejide process ahụ. A na-anabata ubi ahụ dị ka no-op, nyocha nkwado ahụ na-ewepụtakwa ịdọ aka ná ntị.
A na-akọwa nke a ụma dị ka **ndakọrịta RTK TOML schema v1**, ọ bụghị ndakọrịta zuru oke
na RTK executable, shell hooks, mmejuputa iwu Rust, ma ọ bụ nhazi trust-store ya.

Nlele RTK dị elu nke dashboard na-anabata TOML e mado ma ọ bụ e bulite. Nnyocha nkwado bụ naanị maka ịgụ.
Nwụnye na-ede `DATA_DIR/rtk/filters.toml` n'ụzọ atomic yana ikikere siri ike ma na-eme ka
katalọgụ nzacha dị ndụ dị ọhụrụ na-enweghị restart. Iji dochie faịlụ dị adị chọrọ nkwenye `overwrite`
doro anya ma buru ụzọ mepụta `DATA_DIR/rtk/filters.toml.bak`.

## DSL nzacha

Nzacha na-eji JSON schema a kọwara na [Ụdị Iwu Mkpakọ](./COMPRESSION_RULES_FORMAT.md).
Runtime na-etinye usoro ndị a n'usoro:

```txt
stripAnsi -> filterStderr -> replace -> matchOutput -> tụfuo/tinye ahịrị
  -> truncateLineAt -> head/tail/maxLines -> onEmpty
```

Ubi ndị dị mkpa:

| Ubi                          | Ebumnuche                                                           |
| ---------------------------- | ------------------------------------------------------------------- |
| `rules.stripAnsi`            | Wepụ usoro agba/njikwa terminal tupu matching                       |
| `rules.filterStderr`         | Hazie prefixes stderr ndị a na-ahụkarị tupu matching/filtering      |
| `rules.replace`              | Tinye nnọchi regex n'usoro                                          |
| `rules.matchOutput`          | Weghachite nchịkọta mkpirikpi mgbe nsonaazụ dabara na ọnọdụ a maara |
| `rules.matchOutput[].unless` | Mafere ụzọ mkpirisi ahụ mgbe ụkpụrụ njehie/ọdịda dị                 |
| `rules.dropPatterns`         | Wepụ ahịrị ndị na-eme mkpọtụ                                        |
| `rules.includePatterns`      | Nye ahịrị ndị a pụrụ ime ihe na ha mkpa                             |
| `rules.collapsePatterns`     | Kpokọta ahịrị ndị na-emegharị ugboro ugboro ma kwekọọ               |
| `rules.deduplicate`          | Opt-in maka nzacha ọ bụla: kpokọta ahịrị oyiri ndị na-esochi ibe ha |
| `rules.truncateLineAt`       | Mbepụ ahịrị ọ bụla nke na-echekwa Unicode                           |
| `rules.onEmpty`              | Ozi ndabere ma ọ bụrụ na e wepụ ahịrị niile                         |
| `tests[]`                    | Ihe nlele inline nke verify gate na-eji                             |

A na-atụ anya na nzacha arụnyere n'ime ga-agụnye ihe nlele inline `tests[]`. Nzacha omenala kwesịkwara ịgụnye
ha, karịsịa mgbe a na-ekekọrịta ha n'etiti projects.

## Iwepụ Ahịrị Ndị Megharịrị Emegharị (ọkwa abụọ)

RTK na-ejikọta ahịrị ndị megharịrị emegharị n'ọkwa abụọ na-adabereghị onwe ha:

1. **`deduplicate` nke nzacha ọ bụla (a ga-ahọrọ itinye ya n'ọrụ, ndabara bụ `false`).** Nzacha nwere ike ịtọ `rules.deduplicate: true`
   iji jikọta ahịrị ndị megharịrị emegharị nke na-esochi onwe ha _n'ime nsonaazụ dabara na nzacha ahụ_, tupu ebipụ ya.
   Nke a na-arụ ọrụ n'ime `lineFilter.ts`. Maka nzacha ochie, a na-eme ka ọ rụọ ọrụ na-akpaghị aka mgbe nzacha ahụ kọwara
   `collapsePatterns`. Schema: `deduplicate: z.boolean().default(false)` n'ime
   `open-sse/services/compression/engines/rtk/filterSchema.ts`.
2. **`deduplicateThreshold` nke injin niile (ndabara bụ `3`).** Mgbe nzacha niile rụchara ọrụ, injin ahụ na-ejikọta
   usoro ọ bụla nwere `>= deduplicateThreshold` ahịrị yiri onwe ha kpamkpam nke na-esochi onwe ha n'ime nsonaazụ niile
   (`deduplicateRepeatedLines`, nke etinyere n'ọrụ na `engines/rtk/index.ts`). A na-amachi uru ahụ n'etiti 2–100 mgbe
   a na-eme nhazi ya ka ọ bụrụ otu ụkpụrụ.

Usoro nke nzacha ọ bụla na-ebu ụzọ rụọ ọrụ (n'ime nzacha ahụ), usoro nke injin niile na-arụ ọrụ n'ikpeazụ (n'elu
nsonaazụ ejikọtara ọnụ), ya mere ha abụọ na-arụkọ ọrụ n'agụghị otu ihe ugboro abụọ.

## Ịchịkọta Ahịrị (`enableGrouping`)

Mgbe `rtkConfig.enableGrouping` bụ `true` (ndabara bụ `false`), RTK na-agba usoro `groupSimilarLines`
ọzọ n'elu nsonaazụ e wepụcharala ihe ndị megharịrị emegharị, nke na-ejikọta usoro ahịrị ndị _fọrọ nke nta ka ha bụrụ otu_ (ọ bụghị ndị yiri onwe ha n'otu byte n'otu byte)
ma na-esochi onwe ha. `rtkConfig.groupingThreshold` (ndabara bụ `3`) bụ ogologo usoro kacha nta nke na-akpalite
ịchịkọta. Nke a bụ ogbo nhazi nke kwekọrọ na `deduplicateThreshold`: dedup na-ahụ maka nkwughachi ndị yiri onwe ha kpamkpam,
ịchịkọta na-ahụ maka "otu nhazi ahụ nwere obere ọdịiche". Ọkọlọtọ abụọ ahụ bụ akụkụ nke JSON `rtkConfig`
echekwara n'ime tebụl `key_value` (lee Nhazi dị n'elu), ya mere ntọala ahụ na-adịgide mgbe ebidogharịrị sistemụ.

## Iwepụ Nkwupụta Koodu (`stripCodeComments` / `preserveDocstrings`)

Mgbe agbanyere `rtkConfig.applyToCodeBlocks`, RTK nwekwara ike iwepụ nkwupụta n'ime ngọngọ koodu ndị e ji fence kaa ókè:

- `stripCodeComments` (ndabara bụ `false`) — a ga-ahọrọ itinye ya n'ọrụ. Mgbe ọ bụ `true`, RTK na-ewepụ nkwupụta n'ime ngọngọ JavaScript
  na TypeScript ndị e ji fence kaa ókè. N'akụkọ ihe mere eme, a na-agụ ọkọlọtọ ahụ mana anaghị etinye ya n'ọrụ, ya mere ndabara ahụ ka bụ
  "chekwaa" iji zere mgbanwe mmepụta nke mere na-enweghị ọkwa.
- `preserveDocstrings` (ndabara bụ `true`) — mgbe a na-ewepụ nkwupụta, a na-edobe nkwupụta ngọngọ JSDoc/`/** … */`
  (ha nwere akwụkwọ API bara uru karịa bytes ha na-eri). Tọọ ya ka ọ bụrụ `false` iji wepụkwa
  ha.

E tinyere iwepụ nkwupụta n'ọrụ n'ime `open-sse/services/compression/engines/rtk/codeStripper.ts`. Ọ na-eji
**parser TypeScript** (ọ bụghị regex) ka e wee ghara iwere string, template, na regex literals
dị ka nkwupụta n'amaghị ama, ọ na-akwụsịkwa usoro ahụ kpamkpam mgbe achọpụtara JSX (ka a ghara
imebi nkwupụta dị n'ime expression-container nke JSX). Ka ọ dị ugbu a, iwepụ nkwupụta na-emetụta naanị **JavaScript na TypeScript** — asụsụ
ndị ọzọ dị na setị `CodeLanguage` nke stripper (Python, Rust, Go, Ruby, Java) nwere mkpakọ ahịrị efu na
oghere ọcha, mana ha enweghị iwepụ nkwupụta. A na-enye usoro ngọngọ e wepụchara akara `rtk:code-strip` n'ime
`rulesApplied`.

> **Mara — GCF / encoding tebụl bụ injin dị iche.** RTK enweghị **"GCF"**
> (Graph Compact Format) encoder JSON nke tebụl/kọlụm. Encoder ahụ — nke nọchiri encoder ochie
> `omni-tabular` — dị n'ime injin **headroom**
> (`open-sse/services/compression/engines/headroom/`, ebe codec e tinyere n'ime ngwugwu dị n'okpuru
> `headroom/gcf/`). O nweghị njikọ na pipeline nzacha RTK akọwara ebe a.

## Nhazi

Ntọala zuru ụwa ọnụ dị site na `/api/settings/compression`. Ntọala ndị metụtara RTK dịkwa
site na `/api/context/rtk/config`.

```json
{
  "defaultMode": "stacked",
  "autoTriggerMode": "stacked",
  "autoTriggerTokens": 32000,
  "stackedPipeline": [
    { "engine": "rtk", "intensity": "standard" },
    { "engine": "caveman", "intensity": "full" }
  ],
  "rtkConfig": {
    "enabled": true,
    "intensity": "standard",
    "applyToToolResults": true,
    "applyToCodeBlocks": false,
    "applyToAssistantMessages": false,
    "enabledFilters": [],
    "disabledFilters": [],
    "maxLinesPerResult": 120,
    "maxCharsPerResult": 12000,
    "deduplicateThreshold": 3,
    "customFiltersEnabled": true,
    "trustProjectFilters": false,
    "rawOutputRetention": "never",
    "rawOutputMaxBytes": 1048576,
    "enableGrouping": false,
    "groupingThreshold": 3,
    "stripCodeComments": false,
    "preserveDocstrings": true
  }
}
```

`enabledFilters` na `disabledFilters` na-eji NJ ndị nzacha, dịka ọmụmaatụ `test-vitest` ma ọ bụ `git-diff`.

A kọwara ọdịdị `rtkConfig` zuru ezu site na `RtkConfig` / `DEFAULT_RTK_CONFIG` n'ime
`open-sse/services/compression/types.ts`. A na-echekwa ihe ahụ niile dịka otu uru JSON n'ime
tebụl SQLite `key_value` n'okpuru `namespace = "compression"`, `key = "rtkConfig"`
(`src/lib/db/compression.ts`), `normalizeRtkConfig` na-ahazikwa ya mgbe a na-agụ ya. Ya mere, mpaghara ọ bụla dị n'okpuru
— gụnyere `enableGrouping`, `groupingThreshold`, `stripCodeComments`, na `preserveDocstrings` —
na-agafe otu ebe nchekwa ahụ ma na-adịgide mgbe ebidogharịrị sistemụ.

| Igodo                  | Ndabara | Ebumnuche                                                                                            |
| ---------------------- | ------- | ---------------------------------------------------------------------------------------------------- |
| `deduplicateThreshold` | `3`     | Maka injin niile: ọnụọgụ kacha nta nke ahịrị ndị yiri onwe ha n'usoro iji chịkọta ha (n'etiti 2–100) |
| `enableGrouping`       | `false` | Nhọrọ onye ọrụ: chịkọta usoro ahịrị ndị na-esochi ibe ha ma yie onwe ha nke ukwuu                    |
| `groupingThreshold`    | `3`     | Ọnụọgụ kacha nta nke ahịrị ndị yiri ibe ha n'usoro nke na-akpalite nchịkọta                          |
| `stripCodeComments`    | `false` | Nhọrọ onye ọrụ: wepụ nkọwa n'ime ngọngọ koodu nwere ngere (chọrọ `applyToCodeBlocks`)                |
| `preserveDocstrings`   | `true`  | Mgbe a na-ewepụ nkọwa, debe ngọngọ JSDoc/`/** … */`                                                  |

## API

| Ụzọ                                | Usoro | Ebumnuche                                           |
| ---------------------------------- | ----- | --------------------------------------------------- |
| `/api/context/rtk/config`          | GET   | Gụọ nhazi RTK                                       |
| `/api/context/rtk/config`          | PUT   | Melite nhazi RTK                                    |
| `/api/context/rtk/filters`         | GET   | Depụta katalọgụ nzacha na nyocha nsogbu nnabata     |
| `/api/context/rtk/import`          | POST  | Nyochaa ma ọ bụ wụnye faịlụ schema v1 RTK TOML      |
| `/api/context/rtk/test`            | POST  | Lelee mkpakọ RTK maka otu ibu ederede tupu oge eruo |
| `/api/context/rtk/raw-output/[id]` | GET   | Gụọ mmepụta raw e chekwara ma kpuchie ozi nzuzo     |
| `/api/compression/preview`         | POST  | Lelee ụdị mkpakọ ọ bụla tupu oge eruo               |

Ibu nnwale RTK:

```json
{
  "command": "npm test",
  "text": "FAIL tests/example.test.ts\nAssertionError: expected true\nTest Files 1 failed",
  "config": {
    "intensity": "standard"
  }
}
```

Ibu nlele mkpakọ:

```json
{
  "mode": "stacked",
  "messages": [
    {
      "role": "tool",
      "content": "FAIL tests/example.test.ts\nAssertionError: expected true\nTest Files 1 failed"
    }
  ],
  "config": {
    "rtkConfig": {
      "rawOutputRetention": "failures"
    }
  }
}
```

Ụzọ nchịkwa chọrọ njirimara nchịkwa dashboard ma ọ bụ iwu API-key kwekọrọ na ya.

Ibu nyocha RTK TOML:

```json
{
  "action": "validate",
  "content": "schema_version = 1\n\n[filters.my-tool]\nmatch_command = \"^my-tool\\\\b\"\nmax_lines = 20\n"
}
```

Jiri `"action": "install"` iji wụnye faịlụ a nyochara n'ụwa niile. Tinye `"overwrite": true` naanị
mgbe ị nyochachara ma kwenye na a ga-eji ya dochie faịlụ zuru ụwa ọnụ dị adị.

## Iweghachite Mmepụta Raw

RTK na-eweghachikarị naanị ederede ebelatara. Maka debugging, `rawOutputRetention` nwere ike idowe mmepụta raw e zoro akụkụ ụfọdụ:

| Uru        | Omume                                                        |
| ---------- | ------------------------------------------------------------ |
| `never`    | Edowela mmepụta raw                                          |
| `failures` | Dowe naanị mmepụta nwere ike ịbụ ọdịda                       |
| `always`   | Dowe mmepụta raw RTK ọ bụla ebelatara, mgbe e zoro ihe nzuzo |

A na-ede faịlụ ndị e dowere n'okpuru:

```txt
DATA_DIR/rtk/raw-output/
```

A na-ezo ihe nzuzo tupu e debe ha, gụnyere bearer tokens ndị a na-ahụkarị, API keys, Slack tokens,
AWS access keys, na ụkpụrụ e kenyere dịka `token=...`, `secret=...`, `password=...`. Analytics
na-echekwa naanị pointer id, nha, na metadata hash.

## Ọnụ Ụzọ Nkwenye

Ọnụ ụzọ nkwenye a lekwasịrị anya na-agba ule filter inline arụnyere n'ime ya na-enweghị ịkpọ iwu mpụga site na shell:

```bash
node --import tsx/esm --test tests/unit/compression/rtk-verify.test.ts
```

Ọnụ ụzọ RTK sara mbara bụ:

```bash
node --import tsx/esm --test \
  tests/unit/compression/rtk-*.test.ts \
  tests/unit/compression/pipeline-integration.test.ts \
  tests/unit/compression/context-compression-api.test.ts
```

Gbaa ọnụ ụzọ compression sara mbara tupu mwepụta:

```bash
node --import tsx/esm --test \
  tests/unit/compression/*.test.ts \
  tests/golden-set/*.test.ts \
  tests/integration/compression-pipeline.test.ts \
  tests/unit/api/compression/compression-api.test.ts
```

## Ịgbasa RTK

1. Tinye ma ọ bụ melite faịlụ JSON filter.
2. Gụnye opekata mpe otu ihe atụ `tests[]` nke na-egosi omume dị mkpa.
3. Tinye fixture n'okpuru `tests/unit/compression/fixtures/rtk/` maka ezinụlọ iwu ọhụrụ.
4. Tinye mkpuchi nchọpụta iwu mgbe ị na-ewebata klas mmepụta ọhụrụ.
5. Gbaa ọnụ ụzọ nkwenye na ọnụ ụzọ RTK sara mbara.
6. Ọ bụrụ na filter ahụ bụ naanị nke project ahụ, commit `.rtk/filters.json` ma mee ka `.rtk/trust.json` dị ọhụrụ naanị mgbe e nyochachara ya.

---

## Ọkwa Ike (v3.8.16+)

RTK na-akwado **ọkwa ike 3** nke na-ehaziri n'etiti **ike mkpakọ** na **nchekwa**. A na-edebe ọkwa ahụ site na `config.intensity` na nhazi engine.

### Ọkwa 3 ahụ

| Ọkwa                 | Ókè mbelata        | Nchekwa token | Ihe egwu         | Kacha dabara maka                    |
| -------------------- | ------------------ | ------------- | ---------------- | ------------------------------------ |
| `minimal`            | ahịrị 24 kwa nkebi | ~20-40%       | Dị ala nke ukwuu | Production nwere context dị oke mkpa |
| `standard` (ndabara) | ahịrị 24 kwa nkebi | ~50-70%       | Ala              | Oge ede koodu kwa ụbọchị             |
| `aggressive`         | ahịrị 16 kwa nkebi | ~70-90%       | Etiti            | Oge ogologo, nchekwa kacha elu       |

### Ebe Mbelata Na-eme

Ókè mbelata ahụ na-emetụta `lineFilter.ts`:

```ts
// Sitere na open-sse/services/compression/engines/rtk/index.ts:329-330
config.intensity === "aggressive" ? 16 : 24,
config.intensity === "aggressive" ? 16 : 24,
```

A na-edebe **mmalite** na **ngwụcha** nke nkebi ọ bụla; a na-ewepụ ọdịnaya nke etiti mgbe mbelata malitere.

### Ihe Na-anọ vs. Ihe A Na-ewepụ

| Ọdịnaya                     | minimal      | standard     | aggressive   |
| --------------------------- | ------------ | ------------ | ------------ |
| Njehie / stack traces       | ✅ echekwara | ✅ echekwara | ✅ echekwara |
| Ule dara ada                | ✅ echekwara | ✅ echekwara | ✅ echekwara |
| Njehie build                | ✅ echekwara | ✅ echekwara | ✅ echekwara |
| Ule gafere (nkọwa zuru ezu) | ✅ echekwara | 🟡 akpakọrọ  | 🟡 akpakọrọ  |
| Mmepụta ọdịnala (ndekọ ozi) | 🟡 akpakọrọ  | 🟡 akpakọrọ  | ❌ ewepụrụ   |
| Ogwe ọganihu                | 🟡 akpakọrọ  | ❌ ewepụrụ   | ❌ ewepụrụ   |
| Banner / nka ASCII          | 🟡 akpakọrọ  | ❌ ewepụrụ   | ❌ ewepụrụ   |

### Ịhọrọ Ike Kwesịrị Ekwesị

```
                  Ịla n'iyi context ọ bụ ọdachi?
                  │
      ┌───────────┼───────────┐
      │           │           │
     EE          MBA        AMAGHI
      │           │           │
      ▼           │           │
   minimal        │           │
      │           │           │
      │           ▼           ▼
      │      Kedu oke mkpa   Nwaa `standard` mbụ
      │      throughput?     (rụrụ ọrụ n'ihe 80%
      │           │          nke ọnọdụ)
      │      ┌────┴────┐
      │      │         │
      │     ALA       ELU
      │      │         │
      │      ▼         ▼
      │   standard   aggressive
      │      │         │
      └──────┴─────────┘
```

### Ịhazi Ike

**Kwa combo** (na nhazi combo):

```json
{
  "combo": "my-coding-combo",
  "routing": {/* ... */},
  "compression": {
    "engine": "rtk",
    "intensity": "aggressive"
  }
}
```

**Site na koodu**:

`rtkEngine` (`@omniroute/open-sse/services/compression/engines/rtk`) bụ
`CompressionEngine` nke na-enweghị usoro `updateConfig`. Kama nke ahụ, melite
nhazi engine site na enyemaka registry:

```ts
import { updateEngineConfig } from "@omniroute/open-sse/services/compression/engines/registry";

updateEngineConfig("rtk", { intensity: "aggressive" });
```

### Ịkwenye Mmetụta ahụ

Jiri **Verify Gate** (lee n'okpuru) hụ ma jide n'aka na ihe nzacha gị nwekwara nchekwa n'ọkwa ike ị họọrọ:

```ts
import { runRtkFilterTests } from "omniroute/compression/engines/rtk/verify";

const result = runRtkFilterTests({ intensity: "aggressive" });
if (!result.passed) {
  console.error("Filters failed at aggressive intensity");
}
```

---

## Mmepe Nzacha Ahaziri Ahazi (v3.8.16+)

Ndekọ `engines/rtk/filters/` nwere **faịlụ JSON nzacha arụnyere n'ime ya karịrị 49**. Ị nwere ike ịgbakwunye nke gị iji mpịakọta mmepụta sitere na ngwa ọrụ ahaziri ahazi ndị ndabara anaghị akwado.

### Schema Nzacha (Zod)

```ts
{
  "id": "string",                      // A chọrọ ya. Ihe njirimara nzacha (kebab-case, dịka, "python-traceback")
  "label": "string",                   // A chọrọ ya. Aha nzacha mmadụ nwere ike ịgụ
  "description": "string",             // Nhọrọ (ndabara: ""). Nkọwa dị mkpirikpi banyere ihe nzacha ahụ na-eme
  "category": "git|test|build|shell|docker|package|infra|cloud|generic",
  "priority": number,                  // Nhọrọ (0-100, ndabara: 50). Usoro mmezu (nke dị elu = nke mbụ)
  "match": {
    "commands": ["string"],            // Aha iwu ndị a ga-adakọ (dịka, "python", "pytest")
    "patterns": ["string"],            // Ụkpụrụ regex ndị a ga-eji dakọtara mmepụta
    "outputTypes": ["string"]          // Klas mmepụta achọpụtara (dịka, "test-failure")
  },
  "rules": {
    "stripAnsi": boolean,              // Nhọrọ (ndabara: false). Wepụ koodu agba ANSI
    "replace": [                       // Iwu ịchọta-na-dochie (ndabara: [])
      { "pattern": "regex", "replacement": "..." }
    ],
    "matchOutput": [                   // Kwụsị ozugbo mgbe ụkpụrụ dakọrọ (ndabara: [])
      {
        "pattern": "regex",
        "message": "short summary",
        "unless": "regex"              // Mafere ma ọ bụrụ na ụkpụrụ a dakọrọ
      }
    ],
    "includePatterns": ["string"],     // Ahịrị ndị a ga-edobe (ụkpụrụ regex, ndabara: [])
    "dropPatterns": ["string"],        // Ahịrị ndị a ga-ewepụ (ụkpụrụ regex, ndabara: [])
    "collapsePatterns": ["string"],    // Ahịrị ndị a ga-achịkọta ka ọ bụrụ naanị otu ngosipụta (ndabara: [])
    "deduplicate": boolean,            // Nhọrọ (ndabara: false). Wepụ ahịrị ndị megharịrị emegharị
    "truncateLineAt": number,          // Nhọrọ (ndabara: 0). Bepụ ahịrị ruo n'ọnụọgụ mkpụrụedemede kachasị
    "maxLines": number,                // Nhọrọ (ndabara: 0). Oke siri ike maka ngụkọta ahịrị
    "headLines": number,               // Nhọrọ (ndabara: 20). Debe ahịrị N mbụ nke mmepụta dakọrọ
    "tailLines": number,               // Nhọrọ (ndabara: 20). Debe ahịrị N ikpeazụ nke mmepụta dakọrọ
    "onEmpty": "string",               // Nhọrọ (ndabara: ""). Ozi ndabere ma ọ bụrụ na enyochara ahịrị niile
    "filterStderr": boolean            // Nhọrọ (ndabara: false). Nyochakwa mmepụta stderr
  },
  "preserve": {
    "errorPatterns": ["string"],       // Ụkpụrụ ndị a ga-edoberịrị mgbe niile (ndabara: [])
    "summaryPatterns": ["string"]      // Ụkpụrụ maka ahịrị nchịkọta ikpeazụ (ndabara: [])
  },
  "tests": [                           // Nnwale inline maka nkwenye (ndabara: [])
    {
      "name": "string",               // A chọrọ ya. Aha nnwale
      "input": "sample output",        // A chọrọ ya. Ederede ntinye nlele
      "expected": "expected output",   // A chọrọ ya. Mmepụta mpịakọ a tụrụ anya ya
      "command": "optional command"    // Nhọrọ. Ọnọdụ iwu
    }
  ]
}
```

### Ọmụmaatụ: Nzacha Python Traceback

```json
{
  "id": "python-traceback",
  "label": "Python Traceback Filter",
  "description": "Compresses Python tracebacks to essential file/line locations and error type",
  "category": "test",
  "priority": 60,
  "match": {
    "commands": ["python", "python3", "pytest", "uv", "poetry"],
    "patterns": ["Traceback \\(most recent call last\\)", "Error", "Exception"],
    "outputTypes": ["error-traceback"]
  },
  "rules": {
    "stripAnsi": true,
    "includePatterns": [
      "Traceback \\(most recent call last\\)",
      "^\\s*File \".+\", line \\d+",
      "^\\s*[A-Z][a-zA-Z]+Error:",
      "^\\s*[A-Z][a-zA-Z]+Exception"
    ],
    "dropPatterns": ["site-packages/", "^\\s+[a-z_]+\\([^)]*\\)$"],
    "headLines": 5,
    "tailLines": 3,
    "maxLines": 25,
    "filterStderr": true
  },
  "preserve": {
    "errorPatterns": ["Error:", "Exception:", "Traceback"],
    "summaryPatterns": ["^[A-Z][a-zA-Z]+(?:Error|Exception):"]
  },
  "tests": [
    {
      "name": "preserves-error-type-and-location",
      "input": "Traceback (most recent call last):\n  File \"app.py\", line 42, in main\n    do_thing()\n  File \"lib/utils.py\", line 17, in helper\n    return 1 / 0\nZeroDivisionError: division by zero",
      "expected": "Traceback (most recent call last):\n  File \"app.py\", line 42, in main\n  File \"lib/utils.py\", line 17, in helper\nZeroDivisionError: division by zero",
      "command": "python app.py"
    }
  ]
}
```

### Ịkwanye Nzacha Ahaziri Ahazi

Debe faịlụ ahụ n'ebe sistemụ na-amata:

```
~/.omniroute/rtk/filters/my-filter.json     # Ọkwa onye ọrụ
<project>/.rtk/filters/my-filter.json      # Ọkwa ọrụ ngo
```

A na-ebunye nzacha na-akpaghị aka mgbe sistemụ malitere site na `loadRtkFilters()` dị na `open-sse/services/compression/engines/rtk/filterLoader.ts`. Onye na-ebunye ya na-achọpụta nzacha site na:

- Katalọgụ arụnyere n'ime ya: `open-sse/services/compression/engines/rtk/filters/`
- Ndekọ onye ọrụ: `~/.omniroute/rtk/filters/`
- Ndekọ ọrụ ngo: `<project>/.rtk/filters/`

Iji koodu buru nzacha:

```ts
import { loadRtkFilters } from "@omniroute/open-sse/services/compression/engines/rtk/filterLoader";

// Nhọrọ: customFiltersEnabled (buru nzacha onye ọrụ/ọrụ ngo, agbanyere na ndabara),
// trustProjectFilters, refresh.
const filters = loadRtkFilters({ customFiltersEnabled: true });
```

### Nkwado Izi Ezi

A na-enyocha nzacha megide schema Zod mgbe a na-ebunye ha. Nzacha nwere nhazi na-adịghị mma agaghị ebunye, ọ ga-edekwa njehie:

```
RTK_FILTER_LOADER: filter "my-filter" failed validation:
  - rules.replace.0.pattern: Invalid regex
  - match.commands: must not be empty
```

Iji nyochaa nzacha niile arụnyere, kpọọ `runRtkFilterTests()` nke e si na `open-sse/services/compression/engines/rtk/verify.ts` ebupụ.

### Omume Kachasị Mma

1. **Na-etinye `tests[]` mgbe niile** — ha na-egosi na nzacha gị na-arụ ọrụ ma na-egbochi nlọghachi nke mmejọ
2. **Jiri `matchOutput` maka nkwụsị ngwa ngwa** — ọ bụrụ na otu ahịrị na-akọwa ihe niile, jiri ya dochie ngọngọ ahụ dum
3. **Ka `keep` ka mma karịa `strip`** — iwu doro anya nke “chekwaa mgbe niile” dị nchebe karịa nke “wepụ mgbe niile”
4. **Nwalee n'ọkwa ike atọ niile** — `minimal` ekwesịghị ime mgbanwe ọ bụla, ebe `aggressive` ka kwesịrị ichekwa njehie
5. **Jiri mpaghara `unless`** — jiri “akpalitela ma ọ bụrụ na X dị” chekwaa nkwụsị ngwa ngwa

---

## Iweghachite Mmepụta Izizi & Ọnụ Ụzọ Nkwenye

Mgbe RTK na-akpakọ mmepụta nke ukwuu, ị nwere ike **iweghachite ederede izizi** maka idozi nsogbu, nyocha, ma ọ bụ ịkpọgharị ya.

### Otu Iweghachite Mmepụta Izizi Si Arụ Ọrụ

```
Mmepụta izizi (token 10K)
        │
        ▼
RTK na-akpakọ (na rawOutput.enabled=true)
        │
        ├─▶ Mmepụta akpakọtara (token 2K)  ──▶ gaa na LLM
        │
        └─▶ Mmepụta izizi (token 10K)      ──▶ echekwara na DB
                                                  (request_id jikọtara ya)
```

### Ime Ka Nchekwa Mmepụta Izizi Rụọ Ọrụ

**Maka arịrịọ ọ bụla** (na nhazi combo):

```json
{
  "compression": {
    "engine": "rtk",
    "intensity": "aggressive",
    "rawOutput": {
      "enabled": true,
      "maxBytes": 1048576 // Oke 1MB
    }
  }
}
```

**Ndịabara**: `rawOutput.enabled: false` (na-echekwa ohere nchekwa).

### Ọnụ Ahịa Nchekwa

| Maka arịrịọ ọ bụla             | Oke 1MB         | Oke 10MB         |
| ------------------------------ | --------------- | ---------------- |
| Nkezi mmepụta akpakọtara       | ~5KB            | ~5KB             |
| Mmepụta izizi echekwara        | ~50-500KB       | ~500KB-5MB       |
| Site na arịrịọ 1000 kwa ụbọchị | 50-500MB/ụbọchị | 500MB-5GB/ụbọchị |

> **Nkwado**: Mee ka mmepụta izizi rụọ ọrụ naanị maka **oge idozi nsogbu** ma ọ bụ **nyocha e họpụtara ụfọdụ nlele maka ya**, ọ bụghị mgbe niile.

### Iweghachite Nke Izizi

```ts
import { readRtkRawOutput } from "omniroute/compression/engines/rtk/rawOutput";

const raw = readRtkRawOutput(pointerId); // pointerId sitere na ọnụ ọgụgụ mkpakọ
if (raw) {
  console.log("Original output:", raw);
}
```

A na-eweghachi `pointerId` na `CompressionStats.rtkRawOutputPointers[]` mgbe mkpakọ gasịrị.
Lee `open-sse/services/compression/engines/rtk/rawOutput.ts:102` maka mbinye aka ọrụ ahụ.

### Ọnụ Ụzọ Nkwenye

**Nkwenye Nzacha RTK** (`open-sse/services/compression/engines/rtk/verify.ts`) na-enyocha nzacha niile site na `tests[]` ha ma hụ na omume ha ziri ezi n'ọkwa ike 3 niile.

**Kpọọ `runRtkFilterTests()`** iji mee nkwenye:

```ts
import { runRtkFilterTests } from "open-sse/services/compression/engines/rtk/verify";

const result = runRtkFilterTests();
console.log(`Passed: ${result.outcomes.filter((o) => o.passed).length}`);
console.log(`Failed: ${result.outcomes.filter((o) => !o.passed).length}`);
if (!result.passed) {
  console.error("Filters failed verification");
  result.outcomes
    .filter((o) => !o.passed)
    .forEach((o) => {
      console.error(
        `  - ${o.filterId} / ${o.testName}: expected "${o.expected}", got "${o.actual}"`
      );
    });
}
```

**Ihe ọ na-enyocha**:

1. Nzacha ọ bụla na-eburu nke ọma ma gafee nkwenye schema
2. Ndenye ọ bụla dị na `tests[]` na-emepụta mmepụta a tụrụ anya ya
3. Ọkwa ike `minimal` anaghị eme mgbanwe ọ bụla (ọ na-edobe nke izizi, ma na-etinye naanị nzacha nhazi)
4. Ọkwa ike `aggressive` na-edobe njehie, ọdịda ule, na stack traces
5. Mmepụta akpakọtara anaghị ebu ibu karịa ntinye izizi

- Isi mmalite: `open-sse/services/compression/engines/rtk/` (faịlụ 63, ~70KB)

- **Tupu ijikọta mgbanwe nzacha** — hụ mgbe niile na ule niile gafere
- **Mgbe emelitechara injin RTK** — schema nwere ike ịgbanweela
- **Kwa oge n'ime nlekota** — na-echebe megide mgbanwe na-atụghị anya ya na test fixtures
- **Mgbe ị na-agbakwunye ezinụlọ ngwa ọrụ/iwu ọhụrụ** — na-egosi na nzacha ọhụrụ ahụ na-arụ ọrụ

---

## Hụkwa

- [COMPRESSION_GUIDE.md](./COMPRESSION_GUIDE.md) — Nchịkọta zuru ezu nke usoro mkpakọ
- [COMPRESSION_ENGINES.md](./COMPRESSION_ENGINES.md) — Ndebanye igwe na igwe ndị e wuru n'ime ya
- [EXTENDING_COMPRESSION.md](./EXTENDING_COMPRESSION.md) — Igwe ahaziri iche, ngwugwu asụsụ, na usoro ndị a chịkọtara n'elu ibe ha
- Isi mmalite: `open-sse/services/compression/engines/rtk/` (faịlụ 63, ~70KB)