@indexnetwork/protocol 4.14.2-rc.356.1 → 4.16.0-rc.358.1

package/dist/shared/hyde/hyde.graph.js

@@ -1,18 +1,27 @@
 /**
  * HyDE Graph: cache-aware hypothetical document generation with lens inference.
  *
- * Flow: infer_lenses → check_cache → (generate_missing if needed) → embed → cache_results.
- * Constructor injects Database, Embedder, Cache, LensInferrer, HydeGenerator.
+ * Legacy flow: infer_lenses → check_cache → generate_missing? → embed → cache_results.
+ * Frame-v1 flow adds one batch validate_generated node before embed.
  */
-import { StateGraph, START, END } from '@langchain/langgraph';
 import { createHash } from 'crypto';
+import { END, START, StateGraph } from '@langchain/langgraph';
 import { getAbortSignalConfig } from '../agent/model-signal.js';
-import { HydeGraphState } from './hyde.state.js';
-import { HYDE_DEFAULT_CACHE_TTL } from './hyde.strategies.js';
 import { protocolLogger } from '../observability/protocol.logger.js';
 import { timed } from '../observability/performance.js';
 import { requestContext } from "../observability/request-context.js";
+import { computeHydeSourceTextHash } from './hyde.documents.js';
+import { getHydeGenerationMode, HYDE_FRAME_GENERATION_VERSION } from './hyde.env.js';
+import { sanitizeHydeSourceFrame } from './hyde.frame.js';
+import { HydeGraphState } from './hyde.state.js';
+import { HYDE_DEFAULT_CACHE_TTL } from './hyde.strategies.js';
+import { HydeValidator } from './hyde.validator.js';
 const logger = protocolLogger("HyDEGraphFactory");
+let lastGenerationTimestamp = 0;
+function nextGenerationMarker() {
+    lastGenerationTimestamp = Math.max(Date.now(), lastGenerationTimestamp + 1);
+    return new Date(lastGenerationTimestamp).toISOString();
+}
 /** Hash a lens label (+ optional corpus) to a short key for cache/DB indexing. */
 function lensHash(label, corpus) {
     const input = corpus
@@ -20,149 +29,367 @@ function lensHash(label, corpus) {
         : label.toLowerCase().trim();
     return createHash('sha256').update(input).digest('hex').slice(0, 16);
 }
-/** Build cache key for a specific lens. */
-function cacheKey(sourceType, sourceId, sourceText, lens, corpus) {
-    const entityKey = sourceId ?? `q:${createHash('sha256').update(sourceText).digest('hex').slice(0, 16)}`;
-    return `hyde:${sourceType}:${entityKey}:${lensHash(lens, corpus)}`;
+function entityCacheKey(sourceId, sourceText) {
+    return sourceId ?? `q:${createHash('sha256').update(sourceText).digest('hex').slice(0, 16)}`;
 }
-/**
- * Factory for the HyDE generation graph.
- * Injects Database, Embedder, Cache, LensInferrer, and HydeGenerator.
- */
+function sortedFrame(frame) {
+    const sort = (items) => [...items].sort((left, right) => {
+        const leftJson = JSON.stringify(left);
+        const rightJson = JSON.stringify(right);
+        return leftJson < rightJson ? -1 : leftJson > rightJson ? 1 : 0;
+    });
+    return {
+        sourceRoles: sort(frame.sourceRoles),
+        counterpartRoles: sort(frame.counterpartRoles),
+        hardConstraints: sort(frame.hardConstraints),
+        namedEntities: sort(frame.namedEntities),
+        domainVocabulary: sort(frame.domainVocabulary),
+    };
+}
+/** Deterministic identity for the source content and sanitized frame. */
+function computeHydeFrameFingerprint(sourceText, sourceFrame) {
+    return createHash('sha256')
+        .update(sourceText)
+        .update('\0')
+        .update(JSON.stringify(sortedFrame(sourceFrame)))
+        .digest('hex');
+}
+function requireFrameFingerprint(frameFingerprint) {
+    if (!frameFingerprint)
+        throw new Error('frame-v1 HyDE requires a frame fingerprint');
+    return frameFingerprint;
+}
+/** Preserve the exact legacy Redis key and isolate frame-v1 data by namespace. */
+function cacheKey(mode, sourceType, sourceId, sourceText, lens, corpus, frameFingerprint) {
+    const entityKey = entityCacheKey(sourceId, sourceText);
+    if (mode === 'legacy')
+        return `hyde:${sourceType}:${entityKey}:${lensHash(lens, corpus)}`;
+    return `hyde:${HYDE_FRAME_GENERATION_VERSION}:${sourceType}:${entityKey}:${requireFrameFingerprint(frameFingerprint)}:${lensHash(lens, corpus)}`;
+}
+/** Preserve legacy identity and use a stable frame-v1 identity per lens/corpus. */
+function dbStrategy(mode, label, corpus) {
+    const hash = lensHash(label, corpus);
+    return mode === 'legacy' ? hash : `${HYDE_FRAME_GENERATION_VERSION}:${hash}`;
+}
+function isValidGenerationMarker(value) {
+    return typeof value === 'string' && Number.isFinite(Date.parse(value));
+}
+function isFrameCacheDocument(doc, lensLabel, frameFingerprint, sourceTextHash) {
+    return doc.hydeGenerationVersion === HYDE_FRAME_GENERATION_VERSION
+        && doc.validationStatus === 'valid'
+        && doc.lens === lensLabel
+        && doc.frameFingerprint === frameFingerprint
+        && doc.sourceTextHash === sourceTextHash
+        && isValidGenerationMarker(doc.generatedAt);
+}
+function isFrameDbContext(context, lensLabel, frameFingerprint, sourceTextHash) {
+    return context?.hydeGenerationVersion === HYDE_FRAME_GENERATION_VERSION
+        && context.lensLabel === lensLabel
+        && context.validationStatus === 'valid'
+        && context.frameFingerprint === frameFingerprint
+        && context.sourceTextHash === sourceTextHash
+        && isValidGenerationMarker(context.generatedAt);
+}
+function emptyFrame() {
+    return {
+        sourceRoles: [],
+        counterpartRoles: [],
+        hardConstraints: [],
+        namedEntities: [],
+        domainVocabulary: [],
+    };
+}
+function opaqueDocumentKey(doc) {
+    return `d-${createHash('sha256')
+        .update(`${doc.lens}\0${doc.targetCorpus}\0${doc.hydeText}`)
+        .digest('hex')
+        .slice(0, 16)}`;
+}
+function isRuntimeVerdict(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const verdict = value;
+    return typeof verdict.key === 'string'
+        && typeof verdict.valid === 'boolean'
+        && Array.isArray(verdict.unsupportedNamedEntities)
+        && verdict.unsupportedNamedEntities.every((item) => typeof item === 'string')
+        && Array.isArray(verdict.unsupportedHardConstraints)
+        && verdict.unsupportedHardConstraints.every((item) => typeof item === 'string')
+        && typeof verdict.reasoning === 'string';
+}
+/** Factory for the HyDE generation graph. Existing five-argument calls remain valid. */
 export class HydeGraphFactory {
-    constructor(database, embedder, cache, inferrer, generator) {
+    constructor(database, embedder, cache, inferrer, generator, options = {}) {
         this.database = database;
         this.embedder = embedder;
         this.cache = cache;
         this.inferrer = inferrer;
         this.generator = generator;
+        this.options = options;
     }
     createGraph() {
         const self = this;
+        const mode = this.options.mode ?? getHydeGenerationMode();
+        const validator = mode === HYDE_FRAME_GENERATION_VERSION
+            ? (this.options.validator ?? new HydeValidator())
+            : undefined;
         /** Node 1: Infer lenses from source text + optional profile context. */
         const inferLensesNode = async (state) => {
             return timed("HydeGraph.inferLenses", async () => {
                 const { sourceText, profileContext, maxLenses } = state;
-                logger.verbose('Inferring lenses', { sourceTextLength: sourceText.length, hasProfileContext: !!profileContext });
                 const agentTimingsAccum = [];
                 try {
-                    const _traceEmitterLens = requestContext.getStore()?.traceEmitter;
+                    const traceEmitter = requestContext.getStore()?.traceEmitter;
                     const inferrerStart = Date.now();
-                    _traceEmitterLens?.({ type: "agent_start", name: "lens-inferrer" });
+                    traceEmitter?.({ type: "agent_start", name: "lens-inferrer" });
                     const result = await self.inferrer.infer({
                         sourceText,
                         profileContext,
                         maxLenses,
+                        ...(mode === HYDE_FRAME_GENERATION_VERSION ? { frameConstrained: true } : {}),
                     });
-                    const _inferrerDuration = Date.now() - inferrerStart;
-                    agentTimingsAccum.push({ name: 'lens.inferrer', durationMs: _inferrerDuration });
-                    _traceEmitterLens?.({ type: "agent_end", name: "lens-inferrer", durationMs: _inferrerDuration, summary: result.lenses.length > 0 ? `Inferred ${result.lenses.length} lens(es)` : "lens-inferrer completed" });
-                    logger.verbose('Lenses inferred', {
-                        count: result.lenses.length,
-                        lenses: result.lenses.map(l => ({ label: l.label, corpus: l.corpus })),
-                    });
+                    const durationMs = Date.now() - inferrerStart;
+                    agentTimingsAccum.push({ name: 'lens.inferrer', durationMs });
+                    traceEmitter?.({ type: "agent_end", name: "lens-inferrer", durationMs, summary: result.lenses.length > 0 ? `Inferred ${result.lenses.length} lens(es)` : "lens-inferrer completed" });
+                    if (mode === HYDE_FRAME_GENERATION_VERSION) {
+                        const sourceFrame = sanitizeHydeSourceFrame(sourceText, result.sourceFrame ?? emptyFrame());
+                        return {
+                            lenses: result.lenses,
+                            sourceFrame,
+                            frameFingerprint: computeHydeFrameFingerprint(sourceText, sourceFrame),
+                            sourceTextHash: computeHydeSourceTextHash(sourceText),
+                            generatedAt: nextGenerationMarker(),
+                            agentTimings: agentTimingsAccum,
+                        };
+                    }
                     return { lenses: result.lenses, agentTimings: agentTimingsAccum };
                 }
                 catch (error) {
                     logger.error('Lens inference failed in graph node', { error });
+                    if (mode === HYDE_FRAME_GENERATION_VERSION) {
+                        const sourceFrame = emptyFrame();
+                        return {
+                            lenses: [],
+                            sourceFrame,
+                            frameFingerprint: computeHydeFrameFingerprint(sourceText, sourceFrame),
+                            sourceTextHash: computeHydeSourceTextHash(sourceText),
+                            generatedAt: nextGenerationMarker(),
+                            agentTimings: agentTimingsAccum,
+                        };
+                    }
                     return { lenses: [], agentTimings: agentTimingsAccum };
                 }
             });
         };
-        /** Node 2: Check cache/DB for existing HyDE docs matching inferred lenses. */
+        /** Node 2: Check the mode-isolated cache/DB for matching documents. */
         const checkCacheNode = async (state) => {
             return timed("HydeGraph.checkCache", async () => {
                 const { sourceType, sourceId, sourceText, lenses, forceRegenerate } = state;
-                if (forceRegenerate) {
-                    logger.verbose('Force regenerate - skipping cache');
+                if (forceRegenerate)
                     return { hydeDocuments: {} };
-                }
+                const frameFingerprint = mode === HYDE_FRAME_GENERATION_VERSION
+                    ? requireFrameFingerprint(state.frameFingerprint)
+                    : undefined;
+                const sourceTextHash = mode === HYDE_FRAME_GENERATION_VERSION
+                    ? state.sourceTextHash ?? computeHydeSourceTextHash(sourceText)
+                    : undefined;
                 const cached = {};
                 for (const lens of lenses) {
-                    const key = cacheKey(sourceType, sourceId ?? undefined, sourceText, lens.label, lens.corpus);
+                    const key = cacheKey(mode, sourceType, sourceId ?? undefined, sourceText, lens.label, lens.corpus, frameFingerprint);
                     const fromCache = await self.cache.get(key);
-                    if (fromCache?.hydeText && fromCache.hydeEmbedding?.length) {
-                        logger.verbose('Cache hit', { lens: lens.label });
-                        cached[lens.label] = fromCache;
+                    const cacheAccepted = fromCache?.hydeText
+                        && fromCache.hydeEmbedding?.length
+                        && (mode === 'legacy' || isFrameCacheDocument(fromCache, lens.label, frameFingerprint, sourceTextHash));
+                    if (cacheAccepted && fromCache) {
+                        cached[lens.label] = {
+                            ...fromCache,
+                            ...(mode === HYDE_FRAME_GENERATION_VERSION ? { origin: 'cache' } : {}),
+                        };
                         continue;
                     }
-                    // For entity sources, check DB for persisted docs
                     if (sourceId) {
-                        const fromDb = await self.database.getHydeDocument(sourceType, sourceId, lensHash(lens.label, lens.corpus));
-                        if (fromDb) {
-                            logger.verbose('DB hit', { lens: lens.label });
+                        const fromDb = await self.database.getHydeDocument(sourceType, sourceId, dbStrategy(mode, lens.label, lens.corpus));
+                        const frameDbContext = mode === HYDE_FRAME_GENERATION_VERSION && fromDb
+                            ? fromDb.context
+                            : null;
+                        if (fromDb && (mode === 'legacy' || isFrameDbContext(frameDbContext, lens.label, frameFingerprint, sourceTextHash))) {
                             cached[lens.label] = {
                                 lens: lens.label,
                                 targetCorpus: fromDb.targetCorpus,
                                 hydeText: fromDb.hydeText,
                                 hydeEmbedding: fromDb.hydeEmbedding,
+                                ...(mode === HYDE_FRAME_GENERATION_VERSION
+                                    ? {
+                                        origin: 'db',
+                                        validationStatus: 'valid',
+                                        hydeGenerationVersion: HYDE_FRAME_GENERATION_VERSION,
+                                        frameFingerprint,
+                                        sourceTextHash,
+                                        generatedAt: frameDbContext.generatedAt,
+                                    }
+                                    : {}),
                             };
                         }
                     }
                 }
-                logger.verbose('Check cache done', {
-                    found: Object.keys(cached).length,
-                    requested: lenses.length,
-                });
+                if (mode === HYDE_FRAME_GENERATION_VERSION) {
+                    const newestTimestamp = Math.max(...Object.values(cached).map((doc) => Date.parse(doc.generatedAt ?? '')));
+                    if (Number.isFinite(newestTimestamp)) {
+                        return {
+                            hydeDocuments: Object.fromEntries(Object.entries(cached).filter(([, doc]) => Date.parse(doc.generatedAt ?? '') === newestTimestamp)),
+                        };
+                    }
+                }
                 return { hydeDocuments: cached };
             });
         };
-        /** Conditional: decide whether to generate or skip to embed. */
-        const shouldGenerate = (state) => {
-            const { lenses, hydeDocuments } = state;
-            const missing = lenses.filter((l) => !hydeDocuments[l.label]);
-            if (missing.length > 0) {
-                logger.verbose('Need to generate', { missing: missing.map(l => l.label) });
-                return 'generate';
-            }
-            logger.verbose('All lenses cached, skipping generation');
-            return 'skip';
-        };
-        /** Node 3: Generate HyDE documents for lenses not in cache. */
+        const shouldGenerate = (state) => state.lenses.some((lens) => !state.hydeDocuments[lens.label]) ? 'generate' : 'skip';
+        /** Node 3: Generate all missing documents and return a complete snapshot. */
         const generateMissingNode = async (state) => {
             return timed("HydeGraph.generateMissing", async () => {
-                const { sourceText, lenses, hydeDocuments } = state;
-                const missing = lenses.filter((l) => !hydeDocuments[l.label]);
-                logger.verbose('Generating HyDE documents', {
-                    count: missing.length,
-                    lenses: missing.map(l => l.label),
-                });
+                const { sourceText, sourceFrame, lenses, hydeDocuments } = state;
+                const missing = lenses.filter((lens) => !hydeDocuments[lens.label]);
                 const agentTimingsAccum = [];
                 const generated = {};
+                const sourceTextHash = mode === HYDE_FRAME_GENERATION_VERSION
+                    ? state.sourceTextHash ?? computeHydeSourceTextHash(sourceText)
+                    : undefined;
+                const generatedAt = mode === HYDE_FRAME_GENERATION_VERSION
+                    ? state.generatedAt ?? nextGenerationMarker()
+                    : undefined;
                 await Promise.all(missing.map(async (lens) => {
-                    const _traceEmitterHyde = requestContext.getStore()?.traceEmitter;
+                    const traceEmitter = requestContext.getStore()?.traceEmitter;
                     const generatorStart = Date.now();
-                    _traceEmitterHyde?.({ type: "agent_start", name: "hyde-generator" });
+                    traceEmitter?.({ type: "agent_start", name: "hyde-generator" });
                     const out = await self.generator.generate({
                         sourceText,
                         lens: lens.label,
                         corpus: lens.corpus,
+                        ...(mode === HYDE_FRAME_GENERATION_VERSION && sourceFrame ? { sourceFrame } : {}),
                     });
-                    const _hydeDuration = Date.now() - generatorStart;
-                    agentTimingsAccum.push({ name: 'hyde.generator', durationMs: _hydeDuration });
-                    _traceEmitterHyde?.({ type: "agent_end", name: "hyde-generator", durationMs: _hydeDuration, summary: `Generated: ${lens.label}` });
+                    const durationMs = Date.now() - generatorStart;
+                    agentTimingsAccum.push({ name: 'hyde.generator', durationMs });
+                    traceEmitter?.({ type: "agent_end", name: "hyde-generator", durationMs, summary: `Generated: ${lens.label}` });
                     generated[lens.label] = {
                         lens: lens.label,
                         targetCorpus: lens.corpus,
                         hydeText: out.text,
                         hydeEmbedding: [],
+                        ...(mode === HYDE_FRAME_GENERATION_VERSION
+                            ? {
+                                origin: 'generated',
+                                frameFingerprint: requireFrameFingerprint(state.frameFingerprint),
+                                sourceTextHash,
+                                generatedAt,
+                            }
+                            : {}),
                     };
                 }));
-                return { hydeDocuments: { ...state.hydeDocuments, ...generated }, agentTimings: agentTimingsAccum };
+                const retained = mode === HYDE_FRAME_GENERATION_VERSION
+                    ? Object.fromEntries(Object.entries(hydeDocuments).map(([label, doc]) => [
+                        label,
+                        {
+                            ...doc,
+                            frameFingerprint: requireFrameFingerprint(state.frameFingerprint),
+                            sourceTextHash,
+                            generatedAt,
+                        },
+                    ]))
+                    : hydeDocuments;
+                return { hydeDocuments: { ...retained, ...generated }, agentTimings: agentTimingsAccum };
             });
         };
-        /** Node 4: Embed all HyDE documents that don't have embeddings yet. */
+        /** Frame-v1 only: validate newly generated docs in one batch. */
+        const validateGeneratedNode = async (state) => {
+            return timed("HydeGraph.validateGenerated", async () => {
+                const generated = Object.values(state.hydeDocuments).filter((doc) => doc.origin === 'generated');
+                if (generated.length === 0 || !validator)
+                    return { hydeDocuments: state.hydeDocuments };
+                const frame = sanitizeHydeSourceFrame(state.sourceText, state.sourceFrame ?? emptyFrame());
+                const documents = {};
+                const lensByDocumentKey = new Map();
+                for (const doc of generated) {
+                    const key = opaqueDocumentKey(doc);
+                    documents[key] = { corpus: doc.targetCorpus, text: doc.hydeText };
+                    lensByDocumentKey.set(key, doc.lens);
+                }
+                const updated = { ...state.hydeDocuments };
+                const agentTimingsAccum = [];
+                const traceEmitter = requestContext.getStore()?.traceEmitter;
+                const validatorStart = Date.now();
+                let validCount = 0;
+                let rejectedCount = 0;
+                let failedOpenCount = 0;
+                traceEmitter?.({ type: 'agent_start', name: 'hyde-validator' });
+                try {
+                    const output = await validator.validate({
+                        sourceText: state.sourceText,
+                        sourceFrame: frame,
+                        documents,
+                    });
+                    const rawVerdicts = Array.isArray(output.verdicts)
+                        ? output.verdicts
+                        : [];
+                    for (const key of Object.keys(documents)) {
+                        const lensLabel = lensByDocumentKey.get(key);
+                        if (!lensLabel)
+                            continue;
+                        const matching = rawVerdicts.filter((value) => !!value && typeof value === 'object' && value.key === key);
+                        const doc = updated[lensLabel];
+                        if (!doc)
+                            continue;
+                        if (matching.length !== 1 || !isRuntimeVerdict(matching[0])) {
+                            failedOpenCount += 1;
+                            updated[lensLabel] = { ...doc, validationStatus: 'failed_open', hydeGenerationVersion: HYDE_FRAME_GENERATION_VERSION };
+                            continue;
+                        }
+                        const verdict = matching[0];
+                        const hasUnsupportedGrounding = verdict.unsupportedNamedEntities.length > 0
+                            || verdict.unsupportedHardConstraints.length > 0;
+                        const contradictory = verdict.valid === hasUnsupportedGrounding;
+                        if (contradictory) {
+                            failedOpenCount += 1;
+                            updated[lensLabel] = { ...doc, validationStatus: 'failed_open', hydeGenerationVersion: HYDE_FRAME_GENERATION_VERSION };
+                        }
+                        else if (!verdict.valid) {
+                            rejectedCount += 1;
+                            delete updated[lensLabel];
+                        }
+                        else {
+                            validCount += 1;
+                            updated[lensLabel] = { ...doc, validationStatus: 'valid', hydeGenerationVersion: HYDE_FRAME_GENERATION_VERSION };
+                        }
+                    }
+                }
+                catch (error) {
+                    logger.error('HyDE validation failed open', { error });
+                    validCount = 0;
+                    rejectedCount = 0;
+                    failedOpenCount = generated.length;
+                    for (const doc of generated) {
+                        updated[doc.lens] = { ...doc, validationStatus: 'failed_open', hydeGenerationVersion: HYDE_FRAME_GENERATION_VERSION };
+                    }
+                }
+                finally {
+                    const durationMs = Date.now() - validatorStart;
+                    agentTimingsAccum.push({ name: 'hyde.validator', durationMs });
+                    traceEmitter?.({
+                        type: 'agent_end',
+                        name: 'hyde-validator',
+                        durationMs,
+                        summary: `${validCount} valid, ${rejectedCount} rejected, ${failedOpenCount} failed open`,
+                    });
+                }
+                return { hydeDocuments: updated, agentTimings: agentTimingsAccum };
+            });
+        };
+        /** Embed all accepted/cached documents that do not have embeddings. */
         const embedNode = async (state) => {
             return timed("HydeGraph.embed", async () => {
-                const { hydeDocuments } = state;
-                const lensLabels = Object.keys(hydeDocuments);
                 const toEmbed = [];
                 const updated = {};
                 const hydeEmbeddings = {};
-                for (const label of lensLabels) {
-                    const doc = hydeDocuments[label];
-                    if (!doc)
-                        continue;
+                for (const [label, doc] of Object.entries(state.hydeDocuments)) {
                     if (doc.hydeEmbedding?.length) {
                         updated[label] = doc;
                         hydeEmbeddings[label] = doc.hydeEmbedding;
@@ -172,12 +399,8 @@ export class HydeGraphFactory {
                     }
                 }
                 if (toEmbed.length > 0) {
-                    logger.verbose('Embedding documents', { count: toEmbed.length });
-                    const texts = toEmbed.map((t) => t.doc.hydeText);
-                    const embeddings = await self.embedder.generate(texts, undefined, getAbortSignalConfig());
-                    const embeddingArray = Array.isArray(embeddings[0])
-                        ? embeddings
-                        : [embeddings];
+                    const embeddings = await self.embedder.generate(toEmbed.map((item) => item.doc.hydeText), undefined, getAbortSignalConfig());
+                    const embeddingArray = Array.isArray(embeddings[0]) ? embeddings : [embeddings];
                     for (let i = 0; i < toEmbed.length; i++) {
                         const { label, doc } = toEmbed[i];
                         const embedding = embeddingArray[i] ?? [];
@@ -188,31 +411,43 @@ export class HydeGraphFactory {
                 return { hydeDocuments: updated, hydeEmbeddings };
             });
         };
-        /** Node 5: Cache results in Redis; persist to DB for entity sources. */
+        /** Cache/persist only legacy docs or successfully validated frame-v1 docs. */
         const cacheResultsNode = async (state) => {
             return timed("HydeGraph.cacheResults", async () => {
                 const { sourceType, sourceId, sourceText, hydeDocuments } = state;
-                for (const label of Object.keys(hydeDocuments)) {
-                    const doc = hydeDocuments[label];
-                    if (!doc)
+                const frameFingerprint = mode === HYDE_FRAME_GENERATION_VERSION
+                    ? requireFrameFingerprint(state.frameFingerprint)
+                    : undefined;
+                const sourceTextHash = mode === HYDE_FRAME_GENERATION_VERSION
+                    ? state.sourceTextHash ?? computeHydeSourceTextHash(sourceText)
+                    : undefined;
+                for (const [label, doc] of Object.entries(hydeDocuments)) {
+                    if (mode === HYDE_FRAME_GENERATION_VERSION
+                        && !isFrameCacheDocument(doc, label, frameFingerprint, sourceTextHash))
                         continue;
-                    const key = cacheKey(sourceType, sourceId ?? undefined, sourceText, label, doc.targetCorpus);
+                    const key = cacheKey(mode, sourceType, sourceId ?? undefined, sourceText, label, doc.targetCorpus, frameFingerprint);
                     await self.cache.set(key, doc, { ttl: HYDE_DEFAULT_CACHE_TTL });
-                    // Persist to DB for entity sources (intent/profile)
                     if (sourceId) {
                         await self.database.saveHydeDocument({
                             sourceType,
                             sourceId,
-                            strategy: lensHash(label, doc.targetCorpus),
+                            strategy: dbStrategy(mode, label, doc.targetCorpus),
                             targetCorpus: doc.targetCorpus,
                             hydeText: doc.hydeText,
                             hydeEmbedding: doc.hydeEmbedding,
+                            ...(mode === HYDE_FRAME_GENERATION_VERSION ? {
+                                context: {
+                                    hydeGenerationVersion: HYDE_FRAME_GENERATION_VERSION,
+                                    lensLabel: label,
+                                    validationStatus: 'valid',
+                                    frameFingerprint: doc.frameFingerprint,
+                                    sourceTextHash: doc.sourceTextHash,
+                                    generatedAt: doc.generatedAt,
+                                },
+                            } : {}),
                         });
                     }
                 }
-                logger.verbose('Cached results', {
-                    count: Object.keys(hydeDocuments).length,
-                });
                 return {};
             });
         };
@@ -227,8 +462,17 @@ export class HydeGraphFactory {
             .addConditionalEdges('check_cache', shouldGenerate, {
             generate: 'generate_missing',
             skip: 'embed',
-        })
-            .addEdge('generate_missing', 'embed')
+        });
+        if (mode === HYDE_FRAME_GENERATION_VERSION) {
+            workflow
+                .addNode('validate_generated', validateGeneratedNode)
+                .addEdge('generate_missing', 'validate_generated')
+                .addEdge('validate_generated', 'embed');
+        }
+        else {
+            workflow.addEdge('generate_missing', 'embed');
+        }
+        workflow
             .addEdge('embed', 'cache_results')
             .addEdge('cache_results', END);
         return workflow.compile();