refactor(knowledge): modularize KB and RAG internals

[drewstone]

Summary

• Split the 2,722-line knowledge improvement module and 950-line RAG evaluation module into focused files while preserving their public barrels.
• Split the 1,867-line knowledge improvement test suite into four behavior suites with shared setup.
• Let knowledgeReleaseReport() accept scenario splits so required holdout evidence can pass instead of failing unconditionally.
• Correct the HTTP provenance contract and remove the stale version from the package user agent.
• Remove unused development dependencies and internal exports, update Vitest and Node types, and clean package documentation.

Validation

• pnpm install --frozen-lockfile
• pnpm test: 426 passed, 10 intentionally skipped live or paid cases
• pnpm lint
• pnpm typecheck
• pnpm build
• pnpm verify:package: clean install, five public imports, CLI version, and repack
• Built declaration comparison: 694 public names preserved across six entry points; only the intended release input and user-agent literal changed
• Internal import analysis: 115 source files, 459 edges, zero cycles
• pnpm audit --prod: zero known vulnerabilities

[tangletools]

✅ Auto-approved drewstone PR — bef787bd

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-07-18T17:39:57Z}

[tangletools]

🟡 Value Audit — sound-with-nits

Verdict	sound-with-nits
Concerns	3 (1 low, 2 weak-concern)
Heuristic	0.2s
Duplication	0.0s
Interrogation	198.1s (2 bridge agents)
Total	198.3s

💰 Value — sound-with-nits

Splits two oversized modules into focused files following the established PR #72 pattern, plus two real bug fixes (release holdout gate, HTTP provenance contract) — coherent and on-grain.

• What it does: Refactor of src/kb-improvement.ts (2,722 lines -> 51-line barrel + 7 files: contracts/state/workspace/evaluation/transition/activation/run) and src/rag-eval.ts (950 lines -> 34-line barrel + 6 files: contracts/answer/calibration/knowledge-base/providers/scoring), preserving the public exports consumed by src/index.ts, src/agent-candidate.ts, src/readiness-check.ts and src/kb-improvement/evaluation
• Goals it achieves: (1) Make two of the largest source files reviewable and navigable — the same goal PR #72 achieved for src/benchmarks/index.ts and src/memory/experiment.ts (verified: git log shows commit 1516d20 with identical pattern). (2) Unblock legitimate holdout-gated promotions — previously hasHoldout:true always failed with missing_holdout_split because no scenario corpus was plumbed through, so callers
• Assessment: Sound. The modularization matches an established, just-merged pattern in the same repo (PR #72 / commit 1516d20), uses responsibility-coherent seams (contracts / state / workspace / evaluation / transition / activation / run for kb-improvement; contracts / answer / calibration / knowledge-base / providers / scoring for rag-eval), preserves every public barrel export, and is verified by the PR's ow
• Better / existing approach: none — this is the right approach. Verified the pattern is in-repo: commit 1516d20 (PR #72) used the identical barrel-plus-focused-files decomposition for src/benchmarks/index.ts (3,126 -> 64-line barrel) and src/memory/experiment.ts. This PR is the continuation of that established grain. Verified public barrels still re-export everything via src/kb-improvement.ts:1-51 and src/rag-eval.ts:1-34. Ve
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 2
• Bridge warning: opencode/kimi-for-coding/k2p7: bridge stream ended without value-audit content

🎯 Usefulness — sound-with-nits

Clean modular split of two oversized modules plus a real fix to knowledgeReleaseReport's holdout path, fully wired through existing barrels and used by 100+ call sites — no dead surface added.

• Integration: All reachers verified. kb-improvement.ts is now a 51-line barrel re-exporting from kb-improvement/{contracts,state,run,evaluation,transition,workspace,activation}.ts; counted 41 exports before (git show HEAD~4:src/kb-improvement.ts) vs. the same set re-exported after across the new files (src/kb-improvement.ts:1-51). Same for rag-eval.ts (29 exports preserved across src/rag-eval/*.ts). Consu
• Fit with existing patterns: Follows the established codebase grain exactly. PR #72 (commit 1516d20) just did the same split for memory/; this PR applies the identical barrel-of-focused-files convention to kb-improvement/ and rag-eval/. The single-file 2,722-line kb-improvement.ts was the outlier, not the new layout. No competing pattern exists.
• Real-world viability: Behavior-preserving refactor with one intentional behavior change (holdout scenario input). The un-exports of assertKnowledgeFileTransactionApplied (src/file-transaction.ts:335), KnowledgeMutationRecovery (src/mutation-lock.ts:36), and format (src/memory/experiment/metrics.ts:125) are safe — grep confirms none are referenced outside their own files. User-Agent string change (`agent-knowledge
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 1

🔎 Heuristic Signals

🟡 Cruft: magic number added src/kb-improvement/contracts.ts

+export const DEFAULT_LEASE_TTL_MS = 15 * 60 * 1000

🎯 Usefulness Audit

🟡 Docstring cleanup trims current-rationale context, not just historical narrative [problem-fit] ``

src/sources/http.ts previously documented why three invariants must not regress (Cornell LII serves block pages above 1 req/s; cron re-hits without a cache inflate false-positives; a 200+captcha body still means 'we couldn't authenticate'). The new one-line summary ('Requests to one origin share a throttle, responses are cached by URL, and successful status codes are still checked for block pages') describes WHAT but drops the WHY. AGENTS.md's 'no historical narrative' rule targets history/aud

💰 Value Audit

🟡 Useful invariant context stripped from http.ts JSDoc [maintenance] ``

src/sources/http.ts:9-15 collapsed a 25-line block that documented three concrete bugs the enforcer exists to prevent (Cornell LII 1 req/s block pages, IRS.gov missing ETag, captcha-on-200). The new one-liner ('Requests share a throttle, responses are cached, successful status codes are checked for block pages') preserves the what but loses the why-these-specific-things. The AGENTS.md 'no historical narrative' rule targets history-of-edits comments ('replaces the inline retry loop', 'fix for the

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260718T174459Z}

[drewstone]

Addressed the actionable maintenance concern in 8d75696: the compact JSDoc now retains why shared throttling, URL caching, and 2xx body inspection are required.

The lease-default heuristic is a move, not a new constant: DEFAULT_LEASE_TTL_MS = 15 * 60 * 1000 already existed on origin/main in src/kb-improvement.ts; the split moved it unchanged to the internal contracts module so run.ts and transition.ts can share it. It is not re-exported by the package barrel.

[tangletools]

✅ Auto-approved drewstone PR — 8d756967

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: drewstone_author · 2026-07-18T17:47:41Z}

[tangletools]

🟢 Value Audit — sound

Verdict	sound
Concerns	1 (1 low)
Heuristic	0.2s
Duplication	0.0s
Interrogation	191.6s (2 bridge agents)
Total	191.8s

💰 Value — sound

Cleanly splits two giant modules along the codebase's existing subdir+barrel grain, plus two legitimate behavior fixes (release holdout, HTTP provenance) — ships as-is.

• What it does: Splits src/kb-improvement.ts (2,722 lines) into src/kb-improvement/{contracts,state,workspace,evaluation,activation,transition,run}.ts with the original file kept as a pure re-export barrel; splits src/rag-eval.ts (950 lines) the same way into src/rag-eval/{contracts,knowledge-base,scoring,answer,calibration,providers}.ts; splits the 1,867-line tests/kb-improvement.test.ts into four behavior suite
• Goals it achieves: (1) Get two of the largest files in the repo under a maintainable per-responsibility size — each new module is 69–623 lines, the barrels are 34 and 51 lines. (2) Unblock holdout-gated releases that previously failed closed even when valid holdout runs existed. (3) Make the HTTP fetcher's externally observable contract honest: the version string was wrong (package is at 4.1.0, UA said 0.2.0) and th
• Assessment: Sound. The decomposition follows an established in-repo pattern: ls src/memory/improvement/ already uses the same types/run/candidate/promotion/activation split that the new src/kb-improvement/ adopts, and src/rag-eval/ mirrors src/memory/experiment/. Barrels at src/kb-improvement.ts:1-51 and src/rag-eval.ts:1-34 re-export every previously public name, so the package's import surface is
• Better / existing approach: none — this is the right approach. Verified against src/memory/improvement/ (8 files: types/run/candidate/promotion/activation/validation/output/identity) and src/memory/experiment/ (8 files: cases/cell/metrics/recovery/runtime/run/types/validation): both are the established grain for subdir+barrel modularization in this repo, and the new directories match it. Reusing that grain is the correct
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 2
• Bridge warning: opencode/kimi-for-coding/k2p7: bridge stream ended without value-audit content

🎯 Usefulness — sound

A clean modular split that preserves the public barrels and folds in three real fixes: a release-gate bug that made hasHoldout always fail-closed, a stale user-agent version, and a misleading provenance contract.

• Integration: Every new module is reachable. kb-improvement/{activation,contracts,evaluation,run,state,transition,workspace}.ts are re-exported through src/kb-improvement.ts (lines 1-51), which src/index.ts:20 re-exports and src/agent-candidate.ts:9 consumes. rag-eval/{answer,calibration,contracts,knowledge-base,providers,scoring}.ts are re-exported through src/rag-eval.ts (lines 1-34), which src/index.ts:35 re
• Fit with existing patterns: Follows the existing modularization pattern set one commit earlier (1516d20 refactor(memory): modularize benchmarks and experiments). The release.ts fix imports DatasetScenario from @tangle-network/agent-eval and forwards it to evaluateReleaseConfidence rather than reimplementing scenario logic — same substrate dependency the codebase already uses (README:141 documents this). Comment cleanup align
• Real-world viability: The release.ts fix is material: prior code set requireHoldout: input.hasHoldout and minHoldoutRuns but had no way to pass scenarios, so the substrate's missing_holdout_split axis always failed closed even when real holdout RunRecords were supplied. The old in-source comment explicitly documented this gap. The stale user-agent 'agent-knowledge/0.2.0' (package was at 4.0.1) is the kind of drift that
• Model: opencode/zai-coding-plan/glm-5.2
• Bridge attempts: 1

🔎 Heuristic Signals

🟡 Cruft: magic number added src/kb-improvement/contracts.ts

+export const DEFAULT_LEASE_TTL_MS = 15 * 60 * 1000

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260718T175104Z}