@tangle-network/agent-knowledge 14.0.3 → 15.0.0

package/docs/architecture.md

@@ -67,6 +67,17 @@ Every write in this layer goes through `durable-fs` (`writeFileDurable`, `writeJ
 `O_NOFOLLOW` descriptors anchored through `/proc/self/fd` prevent a directory swapped for a symlink during a write from redirecting it outside the root.
 These are exported from the package entrypoint; consumers that keep their own journals should use them rather than reimplement them.
 
+## Candidate state scope
+
+KB improvement snapshots include pages, raw evidence, and the source registry by default.
+A declared `stateScope.pagesDirectory` selects the same pages for writers, readers, indexing, and promotion.
+Opting into `stateScope.researchState` also binds canonical claim ledgers and research events.
+The hash includes nondefault scope declarations, so two different scopes cannot silently share an identity when their extra directories are empty.
+Resume uses the persisted scope and refuses a changed declaration.
+Promotion and crash recovery apply its narrow path allowlist through the existing file transaction journal.
+Derived indexes, lock state, retrieval artifacts, and external providers are excluded.
+Applications must bind external state through their existing memory branch or evaluation contracts.
+
 ## Runtime Loop
 
 1. Normalize sources into immutable source records.

package/docs/knowledge-use-receipts.md

@@ -62,6 +62,16 @@ const artifact = knowledgeVisibilityArtifactRef({ uri: 'artifact://run/visibilit
 
 The artifact reference is optional at this contract layer: a caller that retains the snapshot in another durable record may omit it. A production adapter should require a durable locator.
 
+When `createKnowledgeTools` has a `recordRetrieval` sink, it persists canonical visibility bytes before calling that sink.
+It stores artifacts under the run's `.agent-knowledge/retrieval-visibility/` directory and attaches a `file:` artifact locator to each receipt.
+Searches over the same view reuse that artifact, including concurrent searches.
+Changed views receive different artifacts.
+A persistence failure or conflicting stored bytes prevents receipt delivery.
+The host must retain these artifacts with its receipts and make the locator accessible to later verification.
+Searches without a receipt sink still return an in-memory receipt without creating durable evidence.
+These artifacts record visibility; they do not promote observations into sourced claims or prove downstream utility.
+
+
 ## Retrieval receipt
 
 `createKnowledgeRetrievalReceipt()` binds:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-knowledge",
-  "version": "14.0.3",
+  "version": "15.0.0",
   "description": "Build, search, evaluate, and improve source-backed knowledge bases.",
   "homepage": "https://github.com/tangle-network/agent-knowledge#readme",
   "repository": {
@@ -84,7 +84,7 @@
     "zod": "4.5.4"
   },
   "peerDependencies": {
-    "@tangle-network/agent-eval": ">=0.174.0 <0.176.0",
+    "@tangle-network/agent-eval": ">=0.174.0 <0.177.0",
     "@tangle-network/agent-interface": "^2.0.0"
   },
   "devDependencies": {