diff --git a/omp-docs/core/index.md b/omp-docs/core/index.md index 7b90f44..46401bc 100644 --- a/omp-docs/core/index.md +++ b/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. diff --git a/omp-docs/core/snapcompact.md b/omp-docs/core/snapcompact.md new file mode 100644 index 0000000..9fa3c5f --- /dev/null +++ b/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). diff --git a/omp-docs/log.md b/omp-docs/log.md index 50f5cfd..3c8317e 100644 --- a/omp-docs/log.md +++ b/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