Merge pull request 'docs(core): snapcompact accuracy audit — measured shape table + pricing law' (#82) from docs/81-snapcompact-accuracy into main

omp-docs/core/index.md

@@ -16,5 +16,6 @@ These files define the structural conventions that govern the agent system itsel
 * [OMP Status Line Customization](statusline.md) — How presets, composer shapes, and segment arrays actually interact; the fleet's tuned bar. (moved from /pi/, 2026-10-19)
 * [OMP Subagent Limits & Fan-out Policy](subagent-limits.md) — Live caps: concurrency 2, no nested spawns (the `maxRecursionDepth: 0` trap), per-endpoint in-flight ceilings, isolation policy. (moved from /pi/, 2026-10-19)
 * [WAN Model Access](wan-model-access.md) — Driving the fleet's models from outside the home network through the OpenWebUI door: the command, the key file and its rotation law, what the door publishes, and the off-network failure modes.
+* [OMP Snapcompact — Bitmap-Frame Compaction](snapcompact.md) — What shape frank-archon actually reads, the measured recall/billing table, the `imageCountBudget` knob and the pricing that isn't, and the 85 % trigger law.
 
 **Change log:** the bundle keeps exactly one, one level up — [Bundle Change Log](../log.md). A directory here never has its own.

omp-docs/core/snapcompact.md

@@ -0,0 +1,113 @@
+---
+type: concept
+title: OMP Snapcompact — Bitmap-Frame Compaction
+description: How snapcompact archives session history as bitmap frames, what shape frank-archon resolves to, the measured recall/billing table behind the fleet's settings, and the models.yml knobs that actually exist.
+resource: https://github.com/can1357/oh-my-pi/tree/main/packages/snapcompact
+tags:
+  - omp
+  - compaction
+  - snapcompact
+  - frank-archon
+verified: 2026-10-27
+timestamp: 2026-10-27
+---
+
+# OMP Snapcompact — Bitmap-Frame Compaction
+
+Snapcompact is omp's automatic-maintenance method that replaces the LLM
+summarizer call with a local, deterministic archival pass: discarded history is
+serialized, whitespace-collapsed, and printed onto dense PNG frames of
+pixel-font glyphs that a vision-capable model reads back directly. No model,
+key, or network is involved, so it also serves overflow recovery. It runs only
+when the current model's row declares `input` including `image`; otherwise
+maintenance advances to the next method in `compaction.methodOrder`.
+
+Fleet position (`agent/config.yml`): `methodOrder: [shake, snapcompact, soft,
+handoff, remote]` — deterministic, lossless-first. Shake elides heavy blocks to
+`artifact://` references before anything is archived; snapcompact then archives
+what shake couldn't reclaim; the lossy LLM lanes (`soft`/`handoff`/`remote` via
+frank-zealot) should never be reached while a vision endpoint is active.
+
+## Shape resolution for the fleet
+
+The frame shape (font grid + pitch + frame width) resolves from the **model
+id** against a measured table, falling back to the **wire API family** when the
+id is unmeasured:
+
+| Matcher | Shape | Frame |
+|---|---|---|
+| claude (fable/mythos) | `11on16-bw` | 1932px |
+| claude | `11on16-bw` | 1568px |
+| gemini | `8on22-bw` | 2048px |
+| gpt / codex | `8on22-bw` | 1568px |
+| kimi | `8on22-bw` | 1568px |
+| glm | `8on16-bw` | 1568px |
+| openai-completions wire (unmeasured id) | `8on22-bw` | 1568px |
+
+There is **no qwen matcher**: `frank-archon` (radiance, Qwen3.8 vision tower,
+`openai-completions` wire) resolves via the wire fallback to `8on22-bw`
+@1568px — which is 56 clean 28px token-rows for a Qwen-style ViT. `snapcompact.shape`
+stays `auto`; forcing a variant would bypass the font-aware CJK escape hatch
+(`silver16-bw`).
+
+## Measured recall and billing (frank-archon, 2026-10-27)
+
+A 212,916-char tool-traffic transcript with 8 planted unique facts was sent to
+`frank-archon` four ways (probe: `@oh-my-pi/snapcompact` renderer, production
+request shape, `omp` 18.12.5-era bundle):
+
+| Leg | Frames | Billed prompt tokens | Recall |
+|---|---|---|---|
+| Plain text baseline | — | 63,066 | 8/8 |
+| auto = `8on22-bw` | 14 | 33,533 | **8/8** |
+| forced `8on16-bw` | 11 | 24,364 | 6/8 (dropped characters) |
+| forced `11on16-bw` | 14 | 33,533 | 6/8 (dropped characters) |
+
+Laws this established:
+
+- **The default shape is the accurate one for the fleet.** The Qwen3.8 FP8
+  tower OCRs `8on22-bw` pixel fonts with full recall; both denser grids drop
+  single characters inside identifiers — matching upstream's toolbench finding
+  (spacing-tuned cells won everywhere; dense prose-era shapes erase line
+  structure).
+- **Bitmap archive ≈ 47 % of the billed tokens of raw text at equal recall.**
+- **True radiance billing is ~2,400 tokens/frame; the harness charges a blind
+  5,024 floor.** Unpriced custom endpoints get `FRAME_TOKEN_ESTIMATE` (5,024)
+  per frame in archive sizing, so archives plan roughly half the frames the
+  window actually fits. This is conservative (never overflows) and costs
+  recall-per-compaction.
+
+## The knobs that exist (and the one that doesn't)
+
+- `imageCountBudget: 16` (top-level models.yml row field, set on
+  `frank-archon`): the catalog never matches custom providers, so the
+  unknown-provider floor of **5 images per request** silently caps archives.
+  Radiance accepted 14 frames in one probe request; 16 leaves margin. Real
+  frame count stays bounded by the sizing law below.
+- `imageTokenization` is **catalog-only** (compiled KDL compat rules; no
+  user-row key reaches the pricing path). A custom row cannot mark frames
+  verified or price them — until upstream prices `openai-completions` vision,
+  custom-endpoint archive capacity is count-bound.
+- Archive sizing law: frames get **half the room left under the compaction
+  threshold** after system prompt, tools, and kept recent turns; the compacted
+  result targets ≤ 60 % of threshold, and post-compaction headroom must reach
+  the 80 % recovery band.
+- `snapcompact.systemPrompt: none` and `snapcompact.toolResults: false` stay
+  off fleet-wide: imaging inline text is a token-cost lever that routes
+  always-loaded instructions through the OCR path — accuracy-negative.
+
+## The 85 % trigger law
+
+`compaction.thresholdPercent: 85` on frank-archon is load-bearing for the
+max_tokens clamp documented in `agent/models.yml`:
+`170,000 est × 1.03 + 16,384 ≤ 200,000`. At 95 % the clamp squeezes output to
+~6 k near the trigger and the worst-case request overshoots the window, so
+radiance **refuses** and compaction reroutes through the overflow-recovery
+emergency path instead of the planned threshold pass.
+
+## Follow-ups
+
+- `frank-dragoon` / `frank-zealot` rows carry the same unpriced vision towers;
+  the count budget and probe apply to them but are unmeasured there.
+- Re-run the probe after the next upstream snapcompact/omp release (renderer
+  and shape table move under us).

omp-docs/log.md

@@ -22,6 +22,22 @@ not restated here — entry, then pointer. That is what the 2026-10-21 audit pas
 newest twelve entries: the facts stayed, the duplicates went, `git log --follow` keeps the
 long form.
 
+## 2026-10-27
+
+### Snapcompact audited against frank-archon; the blind frame price is the real limit
+
+A live recall probe (212,916-char archive, 8 planted facts, four legs) against
+frank-archon: the auto shape `8on22-bw` reads back at full recall for 47 % of
+the billed tokens of raw text, while both denser grids drop characters inside
+identifiers — `snapcompact.shape: auto` stays. `thresholdPercent` returns 95 →
+85 (the max_tokens gap math in `models.yml` was written for 85; 95 routes
+compaction through the overflow-refuse path). `imageCountBudget: 16` lands on
+the frank-archon row: custom providers inherit the unknown-provider floor of 5
+images/request and silently halve the archive. Law: **frame pricing is
+catalog-only** — radiance charges ~2,400 tokens/frame and the harness assumes
+5,024, and no user-row key can fix that until upstream prices
+`openai-completions` vision. Page: [core/snapcompact.md](core/snapcompact.md).
+
 ## 2026-10-21
 
 ### The WAN door into the model registry