The gate ladder

Every get(query) walks a fixed ladder of gates, top to bottom. Since v0.6 there are two ladders, selected by one constructor knob: the default unit path (read_path="unit" — byte-identical v0.5 behavior, its ladder unchanged) and the opt-in pool path (read_path="pool" — pooled cross-unit claim ranking, budgeted packing, an adaptive serve gate). Each rung is also a knob — but you rarely touch one. The defaults are pure cosine: both ladders run with no extra model and no extra dependency, and only reach for raw when the cache genuinely under-covers.

New in v0.6 get() now dispatches on read_path first: "unit" (default) walks the eight-gate ladder exactly as in v0.5; "pool" (opt-in) runs the pool sequence instead. On the pool path the unit-path read knobs (hit_threshold, hit_margin, route_by_claim, recall_*, select_floor, ...) are inert — but coverage_floor (the RAG floor) and the S2 band (coverage_scorer) keep their jobs on both paths.

The two ladders, in firing order

A read flows down its spine — matched or pooled, fresh, covered, served. Each gate can branch off: a miss (unit) or a below-gate read (pool) builds, a stale unit re-materializes, an under-covered serve escalates to attributed raw (the RAG floor), and — on the pool path with the behavioral stack armed — a downstream refusal re-enters through report_refusal. It never fabricates.

Unit path ladder (default, unchanged from v0.5)

read_path="unit" is the default and is byte-identical v0.5 — the same eight gates, same defaults, same firing order. (New in v0.4 the matched unit is a list of query-independent extractive claims — see The Synthesizer — and cross-unit recall is on by default, gate 5, so multi-hop questions resolve for free on the read path.)

A hit that survives gate 1–2, is fresh (3), covers the query (4–7), and is trimmed (8) is served straight from the cache. A miss at gate 1 or an ambiguous tie at gate 2 builds a new unit; an under-covered hit at gate 7 escalates to fresh raw — never a fabricated answer.

Before the ladder: residual_floor (build time)

residual_floor runs once, at build, not on the read path. When the extractor drops a number-bearing source span — its max per-claim cosine falls below the floor — that span is kept verbatim as an extra atom bound to the unit, closing the extractor-recall gap for stray numbers. residual_limit (default 24) caps how many are kept, ranked most-missed first, so the safety net can't defeat the token win. Embedding-only, no extra LLM call; None = off.

v0.5 hooks around the unit ladder

New in v0.5 Five knobs sit at fixed points around the eight gates. All default off; preset="multi_hop" arms the recall pair with calibrated thresholds, and explicit kwargs always override the preset.

Pool path ladder (v0.6, opt-in)

New in v0.6 On the pool path, every read is answered by budget-packing the global fresh-claim pool — the best claims from any fresh unit, ranked against the query — while units remain the ownership / freshness / build / provenance skeleton. Validated at n=605 (strict grading): 0.731 accuracy @ 981 mean tokens with a metadata pool_header — naive top-9's accuracy (0.711 @ 1311) at ~25% fewer context tokens, and naive's best measured point (k12: 0.731 @ 1729) at ~43% fewer; gold-claim serving rank p50/p75/p90 = 1/6/15. The v0.5 preview point (0.699 @ 1036) holds. This is parity at fewer tokens, not an accuracy win over naive — and the shipping default header grades 0.68 on the same rig; the 0.73 rung needs your metadata (pool_header, below).

A pool read runs these stages in order — the code's own stage names:

Three guard rails fire at construction, not mid-read: read_path="pool" under the lexical HashingEmbedder raises (claim cosine collapses to keyword overlap); query_keys=True off the pool path raises (keys could attach and confirm yet structurally never fire); and pool without a pool_header warns — attribution falls back to the built-in header, the middle rung of a measured ~9-point ladder (below).

The pool knobs

Behavioral triggers (default-OFF)

New in v0.6 The behavioral stack sits around the pool ladder, not on it — nothing below runs unless switched on, and the pool defaults are byte-identical with it off. The loop: build-time span capture → read-time side channel → your answerer refuses → report_refusal(read_id) returns an attributed retry payload → report_success(read_id) confirms the rescue as a durable query key → the key overlays the next scan (P3) → repeated signals mark the unit lossy → append-only repair on its next rebuild touch. Measured on the n=605 rig: refusals 91 → 61 (−33%) with zero newly-wrong answers; the full stack +3.1 pts same-store at ~2% token cost; keyed-class first-pass 0% → 61% on mild paraphrases (small n — keys are a latency/round-trip lever, not an accuracy lever on diverse rewordings).

report_refusal and report_success never raise: an unknown or aged-out read_id (64-read ring), a disarmed stack, or no qualifying span is a silent None / no-op. Neither makes a retrieval or LLM call; the only side effect is report_success persisting the confirmed key when a store is configured.

Other hooks on the read path

These sit alongside the ladders rather than on them:

• route_by_claim (default off; unit path) — route the match on the best per-claim embedding instead of the unit's topic embedding; useful when one unit holds many distinct facts.
• relevance_gate — a (query, chunks) -> chunks callable that drops irrelevant retrieved chunks before synthesis on either path, so a new unit is built from cleaner evidence.
• depth — on the LLMSynthesizer (0.0 terse → 0.5 balanced default → 1.0 exhaustive); trades synthesis cost against how often later reads escalate. See The Synthesizer.
• calibrate_thresholds(embedder, positives, negatives) — derive hit_threshold / coverage_floor from labeled (query, understanding) pairs for a custom or text-embedding-3-large embedder; the shipped embedders are auto-calibrated already.

Which knob for which workload

Reading the ladder in production

s = cache.stats()
s["hit_rate"]          # share of reads served from cache
s["escalation_rate"]   # share that hit the RAG floor
s["hit_threshold"], s["hit_margin"], s["coverage_floor"]
s["recall_threshold"], s["select_floor"], s["residual_floor"]

# read_path="pool" adds the pool dashboard:
s["serve_gate_effective"], s["pool_noise_ceiling"]      # the gate actually applied
s["pool_serves"], s["probe_reads"], s["admission_reuses"]
s["rebuilds_by_read"], s["builds_by_gap"]               # why builds happened
s["pool_claims_fresh"], s["pool_claims_total"], s["pool_mask_rate"]
s["avg_units_per_serve"], s["pool_scan_slow"]

cache.stats() reports hit_rate and escalation_rate alongside the effective operating thresholds — so you can see which rung is doing the work and confirm exactly which knobs are live. A climbing escalation_rate means understanding is too thin (raise depth); a low hit_rate on paraphrases of the same question means the match bar is too high (hit_threshold, unit path). On the pool path, cache_hit means zero synthesis calls ran — probe_reads counts reads that retrieved without building (the gate-miss dashboard), and a climbing builds_by_gap with flat accuracy means the serve gate is set too high.

Next

• Context intelligence — the pool payload contract, the pool_header golden path, and the behavioral stack in detail.
• The Synthesizer — where extractive understanding and depth come from.
• get() & Result — the single read API and every field it returns.