@tangle-network/agent-knowledge 6.1.11 → 7.0.0

package/AGENTS.md

@@ -84,6 +84,15 @@ Use `knowledgeReleaseReport()` before promotion. It folds the candidate and base
 ## Integration Boundaries
 
 - Use `KbStore` for storage. Applications may provide any durable backend that implements it.
+- Use `new FileSystemKbStore({ root })` when opening a knowledge-base root; it keeps every record under `<root>/.agent-knowledge/` — index, event log, and per-run claim ledgers.
+  The string constructor retains the published direct-directory behavior.
+  A legacy string that names `<root>/.agent-knowledge` is canonicalized to the same root lock, so the two constructor forms cannot race on one file under different locks.
+  The store is the single writer of `index.json`; `writeKnowledgeIndex` goes through it.
+  Do not add a second writer for a record this store owns.
+- Research state is durable state. A driver that accumulates belief across rounds takes a store and a `ledgerId` (`createPersistentResearchDrivingDriver`) so corroboration counts, contradiction edges, and open questions survive the process. `runVerifiedResearchLoop` durably announces a fold before its synchronous question generation, calls `driver.checkpoint()` before publishing the round event, and reconstructs an interrupted fold on resume.
+- `TrackedClaim` remains the live Set-based driver API; `ResearchClaimRecord` is its sorted-array durable form. Convert at the persistence boundary rather than changing the published live shape.
+- More than one writer per ledger means `mergeClaimLedger(id, merge)`, never `putClaimLedger`. `putClaimLedger` writes the whole record, so two writers accumulating into one ledger each write what they built from a stale read and the later write erases the earlier writer's claims. `mergeClaimLedger` holds the store's lock across read, merge, and write; `mergeClaimLedgers` is the combining rule and is commutative, associative, and idempotent, so replay and arrival order cannot change the result.
+- Use `writeFileDurable` / `writeJsonDurableWithinRoot` from the entrypoint for any file that must survive a crash. They are atomic, fsynced, and symlink-safe; a hand-rolled `writeFile` is none of those.
 - Use `KnowledgeDiscoveryDispatcher` for research workers. Applications should connect it to their own runtime.
 - Do not bypass `lint` or `validate` before using generated knowledge in an agent.
 

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 7.0.0
+
+### Breaking Changes
+
+- Changed research source confirmation from URI strings to exact `SourceRecord` values and versioned the durable claim ledger schema so every observation is bound to its registry id, original URI, and full SHA-256 content hash.
+- URI-only 6.2 ledgers now fail with `ClaimLedgerMigrationRequiredError` and remain untouched for explicit archive-and-reverify migration; they are never guessed into the exact-source schema.
+
+### Fixed
+
+- Prevented registering one version of a URI from activating claims extracted from different bytes at that URI, including concurrent writers and crash recovery.
+- Snapshotted source proposals before asynchronous work, preserved the exact submitted raw bytes, and used full content hashes in raw-source paths.
+- Kept one-sided contradiction observations pending until both claims have exact registered support, preventing a missing counterpart from satisfying completion.
+
+## 6.2.0
+
+### Added
+
+- Added durable, merge-safe research claim ledgers and `createPersistentResearchDrivingDriver`, preserving corroboration, contradictions, deep questions, and round state across crashes, resumes, and concurrent workers.
+- Exported the durable filesystem write primitives used by the reference store so other journaled consumers can reuse the same atomic, symlink-safe writes.
+
+### Fixed
+
+- Kept extracted claim evidence pending until its exact source registration is confirmed, and reconciled interrupted registrations on restart so absent sources cannot satisfy completion while registered sources are not lost.
+- Routed knowledge indexes, research iteration events, and claim ledgers through the canonical store layout and one mutation-lock domain.
+
 ## 6.1.11
 
 ### Changed

package/README.md

@@ -9,7 +9,7 @@ Supply application callbacks for those decisions, or use `@tangle-network/agent-
 ## Install
 
 ```bash
-pnpm add @tangle-network/agent-knowledge@6.1.11 @tangle-network/agent-eval@0.135.2
+pnpm add @tangle-network/agent-knowledge@7.0.0 @tangle-network/agent-eval@0.135.2
 ```
 
 Requires Node.js 20.19 or later.

package/dist/benchmarks/index.d.ts

@@ -1,2 +1,2 @@
-import { A as KnowledgeBenchmarkResponder, B as KnowledgeMemoryEvent, C as KnowledgeBenchmarkArtifact, Ct as createInMemoryBenchmarkAdapter, D as KnowledgeBenchmarkEvaluation, E as KnowledgeBenchmarkDistribution, F as KnowledgeBenchmarkSplit, G as MemoryAdapterBenchmarkCandidate, H as KnowledgeRetrievalBenchmarkCase, I as KnowledgeBenchmarkTaskKind, J as RunKnowledgeBenchmarkSuiteResult, K as MemoryAdapterBenchmarkRankingRow, L as KnowledgeClaimMatcher, M as KnowledgeBenchmarkSliceSummary, N as KnowledgeBenchmarkSource, O as KnowledgeBenchmarkFamily, P as KnowledgeBenchmarkSpec, R as KnowledgeMemoryBenchmarkCase, S as KnowledgeAnswerBenchmarkTaskKind, T as KnowledgeBenchmarkCaseBase, U as KnowledgeRetrievalBenchmarkQrel, V as KnowledgeMemoryFactMatcher, W as KnowledgeRetrievalBenchmarkQuery, X as RunMemoryAdapterBenchmarkResult, Y as RunMemoryAdapterBenchmarkOptions, _ as buildIndustryRagBenchmarkSmokeCases, a as runKnowledgeBenchmarkSuite, b as BuildRetrievalBenchmarkCasesFromQrelsOptions, c as buildRetrievalBenchmarkCasesFromQrels, d as summarizeKnowledgeBenchmarkCampaign, f as runMemoryAdapterBenchmark, g as buildIndustryMemoryBenchmarkSmokeCases, h as buildFirstPartyMemoryLifecycleBenchmarkCases, i as renderKnowledgeBenchmarkReportMarkdown, j as KnowledgeBenchmarkScenario, k as KnowledgeBenchmarkReport, l as parseKnowledgeBenchmarkJsonl, m as INDUSTRY_RAG_BENCHMARKS, n as buildKnowledgeBenchmarkScenarios, o as scoreKnowledgeBenchmarkArtifact, p as INDUSTRY_MEMORY_BENCHMARKS, q as RunKnowledgeBenchmarkSuiteOptions, r as knowledgeBenchmarkJudge, s as scoreMemoryBenchmarkArtifact, t as isKnowledgeMemoryBenchmarkCase, u as parseKnowledgeBenchmarkQrels, v as respondToIndustryMemoryBenchmarkSmokeCase, w as KnowledgeBenchmarkCase, wt as createNoopMemoryBenchmarkAdapter, x as KnowledgeAnswerBenchmarkCase, y as respondToIndustryRagBenchmarkSmokeCase, z as KnowledgeMemoryBenchmarkTaskKind } from "../index-CIW3G4s_.js";
+import { A as KnowledgeBenchmarkResponder, B as KnowledgeMemoryEvent, C as KnowledgeBenchmarkArtifact, Ct as createInMemoryBenchmarkAdapter, D as KnowledgeBenchmarkEvaluation, E as KnowledgeBenchmarkDistribution, F as KnowledgeBenchmarkSplit, G as MemoryAdapterBenchmarkCandidate, H as KnowledgeRetrievalBenchmarkCase, I as KnowledgeBenchmarkTaskKind, J as RunKnowledgeBenchmarkSuiteResult, K as MemoryAdapterBenchmarkRankingRow, L as KnowledgeClaimMatcher, M as KnowledgeBenchmarkSliceSummary, N as KnowledgeBenchmarkSource, O as KnowledgeBenchmarkFamily, P as KnowledgeBenchmarkSpec, R as KnowledgeMemoryBenchmarkCase, S as KnowledgeAnswerBenchmarkTaskKind, T as KnowledgeBenchmarkCaseBase, U as KnowledgeRetrievalBenchmarkQrel, V as KnowledgeMemoryFactMatcher, W as KnowledgeRetrievalBenchmarkQuery, X as RunMemoryAdapterBenchmarkResult, Y as RunMemoryAdapterBenchmarkOptions, _ as buildIndustryRagBenchmarkSmokeCases, a as runKnowledgeBenchmarkSuite, b as BuildRetrievalBenchmarkCasesFromQrelsOptions, c as buildRetrievalBenchmarkCasesFromQrels, d as summarizeKnowledgeBenchmarkCampaign, f as runMemoryAdapterBenchmark, g as buildIndustryMemoryBenchmarkSmokeCases, h as buildFirstPartyMemoryLifecycleBenchmarkCases, i as renderKnowledgeBenchmarkReportMarkdown, j as KnowledgeBenchmarkScenario, k as KnowledgeBenchmarkReport, l as parseKnowledgeBenchmarkJsonl, m as INDUSTRY_RAG_BENCHMARKS, n as buildKnowledgeBenchmarkScenarios, o as scoreKnowledgeBenchmarkArtifact, p as INDUSTRY_MEMORY_BENCHMARKS, q as RunKnowledgeBenchmarkSuiteOptions, r as knowledgeBenchmarkJudge, s as scoreMemoryBenchmarkArtifact, t as isKnowledgeMemoryBenchmarkCase, u as parseKnowledgeBenchmarkQrels, v as respondToIndustryMemoryBenchmarkSmokeCase, w as KnowledgeBenchmarkCase, wt as createNoopMemoryBenchmarkAdapter, x as KnowledgeAnswerBenchmarkCase, y as respondToIndustryRagBenchmarkSmokeCase, z as KnowledgeMemoryBenchmarkTaskKind } from "../index-D0wc4GYg.js";
 export { type BuildRetrievalBenchmarkCasesFromQrelsOptions, INDUSTRY_MEMORY_BENCHMARKS, INDUSTRY_RAG_BENCHMARKS, type KnowledgeAnswerBenchmarkCase, type KnowledgeAnswerBenchmarkTaskKind, type KnowledgeBenchmarkArtifact, type KnowledgeBenchmarkCase, type KnowledgeBenchmarkCaseBase, type KnowledgeBenchmarkDistribution, type KnowledgeBenchmarkEvaluation, type KnowledgeBenchmarkFamily, type KnowledgeBenchmarkReport, type KnowledgeBenchmarkResponder, type KnowledgeBenchmarkScenario, type KnowledgeBenchmarkSliceSummary, type KnowledgeBenchmarkSource, type KnowledgeBenchmarkSpec, type KnowledgeBenchmarkSplit, type KnowledgeBenchmarkTaskKind, type KnowledgeClaimMatcher, type KnowledgeMemoryBenchmarkCase, type KnowledgeMemoryBenchmarkTaskKind, type KnowledgeMemoryEvent, type KnowledgeMemoryFactMatcher, type KnowledgeRetrievalBenchmarkCase, type KnowledgeRetrievalBenchmarkQrel, type KnowledgeRetrievalBenchmarkQuery, type MemoryAdapterBenchmarkCandidate, type MemoryAdapterBenchmarkRankingRow, type RunKnowledgeBenchmarkSuiteOptions, type RunKnowledgeBenchmarkSuiteResult, type RunMemoryAdapterBenchmarkOptions, type RunMemoryAdapterBenchmarkResult, buildFirstPartyMemoryLifecycleBenchmarkCases, buildIndustryMemoryBenchmarkSmokeCases, buildIndustryRagBenchmarkSmokeCases, buildKnowledgeBenchmarkScenarios, buildRetrievalBenchmarkCasesFromQrels, createInMemoryBenchmarkAdapter, createNoopMemoryBenchmarkAdapter, isKnowledgeMemoryBenchmarkCase, knowledgeBenchmarkJudge, parseKnowledgeBenchmarkJsonl, parseKnowledgeBenchmarkQrels, renderKnowledgeBenchmarkReportMarkdown, respondToIndustryMemoryBenchmarkSmokeCase, respondToIndustryRagBenchmarkSmokeCase, runKnowledgeBenchmarkSuite, runMemoryAdapterBenchmark, scoreKnowledgeBenchmarkArtifact, scoreMemoryBenchmarkArtifact, summarizeKnowledgeBenchmarkCampaign };

package/dist/benchmarks/index.js

@@ -1,2 +1,2 @@
-import { A as INDUSTRY_RAG_BENCHMARKS, F as respondToIndustryRagBenchmarkSmokeCase, I as isKnowledgeMemoryBenchmarkCase, L as createInMemoryBenchmarkAdapter, M as buildIndustryMemoryBenchmarkSmokeCases, N as buildIndustryRagBenchmarkSmokeCases, P as respondToIndustryMemoryBenchmarkSmokeCase, R as createNoopMemoryBenchmarkAdapter, a as buildKnowledgeBenchmarkScenarios, c as runKnowledgeBenchmarkSuite, d as summarizeKnowledgeBenchmarkCampaign, i as runMemoryAdapterBenchmark, j as buildFirstPartyMemoryLifecycleBenchmarkCases, k as INDUSTRY_MEMORY_BENCHMARKS, l as scoreKnowledgeBenchmarkArtifact, n as parseKnowledgeBenchmarkJsonl, o as knowledgeBenchmarkJudge, r as parseKnowledgeBenchmarkQrels, s as renderKnowledgeBenchmarkReportMarkdown, t as buildRetrievalBenchmarkCasesFromQrels, u as scoreMemoryBenchmarkArtifact } from "../benchmarks-CmW6iORW.js";
+import { A as INDUSTRY_RAG_BENCHMARKS, F as respondToIndustryRagBenchmarkSmokeCase, I as isKnowledgeMemoryBenchmarkCase, L as createInMemoryBenchmarkAdapter, M as buildIndustryMemoryBenchmarkSmokeCases, N as buildIndustryRagBenchmarkSmokeCases, P as respondToIndustryMemoryBenchmarkSmokeCase, R as createNoopMemoryBenchmarkAdapter, a as buildKnowledgeBenchmarkScenarios, c as runKnowledgeBenchmarkSuite, d as summarizeKnowledgeBenchmarkCampaign, i as runMemoryAdapterBenchmark, j as buildFirstPartyMemoryLifecycleBenchmarkCases, k as INDUSTRY_MEMORY_BENCHMARKS, l as scoreKnowledgeBenchmarkArtifact, n as parseKnowledgeBenchmarkJsonl, o as knowledgeBenchmarkJudge, r as parseKnowledgeBenchmarkQrels, s as renderKnowledgeBenchmarkReportMarkdown, t as buildRetrievalBenchmarkCasesFromQrels, u as scoreMemoryBenchmarkArtifact } from "../benchmarks-C8L7HJb4.js";
 export { INDUSTRY_MEMORY_BENCHMARKS, INDUSTRY_RAG_BENCHMARKS, buildFirstPartyMemoryLifecycleBenchmarkCases, buildIndustryMemoryBenchmarkSmokeCases, buildIndustryRagBenchmarkSmokeCases, buildKnowledgeBenchmarkScenarios, buildRetrievalBenchmarkCasesFromQrels, createInMemoryBenchmarkAdapter, createNoopMemoryBenchmarkAdapter, isKnowledgeMemoryBenchmarkCase, knowledgeBenchmarkJudge, parseKnowledgeBenchmarkJsonl, parseKnowledgeBenchmarkQrels, renderKnowledgeBenchmarkReportMarkdown, respondToIndustryMemoryBenchmarkSmokeCase, respondToIndustryRagBenchmarkSmokeCase, runKnowledgeBenchmarkSuite, runMemoryAdapterBenchmark, scoreKnowledgeBenchmarkArtifact, scoreMemoryBenchmarkArtifact, summarizeKnowledgeBenchmarkCampaign };

package/dist/{benchmarks-CmW6iORW.js → benchmarks-C8L7HJb4.js}

@@ -1,4 +1,4 @@
-import { r as stableId, t as sha256 } from "./ids-DRqPZ42_.js";
+import { r as stableId, t as sha256 } from "./ids-Bevz_pXV.js";
 import { n as searchKnowledge } from "./search-CP0QtBJZ.js";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
@@ -2715,4 +2715,4 @@ function defaultDocumentTarget(documentId, targetKind) {
 //#endregion
 export { INDUSTRY_RAG_BENCHMARKS as A, memoryWriteResultToSourceRecord as B, appendDurableJournalEvent as C, reconcileInterruptedMemoryPaidCalls as D, readActiveAttemptJournal as E, respondToIndustryRagBenchmarkSmokeCase as F, retrievalRecallJudge as G, partitionRetrievalScenarios as H, isKnowledgeMemoryBenchmarkCase as I, scoreRetrievalArtifact as K, createInMemoryBenchmarkAdapter as L, buildIndustryMemoryBenchmarkSmokeCases as M, buildIndustryRagBenchmarkSmokeCases as N, reserveRecoveryAttempts as O, respondToIndustryMemoryBenchmarkSmokeCase as P, createNoopMemoryBenchmarkAdapter as R, appendAttemptJournalEvent as S, hasSettledPaidCall as T, retrievalConfigFromSurface as U, buildRetrievalEvalDispatch as V, retrievalConfigSurface as W, memoryRecoveryDelayMs as _, buildKnowledgeBenchmarkScenarios as a, runBoundedMemoryLifecycle as b, runKnowledgeBenchmarkSuite as c, summarizeKnowledgeBenchmarkCampaign as d, acquireAgentMemoryRunLease as f, createMemoryExecutionPool as g, DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS as h, runMemoryAdapterBenchmark as i, buildFirstPartyMemoryLifecycleBenchmarkCases as j, INDUSTRY_MEMORY_BENCHMARKS as k, scoreKnowledgeBenchmarkArtifact as l, AgentMemoryLifecycleUnsafeError as m, parseKnowledgeBenchmarkJsonl as n, knowledgeBenchmarkJudge as o, AgentMemoryLifecycleTimeoutError as p, parseKnowledgeBenchmarkQrels as r, renderKnowledgeBenchmarkReportMarkdown as s, buildRetrievalBenchmarkCasesFromQrels as t, scoreMemoryBenchmarkArtifact as u, releaseMemoryAdapterCreatedAfterAbort as v, assertNoInterruptedPaidCalls as w, sleepForMemoryRecovery as x, resolveMemoryCleanupTimeoutMs as y, memoryHitToSourceRecord as z };
 
-//# sourceMappingURL=benchmarks-CmW6iORW.js.map
+//# sourceMappingURL=benchmarks-C8L7HJb4.js.map