ai-capability-framework 1.0.3 → 1.1.0

package/dist/discovery/discoverer.js

@@ -0,0 +1,261 @@
+import { assertProviderRunScope } from "../runtime/provider-run.js";
+import { retrievalPolicyFingerprint } from "./retrieval-policy.js";
+import { performance } from "node:perf_hooks";
+import { captureEligibility } from "./bindings.js";
+import { hasOnlyKeys, isRecord, lexicalConfiguration, nonblank, resolveDiscoveryConfiguration } from "./configuration.js";
+import { buildCapabilitySearchCorpus, registrySourceFingerprint } from "./corpus.js";
+import { DiscoveryError } from "./diagnostics.js";
+import { checkEmbeddingTexts, invalidEmbeddingConfiguration, resolveEmbeddingConfiguration, resolveEmbeddingExecution, resolveIndexLimits } from "./embedding-configuration.js";
+import { runEmbeddingAttempt, stopReason, validateProviderInvocation } from "./embeddings.js";
+import { validateCapabilityEmbeddingIndex } from "./index-validation.js";
+import { boundedJsonSnapshot, deepFreeze } from "./json-snapshot.js";
+import { rankLexically, tokenizeDiscoveryText } from "./lexical.js";
+import { rankHybridCandidates, shortlistCandidates, validateLexicalCandidates } from "./ranking.js";
+import { aggregateDiscoveryUsage } from "./usage.js";
+export { HYBRID_RANKER_VERSION, QUERY_EMBEDDING_PROJECTION_VERSION } from "./retrieval-policy.js";
+export class CapabilityDiscoverer {
+    configuration;
+    ranker;
+    embedding;
+    constructor(configuration, options = {}) {
+        this.configuration = resolveDiscoveryConfiguration(configuration);
+        if (!isRecord(options) || !hasOnlyKeys(options, ["ranker", "embedding"])
+            || (options.ranker !== undefined && (!options.ranker || !nonblank(options.ranker.version) || typeof options.ranker.rank !== "function"))) {
+            throw new DiscoveryError({ code: "invalid_configuration", message: "A custom ranker requires a version and synchronous rank function." });
+        }
+        if (options.ranker)
+            this.ranker = Object.freeze({
+                version: options.ranker.version, rank: options.ranker.rank.bind(options.ranker)
+            });
+        if (this.configuration.mode === "hybrid") {
+            const embedding = options.embedding;
+            if (!embedding || !isRecord(embedding) || !hasOnlyKeys(embedding, ["client", "index", "indexLimits", "execution"])
+                || !embedding.client || typeof embedding.client.mock !== "boolean" || typeof embedding.client.embed !== "function")
+                throw invalidEmbeddingConfiguration();
+            const indexLimits = resolveIndexLimits(embedding.indexLimits);
+            let index = null;
+            try {
+                index = deepFreeze(boundedJsonSnapshot(embedding.index, indexLimits.maxArtifactBytes));
+            }
+            catch { /* Invalid artifacts yield per-query unavailable/fallback outcomes before any provider purchase. */ }
+            this.embedding = Object.freeze({
+                client: embedding.client, index, indexLimits, execution: resolveEmbeddingExecution(embedding.execution),
+                configuration: resolveEmbeddingConfiguration(embedding.client.configuration), mock: embedding.client.mock
+            });
+        }
+        else if (options.embedding !== undefined) {
+            throw new DiscoveryError({ code: "invalid_configuration", message: "Lexical discovery does not accept embedding dependencies." });
+        }
+    }
+    async discover(request) {
+        if (request.providerRun) {
+            const run = request.providerRun;
+            assertProviderRunScope(run, request.runId, request.budget ? { ledger: request.budget, policy: run.budget.policy } : undefined);
+            const signals = [request.signal, run.signal].filter((item) => !!item);
+            request = { ...request, budget: request.budget ?? run.budget.ledger, signal: signals.length ? AbortSignal.any(signals) : undefined,
+                deadlineAt: Math.min(request.deadlineAt ?? Infinity, run.deadlineAt) };
+        }
+        const configuration = this.invocationConfiguration(request);
+        const queries = validateQueries(request, configuration);
+        if (!queries.length)
+            return [];
+        const started = performance.now();
+        const corpus = buildCapabilitySearchCorpus(request.routeRequest.registry);
+        const eligibility = captureEligibility(request.routeRequest);
+        const eligibleIds = new Set(eligibility.eligible.map(({ manifest }) => manifest.id));
+        const documents = Object.freeze(corpus.documents.filter(document => eligibleIds.has(document.capabilityId)));
+        const lexical = lexicalConfiguration(configuration);
+        const policy = retrievalPolicyFingerprint(configuration, this.ranker?.version);
+        const current = () => {
+            try {
+                return captureEligibility(request.routeRequest).fingerprint === eligibility.fingerprint
+                    && registrySourceFingerprint(request.routeRequest.registry) === corpus.registrySourceFingerprint;
+            }
+            catch {
+                return false;
+            }
+        };
+        const result = (queryId, status, code, usage = zeroDiscoveryUsage(performance.now() - started)) => ({
+            queryId, status, requestedMode: configuration.mode, actualMode: status === "cancelled" || status === "unavailable" ? null : configuration.mode,
+            candidates: [], corpusFingerprint: corpus.corpusFingerprint, eligibilityFingerprint: eligibility.fingerprint,
+            retrievalPolicyFingerprint: policy, policyVersion: configuration.policyVersion, usage,
+            diagnostics: code ? [{ code, queryId, message: diagnosticMessage(code) }] : []
+        });
+        const lexicalOutput = (query) => {
+            const input = Object.freeze({ query, documents, configuration: lexical });
+            return this.ranker ? this.ranker.rank(input) : rankLexically(input);
+        };
+        const lexicalResult = (query, usage, degradation) => {
+            try {
+                const candidates = shortlistCandidates(lexicalOutput(query), query, documents, lexical);
+                return {
+                    ...result(query.id, candidates.length ? "matched" : "no_match", candidates.length ? undefined : "no_matching_candidates", usage),
+                    actualMode: "lexical", candidates,
+                    ...(degradation ? { degradedReason: degradation, diagnostics: [
+                            { code: degradation, queryId: query.id, message: diagnosticMessage(degradation) },
+                            { code: "lexical_fallback", queryId: query.id, message: "The whole query used the explicit lexical fallback policy." }
+                        ] } : {})
+                };
+            }
+            catch {
+                return result(query.id, "unavailable", "invalid_ranker_output", usage);
+            }
+        };
+        const semanticFailure = (query, code, usage) => {
+            if (configuration.mode === "hybrid" && configuration.failurePolicy === "lexical_fallback"
+                && ["invalid_index", "embedding_configuration_mismatch", "invalid_embedding", "provider_unavailable"].includes(code)) {
+                if (!current())
+                    return result(query.id, "unavailable", "stale_binding", usage);
+                return lexicalResult(query, usage, code);
+            }
+            return result(query.id, code === "cancelled" || code === "deadline_exceeded" ? "cancelled" : "unavailable", code, usage);
+        };
+        const hasWork = documents.length && queries.some(query => query.fragments.some(fragment => tokenizeDiscoveryText(fragment.text).length));
+        const embedding = this.embedding;
+        const index = embedding && hasWork ? validateCapabilityEmbeddingIndex(embedding.index, {
+            corpus, configuration: embedding.configuration, mock: embedding.mock, limits: embedding.indexLimits
+        }) : undefined;
+        if (embedding && index?.valid && !discoveryStopReason(request)) {
+            validateProviderInvocation(request);
+            for (const query of queries) {
+                if (query.fragments.some(fragment => tokenizeDiscoveryText(fragment.text).length)) {
+                    checkEmbeddingTexts([query.fragments.map(fragment => fragment.text).join("\n")], embedding.execution.limits);
+                }
+            }
+        }
+        const results = [];
+        for (const query of queries) {
+            const stopped = discoveryStopReason(request);
+            if (stopped) {
+                results.push(result(query.id, "cancelled", stopped));
+                continue;
+            }
+            if (!query.fragments.some(fragment => tokenizeDiscoveryText(fragment.text).length)) {
+                results.push(result(query.id, "no_match", "empty_query"));
+                continue;
+            }
+            if (!documents.length) {
+                results.push(result(query.id, "no_match", "no_eligible_capabilities"));
+                continue;
+            }
+            if (!current()) {
+                results.push(result(query.id, "unavailable", "stale_binding"));
+                continue;
+            }
+            if (configuration.mode === "lexical") {
+                results.push(lexicalResult(query));
+                continue;
+            }
+            if (!index?.valid) {
+                results.push(semanticFailure(query, index?.diagnostics[0]?.code ?? "invalid_index"));
+                continue;
+            }
+            let candidates;
+            try {
+                candidates = validateLexicalCandidates(lexicalOutput(query), query, documents, true);
+            }
+            catch {
+                results.push(result(query.id, "unavailable", "invalid_ranker_output"));
+                continue;
+            }
+            if (!candidates.length) {
+                results.push(result(query.id, "no_match", "no_matching_candidates"));
+                continue;
+            }
+            const attempted = await runEmbeddingAttempt({
+                ...request, deadlineAt: request.deadlineAt, budget: request.budget, client: embedding.client,
+                configuration: embedding.configuration, mock: embedding.mock, execution: embedding.execution,
+                texts: [query.fragments.map(fragment => fragment.text).join("\n")], stage: "query_embedding",
+                maxVectorDimension: embedding.indexLimits.maxVectorDimension, expectedDimension: index.index.vectorDimension,
+                controls: request.routeRequest.controls, runtimeContext: request.routeRequest.builtContext.runtimeContext, isCurrent: current
+            });
+            if (attempted.status !== "completed") {
+                results.push(semanticFailure(query, attempted.diagnostics[0].code, attempted.usage));
+                continue;
+            }
+            const vectors = new Map(index.index.entries.map(entry => [entry.capabilityId, entry.vector]));
+            const selected = rankHybridCandidates(candidates, attempted.vectors[0], vectors, documents, configuration);
+            results.push({
+                ...result(query.id, selected.length ? "matched" : "no_match", selected.length ? undefined : "no_matching_candidates", attempted.usage),
+                candidates: selected, indexFingerprint: index.index.indexFingerprint
+            });
+        }
+        const valid = current();
+        return results.map(entry => {
+            const stopped = discoveryStopReason(request);
+            if (stopped || !valid && entry.status === "matched") {
+                const { indexFingerprint: _, ...retained } = entry;
+                const code = stopped ?? "stale_binding";
+                return { ...retained, status: stopped ? "cancelled" : "unavailable", actualMode: null, candidates: [],
+                    diagnostics: [{ code, queryId: entry.queryId, message: diagnosticMessage(code) }] };
+            }
+            return entry;
+        });
+    }
+    invocationConfiguration(request) {
+        if (!isRecord(request) || !nonblank(request.runId) || !nonblank(request.requestId)
+            || (request.deadlineAt !== undefined && (typeof request.deadlineAt !== "number" || !Number.isFinite(request.deadlineAt)))
+            || (request.signal !== undefined && !(request.signal instanceof AbortSignal))) {
+            throw new DiscoveryError({ code: "invalid_input", message: "Discovery requires invocation identifiers and valid cancellation bounds." });
+        }
+        const limit = request.maxCandidates === undefined ? this.configuration.limits.maxCandidates : request.maxCandidates;
+        if (!Number.isInteger(limit) || limit < 1 || limit > this.configuration.limits.maxCandidates) {
+            throw new DiscoveryError({ code: "invalid_input", message: "The invocation candidate limit must lower or equal the configured limit." });
+        }
+        return Object.freeze({ ...this.configuration, limits: Object.freeze({
+                ...this.configuration.limits, maxCandidates: limit, aliasDiversitySlots: limit === 1 ? 0 : this.configuration.limits.aliasDiversitySlots
+            }) });
+    }
+}
+export function validateQueries(request, configuration) {
+    const invalid = () => new DiscoveryError({ code: "invalid_input", message: "Discovery requires unique query IDs and string fragments." });
+    const exceeded = () => new DiscoveryError({ code: "input_limit_exceeded", message: "Discovery input exceeds the configured batch, fragment, or text limit." });
+    if (!Array.isArray(request.queries))
+        throw invalid();
+    if (request.queries.length > configuration.limits.maxQueries)
+        throw exceeded();
+    const ids = new Set();
+    return Object.freeze(Array.from(request.queries, query => {
+        if (!isRecord(query) || !hasOnlyKeys(query, ["id", "fragments"]) || !nonblank(query.id)
+            || ids.has(query.id) || !Array.isArray(query.fragments))
+            throw invalid();
+        ids.add(query.id);
+        if (query.fragments.length > configuration.limits.maxFragmentsPerQuery)
+            throw exceeded();
+        let characters = 0;
+        const fragments = Array.from(query.fragments, fragment => {
+            if (!isRecord(fragment) || !hasOnlyKeys(fragment, ["key", "text"])
+                || !nonblank(fragment.key) || typeof fragment.text !== "string")
+                throw invalid();
+            characters += fragment.text.length;
+            if (characters > configuration.limits.maxQueryCharacters)
+                throw exceeded();
+            return Object.freeze({ key: fragment.key, text: fragment.text });
+        });
+        return Object.freeze({ id: query.id, fragments: Object.freeze(fragments) });
+    }));
+}
+export function discoveryStopReason(request) {
+    return stopReason(request);
+}
+export function zeroDiscoveryUsage(elapsedMs) {
+    return aggregateDiscoveryUsage([], elapsedMs);
+}
+function diagnosticMessage(code) {
+    switch (code) {
+        case "cancelled": return "Discovery was cancelled.";
+        case "deadline_exceeded": return "The discovery deadline elapsed.";
+        case "empty_query": return "The query has no searchable tokens.";
+        case "no_eligible_capabilities": return "No capabilities are currently eligible.";
+        case "no_matching_candidates": return "No eligible candidates met the retrieval policy.";
+        case "stale_binding": return "Discovery bindings changed before candidates could be returned.";
+        case "invalid_index": return "The embedding index is invalid or stale.";
+        case "embedding_configuration_mismatch": return "Embedding configurations or dimensions were incompatible.";
+        case "invalid_embedding": return "The embedding client returned invalid semantic inputs.";
+        case "provider_unavailable": return "The embedding provider was unavailable.";
+        case "budget_denied": return "The shared embedding budget denied this attempt.";
+        case "control_denied": return "Runtime controls denied the embedding attempt.";
+        case "accounting_unavailable": return "Embedding reservation or settlement accounting was unavailable.";
+        default: return "The lexical ranker was unavailable or returned invalid output.";
+    }
+}

package/dist/discovery/embedding-configuration.d.ts

@@ -0,0 +1,12 @@
+import { DiscoveryError } from "./diagnostics.js";
+import type { EmbeddingCallLimits, EmbeddingExecutionOptions, EmbeddingIndexLimits } from "./embedding-types.js";
+import type { EmbeddingConfiguration } from "./types.js";
+export declare function positiveInteger(value: unknown): value is number;
+export declare function resolveEmbeddingConfiguration(value: EmbeddingConfiguration): Readonly<EmbeddingConfiguration>;
+export declare function resolveIndexLimits(value: EmbeddingIndexLimits): Readonly<EmbeddingIndexLimits>;
+export declare function resolveEmbeddingExecution(value: EmbeddingExecutionOptions): Readonly<EmbeddingExecutionOptions>;
+export declare function nonnegative(value: unknown): value is number;
+export declare function checkEmbeddingTexts(texts: readonly string[], limits: EmbeddingCallLimits): void;
+export declare function invalidEmbeddingConfiguration(): DiscoveryError;
+export declare function inputLimit(): DiscoveryError;
+//# sourceMappingURL=embedding-configuration.d.ts.map

package/dist/discovery/embedding-configuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-configuration.d.ts","sourceRoot":"","sources":["../../src/discovery/embedding-configuration.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE/D;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,sBAAsB,GAAG,QAAQ,CAAC,sBAAsB,CAAC,CAU7G;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,oBAAoB,GAAG,QAAQ,CAAC,oBAAoB,CAAC,CAK9F;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,yBAAyB,GAAG,QAAQ,CAAC,yBAAyB,CAAC,CAiC/G;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE3D;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAO/F;AAED,wBAAgB,6BAA6B,IAAI,cAAc,CAE9D;AAED,wBAAgB,UAAU,IAAI,cAAc,CAE3C"}

package/dist/discovery/embedding-configuration.js

@@ -0,0 +1,81 @@
+import { hasOnlyKeys, isRecord, nonblank } from "./configuration.js";
+import { DiscoveryError } from "./diagnostics.js";
+export function positiveInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+export function resolveEmbeddingConfiguration(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["provider", "model", "configurationId", "revision", "dimensions"])
+        || !nonblank(value.provider) || !nonblank(value.model) || !nonblank(value.configurationId)
+        || (value.revision !== undefined && !nonblank(value.revision))
+        || (value.dimensions !== undefined && !positiveInteger(value.dimensions)))
+        throw invalidEmbeddingConfiguration();
+    return Object.freeze({
+        provider: value.provider, model: value.model, configurationId: value.configurationId,
+        ...(value.revision === undefined ? {} : { revision: value.revision }),
+        ...(value.dimensions === undefined ? {} : { dimensions: value.dimensions })
+    });
+}
+export function resolveIndexLimits(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["maxArtifactBytes", "maxEntries", "maxVectorDimension"])
+        || !positiveInteger(value.maxArtifactBytes) || !positiveInteger(value.maxEntries)
+        || !positiveInteger(value.maxVectorDimension))
+        throw invalidEmbeddingConfiguration();
+    return Object.freeze({ ...value });
+}
+export function resolveEmbeddingExecution(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, ["limits", "budgetPolicy", "estimateCost"])
+        || !isRecord(value.limits) || !hasOnlyKeys(value.limits, ["maxInputTokens", "maxCharactersPerText", "maxCharactersPerCall", "maxEstimatedCostPerCall"])
+        || !positiveInteger(value.limits.maxInputTokens) || !positiveInteger(value.limits.maxCharactersPerText)
+        || !positiveInteger(value.limits.maxCharactersPerCall)
+        || (value.limits.maxEstimatedCostPerCall !== undefined && !nonnegative(value.limits.maxEstimatedCostPerCall))
+        || !isRecord(value.budgetPolicy) || !nonblank(value.budgetPolicy.id) || !isRecord(value.budgetPolicy.scope)
+        || !["global", "provider", "model", "capability", "domain", "risk_tier", "tenant", "autonomy_tier"].includes(value.budgetPolicy.scope.type)
+        || (value.estimateCost !== undefined && typeof value.estimateCost !== "function"))
+        throw invalidEmbeddingConfiguration();
+    const policy = value.budgetPolicy;
+    if (!hasOnlyKeys(policy, ["id", "scope", "mode", "maxEstimatedCostPerRun", "maxInputTokensPerRun",
+        "maxOutputTokensPerRun", "maxProviderCallsPerRun", "maxRetriesPerRun", "maxRuntimeMsPerRun", "maxToolCallsPerRun"])
+        || (policy.mode !== undefined && policy.mode !== "hard" && policy.mode !== "warn")
+        || !Number.isSafeInteger(policy.maxProviderCallsPerRun) || (policy.maxProviderCallsPerRun ?? -1) < 0)
+        throw invalidEmbeddingConfiguration();
+    for (const [key, amount] of Object.entries(policy)) {
+        if (!key.startsWith("max"))
+            continue;
+        if (!nonnegative(amount) || (key !== "maxEstimatedCostPerRun" && !Number.isSafeInteger(amount)))
+            throw invalidEmbeddingConfiguration();
+    }
+    const scopeFields = {
+        global: [], provider: ["providerId"], model: ["providerId", "model"], capability: ["capabilityId"],
+        domain: ["domain"], risk_tier: ["riskTier"], tenant: ["tenantId"], autonomy_tier: ["autonomyTier"]
+    };
+    const fields = scopeFields[policy.scope.type];
+    if (!hasOnlyKeys(policy.scope, ["type", ...fields]) || fields.some(key => !nonblank(policy.scope[key]))
+        || policy.scope.type === "risk_tier" && !["none", "low", "medium", "high", "critical"].includes(policy.scope.riskTier)
+        || policy.scope.type === "autonomy_tier" && !["A0", "A1", "A2", "A3", "A4", "A5"].includes(policy.scope.autonomyTier)
+        || (policy.maxEstimatedCostPerRun !== undefined && value.limits.maxEstimatedCostPerCall === undefined))
+        throw invalidEmbeddingConfiguration();
+    return Object.freeze({
+        limits: Object.freeze({ ...value.limits }),
+        budgetPolicy: Object.freeze({ ...policy, scope: Object.freeze({ ...policy.scope }) }),
+        ...(value.estimateCost ? { estimateCost: value.estimateCost } : {})
+    });
+}
+export function nonnegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+export function checkEmbeddingTexts(texts, limits) {
+    let characters = 0;
+    for (const text of texts) {
+        if (typeof text !== "string" || text.length > limits.maxCharactersPerText)
+            throw inputLimit();
+        characters += text.length;
+        if (characters > limits.maxCharactersPerCall)
+            throw inputLimit();
+    }
+}
+export function invalidEmbeddingConfiguration() {
+    return new DiscoveryError({ code: "invalid_configuration", message: "Embedding configuration, limits, and provider-call budget must be explicit and valid." });
+}
+export function inputLimit() {
+    return new DiscoveryError({ code: "input_limit_exceeded", message: "Embedding input or artifact exceeds the configured limits." });
+}

package/dist/discovery/embedding-types.d.ts

@@ -0,0 +1,75 @@
+import type { AicfRuntimeControls, BudgetPolicy } from "../controls/types.js";
+import type { CapabilityEmbeddingIndexArtifact } from "../generated/manifest-types.js";
+import type { AicfRuntimeContext } from "../runtime/types.js";
+import type { DiscoveryDiagnostic } from "./diagnostics.js";
+import type { CapabilitySearchCorpus, DiscoveryBudgetLedger, DiscoveryInvocation, DiscoveryUsage, EmbeddingClient, EmbeddingConfiguration, ModelUsage } from "./types.js";
+export type DeepReadonly<T> = T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+export type CapabilityEmbeddingIndex = DeepReadonly<CapabilityEmbeddingIndexArtifact>;
+export interface EmbeddingIndexLimits {
+    maxArtifactBytes: number;
+    maxEntries: number;
+    maxVectorDimension: number;
+}
+export interface EmbeddingCallLimits {
+    maxInputTokens: number;
+    maxCharactersPerText: number;
+    maxCharactersPerCall: number;
+    maxEstimatedCostPerCall?: number;
+}
+export interface EmbeddingExecutionOptions {
+    limits: EmbeddingCallLimits;
+    budgetPolicy: BudgetPolicy;
+    /** Return undefined when the available reported usage cannot be priced. */
+    estimateCost?: (usage: Readonly<ModelUsage>, configuration: Readonly<EmbeddingConfiguration>) => number | undefined;
+}
+export interface HybridDiscoveryDependencies {
+    client: EmbeddingClient;
+    index: unknown;
+    indexLimits: EmbeddingIndexLimits;
+    execution: EmbeddingExecutionOptions;
+}
+export interface EmbeddingIndexExpected {
+    corpus: CapabilitySearchCorpus;
+    configuration: EmbeddingConfiguration;
+    mock: boolean;
+    limits: EmbeddingIndexLimits;
+}
+export type EmbeddingIndexValidationResult = {
+    valid: true;
+    index: CapabilityEmbeddingIndex;
+    diagnostics: readonly [];
+} | {
+    valid: false;
+    diagnostics: readonly DiscoveryDiagnostic[];
+};
+export interface CapabilityEmbeddingIndexBuildRequest extends DiscoveryInvocation {
+    deadlineAt: number;
+    corpus: CapabilitySearchCorpus;
+    client: EmbeddingClient;
+    limits: EmbeddingIndexLimits;
+    execution: EmbeddingExecutionOptions;
+    batchSize: number;
+    maxProviderCalls: number;
+    budget: DiscoveryBudgetLedger;
+    controls?: AicfRuntimeControls;
+    runtimeContext?: AicfRuntimeContext;
+}
+export type CapabilityEmbeddingIndexBuildResult = {
+    status: "built";
+    index: CapabilityEmbeddingIndex;
+    usage: DiscoveryUsage;
+    diagnostics: readonly DiscoveryDiagnostic[];
+} | {
+    status: "unavailable" | "cancelled";
+    index: null;
+    usage: DiscoveryUsage;
+    diagnostics: readonly DiscoveryDiagnostic[];
+};
+/** Host implementations replace complete values atomically; no partial artifact may become visible. */
+export interface CapabilityEmbeddingIndexStore {
+    read(key: string): Promise<string | null>;
+    replace(key: string, serializedArtifact: string): Promise<void>;
+}
+//# sourceMappingURL=embedding-types.d.ts.map

package/dist/discovery/embedding-types.d.ts.map

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

package/dist/discovery/embedding-types.js

@@ -0,0 +1 @@
+export {};

package/dist/discovery/embeddings.d.ts

@@ -0,0 +1,38 @@
+import type { AicfRuntimeControls } from "../controls/types.js";
+import type { AicfRuntimeContext } from "../runtime/types.js";
+import { type DiscoveryDiagnostic } from "./diagnostics.js";
+import type { EmbeddingExecutionOptions } from "./embedding-types.js";
+import type { DiscoveryBudgetLedger, DiscoveryInvocation, DiscoveryUsage, EmbeddingClient, EmbeddingConfiguration } from "./types.js";
+export interface EmbeddingAttemptRequest extends DiscoveryInvocation {
+    deadlineAt: number;
+    client: EmbeddingClient;
+    configuration: EmbeddingConfiguration;
+    mock: boolean;
+    texts: readonly string[];
+    stage: "embedding_build" | "query_embedding";
+    execution: EmbeddingExecutionOptions;
+    maxVectorDimension: number;
+    expectedDimension?: number;
+    budget: DiscoveryBudgetLedger;
+    controls?: AicfRuntimeControls;
+    runtimeContext?: AicfRuntimeContext;
+    /** Rechecks current source/authorization immediately after a reservation. */
+    isCurrent?: () => boolean;
+}
+export type EmbeddingAttemptResult = {
+    status: "completed";
+    vectors: readonly (readonly number[])[];
+    vectorDimension: number;
+    usage: DiscoveryUsage;
+    diagnostics: readonly [];
+} | {
+    status: "unavailable" | "cancelled";
+    usage: DiscoveryUsage;
+    diagnostics: readonly DiscoveryDiagnostic[];
+};
+export { stopReason, stopGate } from "../runtime/provider-stop.js";
+export declare function validateProviderInvocation(request: DiscoveryInvocation & {
+    budget?: DiscoveryBudgetLedger;
+}): void;
+export declare function runEmbeddingAttempt(request: EmbeddingAttemptRequest): Promise<EmbeddingAttemptResult>;
+//# sourceMappingURL=embeddings.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings.d.ts","sourceRoot":"","sources":["../../src/discovery/embeddings.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,OAAO,EAAkB,KAAK,mBAAmB,EAAgC,MAAM,kBAAkB,CAAC;AAI1G,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAC;AAGtE,OAAO,KAAK,EACV,qBAAqB,EAAE,mBAAmB,EAAE,cAAc,EAAE,eAAe,EAAE,sBAAsB,EACpG,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,eAAe,CAAC;IACxB,aAAa,EAAE,sBAAsB,CAAC;IACtC,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,KAAK,EAAE,iBAAiB,GAAG,iBAAiB,CAAC;IAC7C,SAAS,EAAE,yBAAyB,CAAC;IACrC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,MAAM,EAAE,qBAAqB,CAAC;IAC9B,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,cAAc,CAAC,EAAE,kBAAkB,CAAC;IACpC,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;CAC3B;AAED,MAAM,MAAM,sBAAsB,GAC9B;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,cAAc,CAAC;IAAC,WAAW,EAAE,SAAS,EAAE,CAAA;CAAE,GAC1I;IAAE,MAAM,EAAE,aAAa,GAAG,WAAW,CAAC;IAAC,KAAK,EAAE,cAAc,CAAC;IAAC,WAAW,EAAE,SAAS,mBAAmB,EAAE,CAAA;CAAE,CAAC;AAEhH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AACnE,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,mBAAmB,GAAG;IAAE,MAAM,CAAC,EAAE,qBAAqB,CAAA;CAAE,GAAG,IAAI,CAMlH;AAED,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAmC3G"}

package/dist/discovery/embeddings.js

@@ -0,0 +1,71 @@
+import { executeProviderAttempt } from "../runtime/provider-attempt.js";
+import { assertProviderRunScope } from "../runtime/provider-run.js";
+import { hasOnlyKeys, isRecord, nonblank } from "./configuration.js";
+import { DiscoveryError } from "./diagnostics.js";
+import { checkEmbeddingTexts, positiveInteger, resolveEmbeddingConfiguration, resolveEmbeddingExecution } from "./embedding-configuration.js";
+import { fingerprintDiscoveryValue } from "./fingerprint.js";
+import { deepFreeze } from "./json-snapshot.js";
+import { validVectorBatch } from "./vectors.js";
+export { stopReason, stopGate } from "../runtime/provider-stop.js";
+export function validateProviderInvocation(request) {
+    if (!nonblank(request.runId) || !nonblank(request.requestId) || typeof request.deadlineAt !== "number"
+        || !Number.isFinite(request.deadlineAt) || request.signal !== undefined && !(request.signal instanceof AbortSignal)
+        || typeof request.budget?.reserve !== "function" || typeof request.budget?.settle !== "function") {
+        throw new DiscoveryError({ code: "invalid_configuration", message: "Embedding attempts require invocation IDs, a deadline, and a shared reservation ledger." });
+    }
+}
+export async function runEmbeddingAttempt(request) {
+    validateProviderInvocation(request);
+    const execution = resolveEmbeddingExecution(request.execution);
+    const configuration = resolveEmbeddingConfiguration(request.configuration);
+    checkEmbeddingTexts(request.texts, execution.limits);
+    const texts = Object.freeze([...request.texts]);
+    if (request.providerRun)
+        assertProviderRunScope(request.providerRun, request.runId, { ledger: request.budget, policy: execution.budgetPolicy });
+    const input = {
+        ...request, maxInputTokens: execution.limits.maxInputTokens, maxEstimatedCostPerCall: execution.limits.maxEstimatedCostPerCall,
+        protocolError: "invalid_embedding", estimateCost: execution.estimateCost,
+        guard: () => {
+            if (request.isCurrent && !request.isCurrent())
+                return "stale_binding";
+            if (request.client.mock !== request.mock
+                || fingerprintDiscoveryValue("embedding_configuration", resolveEmbeddingConfiguration(request.client.configuration))
+                    !== fingerprintDiscoveryValue("embedding_configuration", configuration))
+                return "embedding_configuration_mismatch";
+            return undefined;
+        },
+        invoke: context => request.client.embed({ texts, configuration, maxInputTokens: execution.limits.maxInputTokens,
+            runId: request.runId, requestId: request.requestId, ...context }),
+        validate(response) {
+            if (!isRecord(response) || !hasOnlyKeys(response, ["vectors", "configuration", "vectorDimension", "usage", "providerAttempts"])
+                || !positiveInteger(response.vectorDimension) || response.vectorDimension > request.maxVectorDimension
+                || request.expectedDimension !== undefined && response.vectorDimension !== request.expectedDimension
+                || configuration.dimensions !== undefined && response.vectorDimension !== configuration.dimensions
+                || !validVectorBatch(response.vectors, texts.length, response.vectorDimension))
+                return { code: "invalid_embedding" };
+            if (fingerprintDiscoveryValue("embedding_configuration", resolveEmbeddingConfiguration(response.configuration))
+                !== fingerprintDiscoveryValue("embedding_configuration", configuration))
+                return { code: "embedding_configuration_mismatch" };
+            return { value: { vectors: deepFreeze(response.vectors.map(vector => [...vector])), vectorDimension: response.vectorDimension } };
+        }
+    };
+    const result = request.providerRun ? await request.providerRun.attempt(input)
+        : await executeProviderAttempt(input, { ledger: request.budget, policy: execution.budgetPolicy });
+    if (result.code)
+        return { status: result.code === "cancelled" || result.code === "deadline_exceeded" ? "cancelled" : "unavailable",
+            usage: result.usage, diagnostics: [{ code: result.code, message: safeMessage(result.code) }] };
+    return { status: "completed", ...result.value, usage: result.usage, diagnostics: [] };
+}
+function safeMessage(code) {
+    switch (code) {
+        case "cancelled": return "The embedding operation was cancelled.";
+        case "deadline_exceeded": return "The embedding deadline elapsed.";
+        case "budget_denied": return "The shared embedding budget denied this attempt.";
+        case "control_denied": return "Runtime controls denied the embedding attempt.";
+        case "stale_binding": return "Source or authorization bindings changed during embedding.";
+        case "embedding_configuration_mismatch": return "Embedding model configuration changed or did not match.";
+        case "invalid_embedding": return "The embedding client returned incompatible vectors or attempt counts.";
+        case "accounting_unavailable": return "Embedding reservation or settlement accounting is unavailable.";
+        default: return "The embedding provider was unavailable.";
+    }
+}

package/dist/discovery/evaluation-validation.d.ts

@@ -0,0 +1,8 @@
+import type { DiscoveryEvaluationObservations, DiscoveryEvaluationSuite } from "../generated/manifest-types.js";
+export interface DiscoveryEvaluationDiagnostic {
+    code: string;
+    caseId?: string;
+}
+export declare const evaluationSuiteSnapshot: (value: unknown) => DiscoveryEvaluationSuite | null;
+export declare const evaluationObservationsSnapshot: (value: unknown) => DiscoveryEvaluationObservations | null;
+//# sourceMappingURL=evaluation-validation.d.ts.map

package/dist/discovery/evaluation-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluation-validation.d.ts","sourceRoot":"","sources":["../../src/discovery/evaluation-validation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,+BAA+B,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AAShH,MAAM,WAAW,6BAA6B;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAAE;AASjF,eAAO,MAAM,uBAAuB,GAAI,OAAO,OAAO,oCAA8D,CAAC;AACrH,eAAO,MAAM,8BAA8B,GAAI,OAAO,OAAO,2CAA4E,CAAC"}

package/dist/discovery/evaluation-validation.js

@@ -0,0 +1,19 @@
+import Ajv2020 from "ajv/dist/2020.js";
+import { readFileSync } from "node:fs";
+import { boundedJsonSnapshot } from "../runtime/bounded-json.js";
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+const read = (name) => JSON.parse(readFileSync(new URL(`../../schemas/${name}.schema.json`, import.meta.url), "utf8"));
+ajv.addSchema(read("capability-manifest"));
+const suiteValidator = ajv.compile(read("discovery/eval-suite"));
+const observationsValidator = ajv.compile(read("discovery/eval-observations"));
+function snapshot(value, validate) {
+    try {
+        const detached = boundedJsonSnapshot(value, 16 * 1024 * 1024);
+        return validate(detached) ? detached : null;
+    }
+    catch {
+        return null;
+    }
+}
+export const evaluationSuiteSnapshot = (value) => snapshot(value, suiteValidator);
+export const evaluationObservationsSnapshot = (value) => snapshot(value, observationsValidator);