@tangle-network/agent-knowledge 10.6.0 → 10.8.0

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## 10.8.0 — 2026-08-22
+
+### Fixed
+
+- A knowledge root that canonicalizes to a different path than the caller holds now opens its file transactions instead of failing with `knowledge transaction directory escaped its root`.
+`withTransactionRoot` compared the transaction root against the knowledge root with `resolve` on both sides.
+`resolve` is lexical and cannot read a symbolic link, while the transaction root arrives already canonical from `withSafeDirectory`, so the two described one directory with two strings and the containment test rejected a directory that was inside the root.
+On macOS this happened on every run that placed a knowledge base under `os.tmpdir()`, because `/var/folders/...` is a link to `/private/var/folders/...`.
+It also happened on any platform when a caller passed a root reached through a symbolic link.
+- `loadRunState` and `assertStateIdentity` compared a persisted root against a supplied root the same way, and reported a mismatch between two spellings of one directory.
+
+### Added
+
+- `relativeWithinRoot(root, candidate)`, `canonicalRelativeWithinRoot(root, candidate)`, and `canonicalPathsEqual(left, right)`.
+`src/durable-fs.ts` now owns every comparison between two filesystem paths.
+`canonicalRelativeWithinRoot` and `canonicalPathsEqual` canonicalize both sides first, and neither path has to exist: the deepest existing ancestor is canonicalized and the remaining segments are appended, so a directory that is about to be created is measured against the same root as one that already is.
+Canonicalizing both sides also tightens the boundary, because a candidate that leaves the root through a symbolic link is rejected where a lexical comparison admits it.
+- `pnpm run check:path-containment`, which fails a path comparison written inline instead of through those owners.
+It runs inside `verify:package`, so both workflows enforce it.
+A lexical comparison looks correct on Linux, where `/tmp` is a real directory and the two forms coincide, so this class of defect cannot be caught by running the suite on the machine that gates the merge.
+
+## 10.7.1 — 2026-08-22
+
+### Changed
+
+- Accept Eval `>=0.170.0 <0.171.0`, replacing Eval `>=0.163.2 <0.164.0`, and Interface `^1.6.0`, replacing Interface `^1.4.0`.
+The old Eval range admitted exactly one published version while Eval `latest` was 0.170.0, so a consumer installing the cohort got an unmet peer on this package and could not complete the install.
+- **A consumer must move Eval and Interface with this package.**
+Interface moves because Eval 0.170.0 depends on agent-core 0.9.5, which requires Interface `^1.5.0`.
+Interface 1.4.0 leaves a second physical copy of the contract package in the tree, and one contract package must resolve to one copy.
+Move Eval to 0.170.x and Interface to 1.6.x in the same change.
+- The new Eval ceiling is measured, not assumed.
+This package imports 79 distinct symbols from Eval across five entry points: `.` (37), `/campaign` (35), `/rl` (4), `/experiment` (2), and `/analyst` (1), plus one dynamic `import()` of `/campaign`.
+A compiler probe over every symbol gives the same result against 0.163.2 and against 0.170.0: 78 resolve, and `JsonValue` resolves in neither, because two test files import it from `/campaign` where it has never been exported.
+Eval 0.170.0 removes six `/analyst` exports, which are `createJudgeAdapter`, `createRunCriticAdapter`, `createVerifierAdapter`, and their three option types.
+This package imports none of the six.
+All 15 symbols this package imports from Interface resolve at 1.6.0 exactly as they do at 1.4.0.
+- A pre-1.0 dependency earns a single-minor range, so `<0.171.0` is the boundary the evidence covers.
+An Eval minor above 0.170.x must be verified before the range admits it.
+
+## 10.7.0 — 2026-08-21
+
+### Added
+
+- `createKnowledgeControlLoopAdapter` now returns `stopPolicies.stateFingerprint`. `observe` hands the caller's `AbortSignal` to `act` through the loop state, and Eval's control runtime fingerprints that state with RFC 8785 canonical JSON, which refuses a class instance. Eval's contract names this exact case: a caller whose state is not plain JSON supplies its own fingerprint. The adapter fingerprints the observable knowledge and leaves the signal out, so a caller spreading `...adapter` needs to know none of this.
+
+### Fixed
+
+- Nothing this package writes encodes an absent optional as `undefined` any more. `createKnowledgeEvent` (`actor`, `target`, `metadata`), the research-loop step (`notes`, `applied`, `readiness`, `metadata`), its event metadata (`written`), and readiness requirement metadata (`validUntil`, `lastVerifiedAt`) all omit the key instead. A key present with no value and an absent key are the same JSON, so the canonical encoder refuses to guess between them — and every control-loop run through `createKnowledgeControlLoopAdapter` aborted at step 0 because of it. `createKnowledgeEvent` is the single owner of every event this package emits, so the fix there covers all of them.
+
+### Changed
+
+- Accept Eval `>=0.163.2 <0.164.0` and Interface `^1.4.0`, replacing Eval `>=0.149.0 <0.150.0` and Interface `^1.1.0`. Eval 0.150.0 through 0.163.2 removed the paid model transports, deleted 86 unused exports, and changed the raw-finding codec, the GEPA bridge output, and the GEPA engine seed; this package builds and tests against 0.163.2, so the peer range now states that.
+- **A consumer must move Eval and Interface with this package.** Installing 10.7.0 beside Eval 0.149.x is an unmet peer, not a warning to ignore: the GEPA bridge output shape differs between the two. Move Eval to 0.163.2 and Interface to 1.4.0 in the same change.
+
 ## 10.6.0 — 2026-08-21
 
 ### Added

package/dist/benchmarks/index.js

@@ -1,2 +1,2 @@
-import { B as createNoopMemoryBenchmarkAdapter, F as buildIndustryRagBenchmarkSmokeCases, I as respondToIndustryMemoryBenchmarkSmokeCase, L as respondToIndustryRagBenchmarkSmokeCase, M as INDUSTRY_RAG_BENCHMARKS, N as buildFirstPartyMemoryLifecycleBenchmarkCases, P as buildIndustryMemoryBenchmarkSmokeCases, R as isKnowledgeMemoryBenchmarkCase, a as buildKnowledgeBenchmarkScenarios, c as runKnowledgeBenchmarkSuite, d as summarizeKnowledgeBenchmarkCampaign, i as runMemoryAdapterBenchmark, j 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, z as createInMemoryBenchmarkAdapter } from "../benchmarks-B6fCb6AD.js";
+import { F as buildIndustryRagBenchmarkSmokeCases, H as createInMemoryBenchmarkAdapter, I as respondToIndustryMemoryBenchmarkSmokeCase, L as respondToIndustryRagBenchmarkSmokeCase, M as INDUSTRY_RAG_BENCHMARKS, N as buildFirstPartyMemoryLifecycleBenchmarkCases, P as buildIndustryMemoryBenchmarkSmokeCases, R as isKnowledgeMemoryBenchmarkCase, U as createNoopMemoryBenchmarkAdapter, a as buildKnowledgeBenchmarkScenarios, c as runKnowledgeBenchmarkSuite, d as summarizeKnowledgeBenchmarkCampaign, i as runMemoryAdapterBenchmark, j 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-Qk94Gnj4.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-B6fCb6AD.js → benchmarks-Qk94Gnj4.js}

@@ -422,12 +422,56 @@ function renderMemoryHits(hits) {
 	}).join("\n\n");
 }
 //#endregion
-//#region src/benchmarks/utils.ts
+//#region src/candidate-ranking.ts
+/**
+* Round a US-dollar amount to the precision a cost ledger records.
+*
+* Costs are accumulated by addition, so two runs that spent the same amount
+* can differ in the last bits of the float. Ranking breaks a tie on cost, and
+* without a common precision that float noise decides the order.
+*/
+function normalizeUsd(value) {
+	return Number(value.toFixed(12));
+}
+/**
+* Order candidates best-first and stamp each row with the rank it earned.
+*
+* A candidate with a failed cell measured less than it claims to have
+* measured, so it places below every candidate that completed. Among those,
+* the higher mean score wins, then the higher pass rate, then the lower cost.
+* The candidate id breaks the final tie, so ranking the same results twice
+* gives the same order.
+*/
+function rankCandidates(rows) {
+	return [...rows].sort((a, b) => Number(a.cellsFailed > 0) - Number(b.cellsFailed > 0) || b.scoreMean - a.scoreMean || b.passRate - a.passRate || a.totalCostUsd - b.totalCostUsd || a.candidateId.localeCompare(b.candidateId)).map((row, index) => ({
+		...row,
+		rank: index + 1
+	}));
+}
+//#endregion
+//#region src/statistics.ts
+/**
+* The mean of a set of measurements.
+*
+* A measurement that is not a finite number is not a measurement: it is a
+* scorer that divided by zero or an adapter that answered with nothing usable.
+* Averaging it in would spread one broken probe across the whole aggregate,
+* and carrying it through would make the aggregate itself unusable — a
+* non-finite `scoreMean` fails every numeric comparison in the ranking
+* comparator, so the candidate carrying it falls through to the identifier
+* tie-break and places by name rather than by what it scored. Such values are
+* left out, and the mean reports what was actually measured.
+*
+* An empty set answers `0`. That is a reported score, not an absence, and it
+* is the behavior every caller in this package already depends on.
+*/
 function mean(values) {
 	const finite = values.filter(Number.isFinite);
 	if (finite.length === 0) return 0;
 	return finite.reduce((sum, value) => sum + value, 0) / finite.length;
 }
+//#endregion
+//#region src/benchmarks/utils.ts
 function unique(values) {
 	return [...new Set(values.filter(Boolean))];
 }
@@ -435,9 +479,6 @@ function formatNumber(value) {
 	if (!Number.isFinite(value)) return "0";
 	return value.toFixed(value === 0 || Math.abs(value) >= 10 ? 0 : 3);
 }
-function normalizeUsd(value) {
-	return Number(value.toFixed(12));
-}
 function compactObject(value) {
 	if (Array.isArray(value)) return value.map(compactObject);
 	if (!value || typeof value !== "object") return value;
@@ -2591,15 +2632,12 @@ async function runOwnedMemoryAdapterBenchmark(options, storage, runDir, lease, c
 		await lease.assertOwned();
 	}
 	const costByCandidate = memoryAdapterBenchmarkCostByCandidate(costLedger, runDir, [...options.candidates, ...options.recoveryCandidates ?? []]);
-	const ranked = rows.map((row) => {
+	const ranked = rankCandidates(rows.map((row) => {
 		const totalCostUsd = normalizeUsd(costByCandidate.get(row.candidateId) ?? 0);
 		return {
 			...row,
 			totalCostUsd
 		};
-	}).sort((a, b) => Number(a.cellsFailed > 0) - Number(b.cellsFailed > 0) || b.scoreMean - a.scoreMean || b.passRate - a.passRate || a.totalCostUsd - b.totalCostUsd || a.candidateId.localeCompare(b.candidateId)).map((row, index) => ({
-		...row,
-		rank: index + 1
 	}));
 	const rankingJsonPath = join(runDir, "memory-adapter-ranking.json");
 	const rankingMarkdownPath = join(runDir, "memory-adapter-ranking.md");
@@ -2781,6 +2819,6 @@ function defaultDocumentTarget(documentId, targetKind) {
 	}
 }
 //#endregion
-export { reserveRecoveryAttempts as A, createNoopMemoryBenchmarkAdapter as B, sleepForMemoryRecovery as C, hasSettledPaidCall as D, assertNoInterruptedPaidCalls as E, buildIndustryRagBenchmarkSmokeCases as F, retrievalConfigFromSurface as G, memoryWriteResultToSourceRecord as H, respondToIndustryMemoryBenchmarkSmokeCase as I, scoreRetrievalArtifact as J, retrievalConfigSurface as K, respondToIndustryRagBenchmarkSmokeCase as L, INDUSTRY_RAG_BENCHMARKS as M, buildFirstPartyMemoryLifecycleBenchmarkCases as N, readActiveAttemptJournal as O, buildIndustryMemoryBenchmarkSmokeCases as P, isKnowledgeMemoryBenchmarkCase as R, runBoundedMemoryLifecycle as S, appendDurableJournalEvent as T, buildRetrievalEvalDispatch as U, memoryHitToSourceRecord as V, partitionRetrievalScenarios as W, MEMORY_OPERATION_CANCELLATION_TIMEOUT_MS as _, buildKnowledgeBenchmarkScenarios as a, memoryRecoveryDelayMs as b, runKnowledgeBenchmarkSuite as c, summarizeKnowledgeBenchmarkCampaign as d, acquireAgentMemoryRunLease as f, MEMORY_CAMPAIGN_DISPATCH_SHUTDOWN_TIMEOUT_MS as g, DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS as h, runMemoryAdapterBenchmark as i, INDUSTRY_MEMORY_BENCHMARKS as j, reconcileInterruptedMemoryPaidCalls as k, scoreKnowledgeBenchmarkArtifact as l, AgentMemoryLifecycleUnsafeError as m, parseKnowledgeBenchmarkJsonl as n, knowledgeBenchmarkJudge as o, AgentMemoryLifecycleTimeoutError as p, retrievalRecallJudge as q, parseKnowledgeBenchmarkQrels as r, renderKnowledgeBenchmarkReportMarkdown as s, buildRetrievalBenchmarkCasesFromQrels as t, scoreMemoryBenchmarkArtifact as u, createBoundedMemoryAdapter as v, appendAttemptJournalEvent as w, resolveMemoryCleanupTimeoutMs as x, createMemoryExecutionPool as y, createInMemoryBenchmarkAdapter as z };
+export { reserveRecoveryAttempts as A, normalizeUsd as B, sleepForMemoryRecovery as C, hasSettledPaidCall as D, assertNoInterruptedPaidCalls as E, buildIndustryRagBenchmarkSmokeCases as F, memoryWriteResultToSourceRecord as G, createInMemoryBenchmarkAdapter as H, respondToIndustryMemoryBenchmarkSmokeCase as I, retrievalConfigFromSurface as J, buildRetrievalEvalDispatch as K, respondToIndustryRagBenchmarkSmokeCase as L, INDUSTRY_RAG_BENCHMARKS as M, buildFirstPartyMemoryLifecycleBenchmarkCases as N, readActiveAttemptJournal as O, buildIndustryMemoryBenchmarkSmokeCases as P, isKnowledgeMemoryBenchmarkCase as R, runBoundedMemoryLifecycle as S, appendDurableJournalEvent as T, createNoopMemoryBenchmarkAdapter as U, rankCandidates as V, memoryHitToSourceRecord as W, retrievalRecallJudge as X, retrievalConfigSurface as Y, scoreRetrievalArtifact as Z, MEMORY_OPERATION_CANCELLATION_TIMEOUT_MS as _, buildKnowledgeBenchmarkScenarios as a, memoryRecoveryDelayMs as b, runKnowledgeBenchmarkSuite as c, summarizeKnowledgeBenchmarkCampaign as d, acquireAgentMemoryRunLease as f, MEMORY_CAMPAIGN_DISPATCH_SHUTDOWN_TIMEOUT_MS as g, DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS as h, runMemoryAdapterBenchmark as i, INDUSTRY_MEMORY_BENCHMARKS as j, reconcileInterruptedMemoryPaidCalls as k, scoreKnowledgeBenchmarkArtifact as l, AgentMemoryLifecycleUnsafeError as m, parseKnowledgeBenchmarkJsonl as n, knowledgeBenchmarkJudge as o, AgentMemoryLifecycleTimeoutError as p, partitionRetrievalScenarios as q, parseKnowledgeBenchmarkQrels as r, renderKnowledgeBenchmarkReportMarkdown as s, buildRetrievalBenchmarkCasesFromQrels as t, scoreMemoryBenchmarkArtifact as u, createBoundedMemoryAdapter as v, appendAttemptJournalEvent as w, resolveMemoryCleanupTimeoutMs as x, createMemoryExecutionPool as y, mean as z };
 
-//# sourceMappingURL=benchmarks-B6fCb6AD.js.map
+//# sourceMappingURL=benchmarks-Qk94Gnj4.js.map