The gate ladder

Every get(query) walks a fixed ladder of gates, top to bottom. There are two ladders, selected by one constructor knob — and New in v0.7 the pool path (read_path="pool" — pooled cross-unit claim ranking, budgeted packing, an adaptive serve gate) is the default whenever a semantic embedder is available, which is every keyed or production deployment. It is the path every published benchmark number was measured on, and the path all v0.7 features (the failure chain included) run on. The unit path remains as the legacy escape hatch and the keyless fallback — pass read_path="unit" for byte-identical pre-0.7 behavior. 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.

get() dispatches on read_path first: "pool" (the default under a semantic embedder) runs the pool sequence; "unit" (legacy / keyless fallback) walks the eight-gate ladder exactly as in v0.5. 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. Pool ranking needs a semantic embedder: keyless auto-construction resolves to the unit path with a warning, and explicitly pinning read_path="pool" under the lexical HashingEmbedder still raises (a keyword cosine cannot rank claims) — set OPENAI_API_KEY or pass embedder=.

The two ladders, in firing order

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

Pool path ladder (the default with a semantic embedder)

On the pool path — the default since v0.7.0 whenever a semantic embedder is available, shipped opt-in through the v0.6 transition releases — 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 (a pool_header callable, or New in v0.7 simply meta= at ingest — the default header is now metadata-first).

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

Unit path ladder (legacy escape hatch · keyless fallback)

read_path="unit" is the legacy escape hatch — byte-identical pre-0.7 behavior: the same eight gates, same defaults, same firing order as v0.5. It was the shipped default through v0.6; since New in v0.7 it runs when you pin it explicitly, or automatically (with a warning) when construction is keyless — the lexical fallback embedder cannot rank a claim pool. (The matched unit is a list of query-independent extractive claims — see The Synthesizer — and cross-unit recall is on on this path, gate 5, so multi-hop questions resolve for free.)

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.

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.

The failure chain (v0.7, default-OFF)

New in v0.7 Around the pool ladder sits a second, deeper set of default-OFF triggers — the failure chain: an observe-only gap_detector that banks repair candidates on every read (serving byte-identical ON vs OFF, pinned), subs=/constraints= for a planner to feed the read, and the explicit verbs your app calls when its evaluator says a read failed — repair(read_id) (append-only, permanent), reprobe(read_id), serve_unserved(read_id). None of it runs unless armed, and arming any of it off the pool path fails loud. Full reference: The failure chain; integration recipes: your failure handling.

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

# the pool dashboard (the default path):
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"]

# legacy unit-path thresholds (read_path="unit"):
s["hit_threshold"], s["hit_margin"], s["coverage_floor"]
s["recall_threshold"], s["select_floor"], s["residual_floor"]

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.