yvgude--lean-ctx/docs/contracts/edit-metering-v1.md

Edit Metering v1 — Anchored vs str_replace Efficiency Channel

Status: shipped (GL #1008, phase 4) Owner: core engine Consumers: ctx_metrics, dashboard (/api/stats → edit_efficiency), A/B eval harness

Problem

Anchored editing's pitch is quantitative: referencing the preimage by (line, hash) instead of reproducing it as old_string saves output tokens (the expensive kind, ~5× input) and removes retry round-trips. Without a measurement channel that claim is marketing. Per the honest-metering philosophy (#361), every number must be measured per edit — never estimated, never extrapolated.

Signals

Recorded by the two edit paths themselves, in-process:

Signal	Recorded by	Semantics
anchored_calls	ctx_patch success path	Successful patch calls (a batch counts once)
anchored_ops	ctx_patch success path	Anchored ops applied across those calls
anchored_avoided_output_tokens	ctx_patch success path	Σ per op: max(0, tokens(replaced span) − tokens(anchor args))
anchored_conflicts	ctx_patch CONFLICT path	Stale-anchor responses (each = one self-heal round-trip)
str_replace_calls	ctx_edit success path	Successful str_replace edits
str_replace_old_string_tokens	ctx_edit success path	Σ tokens(old_string) actually paid in output
str_replace_misses	ctx_edit miss path	old_string-not-found responses (blind retry round-trips)

Honesty rules

• Preimage math, measured per applied op — the replaced span is tokenized before the splice; the anchor-args cost is subtracted. What a str_replace of the same span would have paid is exactly the span text; no multiplier.
• Floored at 0 per op — a one-liner can be cheaper to quote than its line:hash anchor; that op books 0 avoided tokens, never negative and never hides in an average. The A/B benchmark asserts this stays a tiny-span exception (rust/tests/edit_reliability.rs).
• op=create books 0 — both paths emit the full new content; nothing is avoided, so nothing is claimed.
• Separate channel — values are never folded into the read-gain ledger (no double counting) and never printed in tool output bodies (#498 determinism).

Persistence

~/.lean-ctx/edit_metering.json (respects LEAN_CTX_DATA_DIR), atomic tmp+rename writes, flushed every 5 recordings and on shutdown via tool_lifecycle::flush_all. Loaded once per process; missing/partial files deserialize field-by-field (serde(default)), so adding fields is backward-compatible.

Observability

• ctx_metrics → Edit efficiency (anchored vs str_replace, all-time) section; hidden until either edit path has been used.
• Dashboard ROI view → Edit Efficiency card (/api/stats → edit_efficiency), labelled measured.
• A/B benchmark: cargo test --test edit_reliability -- --nocapture prints success rates and argument-token costs for identical fixes across 5 languages (see Journey 11 §9).

Invariants

• Recording never blocks an edit: store access is lock-guarded; failure to lock skips the record.
• Counters are saturating (u64), monotone, all-time; there is no windowing in v1.
• anchored_conflicts counts responses, not ops: one CONFLICT reply = one round-trip regardless of how many ops went stale.