ai-capability-framework 1.0.3 → 1.1.0

package/dist/discovery/index-validation.js

@@ -0,0 +1,117 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import Ajv2020 from "ajv/dist/2020.js";
+import { ordinalCompare } from "./corpus.js";
+import { DiscoveryError } from "./diagnostics.js";
+import { resolveEmbeddingConfiguration, resolveIndexLimits } from "./embedding-configuration.js";
+import { canonicalizeDiscoveryValue, fingerprintDiscoveryValue, hashDiscoveryContent } from "./fingerprint.js";
+import { boundedJsonSnapshot, deepFreeze } from "./json-snapshot.js";
+import { validVector } from "./vectors.js";
+import { ownValue } from "./usage.js";
+let schemaValidator;
+export function embeddingIndexFingerprint(index) {
+    return fingerprintDiscoveryValue("index", {
+        schemaVersion: index.schemaVersion, projectionVersion: index.projectionVersion, mock: index.mock,
+        registrySourceFingerprint: index.registrySourceFingerprint, corpusFingerprint: index.corpusFingerprint,
+        embedding: index.embedding, embeddingConfigurationFingerprint: index.embeddingConfigurationFingerprint,
+        vectorDimension: index.vectorDimension,
+        entries: [...index.entries].sort((a, b) => ordinalCompare(a.capabilityId, b.capabilityId))
+            .map(({ capabilityId, capabilityVersion, documentHash, vectorHash }) => ({ capabilityId, capabilityVersion, documentHash, vectorHash }))
+    });
+}
+export function validateCapabilityEmbeddingIndex(value, expected) {
+    let code = "invalid_index";
+    try {
+        const limits = resolveIndexLimits(expected.limits);
+        const configuration = resolveEmbeddingConfiguration(expected.configuration);
+        const rawEntries = ownValue(value, "entries");
+        const rawDimension = ownValue(value, "vectorDimension");
+        if (!Array.isArray(rawEntries) || rawEntries.length > limits.maxEntries
+            || typeof rawDimension !== "number" || !Number.isSafeInteger(rawDimension) || rawDimension < 1
+            || rawDimension > limits.maxVectorDimension)
+            throw new Error();
+        for (const entry of rawEntries) {
+            const vector = ownValue(entry, "vector");
+            if (!Array.isArray(vector) || vector.length !== rawDimension)
+                throw new Error();
+        }
+        const snapshot = boundedJsonSnapshot(value, limits.maxArtifactBytes);
+        schemaValidator ??= new Ajv2020({ strict: false }).compile(JSON.parse(readFileSync(fileURLToPath(new URL("../../schemas/discovery/embedding-index.schema.json", import.meta.url)), "utf8")));
+        if (!schemaValidator(snapshot))
+            throw new Error();
+        const index = snapshot;
+        if (index.entries.length > limits.maxEntries || index.vectorDimension > limits.maxVectorDimension
+            || expected.corpus.documents.length !== index.entries.length
+            || new Date(index.builtAt).toISOString() !== index.builtAt
+            || index.projectionVersion !== expected.corpus.projectionVersion
+            || index.registrySourceFingerprint !== expected.corpus.registrySourceFingerprint
+            || index.corpusFingerprint !== expected.corpus.corpusFingerprint)
+            throw new Error();
+        const embeddingFingerprint = fingerprintDiscoveryValue("embedding_configuration", configuration);
+        if (canonicalizeDiscoveryValue(index.embedding) !== canonicalizeDiscoveryValue(configuration)
+            || index.embeddingConfigurationFingerprint !== embeddingFingerprint || index.mock !== expected.mock
+            || configuration.dimensions !== undefined && configuration.dimensions !== index.vectorDimension) {
+            code = "embedding_configuration_mismatch";
+            throw new Error();
+        }
+        const documents = new Map(expected.corpus.documents.map(document => [document.capabilityId, document]));
+        if (documents.size !== expected.corpus.documents.length)
+            throw new Error();
+        const seen = new Set();
+        for (const entry of index.entries) {
+            const document = documents.get(entry.capabilityId);
+            if (!document || seen.has(entry.capabilityId) || entry.capabilityVersion !== document.capabilityVersion
+                || entry.documentHash !== document.documentHash || !validVector(entry.vector, index.vectorDimension)
+                || entry.vectorHash !== hashDiscoveryContent(entry.vector))
+                throw new Error();
+            seen.add(entry.capabilityId);
+        }
+        if (index.indexFingerprint !== embeddingIndexFingerprint(index))
+            throw new Error();
+        index.entries.sort((a, b) => ordinalCompare(a.capabilityId, b.capabilityId));
+        return { valid: true, index: deepFreeze(index), diagnostics: [] };
+    }
+    catch {
+        return { valid: false, diagnostics: [{ code, message: code === "invalid_index"
+                        ? "The embedding index is invalid, oversized, incomplete, or stale."
+                        : "The embedding index and caller embedding configuration are incompatible." }] };
+    }
+}
+export function serializeCapabilityEmbeddingIndex(value, expected) {
+    const validated = validateCapabilityEmbeddingIndex(value, expected);
+    if (!validated.valid)
+        throw new DiscoveryError(validated.diagnostics[0]);
+    return canonicalizeDiscoveryValue(validated.index);
+}
+export function parseCapabilityEmbeddingIndex(text, expected) {
+    try {
+        const limits = resolveIndexLimits(expected.limits);
+        if (typeof text !== "string" || Buffer.byteLength(text) > limits.maxArtifactBytes)
+            throw new Error();
+        return validateCapabilityEmbeddingIndex(JSON.parse(text), expected);
+    }
+    catch {
+        return { valid: false, diagnostics: [{ code: "invalid_index", message: "The serialized embedding index is invalid or oversized." }] };
+    }
+}
+export async function loadCapabilityEmbeddingIndex(store, key, expected) {
+    try {
+        const value = await store.read(key);
+        return parseCapabilityEmbeddingIndex(value, expected);
+    }
+    catch {
+        return { valid: false, diagnostics: [{ code: "invalid_index", message: "The embedding index could not be loaded." }] };
+    }
+}
+export async function publishCapabilityEmbeddingIndex(store, key, value, expected) {
+    const result = validateCapabilityEmbeddingIndex(value, expected);
+    if (!result.valid)
+        return { published: false, diagnostics: result.diagnostics };
+    try {
+        await store.replace(key, canonicalizeDiscoveryValue(result.index));
+        return { published: true, diagnostics: [] };
+    }
+    catch {
+        return { published: false, diagnostics: [{ code: "invalid_index", message: "The complete embedding index could not be published." }] };
+    }
+}

package/dist/discovery/index.d.ts

@@ -0,0 +1,32 @@
+/** Stable lexical/native facade; advanced APIs retain their documented maturity. */
+export { ModelCapabilitySelector } from "./selection.js";
+export { buildCapabilitySelectionTasks } from "./selection-cards.js";
+export type { BuildCapabilitySelectionTasksRequest } from "./selection-cards.js";
+export type { CapabilitySelectRequest } from "./selection-types.js";
+export { createCapabilityDiscovery, DISCOVERY_STANDARD_PROFILE } from "./facade.js";
+export type { CapabilityDiscovery, CapabilityDiscoveryOptions, CapabilityDiscoveryEmbeddingOptions, CapabilitySearchRequest, CapabilityDiscoveryEligibility, CapabilityResultRouter } from "./facade.js";
+export { createInMemoryDiscoveryBudget } from "./budget.js";
+export type { DiscoveryBudgetScope, InMemoryDiscoveryBudgetOptions } from "./budget.js";
+export { CapabilityDiscoverer } from "./discoverer.js";
+export type { CapabilityDiscovererOptions } from "./discoverer.js";
+export { buildCapabilityEmbeddingIndex } from "./index-builder.js";
+export { validateCapabilityEmbeddingIndex, serializeCapabilityEmbeddingIndex, parseCapabilityEmbeddingIndex, loadCapabilityEmbeddingIndex, publishCapabilityEmbeddingIndex } from "./index-validation.js";
+export { aggregateDiscoveryUsage } from "./usage.js";
+export type { DeepReadonly, CapabilityEmbeddingIndex, EmbeddingIndexLimits, EmbeddingCallLimits, EmbeddingExecutionOptions, HybridDiscoveryDependencies, EmbeddingIndexExpected, EmbeddingIndexValidationResult, CapabilityEmbeddingIndexBuildRequest, CapabilityEmbeddingIndexBuildResult, CapabilityEmbeddingIndexStore } from "./embedding-types.js";
+export { buildCapabilitySearchCorpus } from "./corpus.js";
+export { RetrievalCapabilityRouter } from "./router.js";
+export type { RetrievalCapabilityRouteRequest, RetrievalCapabilityRouterOptions } from "./router.js";
+export { DiscoveryError } from "./diagnostics.js";
+export type { DiscoveryDiagnostic, DiscoveryDiagnosticCode } from "./diagnostics.js";
+export { resolveDiscoveryMetadata } from "./metadata.js";
+export { canonicalizeDiscoveryValue, fingerprintDiscoveryValue, hashDiscoveryContent } from "./fingerprint.js";
+export type { DiscoveryFingerprintKind, DiscoveryFingerprintPayloads, CapabilityVersionBinding } from "./fingerprint.js";
+export { DISCOVERY_BINDING_VERSIONS, DISCOVERY_SCHEMA_VERSION, DISCOVERY_DEFAULT_LIMITS, DISCOVERY_HARD_LIMITS } from "./versions.js";
+export { LEXICAL_TOKENIZER_VERSION, LEXICAL_RANKER_VERSION, tokenizeDiscoveryText } from "./lexical.js";
+export type { DiscoveryLimits, LexicalDiscoveryConfiguration, HybridDiscoveryConfiguration, DiscoveryConfiguration, DiscoveryFragment, DiscoveryQuery, EmbeddingConfiguration, DiscoveryStage, DiscoveryInvocation, CapabilityDiscoveryRequest, RankedCapabilityCandidate, CapabilityDiscoveryResult, CapabilityRetrievalDocument, CapabilitySearchCorpus, ResolvedLexicalDiscoveryConfiguration, ResolvedHybridDiscoveryConfiguration, ResolvedDiscoveryConfiguration, LexicalRankerCandidate, CapabilityLexicalRanker, DiscoveryBudgetReservation, DiscoveryBudgetLedger, ProviderAttemptContext, EmbeddingClient, DiscoveryProviderFailure, DiscoveryProviderError, SelectionMessage, SelectionModelClient, CapabilityCandidateCard, CapabilitySelectionInputTask, SelectionTask, SelectionLimits, CapabilitySelectionRequest, SelectionDecision, SelectionResponse, CapabilitySelectionBatchResult, CapabilitySelectionOutcome, DiscoveryRouteResult, ResolvedDiscoveryMetadata, DiscoveryMetadata, ProviderModelConfiguration, ModelUsage, UsageQuantity, DiscoveryUsageTotals, DiscoveryStageUsage, DiscoveryUsage, ProviderAttemptReservation, ProviderAttemptSettlement } from "./types.js";
+export { createDiscoverySnapshot, validateDiscoverySnapshot, replayDiscoverySnapshot, createDiscoveryReplayHandler } from "./replay.js";
+export type { DiscoverySnapshotInput, DiscoveryReplayFixtures, DiscoveryReplayResult } from "./replay.js";
+export type { CapabilityEmbeddingIndexArtifact, CapabilityDiscoverySnapshot } from "../generated/manifest-types.js";
+export { evaluateCapabilityDiscovery, fingerprintDiscoveryEvaluationSuite } from "./evaluation.js";
+export type { DiscoveryEvaluationSuite, DiscoveryEvaluationObservations, DiscoveryEvaluationRate, DiscoveryEvaluationDistribution, DiscoveryEvaluationReport, DiscoveryEvaluationResult, EvaluateCapabilityDiscoveryRequest, DiscoveryEvaluationDiagnostic } from "./evaluation.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/discovery/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"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"}

package/dist/discovery/index.js

@@ -0,0 +1,18 @@
+/** Stable lexical/native facade; advanced APIs retain their documented maturity. */
+export { ModelCapabilitySelector } from "./selection.js";
+export { buildCapabilitySelectionTasks } from "./selection-cards.js";
+export { createCapabilityDiscovery, DISCOVERY_STANDARD_PROFILE } from "./facade.js";
+export { createInMemoryDiscoveryBudget } from "./budget.js";
+export { CapabilityDiscoverer } from "./discoverer.js";
+export { buildCapabilityEmbeddingIndex } from "./index-builder.js";
+export { validateCapabilityEmbeddingIndex, serializeCapabilityEmbeddingIndex, parseCapabilityEmbeddingIndex, loadCapabilityEmbeddingIndex, publishCapabilityEmbeddingIndex } from "./index-validation.js";
+export { aggregateDiscoveryUsage } from "./usage.js";
+export { buildCapabilitySearchCorpus } from "./corpus.js";
+export { RetrievalCapabilityRouter } from "./router.js";
+export { DiscoveryError } from "./diagnostics.js";
+export { resolveDiscoveryMetadata } from "./metadata.js";
+export { canonicalizeDiscoveryValue, fingerprintDiscoveryValue, hashDiscoveryContent } from "./fingerprint.js";
+export { DISCOVERY_BINDING_VERSIONS, DISCOVERY_SCHEMA_VERSION, DISCOVERY_DEFAULT_LIMITS, DISCOVERY_HARD_LIMITS } from "./versions.js";
+export { LEXICAL_TOKENIZER_VERSION, LEXICAL_RANKER_VERSION, tokenizeDiscoveryText } from "./lexical.js";
+export { createDiscoverySnapshot, validateDiscoverySnapshot, replayDiscoverySnapshot, createDiscoveryReplayHandler } from "./replay.js";
+export { evaluateCapabilityDiscovery, fingerprintDiscoveryEvaluationSuite } from "./evaluation.js";

package/dist/discovery/json-snapshot.d.ts

@@ -0,0 +1,3 @@
+export { deepFreeze } from "../runtime/bounded-json.js";
+export declare function boundedJsonSnapshot(value: unknown, maxBytes: number): unknown;
+//# sourceMappingURL=json-snapshot.d.ts.map

package/dist/discovery/json-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-snapshot.d.ts","sourceRoot":"","sources":["../../src/discovery/json-snapshot.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAG7E"}

package/dist/discovery/json-snapshot.js

@@ -0,0 +1,11 @@
+import { DiscoveryError } from "./diagnostics.js";
+import { boundedJsonSnapshot as snapshot } from "../runtime/bounded-json.js";
+export { deepFreeze } from "../runtime/bounded-json.js";
+export function boundedJsonSnapshot(value, maxBytes) {
+    try {
+        return snapshot(value, maxBytes);
+    }
+    catch {
+        throw new DiscoveryError({ code: "invalid_index", message: "Embedding artifacts require bounded, finite JSON data." });
+    }
+}

package/dist/discovery/lexical.d.ts

@@ -0,0 +1,12 @@
+import type { CapabilityRetrievalDocument, DiscoveryQuery, LexicalRankerCandidate, ResolvedLexicalDiscoveryConfiguration } from "./types.js";
+/** NFKC plus ECMAScript lowercase, not linguistic case folding or word segmentation. */
+export declare const LEXICAL_TOKENIZER_VERSION = "nfkc-lower-unicode-letter-number.v1";
+export declare const LEXICAL_RANKER_VERSION = "coverage-alias.v1";
+export declare function tokenizeDiscoveryText(text: string): string[];
+export declare function matchingAliases(query: DiscoveryQuery, document: CapabilityRetrievalDocument): string[];
+export declare function rankLexically(input: {
+    query: DiscoveryQuery;
+    documents: readonly CapabilityRetrievalDocument[];
+    configuration: ResolvedLexicalDiscoveryConfiguration;
+}): LexicalRankerCandidate[];
+//# sourceMappingURL=lexical.d.ts.map

package/dist/discovery/lexical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lexical.d.ts","sourceRoot":"","sources":["../../src/discovery/lexical.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,2BAA2B,EAAE,cAAc,EAAE,sBAAsB,EAAE,qCAAqC,EAC3G,MAAM,YAAY,CAAC;AAEpB,wFAAwF;AACxF,eAAO,MAAM,yBAAyB,wCAAwC,CAAC;AAC/E,eAAO,MAAM,sBAAsB,sBAAsB,CAAC;AAE1D,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAE5D;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,2BAA2B,GAAG,MAAM,EAAE,CAOtG;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,KAAK,EAAE,cAAc,CAAC;IACtB,SAAS,EAAE,SAAS,2BAA2B,EAAE,CAAC;IAClD,aAAa,EAAE,qCAAqC,CAAC;CACtD,GAAG,sBAAsB,EAAE,CAY3B"}

package/dist/discovery/lexical.js

@@ -0,0 +1,26 @@
+/** NFKC plus ECMAScript lowercase, not linguistic case folding or word segmentation. */
+export const LEXICAL_TOKENIZER_VERSION = "nfkc-lower-unicode-letter-number.v1";
+export const LEXICAL_RANKER_VERSION = "coverage-alias.v1";
+export function tokenizeDiscoveryText(text) {
+    return text.normalize("NFKC").toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? [];
+}
+export function matchingAliases(query, document) {
+    const fragments = query.fragments.map((fragment) => tokenizeDiscoveryText(fragment.text));
+    return document.aliases.filter((alias) => {
+        const phrase = tokenizeDiscoveryText(alias);
+        return phrase.length >= 2 && fragments.some((fragment) => fragment.some((_, start) => phrase.every((token, offset) => fragment[start + offset] === token)));
+    });
+}
+export function rankLexically(input) {
+    const queryTokens = [...new Set(input.query.fragments.flatMap((fragment) => tokenizeDiscoveryText(fragment.text)))];
+    return input.documents.map((document) => {
+        const tokens = new Set(document.tokens);
+        const coverage = queryTokens.length ? queryTokens.filter((token) => tokens.has(token)).length / queryTokens.length : 0;
+        const phrase = matchingAliases(input.query, document).length ? 1 : 0;
+        const lexical = coverage + (1 - coverage) * input.configuration.aliasWeight * phrase;
+        return {
+            capabilityId: document.capabilityId,
+            scores: { lexical, aliasPhrase: phrase, semantic: null, final: lexical }
+        };
+    });
+}

package/dist/discovery/metadata.d.ts

@@ -0,0 +1,4 @@
+import type { CapabilityManifest } from "../types.js";
+import type { ResolvedDiscoveryMetadata } from "./types.js";
+export declare function resolveDiscoveryMetadata(manifest: CapabilityManifest): ResolvedDiscoveryMetadata;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/discovery/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/discovery/metadata.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGtD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAC;AAE5D,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,yBAAyB,CAiChG"}

package/dist/discovery/metadata.js

@@ -0,0 +1,33 @@
+import { validateDiscoveryMetadata } from "../validator.js";
+import { DiscoveryError } from "./diagnostics.js";
+export function resolveDiscoveryMetadata(manifest) {
+    const extensions = manifest.extensions;
+    if (!extensions || !Object.prototype.hasOwnProperty.call(extensions, "discovery")) {
+        return { schemaVersion: "1.0", summary: manifest.summary, aliases: [] };
+    }
+    const value = extensions.discovery;
+    const errors = validateDiscoveryMetadata(value);
+    if (errors.length > 0) {
+        throw new DiscoveryError({
+            code: "invalid_metadata",
+            message: "Capability discovery metadata is invalid.",
+            capabilityId: manifest.id,
+            path: errors[0]?.instancePath ?? "/extensions/discovery"
+        });
+    }
+    const metadata = value;
+    const seen = new Set();
+    const aliases = [];
+    for (const alias of metadata.aliases ?? []) {
+        const key = alias.normalize("NFKC").toLowerCase().trim().replace(/\s+/gu, " ");
+        if (!seen.has(key)) {
+            seen.add(key);
+            aliases.push(alias);
+        }
+    }
+    return {
+        schemaVersion: metadata.schema_version,
+        summary: metadata.summary ?? manifest.summary,
+        aliases
+    };
+}

package/dist/discovery/ranking.d.ts

@@ -0,0 +1,7 @@
+import type { CapabilityRetrievalDocument, DiscoveryQuery, RankedCapabilityCandidate, ResolvedLexicalDiscoveryConfiguration } from "./types.js";
+export declare function shortlistCandidates(output: unknown, query: DiscoveryQuery, documents: readonly CapabilityRetrievalDocument[], configuration: ResolvedLexicalDiscoveryConfiguration): RankedCapabilityCandidate[];
+export declare function validateLexicalCandidates(output: unknown, query: DiscoveryQuery, documents: readonly CapabilityRetrievalDocument[], requireEqual?: boolean): RankedCapabilityCandidate[];
+export declare function selectRankedCandidates(candidates: readonly RankedCapabilityCandidate[], documents: readonly CapabilityRetrievalDocument[], configuration: Pick<ResolvedLexicalDiscoveryConfiguration, "limits" | "minRetrievalScore">): RankedCapabilityCandidate[];
+/** Pure semantic channel shared by serving and authorized offline ranking replay. */
+export declare function rankHybridCandidates(candidates: readonly RankedCapabilityCandidate[], queryVector: readonly number[], vectors: ReadonlyMap<string, readonly number[]>, documents: readonly CapabilityRetrievalDocument[], configuration: import("./types.js").ResolvedHybridDiscoveryConfiguration): RankedCapabilityCandidate[];
+//# sourceMappingURL=ranking.d.ts.map

package/dist/discovery/ranking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ranking.d.ts","sourceRoot":"","sources":["../../src/discovery/ranking.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,2BAA2B,EAAE,cAAc,EAAE,yBAAyB,EAAE,qCAAqC,EAC9G,MAAM,YAAY,CAAC;AAIpB,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,2BAA2B,EAAE,EACzF,aAAa,EAAE,qCAAqC,GACnD,yBAAyB,EAAE,CAE7B;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,SAAS,2BAA2B,EAAE,EAAE,YAAY,UAAQ,GAC9G,yBAAyB,EAAE,CA8B7B;AAED,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,SAAS,yBAAyB,EAAE,EAAE,SAAS,EAAE,SAAS,2BAA2B,EAAE,EACnG,aAAa,EAAE,IAAI,CAAC,qCAAqC,EAAE,QAAQ,GAAG,mBAAmB,CAAC,GACzF,yBAAyB,EAAE,CAa7B;AAED,qFAAqF;AACrF,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,SAAS,yBAAyB,EAAE,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,EAChF,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,SAAS,2BAA2B,EAAE,EAClG,aAAa,EAAE,OAAO,YAAY,EAAE,oCAAoC,GACvE,yBAAyB,EAAE,CAO7B"}

package/dist/discovery/ranking.js

@@ -0,0 +1,68 @@
+import { semanticSimilarity } from "./vectors.js";
+import { hasOnlyKeys, isRecord, unitScore } from "./configuration.js";
+import { ordinalCompare } from "./corpus.js";
+import { DiscoveryError } from "./diagnostics.js";
+import { matchingAliases } from "./lexical.js";
+const riskRank = { none: 0, low: 1, medium: 2, high: 3, critical: 4 };
+export function shortlistCandidates(output, query, documents, configuration) {
+    return selectRankedCandidates(validateLexicalCandidates(output, query, documents), documents, configuration);
+}
+export function validateLexicalCandidates(output, query, documents, requireEqual = false) {
+    const invalid = () => new DiscoveryError({
+        code: "invalid_ranker_output", message: "The lexical ranker did not return valid eligible scores."
+    });
+    const byId = new Map(documents.map((document) => [document.capabilityId, document]));
+    if (!Array.isArray(output) || output.length > documents.length) {
+        // An invalid async implementation must not leave a rejected Promise unobserved.
+        if (output instanceof Promise)
+            void output.catch(() => undefined);
+        throw invalid();
+    }
+    const ids = new Set();
+    const admitted = [];
+    for (const entry of output) {
+        if (!isRecord(entry) || !hasOnlyKeys(entry, ["capabilityId", "scores"])
+            || typeof entry.capabilityId !== "string" || ids.has(entry.capabilityId))
+            throw invalid();
+        const document = byId.get(entry.capabilityId);
+        const scores = entry.scores;
+        if (!document || !isRecord(scores) || !hasOnlyKeys(scores, ["lexical", "aliasPhrase", "semantic", "final"])
+            || !unitScore(scores.lexical) || !unitScore(scores.final) || scores.semantic !== null
+            || (scores.aliasPhrase !== 0 && scores.aliasPhrase !== 1))
+            throw invalid();
+        const aliases = matchingAliases(query, document);
+        if (scores.aliasPhrase !== (aliases.length ? 1 : 0) || requireEqual && scores.final !== scores.lexical)
+            throw invalid();
+        ids.add(entry.capabilityId);
+        admitted.push({
+            capabilityId: document.capabilityId, capabilityVersion: document.capabilityVersion, rank: 0,
+            scores: { lexical: scores.lexical, aliasPhrase: scores.aliasPhrase, semantic: null, final: scores.final },
+            matchedAliases: aliases, inclusionReason: "aggregate_ranking"
+        });
+    }
+    return admitted;
+}
+export function selectRankedCandidates(candidates, documents, configuration) {
+    const byId = new Map(documents.map(document => [document.capabilityId, document]));
+    const admitted = candidates.filter(candidate => candidate.scores.final > 0 && candidate.scores.final >= configuration.minRetrievalScore);
+    admitted.sort((left, right) => right.scores.final - left.scores.final
+        || riskRank[byId.get(left.capabilityId).riskTier] - riskRank[byId.get(right.capabilityId).riskTier]
+        || ordinalCompare(left.capabilityId, right.capabilityId));
+    const limit = configuration.limits.maxCandidates;
+    const selected = admitted.slice(0, limit);
+    if (configuration.limits.aliasDiversitySlots === 1 && selected.length === limit) {
+        const alternative = admitted.slice(limit).find((candidate) => candidate.matchedAliases.length > 0);
+        if (alternative)
+            selected.splice(selected.length - 1, 1, { ...alternative, inclusionReason: "alias_diversity" });
+    }
+    return selected.map((candidate, index) => ({ ...candidate, rank: index + 1 }));
+}
+/** Pure semantic channel shared by serving and authorized offline ranking replay. */
+export function rankHybridCandidates(candidates, queryVector, vectors, documents, configuration) {
+    const scored = candidates.map(candidate => {
+        const semantic = semanticSimilarity(queryVector, vectors.get(candidate.capabilityId));
+        const final = Math.max(0, Math.min(1, configuration.weights.semantic * semantic + configuration.weights.lexical * candidate.scores.lexical));
+        return { ...candidate, scores: { ...candidate.scores, semantic, final } };
+    });
+    return selectRankedCandidates(scored, documents, configuration);
+}

package/dist/discovery/replay.d.ts

@@ -0,0 +1,50 @@
+import type { CapabilityDiscoverySnapshot } from "../generated/manifest-types.js";
+import type { CapabilityRouteRequest } from "../runtime/types.js";
+import type { ReplayProviderRunner, ReplayStepResult } from "../replay/types.js";
+import type { CapabilityDiscoveryResult, CapabilityLexicalRanker, CapabilitySelectionBatchResult, DiscoveryConfiguration, DiscoveryQuery, EmbeddingConfiguration } from "./types.js";
+import type { EmbeddingIndexLimits } from "./embedding-types.js";
+export interface DiscoverySnapshotInput {
+    routeRequest: CapabilityRouteRequest;
+    configuration: DiscoveryConfiguration;
+    queries: readonly DiscoveryQuery[];
+    discovery: readonly CapabilityDiscoveryResult[];
+    selection?: CapabilitySelectionBatchResult;
+    ranker?: CapabilityLexicalRanker;
+}
+export interface DiscoveryReplayFixtures {
+    queries: readonly DiscoveryQuery[];
+    ranker?: CapabilityLexicalRanker;
+    index?: unknown;
+    embedding?: EmbeddingConfiguration;
+    mock?: boolean;
+    indexLimits?: EmbeddingIndexLimits;
+    queryVectors?: Readonly<Record<string, {
+        queryHash: string;
+        configurationFingerprint: string;
+        vector: readonly number[];
+    }>>;
+}
+export interface DiscoveryReplayResult {
+    status: "passed" | "failed" | "refused";
+    mode: "snapshot_validation" | "ranking";
+    semanticCorrectnessTested: false;
+    steps: readonly ReplayStepResult[];
+}
+export declare function createDiscoverySnapshot(input: DiscoverySnapshotInput): CapabilityDiscoverySnapshot;
+export declare function validateDiscoverySnapshot(value: unknown, routeRequest: CapabilityRouteRequest): {
+    valid: true;
+    snapshot: CapabilityDiscoverySnapshot;
+} | {
+    valid: false;
+};
+export declare function replayDiscoverySnapshot(value: unknown, options: {
+    mode: DiscoveryReplayResult["mode"];
+    routeRequest: CapabilityRouteRequest;
+    fixtures?: DiscoveryReplayFixtures;
+}): DiscoveryReplayResult;
+export declare function createDiscoveryReplayHandler(options: {
+    mode: DiscoveryReplayResult["mode"];
+    routeRequest: CapabilityRouteRequest;
+    fixtures?: DiscoveryReplayFixtures;
+}): ReplayProviderRunner;
+//# sourceMappingURL=replay.d.ts.map

package/dist/discovery/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/discovery/replay.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,gCAAgC,CAAC;AAClF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAajF,OAAO,KAAK,EACV,yBAAyB,EAAE,uBAAuB,EAAE,8BAA8B,EAAE,sBAAsB,EAC1G,cAAc,EAAE,sBAAsB,EACvC,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAGjE,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,sBAAsB,CAAC;IACrC,aAAa,EAAE,sBAAsB,CAAC;IACtC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IACnC,SAAS,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAChD,SAAS,CAAC,EAAE,8BAA8B,CAAC;IAC3C,MAAM,CAAC,EAAE,uBAAuB,CAAC;CAClC;AACD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;IACnC,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,sBAAsB,CAAC;IACnC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,WAAW,CAAC,EAAE,oBAAoB,CAAC;IACnC,YAAY,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,wBAAwB,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC,CAAC;CAC7H;AACD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;IACxC,IAAI,EAAE,qBAAqB,GAAG,SAAS,CAAC;IACxC,yBAAyB,EAAE,KAAK,CAAC;IACjC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACpC;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,sBAAsB,GAAG,2BAA2B,CA8BlG;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,sBAAsB,GAC5F;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,2BAA2B,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,CAyC1E;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE;IAC/D,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAAC,YAAY,EAAE,sBAAsB,CAAC;IAAC,QAAQ,CAAC,EAAE,uBAAuB,CAAC;CAC/G,GAAG,qBAAqB,CA+CxB;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAAC,YAAY,EAAE,sBAAsB,CAAC;IAAC,QAAQ,CAAC,EAAE,uBAAuB,CAAA;CAAE,GAAG,oBAAoB,CAS7L"}

package/dist/discovery/replay.js

@@ -0,0 +1,175 @@
+import { validateDiscoverySnapshotStructure } from "../replay/discovery-snapshot.js";
+import { captureEligibility } from "./bindings.js";
+import { lexicalConfiguration, resolveDiscoveryConfiguration } from "./configuration.js";
+import { buildCapabilitySearchCorpus } from "./corpus.js";
+import { validateQueries } from "./discoverer.js";
+import { DiscoveryError } from "./diagnostics.js";
+import { fingerprintDiscoveryValue, hashDiscoveryContent } from "./fingerprint.js";
+import { validateCapabilityEmbeddingIndex } from "./index-validation.js";
+import { deepFreeze } from "./json-snapshot.js";
+import { LEXICAL_RANKER_VERSION, LEXICAL_TOKENIZER_VERSION, rankLexically, tokenizeDiscoveryText } from "./lexical.js";
+import { rankHybridCandidates, shortlistCandidates, validateLexicalCandidates } from "./ranking.js";
+import { retrievalPolicyFingerprint } from "./retrieval-policy.js";
+import { validVectorBatch } from "./vectors.js";
+export function createDiscoverySnapshot(input) {
+    const corpus = buildCapabilitySearchCorpus(input.routeRequest.registry);
+    const configuration = resolveDiscoveryConfiguration(input.configuration);
+    const queries = validateQueries({ queries: input.queries }, configuration);
+    if (queries.length !== input.discovery.length)
+        throw invalid();
+    const policy = retrievalPolicyFingerprint(configuration, input.ranker?.version);
+    const payload = {
+        schemaVersion: "1.0", projectionVersion: corpus.projectionVersion, tokenizerVersion: LEXICAL_TOKENIZER_VERSION,
+        rankerVersion: input.ranker ? "custom:" + input.ranker.version : LEXICAL_RANKER_VERSION,
+        registrySourceFingerprint: corpus.registrySourceFingerprint, corpusFingerprint: corpus.corpusFingerprint,
+        retrievalPolicyFingerprint: policy, configuration,
+        tasks: input.discovery.map((result, index) => {
+            const query = queries[index];
+            if (query.id !== result.queryId || result.corpusFingerprint !== corpus.corpusFingerprint || result.retrievalPolicyFingerprint !== policy)
+                throw invalid();
+            const decision = input.selection?.outcomes.find(outcome => outcome.queryId === query.id);
+            return { queryId: query.id, queryHash: queryHash(query), status: result.status, requestedMode: result.requestedMode,
+                actualMode: result.actualMode, eligibilityFingerprint: result.eligibilityFingerprint,
+                retrievalPolicyFingerprint: result.retrievalPolicyFingerprint,
+                ...(result.indexFingerprint ? { indexFingerprint: result.indexFingerprint } : {}),
+                ...(result.degradedReason ? { degradedReason: result.degradedReason } : {}),
+                reasonCodes: result.diagnostics.map(diagnostic => diagnostic.code), candidates: result.candidates.map(candidateProjection),
+                ...(decision ? { selection: { status: decision.status, capabilityId: decision.capabilityId,
+                        ...(decision.status === "selected" ? { capabilityVersion: decision.capabilityVersion } : {}), reasonCode: decision.reasonCode,
+                        selectorFingerprint: decision.selectorFingerprint, inputBindingHash: decision.inputBindingHash } } : {}) };
+        })
+    };
+    const result = { ...payload, snapshotFingerprint: snapshotHash(payload) };
+    const validated = validateDiscoverySnapshot(result, input.routeRequest);
+    if (!validated.valid)
+        throw invalid();
+    return validated.snapshot;
+}
+export function validateDiscoverySnapshot(value, routeRequest) {
+    const shape = validateDiscoverySnapshotStructure(value);
+    if (!shape.valid)
+        return shape;
+    try {
+        const snapshot = shape.snapshot, { snapshotFingerprint, ...payload } = snapshot;
+        if (snapshotHash(payload) !== snapshotFingerprint)
+            return { valid: false };
+        const corpus = buildCapabilitySearchCorpus(routeRequest.registry), eligibility = captureEligibility(routeRequest);
+        const configuration = resolveDiscoveryConfiguration(snapshot.configuration);
+        const custom = snapshot.rankerVersion.startsWith("custom:") ? snapshot.rankerVersion.slice(7) : undefined;
+        const policy = retrievalPolicyFingerprint(configuration, custom);
+        if (snapshot.registrySourceFingerprint !== corpus.registrySourceFingerprint || snapshot.corpusFingerprint !== corpus.corpusFingerprint
+            || snapshot.projectionVersion !== corpus.projectionVersion || snapshot.tokenizerVersion !== LEXICAL_TOKENIZER_VERSION
+            || !custom && snapshot.rankerVersion !== LEXICAL_RANKER_VERSION || snapshot.retrievalPolicyFingerprint !== policy)
+            return { valid: false };
+        const eligible = new Map(eligibility.eligible.map(item => [item.manifest.id, item.manifest.version]));
+        const tasks = new Set();
+        for (const task of snapshot.tasks) {
+            const ids = new Set();
+            if (tasks.has(task.queryId) || task.eligibilityFingerprint !== eligibility.fingerprint || task.retrievalPolicyFingerprint !== policy
+                || task.requestedMode !== configuration.mode || task.candidates.length > configuration.limits.maxCandidates
+                || task.status !== "matched" && task.candidates.length || task.status === "matched" && (!task.candidates.length || task.actualMode === null)
+                || ["unavailable", "cancelled"].includes(task.status) && task.actualMode !== null
+                || task.actualMode === "hybrid" && task.requestedMode !== "hybrid"
+                || task.requestedMode === "hybrid" && task.actualMode === "lexical" && configuration.mode === "hybrid"
+                    && (configuration.failurePolicy !== "lexical_fallback" || !task.degradedReason))
+                return { valid: false };
+            tasks.add(task.queryId);
+            for (const [index, candidate] of task.candidates.entries()) {
+                if (ids.has(candidate.capabilityId) || eligible.get(candidate.capabilityId) !== candidate.capabilityVersion
+                    || candidate.rank !== index + 1 || candidate.scores.final <= 0 || candidate.scores.final < configuration.minRetrievalScore
+                    || task.actualMode === "lexical" && candidate.scores.semantic !== null
+                    || task.actualMode === "hybrid" && (candidate.scores.semantic === null || !task.indexFingerprint))
+                    return { valid: false };
+                ids.add(candidate.capabilityId);
+            }
+            const selection = task.selection;
+            if (selection?.status === "selected") {
+                if (!selection.capabilityId || !ids.has(selection.capabilityId) || eligible.get(selection.capabilityId) !== selection.capabilityVersion
+                    || selection.reasonCode !== "supported_candidate")
+                    return { valid: false };
+            }
+            else if (selection && (selection.capabilityId !== null || selection.capabilityVersion !== undefined
+                || selection.status === "abstained" && !["no_suitable_candidate", "ambiguous_request", "insufficient_context"].includes(selection.reasonCode)))
+                return { valid: false };
+        }
+        return { valid: true, snapshot };
+    }
+    catch {
+        return { valid: false };
+    }
+}
+export function replayDiscoverySnapshot(value, options) {
+    const steps = [];
+    const finish = (status) => deepFreeze({ status, mode: options.mode,
+        semanticCorrectnessTested: false, steps: [...steps, { name: "model_semantic_correctness", status: "skipped", message: "Stored decisions do not establish model semantic correctness." }] });
+    const validated = validateDiscoverySnapshot(value, options.routeRequest);
+    if (!validated.valid) {
+        steps.push({ name: "discovery_snapshot", status: "failed", message: "Snapshot structure, membership or current bindings are incompatible." });
+        return finish("failed");
+    }
+    steps.push({ name: "discovery_snapshot", status: "passed", message: "Snapshot structure, membership and supplied current bindings are valid." });
+    if (options.mode === "snapshot_validation") {
+        steps.push({ name: "discovery_ranking", status: "skipped", message: "Snapshot validation does not recompute ranking." });
+        return finish("passed");
+    }
+    const snapshot = validated.snapshot, fixtures = options.fixtures;
+    try {
+        if (!fixtures || snapshot.rankerVersion.startsWith("custom:") && "custom:" + fixtures.ranker?.version !== snapshot.rankerVersion)
+            throw invalid();
+        const configuration = resolveDiscoveryConfiguration(snapshot.configuration);
+        const queries = validateQueries({ queries: fixtures.queries }, configuration);
+        if (queries.length !== snapshot.tasks.length)
+            throw invalid();
+        const corpus = buildCapabilitySearchCorpus(options.routeRequest.registry), eligibility = captureEligibility(options.routeRequest);
+        const allowed = new Set(eligibility.eligible.map(item => item.manifest.id));
+        const documents = Object.freeze(corpus.documents.filter(document => allowed.has(document.capabilityId)));
+        for (const [index, task] of snapshot.tasks.entries()) {
+            const query = queries[index];
+            if (query.id !== task.queryId || queryHash(query) !== task.queryHash || task.actualMode === null)
+                throw invalid();
+            const lexical = lexicalConfiguration(configuration);
+            const output = () => fixtures.ranker ? fixtures.ranker.rank(Object.freeze({ query, documents, configuration: lexical })) : rankLexically({ query, documents, configuration: lexical });
+            let candidates = [];
+            if (documents.length && query.fragments.some(fragment => tokenizeDiscoveryText(fragment.text).length)) {
+                if (task.actualMode === "lexical")
+                    candidates = shortlistCandidates(output(), query, documents, lexical);
+                else {
+                    if (configuration.mode !== "hybrid" || !fixtures.embedding || fixtures.mock === undefined || !fixtures.indexLimits)
+                        throw invalid();
+                    const artifact = validateCapabilityEmbeddingIndex(fixtures.index, { corpus, configuration: fixtures.embedding, mock: fixtures.mock, limits: fixtures.indexLimits });
+                    const vector = fixtures.queryVectors?.[query.id];
+                    if (!artifact.valid || artifact.index.indexFingerprint !== task.indexFingerprint || !vector || vector.queryHash !== task.queryHash
+                        || vector.configurationFingerprint !== fingerprintDiscoveryValue("embedding_configuration", fixtures.embedding)
+                        || !validVectorBatch([vector.vector], 1, artifact.index.vectorDimension))
+                        throw invalid();
+                    candidates = rankHybridCandidates(validateLexicalCandidates(output(), query, documents, true), vector.vector, new Map(artifact.index.entries.map(entry => [entry.capabilityId, entry.vector])), documents, configuration);
+                }
+            }
+            const same = hashDiscoveryContent(candidates.map(candidateProjection)) === hashDiscoveryContent(task.candidates)
+                && (candidates.length ? "matched" : "no_match") === task.status;
+            steps.push({ name: "discovery_ranking:" + task.queryId, status: same ? "passed" : "failed", message: same ? "Task ranking matched the recorded candidates and scores." : "Task ranking differs from the recorded candidates or scores." });
+        }
+        return finish(steps.some(step => step.status === "failed") ? "failed" : "passed");
+    }
+    catch {
+        steps.push({ name: "discovery_ranking", status: "skipped", message: "Compatible authorized query, ranker or vector fixtures were not supplied." });
+        return finish("refused");
+    }
+}
+export function createDiscoveryReplayHandler(options) {
+    return trace => {
+        const replay = replayDiscoverySnapshot(trace.extensions?.discovery, options);
+        const steps = [...replay.steps];
+        return { schemaVersion: "1.0", traceId: trace.traceId, mode: "router_only", status: replay.status, diagnostics: [], steps,
+            extensions: { discoveryReplayMode: options.mode, semanticCorrectnessTested: false },
+            summary: { total: steps.length, passed: steps.filter(step => step.status === "passed").length,
+                failed: steps.filter(step => step.status === "failed").length, skipped: steps.filter(step => step.status === "skipped").length } };
+    };
+}
+function candidateProjection(candidate) {
+    return { capabilityId: candidate.capabilityId, capabilityVersion: candidate.capabilityVersion, rank: candidate.rank,
+        scores: { ...candidate.scores }, inclusionReason: candidate.inclusionReason, matchedAliasHashes: candidate.matchedAliases.map(alias => hashDiscoveryContent(alias)) };
+}
+function queryHash(query) { return hashDiscoveryContent({ query }); }
+function snapshotHash(payload) { return hashDiscoveryContent({ kind: "discovery_snapshot", version: "1.0", payload }); }
+function invalid() { return new DiscoveryError({ code: "replay_inputs_unavailable", message: "Discovery replay requires complete compatible bindings and authorized fixtures." }); }

package/dist/discovery/retrieval-policy.d.ts

@@ -0,0 +1,5 @@
+import type { ResolvedDiscoveryConfiguration } from "./types.js";
+export declare const HYBRID_RANKER_VERSION = "weighted-cosine-lexical.v1";
+export declare const QUERY_EMBEDDING_PROJECTION_VERSION = "original-fragments-newline.v1";
+export declare function retrievalPolicyFingerprint(configuration: ResolvedDiscoveryConfiguration, customRankerVersion?: string): string;
+//# sourceMappingURL=retrieval-policy.d.ts.map

package/dist/discovery/retrieval-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval-policy.d.ts","sourceRoot":"","sources":["../../src/discovery/retrieval-policy.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,YAAY,CAAC;AACjE,eAAO,MAAM,qBAAqB,+BAA+B,CAAC;AAClE,eAAO,MAAM,kCAAkC,kCAAkC,CAAC;AAClF,wBAAgB,0BAA0B,CAAC,aAAa,EAAE,8BAA8B,EAAE,mBAAmB,CAAC,EAAE,MAAM,GAAG,MAAM,CAK9H"}