@tangle-network/agent-knowledge 4.0.1 → 4.1.0

package/dist/memory/index.d.ts

@@ -1,5 +1,5 @@
-import { b as AgentMemoryAdapter, j as AgentMemorySearchOptions, d as AgentMemoryContext, f as AgentMemoryHit, i as AgentMemoryScope, k as AgentMemoryWriteInput, l as AgentMemoryWriteResult, u as KnowledgeBenchmarkFamily, D as KnowledgeBenchmarkSplit, H as KnowledgeMemoryBenchmarkTaskKind, J as KnowledgeMemoryFactMatcher, h as AgentMemoryRunLease, I as KnowledgeMemoryEvent, G as KnowledgeMemoryBenchmarkCase, e as AgentMemoryControllerMode, A as AgentMemoryAcquireRunLease, $ as RetrievalHoldoutConfig, _ as RetrievalHoldoutCallContext, a2 as RetrievalHoldoutResult, Z as RetrievalHoldoutBypassReason, a1 as RetrievalHoldoutEvent } from '../types-ZzY_x0r7.js';
-export { c as AgentMemoryBranchIsolation, g as AgentMemoryKind, Q as OwnedAgentMemoryRunLease, a0 as RetrievalHoldoutEligibleItem, a3 as RetrievalHoldoutSessionState, af as acquireAgentMemoryRunLease } from '../types-ZzY_x0r7.js';
+import { b as AgentMemoryAdapter, j as AgentMemorySearchOptions, d as AgentMemoryContext, f as AgentMemoryHit, i as AgentMemoryScope, k as AgentMemoryWriteInput, l as AgentMemoryWriteResult, u as KnowledgeBenchmarkFamily, D as KnowledgeBenchmarkSplit, H as KnowledgeMemoryBenchmarkTaskKind, J as KnowledgeMemoryFactMatcher, h as AgentMemoryRunLease, I as KnowledgeMemoryEvent, G as KnowledgeMemoryBenchmarkCase, e as AgentMemoryControllerMode, A as AgentMemoryAcquireRunLease, $ as RetrievalHoldoutConfig, _ as RetrievalHoldoutCallContext, a2 as RetrievalHoldoutResult, Z as RetrievalHoldoutBypassReason, a1 as RetrievalHoldoutEvent } from '../types-DP38encz.js';
+export { c as AgentMemoryBranchIsolation, g as AgentMemoryKind, Q as OwnedAgentMemoryRunLease, a0 as RetrievalHoldoutEligibleItem, a3 as RetrievalHoldoutSessionState, af as acquireAgentMemoryRunLease } from '../types-DP38encz.js';
 import { CampaignResult, Scenario, DispatchContext, CampaignStorage, CostLedgerHandle, JudgeConfig, HeldoutSignificance, Lineage, GovernorContext, GovernorOp, SurfaceProposer, LineageStore, HeldoutSignificanceOptions } from '@tangle-network/agent-eval/campaign';
 import { OffPolicyTrajectory } from '@tangle-network/agent-eval/rl';
 import { z } from 'zod';
@@ -382,28 +382,27 @@ interface RetrievalHoldoutOffPolicyOptions {
     qHat?: (session: RetrievalHoldoutSessionSummary) => number | null;
 }
 interface RetrievalHoldoutOffPolicyResult {
-    /** One trajectory per (configHash, sessionIdHash) — never per call. */
+    /** One trajectory per (configHash, sessionIdHash), never per call. */
     trajectories: OffPolicyTrajectory[];
     /** 1:1 with `trajectories` (same order): the diagnostic view of each converted session. */
     sessions: RetrievalHoldoutSessionSummary[];
-    /** Sessions surfaced but NOT converted (mixed exposure, bypass-only) — counted, never hidden. */
+    /** Sessions not converted because exposure was mixed or retrieval was bypassed. */
     excluded: RetrievalHoldoutSessionSummary[];
     /** Events with no sessionIdHash: outside session randomization, cannot join a reward. */
     unattributableEvents: number;
 }
 /**
- * Maps holdout logs onto agent-eval's `OffPolicyTrajectory`, ONE TRAJECTORY PER SESSION, so
- * EXP-007's analysis consumes the substrate's `inverseProbabilityWeighting` /
- * `selfNormalizedImportanceWeighting` / `doublyRobust` estimators directly. This matches the
- * PREREG estimator (session-sticky self-normalized IPW): the design randomizes per SESSION —
- * the arm coin is flipped once (P(holdout) = epsilon) and the sticky target is drawn once,
+ * Maps retrieval-dropout events onto one `OffPolicyTrajectory` per session for use with
+ * `inverseProbabilityWeighting`, `selfNormalizedImportanceWeighting`, or `doublyRobust`.
+ * Randomization occurs once per session: the arm is selected with P(dropout) = epsilon and
+ * the sticky target is drawn once,
  * uniformly over watchlist ∩ E at the session's first intersecting call.
  *
  * Session-level action space and behavior probabilities (they sum to 1 by construction):
- * - full delivery (control arm observed): `1 − epsilon`;
+ * - full delivery: `1 - epsilon`;
  * - drop candidate i of k = |watchlist ∩ E_first|: `epsilon / k` each (the draw event's logged
  *   `dropPropensity`);
- * - sessions whose eligibility sets never intersect the watchlist: probability 1 — full
+ * - sessions whose eligibility sets never intersect the watchlist: probability 1, because full
  *   delivery was certain in either arm.
  *
  * Per-call events are repeated observations WITHIN one session-level randomization; per-call
@@ -412,14 +411,12 @@ interface RetrievalHoldoutOffPolicyResult {
  * absent from E, and adapter bypass calls, fold into the session summary (callCount /
  * bypassCallCount) instead of generating independent propensities.
  *
- * Join contract: `rewards` is keyed by `sessionIdHash` (sha256(sessionId) first 16 hex — compute
+ * Join contract: `rewards` is keyed by `sessionIdHash` (sha256(sessionId) first 16 hex; compute
  * the same prefix over the outcome table's session ids, or log with
  * `includePlaintextIdentifiers: true` and join on raw ids upstream). Events are grouped per
  * (configHash, sessionIdHash) so different experiment configs are never pooled. Mixed-exposure
  * sessions (arm or target disagreement, e.g. after registry eviction) are excluded from the
- * trajectories and surfaced in `excluded` for the analysis to count.
- * Pre-registration for EXP-007 stays in the research repo by design; the manifest vocabulary for
- * it is agent-eval's `HypothesisManifest` / `signManifest` / `evaluateHypothesis` exports.
+ * trajectories and surfaced in `excluded` for analysis.
  */
 declare function toOffPolicyTrajectory(events: RetrievalHoldoutEvent[], options: RetrievalHoldoutOffPolicyOptions): RetrievalHoldoutOffPolicyResult;
 

package/dist/memory/index.js

@@ -24,7 +24,7 @@ import {
   runAgentMemoryExperiment,
   runAgentMemoryImprovement,
   toOffPolicyTrajectory
-} from "../chunk-3CAAGJCE.js";
+} from "../chunk-CPMLJYA3.js";
 import {
   AgentMemoryLifecycleTimeoutError,
   AgentMemoryLifecycleUnsafeError,

package/dist/sources/index.d.ts

@@ -15,9 +15,9 @@
  * Sources MUST be pure with respect to local filesystem state outside the
  * cache directory the caller hands them — they read remote authorities and
  * return data. They MUST mark `verifiable: false` on any fragment they could
- * not authenticate (block page, 4xx, parse failure) rather than silently
- * substituting empty/partial content. The control loop downstream uses
- * `verifiable` to refuse promotion of un-grounded content.
+ * not fetch and extract (block page, 4xx, parse failure) rather than silently
+ * substituting empty or partial content. The control loop downstream uses
+ * `verifiable` to refuse promotion of unusable content.
  *
  * @stable
  */
@@ -77,10 +77,11 @@ interface FragmentProvenance {
      */
     jurisdiction?: string;
     /**
-     * True iff the source could authenticate the fetched content (HTTP 200,
-     * expected selectors present, parse succeeded). False on any block page,
-     * rate-limit response, 4xx/5xx, or selector miss. Consumers MUST refuse
-     * to promote `verifiable: false` fragments into citable knowledge.
+     * True iff the configured URL returned an acceptable response and the
+     * expected content was extracted. False on a block page, rate-limit
+     * response, 4xx/5xx, or selector miss. This is not publisher authentication
+     * or cryptographic content verification. Consumers MUST refuse to promote
+     * `verifiable: false` fragments into citable knowledge.
      */
     verifiable: boolean;
     /** If `verifiable === false`, the reason — surfaced to operators. */
@@ -222,33 +223,16 @@ declare function extractLinks(html: string, hrefPattern: RegExp, baseUrl: string
 }[];
 
 /**
- * Polite HTTP fetcher used by every shipped source.
+ * Polite HTTP fetcher shared by remote sources.
  *
- * Three invariants this enforces — each was a bug found while wiring real
- * authorities; do not regress:
- *
- *   1. Per-host throttling. Cornell LII serves under 1 req/s/origin
- *      politely and will start serving block pages above that. The lock
- *      is per-host (`hostThrottle`) rather than per-source so that two
- *      independent sources targeting the same authority still cooperate.
- *
- *   2. On-disk content cache keyed by URL. Production sources are called
- *      from a cron loop; without a cache, every run re-hits the same
- *      pages and inflates change-detection false-positives (the authority
- *      occasionally serves slightly different boilerplate). The cache is
- *      content-addressed by URL, not by ETag — authorities like IRS.gov
- *      do not consistently send ETag/Last-Modified.
- *
- *   3. Block-page detection on success. A 200 with a captcha body still
- *      means "we couldn't authenticate." Sources downstream rely on
- *      `verifiable` to refuse promotion — losing that signal because the
- *      fetcher said "well, the status code was 200" is the bug class
- *      this exists to prevent.
- *
- * @stable
+ * Independent sources share a per-origin throttle because rate-limited sites
+ * may return block pages instead of 429 responses. Responses are cached by URL
+ * because many publishers omit reliable ETag and Last-Modified headers. Bodies
+ * are checked even after a 2xx response because captcha and block pages often
+ * use successful status codes.
  */
 /** User-Agent string sent on every outbound request. */
-declare const POLITE_USER_AGENT = "agent-knowledge/0.2.0 (+https://github.com/tangle-network/agent-knowledge)";
+declare const POLITE_USER_AGENT = "agent-knowledge (+https://github.com/tangle-network/agent-knowledge)";
 /** Minimum gap between successive requests to the same origin (ms). */
 declare const MIN_REQUEST_GAP_MS = 1000;
 /** Maximum response body we will buffer in memory (bytes). */
@@ -257,7 +241,7 @@ interface PoliteFetchOptions {
     signal?: AbortSignal;
     cacheDir?: string;
     /**
-     * Cache age beyond which we re-fetch. Default 1 hour — long enough to
+     * Cache age beyond which we re-fetch. Default 1 hour, long enough to
      * batch a cron sweep across many selectors, short enough that hourly
      * authoritative-page changes get picked up next tick.
      */
@@ -291,7 +275,7 @@ interface PoliteFetchResult {
 }
 /**
  * Fetch one URL with per-host throttling, on-disk cache, and block-page
- * detection. Never throws on network/HTTP failure — returns a result with
+ * detection. Never throws on network/HTTP failure. It returns a result with
  * `verifiable: false` and `unverifiableReason` set so the caller can decide
  * whether to skip, retry, or surface.
  *

package/dist/sources/index.js

@@ -13,7 +13,7 @@ import {
   innerHtmlById,
   looksLikeBlockPage,
   politeFetch
-} from "../chunk-WCYW2GDA.js";
+} from "../chunk-MYFM6LKH.js";
 import "../chunk-YMKHCTS2.js";
 export {
   IRS_DIMENSION_HINTS,

package/dist/{types-ZzY_x0r7.d.ts → types-DP38encz.d.ts}

@@ -252,6 +252,11 @@ interface AgentMemoryAdapter {
     flush?(): Promise<void>;
     close?(): Promise<void>;
 }
+/**
+ * Optional session-level retrieval dropout for estimating whether delivered memories affect
+ * task outcomes. The feature is disabled unless configured, and consumers persist events
+ * through `onEvent`.
+ */
 interface RetrievalHoldoutConfig {
     /** Per-session probability that one eligible watchlist item is suppressed. 0 logs the full schema without ever dropping. */
     epsilon: number;
@@ -268,20 +273,20 @@ interface RetrievalHoldoutConfig {
      * sessionIdHash/scopeHash, so PII-bearing identifiers (tenantId/userId/tags) never reach a
      * consumer-controlled sink unless the consumer explicitly owns that decision. Note that
      * replaying assignment draws from logs alone needs the plaintext sessionId, so
-     * privacy-default logs require the consumer's own sessionId mapping for replay audits.
+     * privacy-preserving logs require the consumer's own sessionId mapping for replay.
      */
     includePlaintextIdentifiers?: boolean;
     /**
      * Cap on tracked sessions per experiment config in the sticky wrapper's registry.
-     * Exists so tests can exercise eviction; production should keep the default (10,000).
+     * The default is 10,000.
      */
     maxTrackedSessions?: number;
     /**
      * Uniform-[0,1) generator keyed by a string. Defaults to a sha256-derived deterministic
-     * generator so every assignment is replayable from the logged keys alone (design rule D5).
+     * generator so every assignment is replayable from the logged keys alone.
      */
     rng?: (key: string) => number;
-    /** Receives one event per retrieval call, INCLUDING no-drop calls: control-arm membership is half the data. */
+    /** Receives one event per retrieval call, including calls where nothing is dropped. */
     onEvent: (event: RetrievalHoldoutEvent) => void;
 }
 interface RetrievalHoldoutEligibleItem {
@@ -298,19 +303,18 @@ interface RetrievalHoldoutEvent {
     eventId: string;
     ts: string;
     adapterId?: string;
-    /** Plaintext session id — emitted ONLY when config.includePlaintextIdentifiers is true. */
+    /** Plaintext session id, emitted only when `includePlaintextIdentifiers` is true. */
     sessionId?: string;
     /** Consumer-supplied experiment/outcome join id (scope.tags.taskId); deliberately plaintext. */
     taskId?: string;
     /** 1-based call counter within the session; 0 when the call is outside session randomization. */
     callIndex: number;
     /**
-     * sha256(sessionId) prefix — the default privacy-preserving session join key AND the seed-key
-     * reference for the assignment draws (previously named rngKey; identical derivation, deduped).
+     * sha256(sessionId) prefix used as the privacy-preserving join key and assignment seed.
      */
     sessionIdHash?: string;
     queryHash?: string;
-    /** Verbatim scope — emitted ONLY when config.includePlaintextIdentifiers is true (PII risk). */
+    /** Verbatim scope, emitted only when `includePlaintextIdentifiers` is true. */
     scope?: AgentMemoryScope;
     /** sha256 prefix of the canonical-JSON scope (keys sorted, undefined stripped). */
     scopeHash?: string;

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).