@tangle-network/agent-knowledge 4.0.0 → 4.1.0

package/docs/eval/investment-material-facts.md

@@ -1,10 +1,10 @@
-# Held-out investment-research eval set — material facts + provenance
+# Held-out investment-research eval set: material facts + provenance
 
 This is the answer key and the provenance ledger for `tests/eval/investment-thesis-set.ts`.
 
 **What the set measures.** Give a research loop a company + ticker + an as-of
 **cutoff** date and ask it to write an investment thesis. Then grade that thesis
-against the held-out **material facts** below — facts the loop never saw. A high
+against the held-out **material facts** below, facts the loop never saw. A high
 score means the thesis surfaced the buried, material, non-obvious drivers a
 thorough analyst would flag and a single ticker search would miss; it is **not**
 teaching-to-the-test, because the answer key is firewalled from every loop and
@@ -20,14 +20,13 @@ the grader is a `$0`, model-free substring check (`gradeFactAgainstText`).
    guessed (see the drop log).
 3. **Knowable at the cutoff.** Every value was disclosed in, or computable from, a
    filing available on or before the cutoff. The eventual collapse is **not** a
-   checklist item — it is recorded as `knownOutcome`, for the reader only, and is
-   never graded.
+   checklist item. It is recorded as `knownOutcome` for the reader and is never graded.
 
 All five primary documents were fetched live from `https://www.sec.gov/Archives/`
 during curation (a `curl` with a descriptive `User-Agent`, per SEC fair-access
 rules). Every dollar figure below was read directly out of the de-tagged filing
-text. Provenance is verifiable: each `sourceUrl` contains the company's SEC CIK,
-and `tests/eval/investment-thesis-set.test.ts` asserts that invariant.
+text. Each `sourceUrl` contains the company's SEC CIK, and
+`tests/eval/investment-thesis-set.test.ts` checks that invariant.
 
 ---
 
@@ -47,7 +46,7 @@ set was curated (June 2026); `investment-thesis-set.test.ts` asserts this.
 
 ---
 
-## SIVB — SVB Financial Group (cutoff 2023-02-24)
+## SIVB: SVB Financial Group (cutoff 2023-02-24)
 
 Source: [FY2022 10-K (`sivb-20221231.htm`)](https://www.sec.gov/Archives/edgar/data/719739/000071973923000021/sivb-20221231.htm)
 **Known outcome (not graded):** FDIC receivership March 10, 2023; holding-company Chapter 11 March 17, 2023.
@@ -59,14 +58,14 @@ Source: [FY2022 10-K (`sivb-20221231.htm`)](https://www.sec.gov/Archives/edgar/d
 | SIVB/f3 | concentration | Run-prone uninsured deposit base | "estimated uninsured deposits in U.S. offices that exceed the FDIC insurance limit were **$151.5 billion**" |
 | SIVB/f4 | margin-trend | Cheap deposits fleeing → funding cost set to rise | "Noninterest-bearing demand deposits to total deposits decreased by **20 percentage points to 47 percent**" |
 | SIVB/f5 | concentration | Single-client-type (innovation-economy) deposit + credit base | 10-K frames the franchise around "the innovation economy" (technology, life-science, venture) |
-| SIVB/f6 | off-balance-sheet | AFS loss in AOCI — the visible, smaller tip | "Available-for-sale securities, at fair value (cost of $ **28,602**) **26,069**" → ~$2.5B AFS loss in AOCI |
+| SIVB/f6 | off-balance-sheet | AFS loss in AOCI; the visible, smaller tip | "Available-for-sale securities, at fair value (cost of $ **28,602**) **26,069**" → ~$2.5B AFS loss in AOCI |
 
 The decisive, non-obvious fact is SIVB/f1+f2: an interest-rate loss roughly equal
 to all of equity, sitting in the footnotes because HTM accounting keeps it out of
 both earnings and book equity. A ticker search shows a profitable bank; the
 filing shows a mark-to-market hole the size of its capital.
 
-## BBBY — Bed Bath & Beyond Inc. (cutoff 2022-04-21)
+## BBBY: Bed Bath & Beyond Inc. (cutoff 2022-04-21)
 
 Source: [FY2021 10-K (`bbby-20220226.htm`)](https://www.sec.gov/Archives/edgar/data/886158/000088615822000047/bbby-20220226.htm)
 **Known outcome (not graded):** Chapter 11 on April 23, 2023; equity wiped out.
@@ -80,11 +79,11 @@ Source: [FY2021 10-K (`bbby-20220226.htm`)](https://www.sec.gov/Archives/edgar/d
 | BBBY/f5 | margin-trend | Inventory building into a demand decline | "Merchandise inventories **1,725,410** 1,671,909" ($ thousands) |
 
 The non-obvious fact is BBBY/f1+f2+f4 together: in FY2021 the company **lost $560M,
-generated only $18M of operating cash, and still spent $575M buying back stock** —
+generated only $18M of operating cash, and still spent $575M buying back stock**,
 returning more cash than it had. The buyback, not the income statement alone, is
 why a $1.3B equity base became $174M.
 
-## CVNA — Carvana Co. (cutoff 2023-02-23)
+## CVNA: Carvana Co. (cutoff 2023-02-23)
 
 Source: [FY2022 10-K (`cvna-20221231.htm`)](https://www.sec.gov/Archives/edgar/data/1690820/000169082023000052/cvna-20221231.htm)
 **Known outcome (not graded):** Stock fell ~98% from its 2021 peak; a 2023 debt exchange cut and extended obligations, narrowly avoiding bankruptcy.
@@ -97,18 +96,18 @@ Source: [FY2022 10-K (`cvna-20221231.htm`)](https://www.sec.gov/Archives/edgar/d
 | CVNA/f4 | governance | Recurring related-party leases with the founder's family | Related-Party note: DriveTime, controlled by "Ernest Garcia II, Ernest Garcia III, and entities controlled by one or both of them" |
 | CVNA/f5 | liquidity | A wide loss showing unit economics had not turned | "Net loss $ (**2,894**)" ($ millions) |
 
-The non-obvious facts are CVNA/f2 (interest expense up 2.8x — the debt was now
-expensive, not just large) and CVNA/f4 (the controlling Garcia family on both
+The non-obvious facts are CVNA/f2 (interest expense up 2.8x, making the debt expensive
+as well as large) and CVNA/f4 (the controlling Garcia family on both
 sides of material leases via DriveTime), neither of which a ticker quote shows.
 
-## PTON — Peloton Interactive, Inc. (cutoff 2022-09-07)
+## PTON: Peloton Interactive, Inc. (cutoff 2022-09-07)
 
 Source: [FY2022 10-K (`pton-20220630.htm`)](https://www.sec.gov/Archives/edgar/data/1639825/000163982522000117/pton-20220630.htm)
 **Known outcome (not graded):** Stock fell ~95% from its 2021 peak; founder-CEO departed; mass layoffs and a multi-year turnaround.
 
 | ID | Lens | Material fact | Value read from the filing |
 |---|---|---|---|
-| PTON/f1 | margin-trend | Hardware gross margin turned **negative** | Connected Fitness "Gross Margin decreased to (**11**)" percent — losing money per unit sold |
+| PTON/f1 | margin-trend | Hardware gross margin turned **negative** | Connected Fitness "Gross Margin decreased to (**11**)" percent; losing money per unit sold |
 | PTON/f2 | liquidity | Inventory glut as pandemic demand normalized | "Inventories, net **1,104.5** 937" ($ millions) |
 | PTON/f3 | governance | Dual-class super-voting control | "Class B common stock has **20 votes per share** and our Class A common stock has one vote per share" |
 | PTON/f4 | liquidity | An order-of-magnitude wider loss | "Net loss $ (**2,827**)" ($ millions) |
@@ -116,11 +115,11 @@ Source: [FY2022 10-K (`pton-20220630.htm`)](https://www.sec.gov/Archives/edgar/d
 | PTON/f6 | leverage | Locked-in purchase commitments into falling demand | "purchase commitments related to the manufacture of Peloton products were estimated to be approximately **$334**" million |
 
 The non-obvious fact is PTON/f1: revenue was still large, but the **hardware was
-sold below cost** (−11% gross margin) — the unit economics, not just the growth
-rate, had broken. PTON/f6 compounds it: the company was contractually obliged to
+sold below cost** (−11% gross margin). The unit economics had broken despite the
+top-line growth. PTON/f6 compounds it: the company was contractually obliged to
 buy more inventory it could not sell.
 
-## SI — Silvergate Capital Corporation (cutoff 2022-02-28)
+## SI: Silvergate Capital Corporation (cutoff 2022-02-28)
 
 Source: [FY2021 10-K (`si-20211231.htm`)](https://www.sec.gov/Archives/edgar/data/1312109/000131210922000051/si-20211231.htm)
 **Known outcome (not graded):** After the FTX collapse triggered a deposit run, Silvergate announced a voluntary wind-down and liquidation of Silvergate Bank in March 2023.
@@ -134,7 +133,7 @@ Source: [FY2021 10-K (`si-20211231.htm`)](https://www.sec.gov/Archives/edgar/dat
 | SI/f5 | concentration | The moat AND the funding are the same crypto-only bet | "Silvergate Exchange Network ('SEN'), our proprietary ... payment network for participants in the digital currency industry" |
 
 The non-obvious fact is SI/f1+f2 together: **99.5% noninterest-bearing deposits,
-~58% from crypto exchanges** — a funding base with no contractual term and a
+~58% from crypto exchanges**, a funding base with no contractual term and a
 single correlated counterparty type. A ticker quote shows a fast-growing,
 low-cost-funding bank; the filing shows a bank that could be emptied in days if
 crypto sentiment turned.
@@ -176,8 +175,8 @@ should not be read as a general "investment-research quality" number. The biases
 
 3. **Sector skew toward financials + distressed consumer.** Two of five are banks
    (SIVB, SI). The two banks are deliberately given **different** buried-risk
-   lenses — SIVB is an interest-rate / duration / off-balance-sheet story, SI is a
-   single-industry deposit-concentration story — so they are not redundant, but
+   lenses, SIVB is an interest-rate / duration / off-balance-sheet story, SI is a
+   single-industry deposit-concentration story, so they are not redundant, but
    the set still over-indexes on balance-sheet fragility and under-tests, e.g.,
    technology platform risk, supply-chain concentration, or accounting-policy
    aggressiveness in a healthy grower.
@@ -197,33 +196,33 @@ should not be read as a general "investment-research quality" number. The biases
    required a second independent source to establish was dropped (below) rather
    than sourced to the filing alone.
 
-## Drop log — items considered and NOT included (honesty over coverage)
+## Drop log: excluded items
 
 These were candidate facts I could not independently ground to a primary source
 available at the cutoff, so I **dropped them rather than guess**:
 
-- **First Republic Bank (FRC)** — dropped as a company entirely. First Republic
+- **First Republic Bank (FRC)**: dropped as a company entirely. First Republic
   was a state-chartered bank that filed its annual reports with the **FDIC**, not
   on SEC EDGAR, so its 10-K is not at a `sec.gov/Archives` URL and I could not give
-  it the same clean, CIK-verifiable provenance as the other five. Its widely cited
+  it the same CIK-matched provenance as the other five. Its widely cited
   figures (~$15B HTM-style loss, ~$119.5B uninsured deposits) are real but are best
-  sourced from the FDIC OIG Material Loss Review, a **post**-cutoff document — using
+  sourced from the FDIC OIG Material Loss Review, a **post**-cutoff document, using
   it would violate rule 3. Replaced with Silvergate, whose 10-K is on EDGAR.
 
-- **SIVB exact total unrealized-loss footnote line** — I report the HTM gap as the
+- **SIVB exact total unrealized-loss footnote line**: I report the HTM gap as the
   arithmetic difference of two figures printed on the balance sheet
   ($91,321M − $76,169M), which is exact and on-cutoff. I did **not** include a
   separately-quoted "$15.1B net unrealized loss" sentence because I did not locate
   that exact phrasing in the de-tagged text; quoting a number I could not point to
   verbatim would break rule 2. The computed value is conservative and checkable.
 
-- **CVNA negative gross-profit-per-unit** — a frequently-cited Carvana red flag,
+- **CVNA negative gross-profit-per-unit**: a frequently-cited Carvana red flag,
   but the per-unit figure I could find cleanly was a derived/analyst number, not a
   single line item I could quote verbatim from the 10-K at the cutoff. Dropped in
   favor of the directly-quoted total debt, interest expense, ADESA price, related
   party, and net loss.
 
-- **PTON / SI specific debt-covenant or going-concern language** — I searched for
+- **PTON / SI specific debt-covenant or going-concern language**: I searched for
   explicit "substantial doubt / going concern" wording in both filings and did
   **not** find it at these cutoffs (it came later). I did not invent it. The facts
   included are the ones actually present in the cutoff-date document.
@@ -248,5 +247,5 @@ for (const company of investmentThesisSet) {
 ```
 
 The grader is deterministic and model-free, so the same thesis always scores the
-same and the answer key never reaches a model the loop could observe — the same
+same and the answer key never reaches a model the loop could observe, the same
 firewall the deep-question exam (`tests/loops/held-out-exam.ts`) uses.

package/docs/eval/rag-eval-roadmap.md

@@ -12,7 +12,7 @@ SOTA RAG evaluation requires retrieval quality, context quality, generated-answe
 | [TruLens RAG Triad](https://www.trulens.org/getting_started/core_concepts/rag_triad/) | The minimal end-to-end triad is context relevance, groundedness, and answer relevance. |
 | [RAGChecker](https://papers.nips.cc/paper_files/paper/2024/hash/27245589131d17368cccdfa990cbf16e-Abstract-Datasets_and_Benchmarks_Track.html) | Fine-grained diagnosis should separate retrieval misses, noisy context, and unsupported generated claims. |
 | [BEIR](https://arxiv.org/abs/2104.08663) / TREC-style retrieval | Retrieval still needs classical rank metrics: Recall@k, Precision@k, MRR, MAP, and nDCG. |
-| [CRAG](https://arxiv.org/abs/2406.04744) | Real RAG evals must include long-tail, dynamic, multi-hop, and unanswerable questions, not only easy static facts. |
+| [CRAG](https://arxiv.org/abs/2406.04744) | Real RAG evals must include long-tail, dynamic, multi-hop, and unanswerable questions alongside easy static facts. |
 | [DeepEval RAG metrics](https://deepeval.com/docs/metrics-faithfulness) | Production tools converge on faithfulness, answer relevance, and context relevance as generator/retriever checks. |
 
 ## Current Repo Status
@@ -30,12 +30,13 @@ Done:
 - `normalizeExternalRagScores()` and the row exporters make Ragas, DeepEval, TruLens, RAGChecker, and custom evaluator outputs pluggable instead of hard dependencies.
 - `scoreKnowledgeBaseIndex()` validates generic wiki/KB health: citation coverage, source-backed pages, stale sources, duplicate source hashes, and lint/validation errors.
 - `calibrateRagAnswerJudge()` enforces the strong-vs-weak metric check before trusting a RAG answer metric.
+- `runKnowledgeImprovementJob()` in `@tangle-network/agent-runtime` connects runtime backends and worker factories to candidate KB creation, readiness checks, frozen comparisons, spend measurement, and explicit activation.
+- `agent-knowledge` remains runtime-free; applications with their own agent runner pass an `updateKnowledge` callback directly.
 
 Not done:
 
 - Slice-level reporting for freshness, distractors, multi-hop, and long-tail cases.
-- Packaged runtime adapters for browser/coding/research agents.
-  The lifecycle API accepts those agents as hooks today; it does not hardcode provider-specific workers.
+- A maintained, public benchmark pack with at least 100 labeled scenarios and published baseline results.
 
 ## Completion Criteria
 
@@ -95,7 +96,7 @@ Ship criteria:
 
 - Every failed eval has one primary failure class.
 - At least 95 percent of generated claims can be mapped to supporting context, contradicted context, or no context.
-- Reports show metrics by slice and by failure class, not only the aggregate score.
+- Reports show metrics by slice and failure class as well as the aggregate score.
 
 ### Phase 4: Production Loop
 
@@ -115,5 +116,5 @@ Ship criteria:
 
 1. Add slice-level aggregation helpers for freshness, distractors, multi-hop, long-tail, and unanswerable cases.
 2. Add forbidden/stale source targets to retrieval scenarios.
-3. Add packaged adapters that turn `agent-runtime` browser, research, and coding agents into `runRagKnowledgeImprovementLoop()` hooks.
+3. Add a maintained benchmark pack with at least 100 labeled scenarios and a reproducible baseline report.
 4. Add a CLI command that runs the lifecycle loop and writes a reproducible report under `.agent-knowledge/eval/`.

package/docs/results/adaptive.md

@@ -1,9 +1,9 @@
 # Adaptive topology: spend the LLM verifier only when it pays
 
 The cost/quality A/B (`docs/results/cost-quality.md`) found the LLM relevance
-verifier's cleanliness win is dominated by **de-duplication** — which a
+verifier's cleanliness win is dominated by **de-duplication**, which a
 deterministic content-hash / canonical-URL check captures at ~none of the LLM
-premium — and that an LLM check only earns its dollar on the off-scope tail. The
+premium, and that an LLM check only earns its dollar on the off-scope tail. The
 production move it named was: do the cheap deterministic work first, reserve the
 LLM for the ambiguous tail. `createAdaptiveResearchDriver`
 (`src/adaptive-driver.ts`) is that driver, and this is its measurement.
@@ -19,7 +19,7 @@ stopping at the first that decides:
    github, …) with a substantial body is **kept**; an obvious spam/listicle
    title or a too-thin body is **dropped**; everything else is **ambiguous**.
 3. **LLM escalation ($).** Only ambiguous survivors reach the shipped LLM
-   relevance verifier (`createVerifyingResearchDriver`) — one call each.
+   relevance verifier (`createVerifyingResearchDriver`), one call each.
 
 ## Live frontier, n=5 topics (glm-5.2)
 
@@ -39,24 +39,24 @@ is the per-arm `RouterClient.usage()` diff (#36). Total spend for the run:
 | **total** | **25** | **25** | **12 / 25 / $0.0261** | **20 / 6 / $0.0068** |
 
 **Cost.** Adaptive cuts LLM verifier calls **76%** (25 → 6) and dollars **74%**
-($0.0261 → $0.0068). On 3 of the 5 topics it spent **zero** LLM calls — every
+($0.0261 → $0.0068). On 3 of the 5 topics it spent **zero** LLM calls, every
 unique survivor was on an authoritative host, so the $0 stages decided
 everything.
 
-## The honest reading: adaptive is a frontier POINT, not a free lunch
+## Interpretation: adaptive occupies one cost-quality point
 
 Admitted-source counts (lower = cleaner KB): **single 25, adaptive 20,
 full-LLM 12**. Adaptive sits **between** the two:
 
 - It removes **5 of the 13 sources** the full-LLM judge rejects that the
   single-agent loop keeps (every one of them a real duplicate caught by the $0
-  dedup stage — exactly the de-dup-dominated win the cost/quality result
+  dedup stage, exactly the de-dup-dominated win the cost/quality result
   predicted).
 - It does **NOT** match full-LLM cleanliness. The remaining 8 sources full-LLM
   rejects, adaptive keeps. The cause is structural and visible in the trace: on
   this topic set every non-duplicate survivor landed on an authoritative host
   (arxiv / github / official docs), so the heuristic **kept** it without ever
-  asking the LLM — and the LLM, when full-LLM did ask it, judged several of
+  asking the LLM, and the LLM, when full-LLM did ask it, judged several of
   those same authoritative pages not-quite-on-topic and dropped them. The host
   prior is coarser than the relevance judge.
 
@@ -65,19 +65,19 @@ de-dup half of full-LLM's cleanliness for ~26% of full-LLM's dollars, and gives
 up the relevance-judgment half.** Whether that is the right point depends on the
 cost of a kept-but-marginal source. If a slightly-off-topic authoritative page
 is cheap to carry, adaptive dominates. If every admitted source must clear a
-relevance bar, the host heuristic is too permissive and you want the full LLM —
+relevance bar, the host heuristic is too permissive and you want the full LLM,
 or a tightened heuristic.
 
-## Where the heuristic is weak — stated plainly
+## Where the heuristic is weak: stated plainly
 
 The escalation count is the diagnostic. On 3 of 5 topics it was **zero**: the
 heuristic never deferred to the LLM, so on those topics adaptive is a
 **pure host/title/length rule**, and its cleanliness is exactly that rule's
-cleanliness — no smarter than "trust arxiv/github, drop spam." That is fine when
+cleanliness, no smarter than "trust arxiv/github, drop spam." That is fine when
 the worker's sources are dominated by authoritative hosts (as here), but it
 means the LLM's relevance judgment is contributing nothing on those topics, by
 construction. The two topics where adaptive *did* escalate (grouped-query
-attention, LoRA) are where some survivors were on unknown hosts — and there the
+attention, LoRA) are where some survivors were on unknown hosts, and there the
 3 LLM calls per topic are the off-scope tail the verifier is actually for.
 
 The heuristic would mis-route in two directions a richer worker would expose,
@@ -95,12 +95,12 @@ neither seen on this authoritative-host-heavy set:
 The deployable recommendation from the cost/quality result was "deterministic
 dedup first, reserve the LLM for the tail." This driver ships that and the
 measurement confirms the **cost** half cleanly (76% fewer calls, 74% cheaper)
-and qualifies the **quality** half honestly: adaptive captures the de-dup
+and qualifies the **quality** half accurately: adaptive captures the de-dup
 cleanliness (the dominant, free win) but not the LLM's relevance cleanliness,
 because the host heuristic resolves authoritative survivors without asking. For
 a worker whose sources are mostly authoritative, adaptive is the right frontier
 point. For one whose junk is on-topic-looking pages on unknown hosts, the
-ambiguous tail grows and adaptive converges toward full-LLM cost — which is the
+ambiguous tail grows and adaptive converges toward full-LLM cost, which is the
 correct behavior: it pays for the LLM exactly when the cheap signals can't
 decide.
 

package/docs/results/claim-grounding.md

@@ -1,22 +1,22 @@
 # Claim-grounding: the band where the verifier earns its dollar
 
 `docs/results/cost-quality.md` found the relevance verifier's cleanliness win is
-**dominated by de-duplication** — a deterministic content-hash captures most of it
+**dominated by de-duplication**, a deterministic content-hash captures most of it
 at ~none of the LLM premium. So the open question was: is there an error band where
-a verifier earns its cost — something a hash AND a relevance judge both miss?
+a verifier earns its cost, something a hash AND a relevance judge both miss?
 
 **Yes: misattributed citations.** A source that is on-topic, unique, and real, but
 whose cited CLAIM does not appear in the page (the LLM wrote a plausible sentence
 and hung a real URL off it). De-dup passes it (it's unique). A relevance judge
 passes it (the page is on-topic). Only checking the claim against the fetched text
-catches it — and that check is **deterministic text presence, $0 inference**.
+catches it, and that check is **deterministic text presence, $0 inference**.
 
 ## The mode
 
 Each proposed source now carries the specific claim it is cited for
 (`withCitedClaim` → `metadata.citedClaim`). The verifier
 (`createClaimGroundingVerifier`) runs `groundClaimInText(claim, pageText)` over the
-`htmlToText` output of the page the worker actually fetched — verbatim, normalized
+`htmlToText` output of the page the worker actually fetched, verbatim, normalized
 (punctuation/whitespace-insensitive), or a ≥70% content-word overlap close
 paraphrase. A claim that isn't present is rejected as **misattributed**. The oracle
 is text presence, not a model call, so it composes with the LLM relevance verifier
@@ -31,25 +31,25 @@ proposals. Cost diffed per arm with the #36 `RouterClient.usage()` instrumentati
 
 | n=5 topics | misattributions caught | marginal $ | $/topic | per-$ caught |
 |---|---|---|---|---|
-| no-verifier | 0 / 5 | $0.0000 | — | — |
+| no-verifier | 0 / 5 | $0.0000 | n/a | n/a |
 | relevance (LLM judge) | **4 / 5** | $0.0157 | ~$0.0031 | 254 |
 | claim-grounding (text) | **5 / 5** | **$0.0000** | $0 | ∞ |
 
 Per-topic (caught relevance / grounding): self-speculative decoding 1/1, rotary
 position embeddings 1/1, grouped-query attention 1/1, **KV-cache quantization 0/1**,
-LoRA 1/1. (An earlier 3-topic run missed self-speculative decoding instead — the
+LoRA 1/1. (An earlier 3-topic run missed self-speculative decoding instead, the
 miss moves around; it is not a fixed topic.)
 
 **Reading.** Claim-grounding catches every misattribution at **$0**; the relevance
 judge catches most but **misses one in five at ~$0.003/topic**. The miss is the
 point: the relevance verifier only ever sees the page text, never the cited claim,
-so it is *structurally blind* to misattribution. It catches one only by accident —
+so it is *structurally blind* to misattribution. It catches one only by accident:
 when the fabricated claim happens to also make the page read off-topic
 (e.g. a "12-billion-parameter draft transformer" claim on a rotary-embeddings page).
 When the fabrication stays on-topic (the KV-cache case), the judge waves it through.
 
 So on THIS band the verifier-per-dollar comparison inverts the cost/quality result:
-there, the LLM verifier bought a dedup-shaped gain a free hash already captures —
+there, the LLM verifier bought a dedup-shaped gain a free hash already captures;
 expensive for what a cheap rule does. Here the cheap, deterministic check
 **dominates** the expensive judge: it catches strictly more (5/5 vs 4/5) at strictly
 less ($0 vs $0.0157). The verifier earns its dollar on misattribution; it does not on
@@ -63,7 +63,7 @@ de-duplication.
   (and the offline relevance stand-in) accept them. The error is in the *claim*, not
   the *topic*.
 - **Executable ground truth.** The check is presence/close-paraphrase of the claim
-  in the fetched text — deployable in production with no oracle and no model call.
+  in the fetched text, deployable in production with no oracle and no model call.
 
 The offline arm proves the floor with a controlled 4-source pool (2 grounded, 2
 misattributed): claim-grounding admits **0/2** misattributions and keeps **2/2**
@@ -78,9 +78,9 @@ grounded sources, while relevance and no-verifier both admit **2/2**.
 - **Planted misattributions, not naturally-occurring ones.** Like the cost/quality
   offline floor, the misattribution is injected so the band is measurable. It models
   the real LLM citation-fabrication failure but does not measure its base rate in the
-  wild — that needs a corpus of model-written citations checked by hand.
+  wild, that needs a corpus of model-written citations checked by hand.
 - **The grounding oracle is conservative.** A real paraphrase whose inflected words
-  differ from the page ("drafts" vs "draft") can score below 0.7 and be rejected —
+  differ from the page ("drafts" vs "draft") can score below 0.7 and be rejected,
   a false-positive misattribution flag. `minOverlap` tunes this; the worker should
   cite the page's own key terms (the `createClaimDecorator` extractor is told to).
 

package/docs/results/cost-quality.md

@@ -2,7 +2,7 @@
 
 Live 9-topic A/B (glm-5.2, budget B ≤ 4 passes/arm), measured per arm with the
 router-client instrumentation. The original A/B reported only admitted-sources at
-"equal passes" — which charged the two-agent verify step as one pass while it is
+"equal passes", which charged the two-agent verify step as one pass while it is
 actually N `verifySource` LLM calls. Pricing the calls shows what that hid.
 
 | per topic (mean) | two-agent | single-agent | ratio |
@@ -11,7 +11,7 @@ actually N `verifySource` LLM calls. Pricing the calls shows what that hid.
 | tokens (in+out) | ~4,900 | ~530 | ~9× |
 | cost (USD) | ~$0.0072 | ~$0.0013 | ~5.5× |
 | latency (wall) | ~37 s | ~11 s | ~3.4× |
-| cleanliness Δ (single − two admitted) | — | — | +1.56, 95% CI [0.33, 2.67] |
+| cleanliness Δ (single − two admitted) | n/a | n/a | +1.56, 95% CI [0.33, 2.67] |
 
 Per-topic Δ (single − two admitted) this run: self-speculative decoding +4,
 grouped-query attention 0, rotary position embeddings +1, KV-cache quantization
@@ -19,9 +19,9 @@ grouped-query attention 0, rotary position embeddings +1, KV-cache quantization
 descent **−1**. Coverage 1.00 every topic, both arms.
 
 **Reading.** The verifier buys ~1.5–2.7 fewer junk sources for roughly **5× the
-dollars, 9× the tokens, and 3× the latency** — and on two topics it admitted *more*
+dollars, 9× the tokens, and 3× the latency**, and on two topics it admitted *more*
 than the single agent (the cleanliness signal is real but noisier than the +2.3 /
 +2.7 of earlier runs). The cleanliness gain is dominated by de-duplication, so the
-honest production move is a deterministic content-hash / canonical-URL dedup, which
+production move is a deterministic content-hash / canonical-URL dedup, which
 captures most of the cleanliness at ~none of this premium; reserve an LLM check for
 the off-scope tail. This is the cost half the "equal passes" framing left out.