@indexnetwork/protocol 14.3.2-rc.477.1 → 17.0.0-rc.479.1

package/dist/discovery/hyde.graph.js

@@ -120,343 +120,23 @@ function isRuntimeVerdict(value) {
 /** Factory for the HyDE generation graph. Existing five-argument calls remain valid. */
 export class HydeGraphFactory {
     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;
+        const mode = options.mode ?? getHydeGenerationMode();
+        this.deps = {
+            database, embedder, cache, inferrer, generator, options, mode,
+            ...(mode === HYDE_FRAME_GENERATION_VERSION
+                ? { validator: options.validator ?? new HydeValidator() }
+                : {}),
+        };
     }
     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;
-                const agentTimingsAccum = [];
-                try {
-                    const traceEmitter = requestContext.getStore()?.traceEmitter;
-                    const inferrerStart = Date.now();
-                    traceEmitter?.({ type: "agent_start", name: "lens-inferrer" });
-                    const result = await self.inferrer.infer({
-                        sourceText,
-                        profileContext,
-                        maxLenses,
-                        ...(mode === HYDE_FRAME_GENERATION_VERSION ? { frameConstrained: true } : {}),
-                    });
-                    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 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)
-                    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(mode, sourceType, sourceId ?? undefined, sourceText, lens.label, lens.corpus, frameFingerprint);
-                    const fromCache = await self.cache.get(key);
-                    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;
-                    }
-                    if (sourceId) {
-                        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,
-                                    }
-                                    : {}),
-                            };
-                        }
-                    }
-                }
-                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 };
-            });
-        };
-        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, 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 traceEmitter = requestContext.getStore()?.traceEmitter;
-                    const generatorStart = Date.now();
-                    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 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,
-                            }
-                            : {}),
-                    };
-                }));
-                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 };
-            });
-        };
-        /** 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 toEmbed = [];
-                const updated = {};
-                const hydeEmbeddings = {};
-                for (const [label, doc] of Object.entries(state.hydeDocuments)) {
-                    if (doc.hydeEmbedding?.length) {
-                        updated[label] = doc;
-                        hydeEmbeddings[label] = doc.hydeEmbedding;
-                    }
-                    else {
-                        toEmbed.push({ label, doc });
-                    }
-                }
-                if (toEmbed.length > 0) {
-                    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] ?? [];
-                        updated[label] = { ...doc, hydeEmbedding: embedding };
-                        hydeEmbeddings[label] = embedding;
-                    }
-                }
-                return { hydeDocuments: updated, hydeEmbeddings };
-            });
-        };
-        /** 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;
-                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(mode, sourceType, sourceId ?? undefined, sourceText, label, doc.targetCorpus, frameFingerprint);
-                    await self.cache.set(key, doc, { ttl: HYDE_DEFAULT_CACHE_TTL });
-                    if (sourceId) {
-                        await self.database.saveHydeDocument({
-                            sourceType,
-                            sourceId,
-                            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,
-                                },
-                            } : {}),
-                        });
-                    }
-                }
-                return {};
-            });
-        };
+        const deps = this.deps;
+        const mode = deps.mode;
         const workflow = new StateGraph(HydeGraphState)
-            .addNode('infer_lenses', inferLensesNode)
-            .addNode('check_cache', checkCacheNode)
-            .addNode('generate_missing', generateMissingNode)
-            .addNode('embed', embedNode)
-            .addNode('cache_results', cacheResultsNode)
+            .addNode('infer_lenses', (state) => inferLensesNode(state, deps))
+            .addNode('check_cache', (state) => checkCacheNode(state, deps))
+            .addNode('generate_missing', (state) => generateMissingNode(state, deps))
+            .addNode('embed', (state) => embedNode(state, deps))
+            .addNode('cache_results', (state) => cacheResultsNode(state, deps))
             .addEdge(START, 'infer_lenses')
             .addEdge('infer_lenses', 'check_cache')
             .addConditionalEdges('check_cache', shouldGenerate, {
@@ -465,7 +145,7 @@ export class HydeGraphFactory {
         });
         if (mode === HYDE_FRAME_GENERATION_VERSION) {
             workflow
-                .addNode('validate_generated', validateGeneratedNode)
+                .addNode('validate_generated', (state) => validateGeneratedNode(state, deps))
                 .addEdge('generate_missing', 'validate_generated')
                 .addEdge('validate_generated', 'embed');
         }
@@ -476,5 +156,327 @@ export class HydeGraphFactory {
             .addEdge('embed', 'cache_results')
             .addEdge('cache_results', END);
         return workflow.compile();
+        return workflow.compile();
     }
 }
+/** Node 1: Infer lenses from source text + optional profile context. */
+export async function inferLensesNode(state, deps) {
+    return timed("HydeGraph.inferLenses", async () => {
+        const { sourceText, profileContext, maxLenses } = state;
+        const agentTimingsAccum = [];
+        try {
+            const traceEmitter = requestContext.getStore()?.traceEmitter;
+            const inferrerStart = Date.now();
+            traceEmitter?.({ type: "agent_start", name: "lens-inferrer" });
+            const result = await deps.inferrer.infer({
+                sourceText,
+                profileContext,
+                maxLenses,
+                ...(deps.mode === HYDE_FRAME_GENERATION_VERSION ? { frameConstrained: true } : {}),
+            });
+            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 (deps.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 (deps.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 the mode-isolated cache/DB for matching documents. */
+export async function checkCacheNode(state, deps) {
+    return timed("HydeGraph.checkCache", async () => {
+        const { sourceType, sourceId, sourceText, lenses, forceRegenerate } = state;
+        if (forceRegenerate)
+            return { hydeDocuments: {} };
+        const frameFingerprint = deps.mode === HYDE_FRAME_GENERATION_VERSION
+            ? requireFrameFingerprint(state.frameFingerprint)
+            : undefined;
+        const sourceTextHash = deps.mode === HYDE_FRAME_GENERATION_VERSION
+            ? state.sourceTextHash ?? computeHydeSourceTextHash(sourceText)
+            : undefined;
+        const cached = {};
+        for (const lens of lenses) {
+            const key = cacheKey(deps.mode, sourceType, sourceId ?? undefined, sourceText, lens.label, lens.corpus, frameFingerprint);
+            const fromCache = await deps.cache.get(key);
+            const cacheAccepted = fromCache?.hydeText
+                && fromCache.hydeEmbedding?.length
+                && (deps.mode === 'legacy' || isFrameCacheDocument(fromCache, lens.label, frameFingerprint, sourceTextHash));
+            if (cacheAccepted && fromCache) {
+                cached[lens.label] = {
+                    ...fromCache,
+                    ...(deps.mode === HYDE_FRAME_GENERATION_VERSION ? { origin: 'cache' } : {}),
+                };
+                continue;
+            }
+            if (sourceId) {
+                const fromDb = await deps.database.getHydeDocument(sourceType, sourceId, dbStrategy(deps.mode, lens.label, lens.corpus));
+                const frameDbContext = deps.mode === HYDE_FRAME_GENERATION_VERSION && fromDb
+                    ? fromDb.context
+                    : null;
+                if (fromDb && (deps.mode === 'legacy' || isFrameDbContext(frameDbContext, lens.label, frameFingerprint, sourceTextHash))) {
+                    cached[lens.label] = {
+                        lens: lens.label,
+                        targetCorpus: fromDb.targetCorpus,
+                        hydeText: fromDb.hydeText,
+                        hydeEmbedding: fromDb.hydeEmbedding,
+                        ...(deps.mode === HYDE_FRAME_GENERATION_VERSION
+                            ? {
+                                origin: 'db',
+                                validationStatus: 'valid',
+                                hydeGenerationVersion: HYDE_FRAME_GENERATION_VERSION,
+                                frameFingerprint,
+                                sourceTextHash,
+                                generatedAt: frameDbContext.generatedAt,
+                            }
+                            : {}),
+                    };
+                }
+            }
+        }
+        if (deps.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 };
+    });
+}
+/** Node 3: Generate all missing documents and return a complete snapshot. */
+export async function generateMissingNode(state, deps) {
+    return timed("HydeGraph.generateMissing", async () => {
+        const { sourceText, sourceFrame, lenses, hydeDocuments } = state;
+        const missing = lenses.filter((lens) => !hydeDocuments[lens.label]);
+        const agentTimingsAccum = [];
+        const generated = {};
+        const sourceTextHash = deps.mode === HYDE_FRAME_GENERATION_VERSION
+            ? state.sourceTextHash ?? computeHydeSourceTextHash(sourceText)
+            : undefined;
+        const generatedAt = deps.mode === HYDE_FRAME_GENERATION_VERSION
+            ? state.generatedAt ?? nextGenerationMarker()
+            : undefined;
+        await Promise.all(missing.map(async (lens) => {
+            const traceEmitter = requestContext.getStore()?.traceEmitter;
+            const generatorStart = Date.now();
+            traceEmitter?.({ type: "agent_start", name: "hyde-generator" });
+            const out = await deps.generator.generate({
+                sourceText,
+                lens: lens.label,
+                corpus: lens.corpus,
+                ...(deps.mode === HYDE_FRAME_GENERATION_VERSION && sourceFrame ? { sourceFrame } : {}),
+            });
+            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: [],
+                ...(deps.mode === HYDE_FRAME_GENERATION_VERSION
+                    ? {
+                        origin: 'generated',
+                        frameFingerprint: requireFrameFingerprint(state.frameFingerprint),
+                        sourceTextHash,
+                        generatedAt,
+                    }
+                    : {}),
+            };
+        }));
+        const retained = deps.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 };
+    });
+}
+/** Frame-v1 only: validate newly generated docs in one batch. */
+export async function validateGeneratedNode(state, deps) {
+    return timed("HydeGraph.validateGenerated", async () => {
+        const generated = Object.values(state.hydeDocuments).filter((doc) => doc.origin === 'generated');
+        if (generated.length === 0 || !deps.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 deps.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. */
+export async function embedNode(state, deps) {
+    return timed("HydeGraph.embed", async () => {
+        const toEmbed = [];
+        const updated = {};
+        const hydeEmbeddings = {};
+        for (const [label, doc] of Object.entries(state.hydeDocuments)) {
+            if (doc.hydeEmbedding?.length) {
+                updated[label] = doc;
+                hydeEmbeddings[label] = doc.hydeEmbedding;
+            }
+            else {
+                toEmbed.push({ label, doc });
+            }
+        }
+        if (toEmbed.length > 0) {
+            const embeddings = await deps.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] ?? [];
+                updated[label] = { ...doc, hydeEmbedding: embedding };
+                hydeEmbeddings[label] = embedding;
+            }
+        }
+        return { hydeDocuments: updated, hydeEmbeddings };
+    });
+}
+/** Cache/persist only legacy docs or successfully validated frame-v1 docs. */
+export async function cacheResultsNode(state, deps) {
+    return timed("HydeGraph.cacheResults", async () => {
+        const { sourceType, sourceId, sourceText, hydeDocuments } = state;
+        const frameFingerprint = deps.mode === HYDE_FRAME_GENERATION_VERSION
+            ? requireFrameFingerprint(state.frameFingerprint)
+            : undefined;
+        const sourceTextHash = deps.mode === HYDE_FRAME_GENERATION_VERSION
+            ? state.sourceTextHash ?? computeHydeSourceTextHash(sourceText)
+            : undefined;
+        for (const [label, doc] of Object.entries(hydeDocuments)) {
+            if (deps.mode === HYDE_FRAME_GENERATION_VERSION
+                && !isFrameCacheDocument(doc, label, frameFingerprint, sourceTextHash))
+                continue;
+            const key = cacheKey(deps.mode, sourceType, sourceId ?? undefined, sourceText, label, doc.targetCorpus, frameFingerprint);
+            await deps.cache.set(key, doc, { ttl: HYDE_DEFAULT_CACHE_TTL });
+            if (sourceId) {
+                await deps.database.saveHydeDocument({
+                    sourceType,
+                    sourceId,
+                    strategy: dbStrategy(deps.mode, label, doc.targetCorpus),
+                    targetCorpus: doc.targetCorpus,
+                    hydeText: doc.hydeText,
+                    hydeEmbedding: doc.hydeEmbedding,
+                    ...(deps.mode === HYDE_FRAME_GENERATION_VERSION ? {
+                        context: {
+                            hydeGenerationVersion: HYDE_FRAME_GENERATION_VERSION,
+                            lensLabel: label,
+                            validationStatus: 'valid',
+                            frameFingerprint: doc.frameFingerprint,
+                            sourceTextHash: doc.sourceTextHash,
+                            generatedAt: doc.generatedAt,
+                        },
+                    } : {}),
+                });
+            }
+        }
+        return {};
+    });
+}
+/** After the cache check: generate the missing documents, or skip straight to embedding. */
+export function shouldGenerate(state) {
+    return state.lenses.some((lens) => !state.hydeDocuments[lens.label]) ? 'generate' : 'skip';
+}