@tangle-network/agent-knowledge 8.0.7 → 8.0.9

package/dist/memory/index.d.ts

@@ -1,3 +1,3 @@
-import { At as AgentMemoryScope, Bt as RetrievalHoldoutSessionState, Dt as AgentMemoryContext, Et as AgentMemoryBranchIsolation, Ft as RetrievalHoldoutCallContext, It as RetrievalHoldoutConfig, Lt as RetrievalHoldoutEligibleItem, Mt as AgentMemoryWriteInput, Nt as AgentMemoryWriteResult, Ot as AgentMemoryHit, Pt as RetrievalHoldoutBypassReason, Rt as RetrievalHoldoutEvent, St as acquireAgentMemoryRunLease, Tt as AgentMemoryAdapter, bt as AgentMemoryRunLease, jt as AgentMemorySearchOptions, kt as AgentMemoryKind, vt as AgentMemoryAcquireRunLease, xt as OwnedAgentMemoryRunLease, yt as AgentMemoryControllerMode, zt as RetrievalHoldoutResult } from "../index-CLNBGN_f.js";
-import { $ as runAgentMemoryLearningExperiment, A as AgentMemoryFinalPair, At as BuildAgentMemorySequencesFromBenchmarkCasesOptions, B as applySessionStickyRetrievalHoldout, Bt as AgentMemorySharingPolicy, C as runBoundedMemoryLifecycle, Ct as AgentMemorySequenceArtifact, D as AgentMemoryActivationDriver, Dt as AgentMemorySequenceStep, E as AgentMemoryActivation, Et as AgentMemorySequenceScenario, F as RunAgentMemoryImprovementResult, Ft as RunAgentMemoryLearningExperimentResult, G as toOffPolicyTrajectory, Gt as forkAgentMemoryBranchSnapshot, H as emitRetrievalHoldoutBypass, Ht as CreateAgentMemoryBranchOptions, I as RetrievalHoldoutOffPolicyOptions, It as AgentMemoryBranch, J as GraphitiToolNames, K as GraphitiMcpClientLike, Kt as defaultGetMemoryContext, L as RetrievalHoldoutOffPolicyResult, Lt as AgentMemoryBranchLifetime, M as AgentMemoryPromotionDecision, Mt as RunAgentMemoryExperimentOptions, N as MemoryConfigScenario, Nt as RunAgentMemoryExperimentResult, O as AgentMemoryDimensionComparison, Ot as AgentMemoryTransferCellComparison, P as RunAgentMemoryImprovementOptions, Pt as RunAgentMemoryLearningExperimentOptions, Q as compareAgentMemoryLearning, R as RetrievalHoldoutSessionSummary, Rt as AgentMemoryBranchSnapshot, S as resolveMemoryCleanupTimeoutMs, St as AgentMemorySequence, T as runAgentMemoryImprovement, Tt as AgentMemorySequenceProbeResult, U as resetRetrievalHoldoutRegistry, Ut as ForkAgentMemoryBranchSnapshotOptions, V as deterministicRng, Vt as AgentMemoryVisibility, W as retrievalHoldoutConfigHash, Wt as createAgentMemoryBranch, X as graphitiMemoryAdapterIdentity, Y as createGraphitiMemoryAdapter, Z as runAgentMemoryExperiment, _ as AgentMemoryLifecycleTimeoutError, _t as AgentMemoryLearningArmOrder, a as AgentMemoryScopeSchema, at as AgentMemoryExecutionContext, b as createMemoryExecutionPool, bt as AgentMemoryLearningComparison, c as createNeo4jAgentMemoryAdapter, ct as AgentMemoryExecutionPaidCallInput, d as Mem0HostedMemoryAdapterOptions, dt as AgentMemoryExperimentCandidate, et as agentMemorySequenceJudge, f as Mem0MemoryAdapterOptions, ft as AgentMemoryExperimentCandidateRef, g as mem0MemoryAdapterIdentity, gt as AgentMemoryForgettingComparison, h as createMem0MemoryAdapter, ht as AgentMemoryExperimentRunLease, i as AgentMemoryKindSchema, it as AgentMemoryEvidenceRef, j as AgentMemoryImprovementRunLease, jt as CompareAgentMemoryLearningOptions, k as AgentMemoryFinalEvaluation, kt as AgentMemoryTransferStepSummary, l as Mem0ClientMode, lt as AgentMemoryExecutionPaidCallResult, m as Mem0OssMemoryAdapterOptions, mt as AgentMemoryExperimentRankingRow, n as memoryWriteResultToSourceRecord, nt as buildAgentMemorySequencesFromBenchmarkCases, o as AgentMemoryWriteInputSchema, ot as AgentMemoryExecutionCostMeter, p as Mem0OssClient, pt as AgentMemoryExperimentComparisonRef, q as GraphitiMemoryAdapterOptions, qt as renderMemoryContext, r as AgentMemoryHitSchema, rt as AgentMemoryAttemptEvent, s as Neo4jAgentMemoryAdapterOptions, st as AgentMemoryExecutionCostReceipt, t as memoryHitToSourceRecord, tt as buildAgentMemorySequenceScenarios, u as Mem0HostedClient, ut as AgentMemoryExecutionStep, v as AgentMemoryLifecycleUnsafeError, vt as AgentMemoryLearningCandidateSummary, w as sleepForMemoryRecovery, wt as AgentMemorySequenceProbe, x as memoryRecoveryDelayMs, xt as AgentMemoryMode, y as DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS, yt as AgentMemoryLearningCellComparison, z as applyRetrievalHoldout, zt as AgentMemoryJournalEntry } from "../index-BPNsQVSx.js";
+import { At as AgentMemoryScope, Bt as RetrievalHoldoutSessionState, Dt as AgentMemoryContext, Et as AgentMemoryBranchIsolation, Ft as RetrievalHoldoutCallContext, It as RetrievalHoldoutConfig, Lt as RetrievalHoldoutEligibleItem, Mt as AgentMemoryWriteInput, Nt as AgentMemoryWriteResult, Ot as AgentMemoryHit, Pt as RetrievalHoldoutBypassReason, Rt as RetrievalHoldoutEvent, St as acquireAgentMemoryRunLease, Tt as AgentMemoryAdapter, bt as AgentMemoryRunLease, jt as AgentMemorySearchOptions, kt as AgentMemoryKind, vt as AgentMemoryAcquireRunLease, xt as OwnedAgentMemoryRunLease, yt as AgentMemoryControllerMode, zt as RetrievalHoldoutResult } from "../index-DypNCZtP.js";
+import { $ as runAgentMemoryLearningExperiment, A as AgentMemoryFinalPair, At as BuildAgentMemorySequencesFromBenchmarkCasesOptions, B as applySessionStickyRetrievalHoldout, Bt as AgentMemorySharingPolicy, C as runBoundedMemoryLifecycle, Ct as AgentMemorySequenceArtifact, D as AgentMemoryActivationDriver, Dt as AgentMemorySequenceStep, E as AgentMemoryActivation, Et as AgentMemorySequenceScenario, F as RunAgentMemoryImprovementResult, Ft as RunAgentMemoryLearningExperimentResult, G as toOffPolicyTrajectory, Gt as forkAgentMemoryBranchSnapshot, H as emitRetrievalHoldoutBypass, Ht as CreateAgentMemoryBranchOptions, I as RetrievalHoldoutOffPolicyOptions, It as AgentMemoryBranch, J as GraphitiToolNames, K as GraphitiMcpClientLike, Kt as defaultGetMemoryContext, L as RetrievalHoldoutOffPolicyResult, Lt as AgentMemoryBranchLifetime, M as AgentMemoryPromotionDecision, Mt as RunAgentMemoryExperimentOptions, N as MemoryConfigScenario, Nt as RunAgentMemoryExperimentResult, O as AgentMemoryDimensionComparison, Ot as AgentMemoryTransferCellComparison, P as RunAgentMemoryImprovementOptions, Pt as RunAgentMemoryLearningExperimentOptions, Q as compareAgentMemoryLearning, R as RetrievalHoldoutSessionSummary, Rt as AgentMemoryBranchSnapshot, S as resolveMemoryCleanupTimeoutMs, St as AgentMemorySequence, T as runAgentMemoryImprovement, Tt as AgentMemorySequenceProbeResult, U as resetRetrievalHoldoutRegistry, Ut as ForkAgentMemoryBranchSnapshotOptions, V as deterministicRng, Vt as AgentMemoryVisibility, W as retrievalHoldoutConfigHash, Wt as createAgentMemoryBranch, X as graphitiMemoryAdapterIdentity, Y as createGraphitiMemoryAdapter, Z as runAgentMemoryExperiment, _ as AgentMemoryLifecycleTimeoutError, _t as AgentMemoryLearningArmOrder, a as AgentMemoryScopeSchema, at as AgentMemoryExecutionContext, b as createMemoryExecutionPool, bt as AgentMemoryLearningComparison, c as createNeo4jAgentMemoryAdapter, ct as AgentMemoryExecutionPaidCallInput, d as Mem0HostedMemoryAdapterOptions, dt as AgentMemoryExperimentCandidate, et as agentMemorySequenceJudge, f as Mem0MemoryAdapterOptions, ft as AgentMemoryExperimentCandidateRef, g as mem0MemoryAdapterIdentity, gt as AgentMemoryForgettingComparison, h as createMem0MemoryAdapter, ht as AgentMemoryExperimentRunLease, i as AgentMemoryKindSchema, it as AgentMemoryEvidenceRef, j as AgentMemoryImprovementRunLease, jt as CompareAgentMemoryLearningOptions, k as AgentMemoryFinalEvaluation, kt as AgentMemoryTransferStepSummary, l as Mem0ClientMode, lt as AgentMemoryExecutionPaidCallResult, m as Mem0OssMemoryAdapterOptions, mt as AgentMemoryExperimentRankingRow, n as memoryWriteResultToSourceRecord, nt as buildAgentMemorySequencesFromBenchmarkCases, o as AgentMemoryWriteInputSchema, ot as AgentMemoryExecutionCostMeter, p as Mem0OssClient, pt as AgentMemoryExperimentComparisonRef, q as GraphitiMemoryAdapterOptions, qt as renderMemoryContext, r as AgentMemoryHitSchema, rt as AgentMemoryAttemptEvent, s as Neo4jAgentMemoryAdapterOptions, st as AgentMemoryExecutionCostReceipt, t as memoryHitToSourceRecord, tt as buildAgentMemorySequenceScenarios, u as Mem0HostedClient, ut as AgentMemoryExecutionStep, v as AgentMemoryLifecycleUnsafeError, vt as AgentMemoryLearningCandidateSummary, w as sleepForMemoryRecovery, wt as AgentMemorySequenceProbe, x as memoryRecoveryDelayMs, xt as AgentMemoryMode, y as DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS, yt as AgentMemoryLearningCellComparison, z as applyRetrievalHoldout, zt as AgentMemoryJournalEntry } from "../index-Ij4giqqj.js";
 export { AgentMemoryAcquireRunLease, type AgentMemoryActivation, type AgentMemoryActivationDriver, AgentMemoryAdapter, type AgentMemoryAttemptEvent, AgentMemoryBranch, AgentMemoryBranchIsolation, AgentMemoryBranchLifetime, AgentMemoryBranchSnapshot, AgentMemoryContext, AgentMemoryControllerMode, type AgentMemoryDimensionComparison, type AgentMemoryEvidenceRef, type AgentMemoryExecutionContext, type AgentMemoryExecutionCostMeter, type AgentMemoryExecutionCostReceipt, type AgentMemoryExecutionPaidCallInput, type AgentMemoryExecutionPaidCallResult, type AgentMemoryExecutionStep, type AgentMemoryExperimentCandidate, type AgentMemoryExperimentCandidateRef, type AgentMemoryExperimentComparisonRef, type AgentMemoryExperimentRankingRow, type AgentMemoryExperimentRunLease, type AgentMemoryFinalEvaluation, type AgentMemoryFinalPair, type AgentMemoryForgettingComparison, AgentMemoryHit, AgentMemoryHitSchema, type AgentMemoryImprovementRunLease, AgentMemoryJournalEntry, AgentMemoryKind, AgentMemoryKindSchema, type AgentMemoryLearningArmOrder, type AgentMemoryLearningCandidateSummary, type AgentMemoryLearningCellComparison, type AgentMemoryLearningComparison, AgentMemoryLifecycleTimeoutError, AgentMemoryLifecycleUnsafeError, type AgentMemoryMode, type AgentMemoryPromotionDecision, AgentMemoryRunLease, AgentMemoryScope, AgentMemoryScopeSchema, AgentMemorySearchOptions, type AgentMemorySequence, type AgentMemorySequenceArtifact, type AgentMemorySequenceProbe, type AgentMemorySequenceProbeResult, type AgentMemorySequenceScenario, type AgentMemorySequenceStep, AgentMemorySharingPolicy, type AgentMemoryTransferCellComparison, type AgentMemoryTransferStepSummary, AgentMemoryVisibility, AgentMemoryWriteInput, AgentMemoryWriteInputSchema, AgentMemoryWriteResult, type BuildAgentMemorySequencesFromBenchmarkCasesOptions, type CompareAgentMemoryLearningOptions, CreateAgentMemoryBranchOptions, DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS, ForkAgentMemoryBranchSnapshotOptions, GraphitiMcpClientLike, GraphitiMemoryAdapterOptions, GraphitiToolNames, Mem0ClientMode, Mem0HostedClient, Mem0HostedMemoryAdapterOptions, Mem0MemoryAdapterOptions, Mem0OssClient, Mem0OssMemoryAdapterOptions, type MemoryConfigScenario, Neo4jAgentMemoryAdapterOptions, OwnedAgentMemoryRunLease, RetrievalHoldoutBypassReason, RetrievalHoldoutCallContext, RetrievalHoldoutConfig, RetrievalHoldoutEligibleItem, RetrievalHoldoutEvent, RetrievalHoldoutOffPolicyOptions, RetrievalHoldoutOffPolicyResult, RetrievalHoldoutResult, RetrievalHoldoutSessionState, RetrievalHoldoutSessionSummary, type RunAgentMemoryExperimentOptions, type RunAgentMemoryExperimentResult, type RunAgentMemoryImprovementOptions, type RunAgentMemoryImprovementResult, type RunAgentMemoryLearningExperimentOptions, type RunAgentMemoryLearningExperimentResult, acquireAgentMemoryRunLease, agentMemorySequenceJudge, applyRetrievalHoldout, applySessionStickyRetrievalHoldout, buildAgentMemorySequenceScenarios, buildAgentMemorySequencesFromBenchmarkCases, compareAgentMemoryLearning, createAgentMemoryBranch, createGraphitiMemoryAdapter, createMem0MemoryAdapter, createMemoryExecutionPool, createNeo4jAgentMemoryAdapter, defaultGetMemoryContext, deterministicRng, emitRetrievalHoldoutBypass, forkAgentMemoryBranchSnapshot, graphitiMemoryAdapterIdentity, mem0MemoryAdapterIdentity, memoryHitToSourceRecord, memoryRecoveryDelayMs, memoryWriteResultToSourceRecord, renderMemoryContext, resetRetrievalHoldoutRegistry, resolveMemoryCleanupTimeoutMs, retrievalHoldoutConfigHash, runAgentMemoryExperiment, runAgentMemoryImprovement, runAgentMemoryLearningExperiment, runBoundedMemoryLifecycle, sleepForMemoryRecovery, toOffPolicyTrajectory };

package/dist/{types-CXZS0w00.d.ts → types-CTT16XnO.d.ts}

@@ -87,6 +87,8 @@ interface KnowledgePage {
   sourceIds: string[];
   tags: string[];
   outLinks: string[];
+  /** Stable page ids this page explicitly builds on. */
+  cites?: KnowledgeId[];
   /** Page ids this page explicitly refutes. */
   contradicts?: KnowledgeId[];
   /** Present only when this page's own evidence has refuted the page. */
@@ -142,7 +144,7 @@ interface KnowledgeSearchResult {
   reasons: string[];
 }
 interface KnowledgeLintFinding {
-  type: 'broken-link' | 'orphan' | 'no-outlinks' | 'uncited-claim' | 'missing-source' | 'duplicate-title' | 'duplicate-page-id' | 'duplicate-source-hash' | 'missing-frontmatter' | 'ungradeable-evidence' | 'missing-evidence-path' | 'nonportable-evidence' | 'broken-contradiction' | 'invalid-invalidation';
+  type: 'broken-link' | 'broken-citation' | 'ambiguous-citation' | 'orphan' | 'no-outlinks' | 'uncited-claim' | 'missing-source' | 'duplicate-title' | 'duplicate-page-id' | 'duplicate-source-hash' | 'missing-frontmatter' | 'ungradeable-evidence' | 'missing-evidence-path' | 'nonportable-evidence' | 'broken-contradiction' | 'invalid-invalidation';
   severity: 'info' | 'warning' | 'error';
   page?: string;
   message: string;
@@ -323,4 +325,4 @@ interface KnowledgeRelease {
 }
 //#endregion
 export { SourceRegistry as A, KnowledgeWriteParseResult as C, ResearchSourceVersion as D, ResearchClaimRecord as E, SourceAnchor as O, KnowledgeWriteBlock as S, ResearchClaimLedger as T, KnowledgePolicy as _, KnowledgeBaseCandidate as a, KnowledgeSearchResult as b, KnowledgeEventType as c, KnowledgeGraphNode as d, KnowledgeId as f, KnowledgePageInvalidation as g, KnowledgePage as h, KNOWLEDGE_EVENT_TYPES as i, TrackedClaim as j, SourceRecord 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, KnowledgeRelation as v, ResearchClaimEvidence as w, KnowledgeUnit as x, KnowledgeRelease as y };
-//# sourceMappingURL=types-CXZS0w00.d.ts.map
+//# sourceMappingURL=types-CTT16XnO.d.ts.map

package/dist/types-CTT16XnO.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-CTT16XnO.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;;;;;;;;;;UAWe;EACf;EACA;EACA;EACA;EACA;EACA,WAAW;;UAGI;EACf,IAAI;EACJ;EACA;EACA;EACA,aAAa;EACb;EACA;EACA;;EAEA,QAAQ;;EAER,cAAc;;EAEd,eAAe;;UAGA;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;EAiBA;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-CXZS0w00.js";
+import { d as KnowledgeGraphNode, l as KnowledgeGraph, u as KnowledgeGraphEdge } from "../types-CTT16XnO.js";
 //#region src/viz/index.d.ts
 interface KnowledgeVizNode extends KnowledgeGraphNode {
   degree: number;

package/docs/knowledge-use-receipts.md

@@ -0,0 +1,182 @@
+# Knowledge retrieval and use receipts
+
+A knowledge page appearing in a prompt, a final answer resembling a prior result, and a citation in a generated document are three different facts. None of them alone proves that a particular agent retrieved a particular page and used it in a downstream decision.
+
+This module records two immutable links:
+
+```text
+exact visible knowledge snapshot
+        ↓
+retrieval receipt
+        ↓
+selected returned result
+        ↓
+knowledge-use receipt
+        ↓
+decision / artifact / experiment / candidate / message
+```
+
+The receipts establish provenance. They do not decide whether using the knowledge was wise, whether the downstream result is correct, or whether it is novel. Those are Eval questions over the retained evidence.
+
+## Visibility snapshot
+
+`createKnowledgeVisibilitySnapshot()` binds the ordered set of pages visible to one retrieval operation. Every entry records:
+
+- position;
+- stable page id;
+- origin (`here`, `inherited:<runId>`, or `shared`);
+- path;
+- canonical page digest;
+- source ids;
+- whether the page was invalidated.
+
+Order is identity-bearing because retrieval algorithms may use order as a tie break or candidate window. Page text, frontmatter, citations, contradictions, invalidation state, path, and source joins are included in each page digest.
+
+```ts
+import { createKnowledgeVisibilitySnapshot } from '@tangle-network/agent-knowledge'
+
+const visibility = createKnowledgeVisibilitySnapshot(await stores.loadChain(runId))
+console.log(visibility.snapshotDigest)
+```
+
+A repeated path at the same origin is refused. The same stable page id may remain visible at different origins; ambiguity-safe citation resolution is handled separately.
+
+## Retrieval receipt
+
+`createKnowledgeRetrievalReceipt()` binds:
+
+- run id;
+- optional actor, profile, and execution identities;
+- exact query;
+- retriever id, version, and configuration digest;
+- the complete visibility snapshot;
+- every ranked returned page, origin, path, digest, score, snippet, and reason;
+- trace or artifact evidence references;
+- bounded scalar attributes;
+- creation timestamp.
+
+A result is accepted only when its exact page bytes, path, id, and origin occur in the visibility snapshot. Ranks must be unique and contiguous from one. Scores must be finite, and normalized scores must lie in `[0, 1]`.
+
+```ts
+import { canonicalCandidateDigest } from '@tangle-network/agent-interface'
+import { createKnowledgeRetrievalReceipt } from '@tangle-network/agent-knowledge'
+
+const receipt = createKnowledgeRetrievalReceipt({
+  runId,
+  actorId: 'root:s0',
+  profileDigest,
+  executionRef,
+  query: 'prior obstruction calibrated verifier',
+  retriever: {
+    id: 'inspectable-token-overlap',
+    version: '1.0.0',
+    configDigest: canonicalCandidateDigest({ tokenizer: 'unicode-words', limit: 5 }),
+  },
+  visiblePages,
+  results,
+  evidenceRefs: [{ kind: 'event', uri: `event://${runId}/retrieval-1` }],
+})
+```
+
+`verifyKnowledgeRetrievalReceipt()` recomputes the visibility and receipt digests and checks every result-to-visibility join. `assertKnowledgeRetrievalMatchesVisibility()` additionally proves that the receipt still describes a supplied page snapshot; a later page mutation fails this check.
+
+## Use receipt
+
+`createKnowledgeUseReceipt()` selects one exact rank returned by a verified retrieval and binds it to a downstream consumer:
+
+```ts
+const use = createKnowledgeUseReceipt({
+  retrieval: receipt,
+  selectedRank: 1,
+  relation: 'extends',
+  consumer: {
+    kind: 'artifact',
+    uri: `artifact://${runId}/DECISION.md`,
+    digest: decisionArtifactDigest,
+  },
+  evidenceRefs: [{ kind: 'span', uri: `trace://${runId}/span/knowledge-use-1` }],
+})
+```
+
+Relations are descriptive:
+
+- `supports`
+- `contradicts`
+- `extends`
+- `rederives`
+- `background`
+
+Consumer kinds are:
+
+- `decision`
+- `artifact`
+- `experiment`
+- `candidate`
+- `message`
+- `other`
+
+The use receipt copies the selected result's rank, page id, origin, path, and digest. It references the retrieval receipt digest. `verifyKnowledgeUseReceipt()` refuses verification against a different retrieval, a result that was not returned, a changed selected page, or any mutation of the relation or consumer identity.
+
+## Canonical serialization
+
+Optional actor, profile, execution, consumer-digest, and evidence-excerpt fields are omitted when absent. They are never emitted with a JavaScript `undefined` value. Empty evidence and attribute collections remain explicit empty arrays or objects because they are part of the receipt contract.
+
+Attribute values are deliberately limited to strings, finite numbers, booleans, and `null`. Nested arbitrary objects are refused rather than passed through a language-specific serializer. More structured evidence belongs in an artifact or a versioned contract referenced by digest.
+
+The receipt digest covers the complete canonical material except the digest field itself. A verifier recomputes both the visibility snapshot digest and the outer receipt digest; copying a digest onto modified content does not verify.
+
+## What a receipt proves
+
+A valid retrieval receipt proves:
+
+> Under this exact run/actor/profile/execution identity, this exact retriever configuration searched this exact ordered knowledge snapshot with this exact query and returned these exact ranked page versions.
+
+A valid use receipt additionally proves:
+
+> The consumer selected this exact returned page version and declared this exact relation while producing this exact downstream consumer identity.
+
+It does **not** prove:
+
+- that the page's claim is true;
+- that the declared relation is semantically correct;
+- that the consumer complied with the page;
+- that the downstream artifact passed its verifier;
+- that the result is novel rather than a re-derivation;
+- that knowledge improved the outcome.
+
+Those claims require Eval findings, artifact checks, paired experiments, novelty/reuse adjudication, and downstream outcome evidence.
+
+## Trace integration
+
+Both receipts accept canonical Eval `EvidenceRef` values. A Runtime or product adapter should emit a trace event/span containing the receipt digest and retain the receipt itself as an artifact or durable record. The trace is an index into the receipt; it is not a second copy of its truth.
+
+Recommended event attributes:
+
+```text
+knowledge.receipt.kind
+knowledge.receipt.digest
+knowledge.visibility.digest
+knowledge.retriever.id
+knowledge.retriever.version
+knowledge.result.count
+knowledge.used.page_id
+knowledge.used.origin
+knowledge.consumer.kind
+knowledge.consumer.uri
+knowledge.relation
+```
+
+Do not encode absent token, cost, model, status, or artifact state as zero or success while attaching these receipts. Knowledge provenance cannot repair incomplete execution evidence.
+
+## Experiment use
+
+For a knowledge-compounding comparison, record separately:
+
+1. knowledge available to the arm;
+2. knowledge retrieved;
+3. knowledge selected for use;
+4. the downstream decision or artifact;
+5. the verifier outcome;
+6. whether the contribution duplicated, verified, extended, corrected, newly applied, or independently discovered the prior result.
+
+This separation prevents final-prose similarity or citation count from masquerading as causal evidence that accumulated knowledge improved research.

package/docs/run-scoped-citations.md

@@ -0,0 +1,106 @@
+# Run-scoped citations
+
+A run-scoped knowledge chain contains three visibility classes:
+
+1. pages written by the current run (`here`);
+2. pages written by declared ancestors (`inherited:<runId>`);
+3. pages in an optional curated shared store (`shared`).
+
+`createRunScopedStores()` preserves every visible page and its origin. It does not shadow a page merely because a nearer store has the same stable id.
+
+## Persisted citation form
+
+A page records stable page references in `cites` frontmatter:
+
+```yaml
+---
+id: later-result
+cites:
+  - prior-result
+---
+```
+
+An unqualified id is valid only when exactly one visible page has that id. When duplicate ids are intentional, qualify the origin:
+
+```yaml
+cites:
+  - here::current-result
+  - inherited:run-2026-08-16::prior-result
+  - shared::instrument-calibration
+```
+
+Use `parseKnowledgeCitationReference()` and `formatKnowledgeCitationReference()` rather than assembling qualified strings in application code.
+
+## Resolution
+
+```ts
+import {
+  assertCurrentRunCitationsResolved,
+  createRunScopedStores,
+  resolveRunScopedCitation,
+} from '@tangle-network/agent-knowledge'
+
+const stores = createRunScopedStores({
+  root: './runs',
+  sharedRoot: './curated-knowledge',
+})
+
+const resolved = await resolveRunScopedCitation(stores, 'run-b', {
+  pageId: 'prior-result',
+})
+
+if (resolved.status !== 'resolved') {
+  console.error(resolved.status, resolved.candidates)
+}
+
+await assertCurrentRunCitationsResolved(stores, 'run-b')
+```
+
+Resolution has three non-coercing outcomes:
+
+- `resolved`: exactly one visible page matches;
+- `missing`: no visible page matches;
+- `ambiguous`: more than one visible page matches.
+
+Missing and ambiguous references remain explicit. They never select the nearest page, the newest page, or the shared page by default.
+
+## Product-owned lineage
+
+A product that already owns run ancestry should provide a `RunLineageAuthority` rather than copying its manifest into `lineage.json`:
+
+```ts
+const stores = createRunScopedStores({
+  root: './runs',
+  runStorePath: (runId) => `./runs/${runId}/knowledge-base`,
+  sharedRoot: './curated-knowledge',
+  lineageAuthority: {
+    async parentOf(runId) {
+      const manifest = await readRunManifest(runId)
+      return manifest.parentRunId
+    },
+  },
+})
+```
+
+A read-only authority must already contain the lineage before `init()` is called. `init()` verifies the requested parent against that authority and fails on disagreement. An authority that also implements `record()` may durably create the lineage itself.
+
+The default file-backed authority is idempotent. Reopening a run with the same parent is accepted; reopening it with another parent is a lineage conflict.
+
+## Lint and graph behavior
+
+`auditCurrentRunCitations()` checks current-run pages against one materialized visibility chain. `lintCurrentRunCitations()` converts missing, ambiguous, and self-citations into blocking package lint findings.
+
+Within one knowledge index, unambiguous `cites` relations become graph edges with reason `citation`. Duplicate target ids do not produce a guessed edge; the relation remains unresolved until it is qualified or the duplicate is removed.
+
+## Migration rule
+
+For an existing application-owned store:
+
+1. freeze the old reader and writer behavior with golden fixtures;
+2. expose the existing run manifest as a `RunLineageAuthority`;
+3. dual-read the same frozen corpus through both implementations;
+4. classify every mismatch without coercion;
+5. switch new reads and writes only after parity is demonstrated;
+6. retain historical bytes and delete the duplicate live owner.
+
+A migration is not complete while two implementations can independently write lineage, page identities, or citation relations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-knowledge",
-  "version": "8.0.7",
+  "version": "8.0.9",
   "description": "Build, search, evaluate, and improve source-backed knowledge bases.",
   "homepage": "https://github.com/tangle-network/agent-knowledge#readme",
   "repository": {
@@ -71,31 +71,36 @@
     "lint": "biome check src tests",
     "format": "biome format --write src tests",
     "check:skills": "node scripts/check-skills.mjs",
-    "verify:package": "pnpm run check:skills && publint && attw --pack --profile esm-only . && node scripts/verify-package.mjs",
-    "verify:official-optimizers": "node scripts/verify-official-optimizers.mjs"
+    "verify:package": "pnpm run check:version-bump && pnpm run check:skills && pnpm run check:api-surface && publint && attw --pack --profile esm-only . && node scripts/verify-package.mjs",
+    "verify:official-optimizers": "node scripts/verify-official-optimizers.mjs",
+    "check:version-bump": "node scripts/check-version-bump.mjs",
+    "check:api-surface": "node scripts/check-api-surface.mjs",
+    "api:surface": "node scripts/check-api-surface.mjs --write"
   },
   "dependencies": {
+    "@types/proper-lockfile": "4.1.4",
     "proper-lockfile": "4.1.2",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@tangle-network/agent-eval": ">=0.147.0 <0.148.0",
-    "@tangle-network/agent-interface": "^1.0.0"
+    "@tangle-network/agent-eval": ">=0.148.0 <0.149.0",
+    "@tangle-network/agent-interface": "^1.1.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@biomejs/biome": "^2.5.5",
     "@neo4j-labs/agent-memory": "0.4.1",
-    "@tangle-network/agent-eval": "0.147.0",
-    "@tangle-network/agent-interface": "1.0.0",
+    "@tangle-network/agent-eval": "0.148.0",
+    "@tangle-network/agent-interface": "1.1.0",
     "@types/node": "^26.1.1",
-    "@types/proper-lockfile": "4.1.4",
     "mem0ai": "3.1.2",
+    "oxc-parser": "0.144.0",
     "publint": "^0.3.22",
     "tsdown": "^0.22.14",
     "typescript": "^7.0.2",
     "vite": "8.1.5",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.10",
+    "yaml": "2.9.0"
   },
   "pnpm": {
     "ignoredBuiltDependencies": [