# Architecture

## Decision

V0.1 is technically feasible on DeepSeek Harness 0.1.0-rc.8 using the public
`tools/post-execute` waterfall. It is a host-only Cordis bundle and does not
modify Core or register replacement tools.

## Pipeline

```text
ToolExecutionResult
  -> call next() (respect downstream tool/result transforms)
  -> accept/content-only guard
  -> plain-text block extraction
  -> inspector (size, estimated tokens, type, tool name)
  -> enabled / excluded / threshold checks
  -> processor router (log | JSON | HTML | text)
  -> evidence and budget guard
  -> retain original with official spillStore
  -> transparent compression notice + locator
  -> accept with replacement content
  -> official spill-policy hard-size fallback
  -> DSH materialization and tools/result
```

## Invariants

1. Never replace canonical `value`.
2. Never mutate `exec`, `result`, content blocks, or decisions.
3. Preserve non-text and mixed content unchanged.
4. Preserve `additionalContexts` from downstream decisions.
5. Return the original if inspection, parsing, compression, retention, or
   notice assembly throws.
6. Do not replace content unless the final output is smaller.
7. Mark all omissions and estimate token counts honestly.
8. Default to retaining the original through the official spill store.

## Processors

- **Log:** head + evidence windows + unique stack-trace roots + tail; collapse
  repeated lines/blocks with exact repeat counts.
- **JSON:** structural/key overview, important/error-bearing records,
  representative samples, and exact per-array omitted counts.
- **HTML:** parse rules, remove script/style/svg/noscript/comments, retain
  semantic text, tables, lists, links, and code. If extraction is unreliable,
  fall back to conservative text processing or the original.
- **Text:** normalize excessive whitespace and collapse exact duplicate lines
  or paragraphs; use conservative evidence/head/tail selection only when still
  over budget.

## Token estimation and budgets

`TokenEstimator` is an interface. V0.1 uses a fast character-class estimate,
with denser accounting for CJK text. No provider tokenizer is bundled.

`minTokens` controls activation, `targetTokens` guides processor budgets, and
`maxTokens` is a final safety ceiling. Configuration validation requires:

```text
0 < minTokens <= maxTokens
0 < targetTokens <= maxTokens
```

## Retention and reversibility

Replacing presentation content also changes the durable tool-result content.
The canonical JSON value is still preserved by DSH, but it is not a substitute
for the formatted original. Before replacement, V0.1 stores the full formatted
text through `ctx.spillStore.saveText` and includes the returned locator and
retrieval hint. With default `retainOriginal: true`, missing storage causes a
fail-open pass-through.

## Relationship to native compaction

This plugin reduces new large results. Native spill remains the hard-size and
retrieval fallback; native compaction/pruning still manages accumulated history.
The systems are complementary. Compression output is append-only, so it does
not rewrite earlier messages or invalidate an already reusable KV-cache prefix.

## Deferred

- Web dashboard and `/squeeze` command
- command-specific processor catalog
- provider tokenizers
- non-text/media processing
- nested `run_code` dispatch-log transformation
- adaptive or LLM-based summarization