chore: import upstream snapshot with attribution

docs/MEMORY_BUDGET.md

@@ -0,0 +1,150 @@
+# Memory Regression Budget
+
+Status: active guardrail
+Updated: 2026-04-18
+
+This document defines the current memory regression budget for jcode.
+
+The goal is not to freeze memory usage forever. The goal is to make memory changes:
+- measurable
+- reviewable
+- intentionally justified
+
+Where possible, budgets below are tied to counters and caps already exposed by the codebase rather than guessed RSS numbers.
+
+## How to collect the metrics
+
+Use existing debug surfaces instead of ad hoc instrumentation:
+
+- TUI aggregate memory profile: `:debug memory`
+- TUI memory sample history: `:debug memory-history`
+- Markdown cache profile: `:debug markdown:memory`
+- Mermaid cache profile: `:debug mermaid:memory`
+- Agent/session memory profile via debug socket: `agent:memory`
+
+Primary sources in code:
+- `src/tui/app/debug_cmds.rs`
+- `src/tui/memory_profile.rs`
+- `src/session.rs`
+- `src/tui/markdown.rs`
+- `src/tui/mermaid.rs`
+- `src/runtime_memory_log.rs`
+
+## Budget model
+
+We use two kinds of budgets:
+
+1. Hard caps
+- These are explicit limits already enforced by caches.
+- Regressions here mean the code changed its bound or bypassed it.
+
+2. Ratchet expectations
+- These are expected relationships between memory counters.
+- Regressions here are allowed only with explanation and updated docs/tests.
+
+## Hard caps
+
+### Markdown cache budget
+
+Source: `src/tui/markdown.rs`
+
+| Metric | Budget | Why |
+|---|---:|---|
+| `highlight_cache_entries` | `<= 256` | Explicit cache cap (`HIGHLIGHT_CACHE_LIMIT`) |
+
+Required review action if violated:
+- explain why the cache limit changed
+- update this doc
+- update any affected tests or benchmarks
+
+### Mermaid cache budget
+
+Sources:
+- `src/tui/mermaid.rs`
+- `src/tui/mermaid_cache_render.rs`
+
+| Metric | Budget | Why |
+|---|---:|---|
+| `render_cache_entries` | `<= 64` | Explicit render-cache cap (`RENDER_CACHE_MAX`) |
+| `image_state_entries` | `<= 12` | Explicit protocol-state cap (`IMAGE_STATE_MAX`) |
+| `source_cache_entries` | `<= 8` | Explicit decoded-source cap (`SOURCE_CACHE_MAX`) |
+| `active_diagrams` | `<= 128` | Explicit active-diagram cap (`ACTIVE_DIAGRAMS_MAX`) |
+| `cache_disk_png_bytes` | `<= 50 MiB` | Explicit on-disk cache cap (`CACHE_MAX_SIZE_BYTES`) |
+| `cache_disk_max_age_secs` | `<= 259200` | 3-day expiry (`CACHE_MAX_AGE_SECS`) |
+
+Required review action if violated:
+- document the new limit and reason
+- verify eviction still works
+- verify no unbounded growth path was introduced
+
+## Ratchet expectations
+
+### Session and transcript memory
+
+Source: `src/session.rs`, `src/tui/memory_profile.rs`
+
+These are not strict caps yet, but they are expected relationships.
+
+| Metric relationship | Expectation |
+|---|---|
+| `provider_messages_cache.count` vs `messages.count` | Should remain in the same order of magnitude for a single session, and normally track the transcript closely |
+| `session_provider_cache_json_bytes` vs `canonical_transcript_json_bytes` | Should remain comparable for normal chat flows, not explode independently |
+| `transient_provider_materialization_json_bytes` | Should return to zero or near-zero outside active materialization-heavy paths |
+| `display_large_tool_output_bytes` | Large values require explanation because they usually mean raw tool output is being retained too aggressively in the UI |
+
+Required review action if violated:
+- show before/after memory profiles
+- explain which retention path grew
+- prefer fixing duplication before raising any budget
+
+### Runtime memory log expectations
+
+Source: `src/runtime_memory_log.rs`
+
+Runtime memory logs are the regression detection mechanism, not just a debug feature.
+
+Expected behavior:
+- server/client logs should be sufficient to explain large changes in:
+  - session/transcript totals
+  - provider cache totals
+  - TUI display totals
+  - side panel totals
+- new large memory owners should emit attributable signals instead of appearing only as unexplained RSS growth
+
+Required review action if violated:
+- add or improve attribution before accepting the memory increase
+
+## Review checklist for memory-affecting changes
+
+When changing memory-heavy code, capture and include:
+
+1. Which counters changed?
+- aggregate `:debug memory`
+- targeted `:debug markdown:memory` / `:debug mermaid:memory`
+- `agent:memory` when session/provider cache behavior changes
+
+2. Was a hard cap changed?
+- if yes, explain why the old cap was insufficient
+
+3. Did duplication increase?
+- canonical transcript
+- provider cache
+- materialized provider view
+- display copy
+- side-panel copy
+
+4. Did observability remain adequate?
+- if memory grew, can logs/profiles explain where?
+
+## Current initial budget summary
+
+These are the concrete enforced limits today:
+
+- Markdown highlight cache entries: 256
+- Mermaid render cache entries: 64
+- Mermaid protocol image-state entries: 12
+- Mermaid decoded source-cache entries: 8
+- Mermaid active diagrams: 128
+- Mermaid on-disk PNG cache: 50 MiB, max age 3 days
+
+Any intentional change to those limits must update this document in the same PR.