@tangle-network/agent-knowledge 6.2.0 → 7.0.2

package/dist/sources/index.js

@@ -1,4 +1,4 @@
-import { t as sha256 } from "../ids-DRqPZ42_.js";
+import { t as sha256 } from "../ids-Bevz_pXV.js";
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 //#region src/sources/html.ts

package/dist/{types-Cd57BPRt.d.ts → types-BOfmvDe-.d.ts}

@@ -227,21 +227,34 @@ interface ResearchClaimRecord {
   contested: boolean;
   firstSeenRound: number;
 }
+/** Immutable identity of one exact version of an original source URI. */
+interface ResearchSourceVersion {
+  /** Canonical source-registry id for this URI and content hash. */
+  sourceId: KnowledgeId;
+  /** The URI supplied before the source was copied into the raw-source store. */
+  uri: string;
+  /** SHA-256 of the exact submitted source text. */
+  contentHash: string;
+}
 /**
  * One immutable claim extraction observed while a source is being verified.
  *
  * An observation is deliberately separate from `ResearchClaimRecord`: source
  * verification happens before source registration, and a process can die in
  * between. The observation is durable immediately, but it contributes support
- * to a claim only after `sourceUri` appears in the ledger's independently
- * confirmed `registeredSourceUris` set.
+ * to a claim only after its expected registry id, original URI, and content hash
+ * appear together in the ledger's independently confirmed `registeredSources` set.
  */
 interface ResearchClaimEvidence {
   /** Stable identity of this claim/source/contradiction observation. */
   id: string;
   claimId: string;
   text: string;
+  /** Canonical source-registry id expected for this source version. */
+  sourceId: KnowledgeId;
   sourceUri: string;
+  /** SHA-256 of the exact source text from which this observation was extracted. */
+  sourceContentHash: string;
   /** Existing claim this observation directly contradicts, when reported. */
   contradictsClaimId?: string;
   firstSeenRound: number;
@@ -255,6 +268,8 @@ interface ResearchClaimEvidence {
  * overwrite each other, so the store addresses ledgers by this id.
  */
 interface ResearchClaimLedger {
+  /** Persistent contract version; version 2 binds evidence to source content. */
+  schemaVersion: 2;
   id: string;
   /** The research goal this ledger accumulated evidence for. */
   goal?: string;
@@ -272,8 +287,8 @@ interface ResearchClaimLedger {
    * not yet been confirmed. Pending observations never count toward claims.
    */
   claimEvidence: ResearchClaimEvidence[];
-  /** Exact original source URIs confirmed present in the source registry. */
-  registeredSourceUris: string[];
+  /** Exact source-registry identities confirmed after their raw bytes were stored. */
+  registeredSources: ResearchSourceVersion[];
   claims: ResearchClaimRecord[];
   questions: DeepQuestion[];
 }
@@ -287,5 +302,5 @@ interface KnowledgeRelease {
   metadata?: Record<string, unknown>;
 }
 //#endregion
-export { ResearchClaimEvidence as C, SourceRecord as D, SourceAnchor as E, SourceRegistry as O, KnowledgeWriteParseResult as S, ResearchClaimRecord as T, KnowledgeRelation as _, KnowledgeBaseCandidate as a, KnowledgeUnit as b, KnowledgeEventType as c, KnowledgeGraphNode as d, KnowledgeId as f, KnowledgePolicy as g, KnowledgePage as h, KNOWLEDGE_EVENT_TYPES as i, TrackedClaim as k, KnowledgeGraph as l, KnowledgeLintFinding as m, DeepQuestion as n, KnowledgeClaim as o, KnowledgeIndex as p, DeepQuestionKind as r, KnowledgeEvent as s, ClaimRef as t, KnowledgeGraphEdge as u, KnowledgeRelease as v, ResearchClaimLedger as w, KnowledgeWriteBlock as x, KnowledgeSearchResult as y };
-//# sourceMappingURL=types-Cd57BPRt.d.ts.map
+export { TrackedClaim as A, ResearchClaimEvidence as C, SourceAnchor as D, ResearchSourceVersion as E, SourceRecord as O, KnowledgeWriteParseResult as S, ResearchClaimRecord as T, KnowledgeRelation as _, KnowledgeBaseCandidate as a, KnowledgeUnit as b, KnowledgeEventType as c, KnowledgeGraphNode as d, KnowledgeId as f, KnowledgePolicy as g, KnowledgePage as h, KNOWLEDGE_EVENT_TYPES as i, SourceRegistry as k, KnowledgeGraph as l, KnowledgeLintFinding as m, DeepQuestion as n, KnowledgeClaim as o, KnowledgeIndex as p, DeepQuestionKind as r, KnowledgeEvent as s, ClaimRef as t, KnowledgeGraphEdge as u, KnowledgeRelease as v, ResearchClaimLedger as w, KnowledgeWriteBlock as x, KnowledgeSearchResult as y };
+//# sourceMappingURL=types-BOfmvDe-.d.ts.map

package/dist/{types-Cd57BPRt.d.ts.map → types-BOfmvDe-.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"types-Cd57BPRt.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";KAAY;UAEK;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,WAAW;;UAGI;EACf,IAAI;EACJ;EACA;EACA;EACA;EACA;EACA,UAAU;;EAEV;;EAEA;EACA,WAAW;EACX;;UAGe;EACf;EACA,SAAS;;UAGM;EACf;EACA;EACA;;UAGe;EACf,IAAI;EACJ;EACA,MAAM;EACN;EACA;EACA,WAAW;;UAGI;EACf,UAAU;EACV,UAAU;EACV;EACA;EACA,WAAW;;UAGI;EACf,IAAI;EACJ;EACA;EACA,SAAS;EACT,YAAY;EACZ;EACA;EACA,WAAW;EACX;;UAGe;EACf,IAAI;EACJ;EACA;EACA;EACA,aAAa;EACb;EACA;EACA;;UAGe;EACf,IAAI;EACJ;EACA;EACA;EACA;EACA;EACA;;UAGe;EACf,QAAQ;EACR,QAAQ;EACR;EACA;;UAGe;EACf,OAAO;EACP,OAAO;;UAGQ;EACf;EACA;EACA,SAAS;EACT,OAAO;EACP,OAAO;;UAGQ;EACf,MAAM;;;;;;;EAON;;EAEA;;;;;;;;EAQA;EACA;EACA;EACA;;UAGe;EACf;EAUA;EACA;EACA;EACA,WAAW;;UAGI;EACf;EACA;EACA;EACA;EACA,WAAW;;UAGI;EACf,IAAI;EACJ,OAAO;EACP;EACA;EACA;EACA;EACA,WAAW;;UAGI;EACf;EACA;;UAGe;EACf,QAAQ;EACR;;;;;;;;;;cAWW;KAWD,6BAA6B;UAExB;EACf;EACA,MAAM;EACN;EACA;EACA;EACA,WAAW;;;KAID;;;;;;;;;UAUK;EACf,MAAM;EACN;;EAEA;;EAEA;;EAEA;;EAEA;;;UAIe;EACf;;EAEA;;EAEA,iBAAiB;;EAEjB;;EAEA,aAAa;;;;;;EAMb;EACA;;;;;;;;;UAUe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;;;;;;;;;;;UAYe;;EAEf;EACA;EACA;EACA;;EAEA;EACA;;;;;;;;;;UAWe;EACf;;EAEA;;EAEA;;EAEA;;;;;EAKA;;;;;EAKA,eAAe;;EAEf;EACA,QAAQ;EACR,WAAW;;UAGI;EACf;EACA;EACA;EACA;EACA;EACA;EACA,WAAW"}
+{"version":3,"file":"types-BOfmvDe-.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";KAAY;UAEK;EACf;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,WAAW;;UAGI;EACf,IAAI;EACJ;EACA;EACA;EACA;EACA;EACA,UAAU;;EAEV;;EAEA;EACA,WAAW;EACX;;UAGe;EACf;EACA,SAAS;;UAGM;EACf;EACA;EACA;;UAGe;EACf,IAAI;EACJ;EACA,MAAM;EACN;EACA;EACA,WAAW;;UAGI;EACf,UAAU;EACV,UAAU;EACV;EACA;EACA,WAAW;;UAGI;EACf,IAAI;EACJ;EACA;EACA,SAAS;EACT,YAAY;EACZ;EACA;EACA,WAAW;EACX;;UAGe;EACf,IAAI;EACJ;EACA;EACA;EACA,aAAa;EACb;EACA;EACA;;UAGe;EACf,IAAI;EACJ;EACA;EACA;EACA;EACA;EACA;;UAGe;EACf,QAAQ;EACR,QAAQ;EACR;EACA;;UAGe;EACf,OAAO;EACP,OAAO;;UAGQ;EACf;EACA;EACA,SAAS;EACT,OAAO;EACP,OAAO;;UAGQ;EACf,MAAM;;;;;;;EAON;;EAEA;;;;;;;;EAQA;EACA;EACA;EACA;;UAGe;EACf;EAUA;EACA;EACA;EACA,WAAW;;UAGI;EACf;EACA;EACA;EACA;EACA,WAAW;;UAGI;EACf,IAAI;EACJ,OAAO;EACP;EACA;EACA;EACA;EACA,WAAW;;UAGI;EACf;EACA;;UAGe;EACf,QAAQ;EACR;;;;;;;;;;cAWW;KAWD,6BAA6B;UAExB;EACf;EACA,MAAM;EACN;EACA;EACA;EACA,WAAW;;;KAID;;;;;;;;;UAUK;EACf,MAAM;EACN;;EAEA;;EAEA;;EAEA;;EAEA;;;UAIe;EACf;;EAEA;;EAEA,iBAAiB;;EAEjB;;EAEA,aAAa;;;;;;EAMb;EACA;;;;;;;;;UAUe;EACf;EACA;EACA;EACA;EACA;EACA;EACA;;;UAIe;;EAEf,UAAU;;EAEV;;EAEA;;;;;;;;;;;UAYe;;EAEf;EACA;EACA;;EAEA,UAAU;EACV;;EAEA;;EAEA;EACA;;;;;;;;;;UAWe;;EAEf;EACA;;EAEA;;EAEA;;EAEA;;;;;EAKA;;;;;EAKA,eAAe;;EAEf,mBAAmB;EACnB,QAAQ;EACR,WAAW;;UAGI;EACf;EACA;EACA;EACA;EACA;EACA;EACA,WAAW"}

package/dist/viz/index.d.ts

@@ -1,4 +1,4 @@
-import { d as KnowledgeGraphNode, l as KnowledgeGraph, u as KnowledgeGraphEdge } from "../types-Cd57BPRt.js";
+import { d as KnowledgeGraphNode, l as KnowledgeGraph, u as KnowledgeGraphEdge } from "../types-BOfmvDe-.js";
 //#region src/viz/index.d.ts
 interface KnowledgeVizNode extends KnowledgeGraphNode {
   degree: number;

package/docs/architecture.md

@@ -38,24 +38,28 @@ When that string is the canonical `<root>/.agent-knowledge` directory, both form
 | --- | --- |
 | `.agent-knowledge/index.json` | the built knowledge index (`writeKnowledgeIndex` writes it through this store) |
 | `.agent-knowledge/events.json` | the knowledge event log, including one `research.iteration` per research-loop round |
-| `.agent-knowledge/claim-ledgers/<id>.json` | one research run's claim ledger — corroboration counts, contradiction edges, open deep questions |
+| `.agent-knowledge/claim-ledgers/<id>.json` | one research run's claim ledger: corroboration counts, contradiction edges, open deep questions |
 | `.agent-knowledge/sources.json` | the immutable source registry |
 | `.agent-knowledge/mutation.lock.durable`, `mutation-epoch.json`, `file-transactions/` | the cross-process mutation lock and its crash-recovery state |
 
 The root is also the directory `withKnowledgeMutation` locks, so every record above is written under one lock and one epoch.
 There is exactly one writer per file: a second index writer alongside this one is a defect, not a variation.
 
-A claim ledger is the one record several writers legitimately share — a resumed run beside a live one, or several workers researching one goal in parallel.
+A claim ledger is the one record several writers legitimately share, such as a resumed run beside a live one or several workers researching one goal in parallel.
 They reach it through `mergeClaimLedger(id, merge)`, which holds the mutation lock across the read, the merge, and the write, so no writer can build its record from a value another writer has already replaced.
 `putClaimLedger` writes the whole record and is correct only for a single writer.
-The combining rule is `mergeClaimLedgers`: support and contradiction edges union, `contested` and `addressed` latch on, `firstSeenRound` moves earlier, and every collection is sorted — so the merge is commutative, associative, and idempotent, and the bytes on disk depend on the evidence rather than on scheduling.
+The combining rule is `mergeClaimLedgers`: support and contradiction edges union, `contested` and `addressed` latch on, `firstSeenRound` moves earlier, and every collection is sorted.
+The merge is commutative, associative, and idempotent, so the bytes on disk depend on the evidence rather than on scheduling.
 Ledgers for two different goals refuse to merge (`ClaimLedgerGoalConflictError`) rather than pooling unrelated evidence into one corroboration count.
 The live driver exposes the published Set-based `TrackedClaim`; the ledger stores a separate `ResearchClaimRecord` with sorted arrays so JSON serialization cannot erase those sets.
-Source verification first persists a `ResearchClaimEvidence` observation that cannot affect claim support or completion, then `runVerifiedResearchLoop` calls `commitSources` only after the source registry write succeeds.
-The ledger unions those observations with exact confirmed original source URIs and materializes only their intersection, so a crash on either side resumes safely without treating an absent source as evidence or losing a registered source's claim.
+Source verification snapshots the proposal and persists a `ResearchClaimEvidence` observation containing the expected registry id, original URI, and full content hash; that observation cannot affect claim support or completion by itself.
+After the exact submitted bytes are durable, `runVerifiedResearchLoop` passes the resulting `SourceRecord` to `commitSources`.
+The ledger materializes only observations whose complete source identity matches a confirmed record, so reusing one URI for different bytes cannot activate the wrong claims and a crash on either side resumes safely.
+Unversioned URI-only ledgers cannot prove which bytes produced their observations; reads and writes fail with `ClaimLedgerMigrationRequiredError` and preserve the original file for an explicit archive-and-reverify migration.
 Before synchronous question generation, the persistent driver records `preparedRounds`; a resume reconstructs and checkpoints any prepared round whose questions were interrupted, and the loop publishes its `research.iteration` event only after that checkpoint succeeds.
 
-Every write in this layer goes through `durable-fs` (`writeFileDurable`, `writeJsonDurableWithinRoot`) — temp file, fsync, atomic rename, fsync parent, through `O_NOFOLLOW` descriptors anchored via `/proc/self/fd` so a directory swapped for a symlink mid-write cannot redirect it outside the root.
+Every write in this layer goes through `durable-fs` (`writeFileDurable`, `writeJsonDurableWithinRoot`): temp file, fsync, atomic rename, and parent fsync.
+`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.
 
 ## Runtime Loop

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-knowledge",
-  "version": "6.2.0",
+  "version": "7.0.2",
   "description": "Build, search, evaluate, and improve source-backed knowledge bases.",
   "homepage": "https://github.com/tangle-network/agent-knowledge#readme",
   "repository": {
@@ -75,8 +75,8 @@
     "verify:official-optimizers": "node scripts/verify-official-optimizers.mjs"
   },
   "dependencies": {
-    "@tangle-network/agent-eval": "0.135.2",
-    "@tangle-network/agent-interface": "0.36.0",
+    "@tangle-network/agent-eval": "0.139.1",
+    "@tangle-network/agent-interface": "0.40.0",
     "proper-lockfile": "4.1.2",
     "zod": "^4.4.3"
   },