@kernlang/core 3.5.9-canary.220.1.c398cd95 → 4.0.0

package/dist/rag-runtime.js

@@ -0,0 +1,823 @@
+import { RAG_MCP_RETRIEVE_OUTPUT_ITEM_SHAPE, RAG_MCP_RETRIEVE_OUTPUT_SHAPE } from './semantic-validator.js';
+export const MAX_IN_MEMORY_RAG_TOP_K = 1000;
+export class InMemoryRagCorpus {
+    chunks = new Map();
+    constructor(chunks = []) {
+        for (const chunk of chunks)
+            this.add(chunk);
+    }
+    get size() {
+        return this.chunks.size;
+    }
+    add(chunk) {
+        if (typeof chunk.id !== 'string' || !chunk.id.trim()) {
+            throw new Error('KERN RAG runtime chunk id must be a non-empty string.');
+        }
+        if (typeof chunk.text !== 'string' || !chunk.text.trim()) {
+            throw new Error(`KERN RAG runtime chunk '${chunk.id}' text must be a non-empty string.`);
+        }
+        if (typeof chunk.source !== 'string' || !chunk.source.trim()) {
+            throw new Error(`KERN RAG runtime chunk '${chunk.id}' source must be a non-empty string.`);
+        }
+        const storedChunk = {
+            ...chunk,
+            citation: chunk.citation ? { ...chunk.citation } : undefined,
+            metadata: chunk.metadata ? cloneMetadata(chunk.metadata) : undefined,
+        };
+        this.chunks.set(chunk.id, { chunk: storedChunk, terms: tokenizeForRetrieval(storedChunk.text) });
+    }
+    get(id) {
+        const stored = this.chunks.get(id);
+        return stored ? cloneChunkInput(stored.chunk) : undefined;
+    }
+    all() {
+        return Array.from(this.chunks.values(), (stored) => cloneChunkInput(stored.chunk));
+    }
+    retrieve(query, options = {}) {
+        if (typeof query !== 'string')
+            throw new Error('KERN RAG runtime query must be a string.');
+        const { topK, minScore } = normalizeRetrieveOptions(options);
+        const queryTerms = tokenizeForRetrieval(query);
+        if (queryTerms.size === 0)
+            return { query, chunks: [] };
+        const chunks = Array.from(this.chunks.values())
+            .map((stored) => ({ chunk: stored.chunk, score: jaccardScore(queryTerms, stored.terms) }))
+            .filter((candidate) => candidate.score > 0 && candidate.score >= minScore)
+            .sort((a, b) => b.score - a.score || a.chunk.id.localeCompare(b.chunk.id))
+            .slice(0, topK)
+            .map(({ chunk, score }) => retrievedChunk(chunk, score));
+        return { query, chunks };
+    }
+}
+export function createInMemoryRetriever(corpus) {
+    return (query, options = {}) => corpus.retrieve(query, options);
+}
+export function retrieveFromInMemoryCorpus(corpus, query, options = {}) {
+    return corpus.retrieve(query, options);
+}
+export function createRagRuntimeProvenance(result, options = {}) {
+    const validResult = validateRetrieveResult(result);
+    const retrieveOptions = normalizeProvenanceRetrieveOptions(options.retrieveOptions);
+    const chunkHashes = validResult.chunks.map((chunk) => hashRetrievedChunkText(chunk.text));
+    const chunkProvenance = validResult.chunks.map((chunk, index) => ({
+        index,
+        id: chunk.id,
+        source: chunk.source,
+        score: chunk.score,
+        citation: { ...chunk.citation },
+        textHash: chunkHashes[index],
+    }));
+    const sources = uniqueOrdered(validResult.chunks.map((chunk) => chunk.source));
+    const startedAtMs = options.startedAtMs ?? Date.now();
+    const durationMs = options.durationMs ?? 0;
+    const contractStatus = options.contractStatus ?? 'success';
+    return {
+        runId: options.runId ??
+            hashRetrievedChunkText(stableStringify({
+                retrieverName: options.retrieverName,
+                targetKind: options.targetKind,
+                targetName: options.targetName,
+                query: validResult.query,
+                retrieveOptions,
+                citationsRequired: options.citationsRequired ?? false,
+                chunks: chunkProvenance,
+                contractStatus,
+            })),
+        ...optionalStringValue('retrieverName', options.retrieverName),
+        ...(options.targetKind ? { targetKind: options.targetKind } : {}),
+        ...optionalStringValue('targetName', options.targetName),
+        query: validResult.query,
+        retrieveOptions,
+        citationsRequired: options.citationsRequired ?? false,
+        startedAtMs,
+        durationMs,
+        chunkCount: validResult.chunks.length,
+        chunkHashes,
+        sources,
+        contractStatus,
+    };
+}
+export function withRagRuntimeProvenance(result, options = {}) {
+    const validResult = validateRetrieveResult(result);
+    return {
+        query: validResult.query,
+        chunks: validResult.chunks.map(cloneRetrievedChunk),
+        provenance: createRagRuntimeProvenance(validResult, options),
+    };
+}
+export function ragMcpRetrieveProvenanceMapping(retrieval) {
+    if (!retrieval)
+        throw new Error('KERN RAG MCP provenance mapping requires a retrieval fact.');
+    return {
+        ...optionalStringValue('outputShape', retrieval.outputShape),
+        ...optionalStringValue('outputItemShape', retrieval.outputItemShape),
+        ...optionalStringValue('citationField', retrieval.citationField),
+        ...optionalStringValue('sourceField', retrieval.sourceField),
+        ...optionalStringValue('scoreField', retrieval.scoreField),
+        ...optionalStringValue('provenance', retrieval.provenance),
+        citationsRequired: retrieval.effectiveRequiresCitations,
+        contractStatus: retrieval.contractStatus,
+        compatible: retrieval.contractStatus === 'valid' &&
+            retrieval.outputShape === RAG_MCP_RETRIEVE_OUTPUT_SHAPE &&
+            (retrieval.outputItemShape === undefined || retrieval.outputItemShape === RAG_MCP_RETRIEVE_OUTPUT_ITEM_SHAPE),
+    };
+}
+export function evaluateRagAnswerContract(contract) {
+    const base = {
+        ...optionalStringValue('id', contract.id),
+        ...optionalStringValue('ragName', contract.ragName),
+        query: typeof contract.query === 'string' ? contract.query : '',
+    };
+    let retrieval;
+    try {
+        retrieval = validateRetrieveResult(contract.retrieval);
+    }
+    catch (error) {
+        return {
+            ...base,
+            passed: false,
+            status: 'invalid',
+            groundingCoverage: 0,
+            groundedChars: 0,
+            answerChars: 0,
+            citedChunkIds: [],
+            sources: [],
+            ...(contract.provenance ? { provenance: contract.provenance } : {}),
+            diagnostics: [
+                {
+                    code: 'RETRIEVER_ERROR',
+                    message: `RAG answer contract retrieval failed: ${error instanceof Error ? error.message : String(error)}.`,
+                },
+            ],
+        };
+    }
+    const answer = typeof contract.answer === 'string' ? contract.answer : '';
+    const answerChars = countAnswerChars(answer);
+    const diagnostics = [];
+    if (typeof contract.answer !== 'string' || answerChars === 0) {
+        diagnostics.push({ code: 'ANSWER_EMPTY', message: 'RAG answer contract answer must be a non-empty string.' });
+    }
+    const minGroundingCoverage = normalizeGroundingCoverageThreshold(contract.minGroundingCoverage);
+    const provenance = contract.provenance ?? retrieveResultProvenance(contract.retrieval);
+    if (contract.query !== retrieval.query) {
+        diagnostics.push({
+            code: 'QUERY_MISMATCH',
+            message: 'RAG answer contract query does not match the retrieval result query.',
+        });
+    }
+    if (provenance && !provenanceMatchesRetrieval(provenance, retrieval)) {
+        diagnostics.push({
+            code: 'PROVENANCE_MISMATCH',
+            message: 'RAG answer contract provenance does not match the retrieval result.',
+        });
+    }
+    const chunkById = new Map(retrieval.chunks.map((chunk) => [chunk.id, chunk]));
+    const grounded = new Array(answer.length).fill(false);
+    const citedChunkIds = new Set();
+    const citationBearingChunkIds = new Set();
+    const groundingSpans = Array.isArray(contract.groundingSpans) ? contract.groundingSpans : [];
+    if (contract.groundingSpans !== undefined && !Array.isArray(contract.groundingSpans)) {
+        diagnostics.push({
+            code: 'SPAN_INVALID',
+            message: 'RAG answer contract groundingSpans must be an array.',
+        });
+    }
+    for (const [spanIndex, span] of groundingSpans.entries()) {
+        if (!isValidGroundingSpan(span, answer.length)) {
+            diagnostics.push({
+                code: 'SPAN_INVALID',
+                spanIndex,
+                message: `RAG answer grounding span at index ${spanIndex} is invalid or outside the answer text.`,
+            });
+            continue;
+        }
+        const validChunkIds = [];
+        let spanHasCitation = false;
+        for (const chunkId of span.chunkIds) {
+            if (chunkById.has(chunkId)) {
+                validChunkIds.push(chunkId);
+                citedChunkIds.add(chunkId);
+                if (chunkHasCitation(chunkById.get(chunkId))) {
+                    spanHasCitation = true;
+                    citationBearingChunkIds.add(chunkId);
+                }
+            }
+            else {
+                diagnostics.push({
+                    code: 'CHUNK_REF_UNKNOWN',
+                    spanIndex,
+                    chunkId,
+                    message: `RAG answer grounding span at index ${spanIndex} references unknown chunk '${chunkId}'.`,
+                });
+            }
+        }
+        if (validChunkIds.length === 0) {
+            diagnostics.push({
+                code: span.required ? 'CITATION_REQUIRED' : 'SPAN_UNGROUNDED',
+                spanIndex,
+                message: `RAG answer grounding span at index ${spanIndex} has no valid retrieved chunk citation.`,
+            });
+            continue;
+        }
+        if (contract.requireCitations && !spanHasCitation) {
+            diagnostics.push({
+                code: 'CITATION_REQUIRED',
+                spanIndex,
+                message: `RAG answer grounding span at index ${spanIndex} requires a non-empty retrieved chunk citation.`,
+            });
+            continue;
+        }
+        for (let index = span.start; index < span.end; index += 1)
+            grounded[index] = true;
+    }
+    const groundedChars = countGroundedAnswerChars(answer, grounded);
+    const groundingCoverage = answerChars === 0 ? 0 : groundedChars / answerChars;
+    if (answerChars > 0 &&
+        contract.requireCitations &&
+        citationBearingChunkIds.size === 0 &&
+        groundingSpans.length === 0) {
+        diagnostics.push({
+            code: 'CITATION_REQUIRED',
+            message: 'RAG answer contract requires citations but no retrieved chunks were cited.',
+        });
+    }
+    if (answerChars > 0 && groundingCoverage < minGroundingCoverage) {
+        diagnostics.push({
+            code: 'GROUNDING_BELOW_THRESHOLD',
+            message: `RAG answer grounding coverage ${groundingCoverage.toFixed(3)} is below required threshold ${minGroundingCoverage.toFixed(3)}.`,
+        });
+    }
+    const passed = diagnostics.length === 0;
+    return {
+        ...base,
+        passed,
+        status: passed ? 'grounded' : ragAnswerStatus(diagnostics, groundingCoverage),
+        groundingCoverage,
+        groundedChars,
+        answerChars,
+        citedChunkIds: [...citedChunkIds].sort(stableStringCompare),
+        sources: uniqueOrdered([...citedChunkIds].map((chunkId) => chunkById.get(chunkId)?.source).filter(isString)),
+        ...(provenance ? { provenance } : {}),
+        diagnostics,
+    };
+}
+export function ragAnswerContractFromSemanticFact(fact, retrieval, options = {}) {
+    return {
+        id: fact.name,
+        ...optionalStringValue('ragName', fact.ragName),
+        ...optionalStringValue('prompt', fact.prompt),
+        query: fact.query,
+        answer: fact.answer,
+        retrieval,
+        ...(options.provenance ? { provenance: options.provenance } : {}),
+        groundingSpans: fact.spans.map((span) => ({
+            start: span.start,
+            end: span.end,
+            chunkIds: [...span.chunkIds],
+            ...(span.required ? { required: true } : {}),
+        })),
+        requireCitations: fact.requireCitations,
+        ...optionalNumberValue('minGroundingCoverage', fact.minGroundingCoverage),
+    };
+}
+export function evaluateRagSemanticAnswerContract(fact, retrieval, options = {}) {
+    return evaluateRagAnswerContract(ragAnswerContractFromSemanticFact(fact, retrieval, options));
+}
+export function evaluateRagEvalContract(evaluation, retriever, options = {}) {
+    const startedAt = runtimeNow(options);
+    const cases = (evaluation.cases ?? []).map((evaluationCase) => evaluateRagCase(evaluation, evaluationCase, retriever, options));
+    const assertionCount = cases.reduce((count, evaluationCase) => count + evaluationCase.assertions.length, 0);
+    const passedAssertionCount = cases.reduce((count, evaluationCase) => count + evaluationCase.assertions.filter((assertion) => assertion.passed).length, 0);
+    return {
+        // Empty eval contracts fail closed; a vacuous pass would hide unconfigured evals.
+        passed: cases.length > 0 && cases.every((evaluationCase) => evaluationCase.passed),
+        ...optionalStringValue('ragName', evaluation.ragName),
+        ...optionalStringValue('evalName', evaluation.name),
+        caseCount: cases.length,
+        passedCaseCount: cases.filter((evaluationCase) => evaluationCase.passed).length,
+        assertionCount,
+        passedAssertionCount,
+        durationMs: runtimeNow(options) - startedAt,
+        cases,
+    };
+}
+export function hashRetrievedChunkText(text) {
+    let left = 0xcbf29ce484222325n;
+    let right = 0x84222325cbf29ce4n;
+    for (const byte of new TextEncoder().encode(text)) {
+        const value = BigInt(byte);
+        left ^= value;
+        left = BigInt.asUintN(64, left * 0x100000001b3n);
+        right ^= value + 0x9en;
+        right = BigInt.asUintN(64, right * 0x100000001b3n);
+    }
+    return `${left.toString(16).padStart(16, '0')}${right.toString(16).padStart(16, '0')}`;
+}
+function normalizeRetrieveOptions(options) {
+    const topK = options.topK ?? 5;
+    const minScore = options.minScore ?? 0;
+    if (!Number.isInteger(topK) || topK <= 0 || topK > MAX_IN_MEMORY_RAG_TOP_K) {
+        throw new Error(`KERN RAG runtime topK must be a positive integer up to ${MAX_IN_MEMORY_RAG_TOP_K}.`);
+    }
+    if (!Number.isFinite(minScore) || minScore < 0 || minScore > 1) {
+        throw new Error('KERN RAG runtime minScore must be between 0 and 1.');
+    }
+    return { topK, minScore };
+}
+function normalizeGroundingCoverageThreshold(value) {
+    if (value === undefined)
+        return 1;
+    if (!Number.isFinite(value) || value < 0 || value > 1) {
+        throw new Error('KERN RAG answer contract minGroundingCoverage must be between 0 and 1.');
+    }
+    return value;
+}
+function retrieveResultProvenance(result) {
+    return result && typeof result === 'object' && 'provenance' in result ? result.provenance : undefined;
+}
+function provenanceMatchesRetrieval(provenance, retrieval) {
+    if (!provenance ||
+        typeof provenance.query !== 'string' ||
+        typeof provenance.chunkCount !== 'number' ||
+        !Array.isArray(provenance.chunkHashes) ||
+        !Array.isArray(provenance.sources)) {
+        return false;
+    }
+    const chunkHashes = retrieval.chunks.map((chunk) => hashRetrievedChunkText(chunk.text));
+    const sources = uniqueOrdered(retrieval.chunks.map((chunk) => chunk.source));
+    return (provenance.query === retrieval.query &&
+        provenance.chunkCount === retrieval.chunks.length &&
+        arraysEqual(provenance.chunkHashes, chunkHashes) &&
+        arraysEqual(provenance.sources, sources));
+}
+function chunkHasCitation(chunk) {
+    return (!!chunk &&
+        ((typeof chunk.citation.uri === 'string' && chunk.citation.uri.trim().length > 0) ||
+            (typeof chunk.citation.locator === 'string' && chunk.citation.locator.trim().length > 0)));
+}
+function isValidGroundingSpan(span, answerLength) {
+    return (!!span &&
+        Number.isInteger(span.start) &&
+        Number.isInteger(span.end) &&
+        span.start >= 0 &&
+        span.end > span.start &&
+        span.end <= answerLength &&
+        Array.isArray(span.chunkIds) &&
+        span.chunkIds.every(isString));
+}
+function countAnswerChars(answer) {
+    if (typeof answer !== 'string')
+        return 0;
+    let count = 0;
+    for (let index = 0; index < answer.length; index += 1) {
+        if (!/\s/u.test(answer[index] ?? ''))
+            count += 1;
+    }
+    return count;
+}
+function countGroundedAnswerChars(answer, grounded) {
+    let count = 0;
+    for (let index = 0; index < answer.length; index += 1) {
+        if (grounded[index] && !/\s/u.test(answer[index] ?? ''))
+            count += 1;
+    }
+    return count;
+}
+function ragAnswerStatus(diagnostics, groundingCoverage) {
+    if (diagnostics.some((diagnostic) => [
+        'ANSWER_EMPTY',
+        'CITATION_REQUIRED',
+        'QUERY_MISMATCH',
+        'RETRIEVER_ERROR',
+        'PROVENANCE_MISMATCH',
+        'SPAN_INVALID',
+        'CHUNK_REF_UNKNOWN',
+    ].includes(diagnostic.code))) {
+        return 'invalid';
+    }
+    if (groundingCoverage === 0)
+        return 'ungrounded';
+    return 'partially_grounded';
+}
+function evaluateRagCase(evaluation, evaluationCase, retriever, options) {
+    const retrieveOptions = caseRetrieveOptions(evaluationCase);
+    const startedAt = runtimeNow(options);
+    let chunks = [];
+    let assertions = [];
+    try {
+        chunks = validateRetrieveResult(retriever(evaluationCase.query, retrieveOptions)).chunks;
+    }
+    catch (error) {
+        assertions = [
+            {
+                kind: 'retriever',
+                passed: false,
+                code: 'RETRIEVER_ERROR',
+                message: `RAG eval case '${evaluationCase.name}' retriever failed: ${error instanceof Error ? error.message : String(error)}.`,
+            },
+        ];
+    }
+    const durationMs = runtimeNow(options) - startedAt;
+    if (assertions.length === 0) {
+        assertions = [
+            ...evaluateExpectedCaseContracts(evaluationCase, chunks),
+            ...(evaluationCase.asserts ?? []).map((assertion) => evaluateRagAssertion(evaluation, evaluationCase, assertion, chunks, durationMs, options)),
+        ];
+    }
+    return {
+        name: evaluationCase.name,
+        query: evaluationCase.query,
+        passed: assertions.every(isPassingOrAdvisoryAssertion),
+        durationMs,
+        retrieveOptions,
+        chunks,
+        assertions,
+    };
+}
+function caseRetrieveOptions(evaluationCase) {
+    return {
+        ...optionalNumberValue('topK', evaluationCase.expected?.topK),
+        ...optionalNumberValue('minScore', evaluationCase.expected?.minScore),
+    };
+}
+function evaluateExpectedCaseContracts(evaluationCase, chunks) {
+    const results = [];
+    const { topK, minScore, chunkCount, sources } = evaluationCase.expected ?? {};
+    if (topK !== undefined) {
+        results.push(assertionResult('expected.topK', chunks.length <= topK, `expected at most ${topK} chunks`, topK, chunks.length));
+    }
+    if (minScore !== undefined) {
+        const actual = chunks.length === 0
+            ? 0
+            : chunks.reduce((minimumScore, chunk) => Math.min(minimumScore, chunk.score), Number.POSITIVE_INFINITY);
+        results.push(assertionResult('expected.minScore', chunks.length > 0 && chunks.every((chunk) => chunk.score >= minScore), `expected all retrieved chunks to score >= ${minScore}`, minScore, actual));
+    }
+    if (chunkCount !== undefined) {
+        results.push(assertionResult('expected.chunkCount', chunks.length === chunkCount, `expected ${chunkCount} chunks`, chunkCount, chunks.length));
+    }
+    if (sources?.length) {
+        const actualSources = [...new Set(chunks.map((chunk) => chunk.source))].sort();
+        const expectedSources = [...sources].sort();
+        const allowed = new Set(expectedSources);
+        results.push(assertionResult('expected.sources', expectedSources.every((source) => actualSources.includes(source)) &&
+            chunks.every((chunk) => allowed.has(chunk.source)), `expected retrieved chunks to cover only sources ${expectedSources.join(', ')}`, expectedSources, actualSources));
+    }
+    return results;
+}
+function evaluateRagAssertion(evaluation, evaluationCase, assertion, chunks, durationMs, options) {
+    switch (assertion.kind) {
+        case 'scoreGte':
+            return withRagAssertRequired(assertion, numericChunkAssertion(assertion, chunks, (chunk, value) => chunk.score >= value, 'score >='));
+        case 'scoreLte':
+            return withRagAssertRequired(assertion, numericChunkAssertion(assertion, chunks, (chunk, value) => chunk.score <= value, 'score <='));
+        case 'contains':
+            return withRagAssertRequired(assertion, stringChunkAssertion(assertion, chunks, 'text', (chunk, value) => chunk.text.toLowerCase().includes(value.toLowerCase()), 'text contains'));
+        case 'sourceEq':
+            return withRagAssertRequired(assertion, stringChunkAssertion(assertion, chunks, 'source', (chunk, value) => chunk.source === value, 'source equals'));
+        case 'sourceGlob':
+            return withRagAssertRequired(assertion, stringChunkAssertion(assertion, chunks, 'source', (chunk, value) => globMatches(value, chunk.source, options.sourceGlobCaseSensitive ?? false), 'source matches'));
+        case 'uniqueSourcesGte': {
+            const expected = numberAssertionValue(assertion);
+            if (expected === undefined)
+                return invalidAssertionResult(assertion, 'requires numeric value.');
+            const actual = new Set(chunks.map((chunk) => chunk.source)).size;
+            return withRagAssertRequired(assertion, assertionResult(assertion.kind, actual >= expected, `expected at least ${expected} unique sources`, expected, actual));
+        }
+        case 'chunkCountEq': {
+            const expected = numberAssertionValue(assertion);
+            if (expected === undefined)
+                return invalidAssertionResult(assertion, 'requires numeric value.');
+            return withRagAssertRequired(assertion, assertionResult(assertion.kind, chunks.length === expected, `expected exactly ${expected} chunks`, expected, chunks.length));
+        }
+        case 'citesRequired': {
+            const actual = chunks.length > 0 && chunks.every((chunk) => !!chunk.citation.uri || !!chunk.citation.locator);
+            return withRagAssertRequired(assertion, assertionResult(assertion.kind, actual, 'expected every chunk to carry citation data', true, actual));
+        }
+        case 'factId': {
+            const expected = stringAssertionValue(assertion);
+            if (expected === undefined)
+                return invalidAssertionResult(assertion, 'requires string value.');
+            const actual = ragEvalCaseFactId(evaluation, evaluationCase);
+            return withRagAssertRequired(assertion, assertionResult(assertion.kind, actual === expected, `expected fact id ${expected}`, expected, actual));
+        }
+        case 'chunkHash': {
+            const expected = stringAssertionValue(assertion);
+            if (expected === undefined)
+                return invalidAssertionResult(assertion, 'requires string value.');
+            const actual = chunks.map((chunk) => hashRetrievedChunkText(chunk.text));
+            return withRagAssertRequired(assertion, assertionResult(assertion.kind, actual.includes(expected), `expected retrieved chunk hash ${expected}`, expected, actual));
+        }
+        case 'latencyLte': {
+            const expected = numberAssertionValue(assertion);
+            if (expected === undefined)
+                return invalidAssertionResult(assertion, 'requires numeric value.');
+            return withRagAssertRequired(assertion, assertionResult(assertion.kind, durationMs <= expected, `expected retrieval latency <= ${expected}ms`, expected, durationMs));
+        }
+        default:
+            return {
+                kind: assertion.kind,
+                required: assertion.required,
+                passed: false,
+                code: 'UNSUPPORTED_ASSERTION',
+                message: `Unsupported RAG eval assertion kind '${assertion.kind}'.`,
+            };
+    }
+}
+function numericChunkAssertion(assertion, chunks, check, label) {
+    const expected = numberAssertionValue(assertion);
+    if (expected === undefined)
+        return invalidAssertionResult(assertion, 'requires numeric value.');
+    const actual = chunks.map((chunk) => chunk.score);
+    return assertionResult(assertion.kind, chunks.length > 0 && chunks.every((chunk) => check(chunk, expected)), `expected every retrieved chunk ${label} ${expected}`, expected, actual);
+}
+function stringChunkAssertion(assertion, chunks, actualField, check, label) {
+    const expected = stringAssertionValue(assertion);
+    if (expected === undefined)
+        return invalidAssertionResult(assertion, 'requires non-empty string value.');
+    const actual = chunks.map((chunk) => (actualField === 'source' ? chunk.source : chunk.text));
+    return assertionResult(assertion.kind, chunks.some((chunk) => check(chunk, expected)), `expected a retrieved chunk ${label} ${expected}`, expected, actual);
+}
+function invalidAssertionResult(assertion, reason) {
+    return {
+        kind: assertion.kind,
+        required: assertion.required,
+        passed: false,
+        code: 'INVALID_ASSERTION',
+        message: `RAG eval assertion kind=${assertion.kind} ${reason}`,
+    };
+}
+function assertionResult(kind, passed, message, expected, actual) {
+    return {
+        kind,
+        passed,
+        code: passed ? 'PASS' : 'ASSERTION_FAIL',
+        message,
+        ...optionalAssertionValue('expected', expected),
+        ...optionalAssertionValue('actual', actual),
+    };
+}
+function numberAssertionValue(assertion) {
+    return typeof assertion.value === 'number' && Number.isFinite(assertion.value) ? assertion.value : undefined;
+}
+function stringAssertionValue(assertion) {
+    return typeof assertion.value === 'string' && assertion.value.length > 0 ? assertion.value : undefined;
+}
+function withRagAssertRequired(assertion, result) {
+    return { ...result, required: assertion.required };
+}
+function isPassingOrAdvisoryAssertion(assertion) {
+    return assertion.passed || (assertion.required === false && assertion.code === 'ASSERTION_FAIL');
+}
+function ragEvalCaseFactId(evaluation, evaluationCase) {
+    return [evaluationCase.ragName ?? evaluation.ragName, evaluationCase.evalName ?? evaluation.name, evaluationCase.name]
+        .filter((part) => !!part)
+        .join(':');
+}
+function globMatches(pattern, value, caseSensitive) {
+    const normalizedPattern = caseSensitive ? pattern : pattern.toLowerCase();
+    const normalizedValue = caseSensitive ? value : value.toLowerCase();
+    return wildcardMatches(normalizedPattern, normalizedValue);
+}
+function wildcardMatches(pattern, value) {
+    let patternIndex = 0;
+    let valueIndex = 0;
+    let starIndex = -1;
+    let starValueIndex = 0;
+    while (valueIndex < value.length) {
+        if (patternIndex < pattern.length &&
+            (pattern[patternIndex] === '?' || pattern[patternIndex] === value[valueIndex])) {
+            patternIndex += 1;
+            valueIndex += 1;
+        }
+        else if (patternIndex < pattern.length && pattern[patternIndex] === '*') {
+            starIndex = patternIndex;
+            starValueIndex = valueIndex;
+            patternIndex += 1;
+        }
+        else if (starIndex !== -1) {
+            patternIndex = starIndex + 1;
+            starValueIndex += 1;
+            valueIndex = starValueIndex;
+        }
+        else {
+            return false;
+        }
+    }
+    while (patternIndex < pattern.length && pattern[patternIndex] === '*')
+        patternIndex += 1;
+    return patternIndex === pattern.length;
+}
+function runtimeNow(options) {
+    return options.now?.() ?? Date.now();
+}
+function optionalStringValue(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}
+function optionalNumberValue(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}
+function optionalAssertionValue(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}
+function normalizeProvenanceRetrieveOptions(options) {
+    if (options === undefined)
+        return {};
+    const out = {};
+    if (options.topK !== undefined) {
+        if (!Number.isInteger(options.topK) || options.topK <= 0 || options.topK > MAX_IN_MEMORY_RAG_TOP_K) {
+            throw new Error(`KERN RAG runtime topK must be a positive integer up to ${MAX_IN_MEMORY_RAG_TOP_K}.`);
+        }
+        out.topK = options.topK;
+    }
+    if (options.minScore !== undefined) {
+        if (!Number.isFinite(options.minScore) || options.minScore < 0 || options.minScore > 1) {
+            throw new Error('KERN RAG runtime minScore must be between 0 and 1.');
+        }
+        out.minScore = options.minScore;
+    }
+    return out;
+}
+function uniqueOrdered(values) {
+    const seen = new Set();
+    const out = [];
+    for (const value of values) {
+        if (seen.has(value))
+            continue;
+        seen.add(value);
+        out.push(value);
+    }
+    return out;
+}
+function stableStringify(value) {
+    return JSON.stringify(stableJsonValue(value, new WeakSet()));
+}
+function stableJsonValue(value, seen) {
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (typeof value === 'symbol')
+        return value.description ?? value.toString();
+    if (typeof value === 'function')
+        return `[Function:${value.name || 'anonymous'}]`;
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (seen.has(value))
+        return '[Circular]';
+    seen.add(value);
+    try {
+        if (Array.isArray(value))
+            return value.map((item) => stableJsonValue(item, seen));
+        if (value instanceof Date)
+            return value.toISOString();
+        if (value instanceof RegExp)
+            return value.toString();
+        if (value instanceof Map) {
+            return Array.from(value.entries())
+                .map(([key, entry]) => [stableJsonValue(key, seen), stableJsonValue(entry, seen)])
+                .sort(([left], [right]) => stableStringCompare(left, right));
+        }
+        if (value instanceof Set) {
+            return Array.from(value.values())
+                .map((entry) => stableJsonValue(entry, seen))
+                .sort(stableStringCompare);
+        }
+        if (isPlainMetadataObject(value)) {
+            const out = {};
+            for (const key of Object.keys(value).sort()) {
+                const entry = value[key];
+                if (entry !== undefined)
+                    out[key] = stableJsonValue(entry, seen);
+            }
+            return out;
+        }
+        return String(value);
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+function stableStringCompare(left, right) {
+    const leftText = String(left);
+    const rightText = String(right);
+    return leftText < rightText ? -1 : leftText > rightText ? 1 : 0;
+}
+function arraysEqual(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function validateRetrieveResult(result) {
+    if (!result || typeof result.query !== 'string' || !Array.isArray(result.chunks)) {
+        throw new Error('retriever result must include query string and chunks array.');
+    }
+    for (const [index, chunk] of result.chunks.entries()) {
+        if (chunk &&
+            typeof chunk.score === 'number' &&
+            (!Number.isFinite(chunk.score) || chunk.score < 0 || chunk.score > 1)) {
+            throw new Error(`retriever chunk at index ${index} score must be between 0 and 1.`);
+        }
+        if (!chunk ||
+            typeof chunk.id !== 'string' ||
+            typeof chunk.text !== 'string' ||
+            typeof chunk.score !== 'number' ||
+            !Number.isFinite(chunk.score) ||
+            chunk.score < 0 ||
+            chunk.score > 1 ||
+            typeof chunk.source !== 'string' ||
+            !isValidCitation(chunk.citation)) {
+            throw new Error(`retriever chunk at index ${index} is not a RetrievedChunk.`);
+        }
+    }
+    const chunkIds = new Set();
+    for (const [index, chunk] of result.chunks.entries()) {
+        if (chunkIds.has(chunk.id)) {
+            throw new Error(`retriever chunk at index ${index} duplicates chunk id '${chunk.id}'.`);
+        }
+        chunkIds.add(chunk.id);
+    }
+    return result;
+}
+function isValidCitation(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const citation = value;
+    return ((citation.uri === undefined || typeof citation.uri === 'string') &&
+        (citation.locator === undefined || typeof citation.locator === 'string'));
+}
+function isString(value) {
+    return typeof value === 'string';
+}
+export function tokenizeForRetrieval(value) {
+    return new Set(value
+        .normalize('NFKC')
+        .toLowerCase()
+        .match(/[\p{L}\p{M}\p{N}]+/gu) ?? []);
+}
+function jaccardScore(queryTerms, chunkTerms) {
+    if (queryTerms.size === 0 || chunkTerms.size === 0)
+        return 0;
+    let intersection = 0;
+    for (const term of queryTerms) {
+        if (chunkTerms.has(term))
+            intersection += 1;
+    }
+    const union = queryTerms.size + chunkTerms.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+function retrievedChunk(chunk, score) {
+    return {
+        id: chunk.id,
+        text: chunk.text,
+        score,
+        source: chunk.source,
+        citation: chunk.citation ? { ...chunk.citation } : { uri: chunk.source },
+        ...(chunk.metadata ? { metadata: cloneMetadata(chunk.metadata) } : {}),
+    };
+}
+function cloneRetrievedChunk(chunk) {
+    return {
+        ...chunk,
+        citation: { ...chunk.citation },
+        ...(chunk.metadata ? { metadata: cloneMetadata(chunk.metadata) } : {}),
+    };
+}
+function cloneChunkInput(chunk) {
+    return {
+        ...chunk,
+        citation: chunk.citation ? { ...chunk.citation } : undefined,
+        metadata: chunk.metadata ? cloneMetadata(chunk.metadata) : undefined,
+    };
+}
+function cloneMetadata(metadata) {
+    return cloneMetadataValue(metadata, new WeakMap());
+}
+function cloneMetadataValue(value, seen) {
+    if (Array.isArray(value)) {
+        const existing = seen.get(value);
+        if (existing)
+            return existing;
+        const out = [];
+        seen.set(value, out);
+        for (const item of value)
+            out.push(cloneMetadataValue(item, seen));
+        return out;
+    }
+    if (isPlainMetadataObject(value)) {
+        const existing = seen.get(value);
+        if (existing)
+            return existing;
+        const out = {};
+        seen.set(value, out);
+        for (const [key, entry] of Object.entries(value)) {
+            if (key === '__proto__' || key === 'constructor' || key === 'prototype')
+                continue;
+            out[key] = cloneMetadataValue(entry, seen);
+        }
+        return out;
+    }
+    return value;
+}
+function isPlainMetadataObject(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+//# sourceMappingURL=rag-runtime.js.map