refactor(knowledge)!: remove unused KB policy optimization, relation graph, and invalidation helpers

CHANGELOG.md

@@ -12,6 +12,8 @@ Compare memory providers on product tasks with Agent Eval.
 Memory adapters, branches, holdout, lifecycle bounds, play memory tools, and the `/benchmarks` in-memory and no-op adapters are unchanged.
 Remove the `/sources` entry point and the unused authority adapters behind it (Cornell LII, IRS publications, state Secretary of State, polite HTTP fetch, HTML extraction), plus `detectChanges` and the freshness stores. No consumer imported them.
 The source registry (`addSourceText`, `addSourcePath`, `loadSourceRegistry`), source adapters such as `textSourceAdapter`, and readiness freshness scoring are unchanged.
+Remove unused root APIs: `optimizeKnowledgeBasePolicy`, `improveSelectedKnowledgeCandidate`, `buildKnowledgeRelationGraph` with its queries and schemas, `knowledgeCitationAuditFindings`, `planInvalidationPropagation`, `formatKnowledgeInvalidationProposal`, `calibrateRagAnswerJudge`, and `createRagAnswerQualityHook`.
+`improveKnowledgeBase`, `buildKnowledgeGraph`, citation resolution and audit, the lint `cites-invalidated` warning, and RAG answer scoring are unchanged.
 
 ## 19.1.5
 

README.md

@@ -29,7 +29,6 @@ Use Knowledge 17 with older Eval releases.
 | Prove what knowledge was visible, retrieved, and selected for use | `createKnowledgeRetrievalReceipt`, `createKnowledgeUseReceipt` | package root |
 | Improve a live knowledge base without editing it in place | `improveKnowledgeBase` | package root |
 | Optimize retrieval or a complete RAG configuration | `runRetrievalImprovementLoop`, `runRagOptimization` | package root |
-| Optimize a KB maintenance policy | `optimizeKnowledgeBasePolicy` | package root |
 | Run retrieval, research, answer checks, and promotion as one process | `runRagKnowledgeImprovementLoop` | package root |
 | Connect a memory provider or branch its state | `AgentMemoryAdapter`, `createAgentMemoryBranch` | `/memory` |
 | Use live research or coding agents | `runKnowledgeImprovementJob` | `@tangle-network/agent-runtime` |
@@ -88,7 +87,6 @@ Pass `refresh: 'always'` to rebuild its index before every query, or call `inval
 Use `asRetrievalEvalRetriever()` to send the same search path into retrieval tests.
 
 `knowledgePageRelations(pages)` lists the labeled relations between pages (`wikilink`, `citation`, `shared-source`, `contradicts`), and `buildKnowledgeGraph` collapses them into the weighted page graph stored in the index.
-For caller-defined provenance (runs, claims, models, any predicate), `buildKnowledgeRelationGraph({ nodes, relations })` keeps one edge per `(sourceId, targetId, predicate)`, refuses a conflicting repeat or an undeclared endpoint, and `neighbors`, `walk`, and `isReachable` query it by predicate and direction; `KnowledgeRelationGraphSchema` round-trips a persisted graph with its metadata.
 
 Pages live under `knowledge/` unless you name another root-relative directory.
 `loadKnowledgePages`, `buildKnowledgeIndex`, `writeKnowledgeIndex`, `applyKnowledgeWriteBlocks`, `createFileSystemSearchProvider`, and `createRunScopedStores` all take one `pagesDirectory` option (`KnowledgePagesOptions`), so a store laid out as `kb/pages/<line>/` is read, indexed, searched, chained, and written through the same value.
@@ -279,19 +277,9 @@ const receipt = createKnowledgeRetrievalReceipt({
 `excludeInvalidated` defaults to **true** here, the opposite of `searchKnowledge`: a brief offers every page it names with an id ready to cite, so a refuted page in it invites a run to build on a dead claim.
 `maxChars` bounds the brief, and a page whose line does not fit is left out of `text`, `hits`, `citationIds`, and `results` alike, so all four always describe one identical set.
 
-## Propagate an invalidation
+## Invalidated pages
 
-A page whose own evidence refuted it carries an `invalidation`. A reader who arrives through a citation never meets that verdict, so run the propagation pass after grading:
-
-```ts
-const plan = planInvalidationPropagation(originatedPages(await loadKnowledgePages(root)))
-if (plan.stamps.length > 0) {
-  await applyKnowledgeWriteBlocks(root, formatKnowledgeInvalidationProposal(plan))
-}
-```
-
-Each stamped page records `citesInvalidated: [ids]` in its frontmatter, and nothing else changes.
-The plan is a diff, so a second pass over an already stamped store produces no mutation, and a citation whose target was revalidated has its stamp removed.
+A page whose own evidence refuted it carries an `invalidation`.
 `agent-knowledge lint` reports a `cites-invalidated` warning for every live citation into a refuted page, and `searchKnowledge(index, query, { excludeInvalidated: true })` drops the refuted pages from a result set.
 The default stays `false`: a caller reading history needs them.
 
@@ -379,9 +367,7 @@ Use the narrowest API that matches the job:
 |---|---|
 | `runRetrievalImprovementLoop` | Runs one complete `OptimizationMethod` over serialized retrieval configuration. |
 | `runRagOptimization` | Optimizes retrieval and answer behavior as one serialized RAG configuration. |
-| `optimizeKnowledgeBasePolicy` | Optimizes a KB maintenance policy, then applies only the selected policy to an isolated candidate. |
 | `scoreKnowledgeBaseIndex` | Measures KB structure, citations, source freshness, and configured quality thresholds. |
-| `createRagAnswerQualityHook` | Adapts answer-quality checks such as support, relevance, citations, and abstention. |
 | `runRagKnowledgeImprovementLoop` | Connects retrieval tuning, gap diagnosis, source acquisition, KB updates, answer checks, and a promotion decision. |
 | `improveKnowledgeBase` | Adds resumable state, isolated candidates, exact promotion, and conflict detection around that process. |
 
@@ -430,7 +416,7 @@ Official external methods must report observed package identity.
 Custom in-process methods have no external package identity, so their behavior must be covered by `executionRef`.
 Treat `accountingComplete: false` as incomplete evidence for activation.
 
-Retrieval, RAG, serialized-candidate, and KB-policy optimization accept Eval's optional `claim` and `finalEvidence` options.
+Retrieval, RAG, and serialized-candidate optimization accept Eval's optional `claim` and `finalEvidence` options.
 Use `claim.independentUnit` to group questions from the same source.
 A `new-units` claim requires separate source units for development and final evaluation.
 Results retain scenario scores, source-unit scores, and both observation counts.
@@ -449,7 +435,6 @@ Only answer evaluation, the terminal promotion decision, and the returned result
 Answer-quality evidence must name at least two final scenario IDs, immutable dataset and evaluator references, non-empty finite metrics, and observed cost accounting.
 Promotion also requires `answerQualityCostCeiling`.
 
-`calibrateRagAnswerJudge()` checks supplied strong and weak fixtures; it does not measure an evaluator's error rates.
 For evaluator admission, use `auditEvaluator()` from `@tangle-network/agent-eval/meta-eval` with actual judgments of independently verified controls.
 The application must enforce evaluator and auditor separation and retain evidence for the labels.
 

api-surface.json

@@ -31,10 +31,8 @@
       "Bm25Hit": "type a6c513ea2447",
       "Bm25Options": "type 9da64a8973e6",
       "BuildEvalKnowledgeBundleOptions": "type 8951c7835e42",
-      "BuildKnowledgeRelationGraphInput": "type f08e22cb9d75",
       "BuildRetrievalEvalDispatchOptions": "type 2a1fe2b2da73",
       "CHECKABLE_RUNG_THRESHOLD": "value 534bcde62c80",
-      "CITES_INVALIDATED_FIELD": "value 3fff28ee6d1f",
       "CheckExecution": "type 884df3b223af",
       "ChunkingOptions": "type 00fb66d7d155",
       "ClaimEvidence": "type f780da49a3ef",
@@ -83,8 +81,6 @@
       "HindsightClientLike": "type e4b6e0bd1488",
       "HindsightMemoryAdapterOptions": "type 995d4468eb3c",
       "HindsightOperationUnknownError": "value 408246fe51ae",
-      "ImproveSelectedKnowledgeCandidateOptions": "type c738ecaa49fa",
-      "ImproveSelectedKnowledgeCandidateResult": "type 3a8454d1031d",
       "KB_CLAIM_LEDGER_DIR": "value 2e94ea580600",
       "KB_EVENTS_PATH": "value 7c4a3ddbac83",
       "KB_INDEX_PATH": "value f450045c9510",
@@ -126,7 +122,6 @@
       "KnowledgeDiscoveryWorker": "type 704c91abebe2",
       "KnowledgeDuplicateIntakeError": "value 1a079e39f277",
       "KnowledgeDuplicateIntakePair": "type 839de966eb41",
-      "KnowledgeEvaluationPhase": "type 1a50f18a958f",
       "KnowledgeEvent": "type 5c127ca4decf",
       "KnowledgeEventQuery": "type 748b7d9d7b93",
       "KnowledgeEventSchema": "value 373728f5643d",
@@ -165,8 +160,6 @@
       "KnowledgeIndex": "type 332f4c423f7d",
       "KnowledgeIndexSchema": "value 373728f5643d",
       "KnowledgeInspection": "type 112825b7bb54",
-      "KnowledgeInvalidationPlan": "type 62d21063bf4d",
-      "KnowledgeInvalidationStamp": "type a31367c54758",
       "KnowledgeLayout": "type beb95ce22863",
       "KnowledgeLexicalFieldBoosts": "type 019abb7897d0",
       "KnowledgeLexicalIndex": "type 81bf4d9fd93b",
@@ -184,7 +177,6 @@
       "KnowledgePageSchema": "value 373728f5643d",
       "KnowledgePagesOptions": "type 07b5e1cb6149",
       "KnowledgePolicy": "type 6e24b2884fd6",
-      "KnowledgePolicyDispatch": "type b5df3ac0d310",
       "KnowledgePromotionEntry": "type 307413f52c66",
       "KnowledgePromotionError": "value d1141cf28fad",
       "KnowledgePromotionErrorCode": "type cb7b16fdb529",
@@ -195,18 +187,7 @@
       "KnowledgeReadinessSpec": "type 946661b52948",
       "KnowledgeReceiptAttributeValue": "type af09de7ef965",
       "KnowledgeRelation": "type f930b03cefcf",
-      "KnowledgeRelationDirection": "type efbba5c61bea",
-      "KnowledgeRelationGraph": "type a4c42e720d21",
-      "KnowledgeRelationGraphError": "value cadf45a5ab8e",
-      "KnowledgeRelationGraphErrorCode": "type 62a06ddc01f3",
-      "KnowledgeRelationGraphSchema": "value 373728f5643d",
-      "KnowledgeRelationNeighbor": "type e463470d2186",
-      "KnowledgeRelationNode": "type 941a44f20696",
-      "KnowledgeRelationNodeSchema": "value 373728f5643d",
-      "KnowledgeRelationQuery": "type 59aad90a4bf4",
       "KnowledgeRelationSchema": "value 373728f5643d",
-      "KnowledgeRelationWalkOptions": "type fe4fbf78ea49",
-      "KnowledgeRelationWalkStep": "type dce4639198b3",
       "KnowledgeRelease": "type 28df725e17fa",
       "KnowledgeReleaseInput": "type 844c1ad8d42f",
       "KnowledgeReleaseReport": "type 5f72778544bd",
@@ -238,7 +219,6 @@
       "KnowledgeWriteIntakeRequest": "type 5074f0dab514",
       "KnowledgeWriteParseResult": "type 3ec744fcaf93",
       "LoadKnowledgeImprovementActivationResultOptions": "type 3c304bc52d1c",
-      "MeasuredKnowledgeSelectionReceipt": "type 28a9a57c6626",
       "Mem0ClientMode": "type abfe4225abaf",
       "Mem0HostedClient": "type 4d1434ac5a9a",
       "Mem0HostedMemoryAdapterOptions": "type 627ef089dd0c",
@@ -250,8 +230,6 @@
       "NearDuplicatePair": "type 31bc35ca4a75",
       "NearDuplicateReport": "type 0ddbba09b111",
       "Neo4jAgentMemoryAdapterOptions": "type c0746e451047",
-      "OptimizeKnowledgeBasePolicyOptions": "type 07a3ccb0b8e0",
-      "OptimizeKnowledgeBasePolicyResult": "type 1e3b03c7a0a3",
       "OriginatedKnowledgeSearchResult": "type 99110190f58f",
       "OriginatedPage": "type 62ba6f531a4a",
       "PageOrigin": "type df33a580b8a9",
@@ -400,9 +378,7 @@
       "buildKnowledgeGraph": "value f4bc0817e156",
       "buildKnowledgeIndex": "value 7a198b5e15bd",
       "buildKnowledgeLexicalIndex": "value 61e7f22cdce2",
-      "buildKnowledgeRelationGraph": "value 2c4502c049ed",
       "buildRetrievalEvalDispatch": "value 4f12d1f4c065",
-      "calibrateRagAnswerJudge": "value 74f91dafd1b1",
       "canonicalPathsEqual": "value 1a1d22b3b1c3",
       "canonicalRelativeWithinRoot": "value 9a5ffa3946f3",
       "chunkMarkdown": "value 3f930d4ba32f",
@@ -431,7 +407,6 @@
       "createPlayMemoryTools": "value cbd6422b065c",
       "createQmdKnowledgeTools": "value 136b3d258c5c",
       "createQmdSearchProvider": "value f1d2a2d4d631",
-      "createRagAnswerQualityHook": "value 7e18d330e76b",
       "createRunScopedStores": "value 6bfc535c7281",
       "decodeKnowledgeVisibilitySnapshot": "value 143bc2b124e6",
       "deepQuestionId": "value ffec05529ae9",
@@ -449,7 +424,6 @@
       "forkAgentMemoryBranchSnapshot": "value 0c258d0909ac",
       "formatFrontmatter": "value e0a4508d4ded",
       "formatKnowledgeCitationReference": "value 8c9301778549",
-      "formatKnowledgeInvalidationProposal": "value 0facdbad3e8e",
       "fromAgentCandidateKnowledgeRef": "value 247b544b764e",
       "gradeClaims": "value 5a3c1c162258",
       "gradeFor": "value 79db4a5137a3",
@@ -458,20 +432,17 @@
       "hashKnowledgeBase": "value bdb2d9eea5f9",
       "hindsightMemoryBankId": "value b828b7e949f0",
       "improveKnowledgeBase": "value a4ebce095bdf",
-      "improveSelectedKnowledgeCandidate": "value 6d48e36af283",
       "initKnowledgeBase": "value 65692669c5c8",
       "inspectKnowledgeIndex": "value 79b67f7de1cd",
       "inspectPendingKnowledgeMutation": "value 38b2e30827bd",
       "isKernelAnchoredPath": "value 2819fa14db65",
       "isKnowledgeMutationHeld": "value e8f0de09e802",
       "isKnowledgePagePath": "value 2819fa14db65",
       "isMissingFile": "value 73ca49f2b72a",
-      "isReachable": "value 980b56e89641",
       "isSafeKnowledgePath": "value 47d3e4caf0ee",
       "isScaffoldPath": "value 2819fa14db65",
       "jsonCandidateCodec": "value 6520c69bb348",
       "jsonObjectCandidateCodec": "value 8eb601cd6de7",
-      "knowledgeCitationAuditFindings": "value 639f15656570",
       "knowledgeImprovementCandidateRef": "value 2c85f9c2a1a0",
       "knowledgeImprovementRunDir": "value d3fdafeff129",
       "knowledgeImprovementRunId": "value b5b9477f7ef3",
@@ -482,7 +453,6 @@
       "knowledgeVisibilityArtifactRef": "value dfa0672dff59",
       "layoutFor": "value a4861d951cf1",
       "linkClaimContradictions": "value cf315a2deab2",
-      "lintCurrentRunCitations": "value 59004ed0538a",
       "lintKnowledgeIndex": "value c866a9cbb418",
       "listRegularFilesWithinRoot": "value f2b302b691fa",
       "loadKnowledgeImprovementActivationResult": "value c55a6c68e27a",
@@ -499,20 +469,17 @@
       "memoryWriteResultToSourceRecord": "value bd019f5d823f",
       "mergeClaimLedgers": "value d40bae24e22c",
       "mergeTrackedClaims": "value af96c4516708",
-      "neighbors": "value 29f67f6cea95",
       "normalizeClaimText": "value 4c9eca896a37",
       "normalizeExternalRagScores": "value 1a2d603c9282",
       "normalizeKnowledgeStateScope": "value beef86fc6f66",
       "normalizeLinkTarget": "value 0258f337b3b3",
       "normalizePageText": "value 9c20decc8888",
       "normalizePagesDirectory": "value 7af1695dc6cf",
-      "optimizeKnowledgeBasePolicy": "value 3cec15621ce3",
       "originatedPages": "value 38bee2f6341e",
       "parseFrontmatter": "value 62f43b77d35a",
       "parseKnowledgeCitationReference": "value 098a42106c17",
       "parseKnowledgeWriteBlocks": "value d6bd24d2858d",
       "partitionRetrievalScenarios": "value 363802debe8a",
-      "planInvalidationPropagation": "value 39da8e2c1a14",
       "promoteKnowledgeCandidate": "value ea1e94a3d6a2",
       "promoteRunScopedPages": "value 58ff1ec22528",
       "proposeFromFinding": "value 1dcecd58e869",
@@ -578,7 +545,6 @@
       "verifyKnowledgeRetrievalReceipt": "value e7dd569982cb",
       "verifyKnowledgeUseReceipt": "value 13e38b6c70c9",
       "verifyKnowledgeVisibilitySnapshot": "value cc5c6db30910",
-      "walk": "value 5035737ef563",
       "withKnowledgeImprovementCandidate": "value 1807f0708eaa",
       "withKnowledgeImprovementComparison": "value 209ea121fc27",
       "withKnowledgeMutation": "value 499371d01638",

docs/architecture.md

@@ -8,7 +8,6 @@ It owns the small set of primitives every serious agent knowledge system needs:
 - generated knowledge pages and units
 - claims with source references
 - deterministic indexing, graph construction, search, and lint
-- labeled relation graphs with one edge per `(source, target, predicate)` and neighbor, walk, and reachability queries
 - retrieval/RAG candidate surfaces, gold-target scoring, and eval-loop adapters
 - safe LLM write proposals
 - eval-gated release confidence through `@tangle-network/agent-eval`

scripts/verify-package.mjs

@@ -24,7 +24,6 @@ const publicImports = [
 const requiredRootExports = [
   'createFileSystemSearchProvider',
   'normalizeKnowledgeStateScope',
-  'optimizeKnowledgeBasePolicy',
   'runRagOptimization',
   'runRetrievalImprovementLoop',
   'runSerializedKnowledgeOptimization',