feat(candidate): export shared knowledge references

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-knowledge",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Source-grounded, eval-gated knowledge growth primitives for agents.",
   "homepage": "https://github.com/tangle-network/agent-knowledge#readme",
   "repository": {
@@ -68,7 +68,8 @@
     "format": "biome format --write src tests"
   },
   "dependencies": {
-    "@tangle-network/agent-eval": "^0.118.3",
+    "@tangle-network/agent-eval": "^0.119.1",
+    "@tangle-network/agent-interface": "^0.26.1",
     "proper-lockfile": "4.1.2",
     "zod": "^4.3.6"
   },

src/agent-candidate.ts

@@ -0,0 +1,46 @@
+import {
+  type AgentCandidateKnowledgeRef,
+  sha256DigestSchema,
+} from '@tangle-network/agent-interface'
+
+import {
+  type KnowledgeImprovementCandidateRef,
+  KnowledgeImprovementCandidateRefSchema,
+} from './kb-improvement'
+
+/** Convert a measured knowledge candidate into the shared review and execution identity. */
+export function toAgentCandidateKnowledgeRef(
+  candidate: KnowledgeImprovementCandidateRef,
+): AgentCandidateKnowledgeRef {
+  const parsed = KnowledgeImprovementCandidateRefSchema.parse(candidate)
+  return {
+    ...parsed,
+    goalHash: prefixedDigest(parsed.goalHash),
+    baseHash: prefixedDigest(parsed.baseHash),
+    candidateHash: prefixedDigest(parsed.candidateHash),
+    evidenceHash: prefixedDigest(parsed.evidenceHash),
+    promotionPlanHash: prefixedDigest(parsed.promotionPlanHash),
+  }
+}
+
+/** Recover agent-knowledge's candidate identity from the shared contract. */
+export function fromAgentCandidateKnowledgeRef(
+  candidate: AgentCandidateKnowledgeRef,
+): KnowledgeImprovementCandidateRef {
+  return KnowledgeImprovementCandidateRefSchema.parse({
+    ...candidate,
+    goalHash: rawDigest(candidate.goalHash),
+    baseHash: rawDigest(candidate.baseHash),
+    candidateHash: rawDigest(candidate.candidateHash),
+    evidenceHash: rawDigest(candidate.evidenceHash),
+    promotionPlanHash: rawDigest(candidate.promotionPlanHash),
+  })
+}
+
+function prefixedDigest(value: string) {
+  return sha256DigestSchema.parse(`sha256:${value}`)
+}
+
+function rawDigest(value: string): string {
+  return sha256DigestSchema.parse(value).slice('sha256:'.length)
+}

src/index.ts

@@ -1,5 +1,6 @@
 export * from './adapters'
 export * from './adaptive-driver'
+export * from './agent-candidate'
 export * from './benchmarks/index'
 export * from './changes'
 export * from './chunking'

tests/agent-candidate.test.ts

@@ -0,0 +1,55 @@
+import {
+  type AgentCandidateKnowledgeRef,
+  agentCandidateKnowledgeSchema,
+} from '@tangle-network/agent-interface'
+import { describe, expect, it } from 'vitest'
+
+import {
+  fromAgentCandidateKnowledgeRef,
+  toAgentCandidateKnowledgeRef,
+} from '../src/agent-candidate'
+import type { KnowledgeImprovementCandidateRef } from '../src/kb-improvement'
+
+const candidate: KnowledgeImprovementCandidateRef = {
+  schemaVersion: 1,
+  kind: 'knowledge-improvement-candidate',
+  runId: 'knowledge-run',
+  candidateId: 'candidate-1',
+  goalHash: '1'.repeat(64),
+  baseHash: '2'.repeat(64),
+  candidateHash: '3'.repeat(64),
+  evidenceHash: '4'.repeat(64),
+  promotionPlanHash: '5'.repeat(64),
+}
+
+const sharedCandidate: AgentCandidateKnowledgeRef = {
+  schemaVersion: 1,
+  kind: 'knowledge-improvement-candidate',
+  runId: 'knowledge-run',
+  candidateId: 'candidate-1',
+  goalHash: `sha256:${'1'.repeat(64)}`,
+  baseHash: `sha256:${'2'.repeat(64)}`,
+  candidateHash: `sha256:${'3'.repeat(64)}`,
+  evidenceHash: `sha256:${'4'.repeat(64)}`,
+  promotionPlanHash: `sha256:${'5'.repeat(64)}`,
+}
+
+describe('agent candidate knowledge references', () => {
+  it('converts every hash into an independently validated shared reference', () => {
+    const shared = toAgentCandidateKnowledgeRef(candidate)
+
+    expect(shared).toEqual(sharedCandidate)
+    expect(agentCandidateKnowledgeSchema.shape.candidate.parse(shared)).toEqual(sharedCandidate)
+  })
+
+  it('recovers the exact knowledge candidate from an independent shared reference', () => {
+    expect(fromAgentCandidateKnowledgeRef(sharedCandidate)).toEqual(candidate)
+  })
+
+  it('rejects malformed shared hashes', () => {
+    const shared = toAgentCandidateKnowledgeRef(candidate)
+    expect(() =>
+      fromAgentCandidateKnowledgeRef({ ...shared, candidateHash: 'sha256:bad' }),
+    ).toThrow()
+  })
+})

tests/loops/adaptive-ab.test.ts

@@ -388,7 +388,7 @@ describe('adaptive A/B (offline, controlled): adaptive escalates only the ambigu
     // junk adaptive rejected) at strictly fewer LLM calls (2 vs 6 = a 3x cut).
     expect(adaptiveLlmCalls).toBeLessThan(fullCalls)
     expect(singleAdmitted).toBeGreaterThan(adaptiveAdmitted)
-  })
+  }, 10_000)
 })
 
 // ===========================================================================