ai-capability-framework 1.0.3 → 1.1.0

package/dist/discovery/facade.js

@@ -0,0 +1,266 @@
+import { assertProviderRunScope } from "../runtime/provider-run.js";
+import { isDeepStrictEqual } from "node:util";
+import { DefaultContextBuilder } from "../runtime/context.js";
+import { hasOnlyKeys, isRecord, nonblank, resolveDiscoveryConfiguration } from "./configuration.js";
+import { registrySourceFingerprint } from "./corpus.js";
+import { CapabilityDiscoverer, validateQueries } from "./discoverer.js";
+import { DiscoveryError } from "./diagnostics.js";
+import { positiveInteger, resolveIndexLimits } from "./embedding-configuration.js";
+import { exportDiscoveryResult, exportSelectedResult, validateRouterLimit } from "./export.js";
+import { boundedJsonSnapshot, deepFreeze } from "./json-snapshot.js";
+import { ModelCapabilitySelector } from "./selection.js";
+import { resolveSelectionLimits } from "./selection-configuration.js";
+import { aggregateDiscoveryUsage } from "./usage.js";
+import { SELECTION_HARD_LIMITS } from "./versions.js";
+export const DISCOVERY_STANDARD_PROFILE = deepFreeze({
+    policyVersion: "aicf.discovery.standard.v1", timeoutMs: 30_000,
+    weights: { semantic: 0.75, lexical: 0.25 }, failurePolicy: "unavailable",
+    indexLimits: { maxArtifactBytes: 16 * 1024 * 1024, maxEntries: 10_000, maxVectorDimension: 4_096 },
+    maxCharactersPerText: 16_384, maxCharactersPerCall: 65_536
+});
+const eligibilityKeys = [
+    "allowedCapabilityTypes", "allowedDomains", "capabilityPermissions", "excludeCapabilityIds", "includeCapabilityIds",
+    "includeDeprecated", "includeDisabledForTests", "includeDraft", "includeExperimental", "includeRestricted",
+    "maxCapabilities", "maxRiskTier"
+];
+function validateEligibility(value) {
+    const invalid = () => new DiscoveryError({ code: "invalid_input", message: "Discovery eligibility options are invalid." });
+    for (const key of ["allowedCapabilityTypes", "allowedDomains", "excludeCapabilityIds", "includeCapabilityIds"]) {
+        if (value[key] !== undefined && (!Array.isArray(value[key]) || !value[key].every(nonblank)))
+            throw invalid();
+    }
+    for (const key of ["includeDeprecated", "includeDisabledForTests", "includeDraft", "includeExperimental", "includeRestricted"]) {
+        if (value[key] !== undefined && typeof value[key] !== "boolean")
+            throw invalid();
+    }
+    if (value.maxRiskTier !== undefined && !["low", "medium", "high", "critical"].includes(value.maxRiskTier))
+        throw invalid();
+    if (value.capabilityPermissions !== undefined) {
+        if (!isRecord(value.capabilityPermissions))
+            throw invalid();
+        for (const permission of Object.values(value.capabilityPermissions)) {
+            if (!isRecord(permission) || !hasOnlyKeys(permission, ["allowed", "permissions", "reason"])
+                || typeof permission.allowed !== "boolean" || !Array.isArray(permission.permissions)
+                || !permission.permissions.every(nonblank) || permission.reason !== undefined && typeof permission.reason !== "string")
+                throw invalid();
+        }
+    }
+    validateRouterLimit(value.maxCapabilities);
+}
+/** Simple application-driven search. Model choice and execution stay in the ordinary runtime. */
+export function createCapabilityDiscovery(options) {
+    const invalid = () => new DiscoveryError({ code: "invalid_configuration", message: "The discovery facade configuration is invalid." });
+    if (!isRecord(options) || !hasOnlyKeys(options, ["registry", "contextBuilder", "ranker", "policyVersion", "timeoutMs",
+        "limits", "aliasWeight", "minRetrievalScore", "mode", "embedding", "weights", "failurePolicy"])
+        || Object.values(options).some(value => value === null)
+        || !options.registry || options.contextBuilder !== undefined && typeof options.contextBuilder?.build !== "function")
+        throw invalid();
+    const timeoutMs = options.timeoutMs ?? DISCOVERY_STANDARD_PROFILE.timeoutMs;
+    if (!positiveInteger(timeoutMs))
+        throw invalid();
+    const registry = options.registry;
+    const contextBuilder = options.contextBuilder ?? new DefaultContextBuilder();
+    const base = { policyVersion: options.policyVersion ?? DISCOVERY_STANDARD_PROFILE.policyVersion,
+        limits: options.limits, aliasWeight: options.aliasWeight, minRetrievalScore: options.minRetrievalScore };
+    const configuration = options.mode === "hybrid"
+        ? { ...base, mode: "hybrid", weights: options.weights ?? DISCOVERY_STANDARD_PROFILE.weights,
+            failurePolicy: options.failurePolicy ?? DISCOVERY_STANDARD_PROFILE.failurePolicy }
+        : { ...base, mode: options.mode ?? "lexical" };
+    const resolved = resolveDiscoveryConfiguration(configuration);
+    const ranker = options.ranker;
+    // Validate even before the first search; the low-level engine remains strict and explicit.
+    const lexicalEngine = new CapabilityDiscoverer({ ...base, mode: "lexical" }, { ranker });
+    let embedding;
+    let indexLimits;
+    if (options.mode === "hybrid") {
+        const value = options.embedding;
+        if (!isRecord(value) || !hasOnlyKeys(value, ["client", "index", "maxInputTokens", "indexLimits", "maxCharactersPerText",
+            "maxCharactersPerCall", "maxEstimatedCostPerCall", "estimateCost"])
+            || !positiveInteger(value.maxInputTokens) || !value.client || typeof value.client.embed !== "function"
+            || typeof value.client.mock !== "boolean" || value.indexLimits !== undefined && !isRecord(value.indexLimits))
+            throw invalid();
+        embedding = { ...value };
+        indexLimits = resolveIndexLimits({ ...DISCOVERY_STANDARD_PROFILE.indexLimits, ...value.indexLimits });
+        for (const key of ["maxCharactersPerText", "maxCharactersPerCall"]) {
+            if (value[key] !== undefined && !positiveInteger(value[key]))
+                throw invalid();
+        }
+    }
+    else if (options.embedding !== undefined || options.weights !== undefined || options.failurePolicy !== undefined)
+        throw invalid();
+    // Entries live only as long as the caller retains the issued result. This is not a retrieval cache.
+    const bindings = new WeakMap();
+    const batches = new WeakMap();
+    return Object.freeze({
+        async search(request) {
+            if (!isRecord(request) || !hasOnlyKeys(request, ["tasks", "runtimeContext", "controls", "eligibility", "signal", "deadlineAt", "budget", "providerRun"])
+                || !Array.isArray(request.tasks) || !request.runtimeContext
+                || request.controls !== undefined && typeof request.controls?.evaluate !== "function"
+                || request.deadlineAt !== undefined && !Number.isFinite(request.deadlineAt)
+                || request.signal !== undefined && !(request.signal instanceof AbortSignal)
+                || request.eligibility !== undefined && (!isRecord(request.eligibility) || !hasOnlyKeys(request.eligibility, eligibilityKeys))) {
+                throw new DiscoveryError({ code: "invalid_input", message: "Search requires tasks, runtime context, and valid request options." });
+            }
+            if (request.tasks.length > resolved.limits.maxQueries)
+                throw new DiscoveryError({ code: "input_limit_exceeded", message: "The task batch exceeds the configured limit." });
+            const queries = Array.from(request.tasks, task => {
+                if (!isRecord(task) || !hasOnlyKeys(task, ["id", "text"]) || !nonblank(task.id) || typeof task.text !== "string") {
+                    throw new DiscoveryError({ code: "invalid_input", message: "Tasks require unique nonblank IDs and string text." });
+                }
+                return { id: task.id, fragments: [{ key: "task", text: task.text }] };
+            });
+            // Reuse the engine's bounds and snapshot validation before invoking application code.
+            validateQueries({ queries }, resolved);
+            if (!queries.length)
+                return Object.freeze([]);
+            const eligibility = request.eligibility ?? {};
+            validateEligibility(eligibility);
+            if (request.providerRun)
+                assertProviderRunScope(request.providerRun, request.runtimeContext.runId, request.budget);
+            const budget = request.budget ?? request.providerRun?.budget;
+            const signals = [request.signal, request.providerRun?.signal].filter((item) => !!item);
+            const signal = signals.length ? AbortSignal.any(signals) : undefined;
+            const deadlineAt = Math.min(Date.now() + timeoutMs, request.deadlineAt ?? Infinity, request.providerRun?.deadlineAt ?? Infinity);
+            let context;
+            try {
+                context = structuredClone(request.runtimeContext);
+            }
+            catch {
+                throw new DiscoveryError({ code: "invalid_input", message: "The runtime context cannot be bound to discovery." });
+            }
+            const source = registrySourceFingerprint(registry);
+            const builtContext = await contextBuilder.build({ baseContext: request.runtimeContext, registry,
+                // This context-only sentinel never enters retrieval or provider input.
+                userInput: { text: queries.find(query => query.fragments[0].text.trim())?.fragments[0].text ?? "[empty discovery query]" } });
+            const routeRequest = { ...eligibility, controls: request.controls, registry, builtContext,
+                userInput: { text: queries[0].fragments[0].text } };
+            let engine = lexicalEngine;
+            if (embedding) {
+                if (!budget || !isRecord(budget) || !hasOnlyKeys(budget, ["ledger", "policy"])
+                    || !Number.isSafeInteger(budget.policy?.maxInputTokensPerRun)
+                    || budget.policy.maxInputTokensPerRun < 0)
+                    throw invalid();
+                engine = new CapabilityDiscoverer(resolved, { ranker, embedding: {
+                        client: embedding.client, index: embedding.index, indexLimits: indexLimits, execution: {
+                            budgetPolicy: budget.policy, estimateCost: embedding.estimateCost,
+                            limits: { maxInputTokens: embedding.maxInputTokens,
+                                maxCharactersPerText: embedding.maxCharactersPerText ?? DISCOVERY_STANDARD_PROFILE.maxCharactersPerText,
+                                maxCharactersPerCall: embedding.maxCharactersPerCall ?? DISCOVERY_STANDARD_PROFILE.maxCharactersPerCall,
+                                ...(embedding.maxEstimatedCostPerCall === undefined ? {} : { maxEstimatedCostPerCall: embedding.maxEstimatedCostPerCall }) }
+                        }
+                    } });
+            }
+            const results = await engine.discover({ routeRequest, queries, runId: context.runId, requestId: context.requestId,
+                deadlineAt, signal, budget: budget?.ledger, providerRun: request.providerRun,
+                maxCandidates: Math.min(eligibility.maxCapabilities ?? resolved.limits.maxCandidates, resolved.limits.maxCandidates) });
+            return Object.freeze(results.map((result, index) => {
+                const current = isDeepStrictEqual(context, request.runtimeContext) && isDeepStrictEqual(context, builtContext.runtimeContext);
+                const issued = deepFreeze(exportDiscoveryResult({ ...routeRequest, deadlineAt, signal }, result, source, current).discovery[0]);
+                bindings.set(issued, { source, taskText: queries[index].fragments[0].text, context,
+                    liveContext: request.runtimeContext, eligibility, controls: request.controls, builtContext, signal, deadlineAt, providerRun: request.providerRun });
+                request.providerRun?.record("discovery.end", context.requestId, { queryId: issued.queryId, outcome: issued.status,
+                    candidateCount: issued.candidates.length, reasonCode: issued.diagnostics[0]?.code, corpusFingerprint: issued.corpusFingerprint, indexFingerprint: issued.indexFingerprint,
+                    retrievalPolicyFingerprint: issued.retrievalPolicyFingerprint, eligibilityFingerprint: issued.eligibilityFingerprint });
+                return issued;
+            }));
+        },
+        async select(request) {
+            const invalidInput = () => new DiscoveryError({ code: "invalid_input", message: "Selection requires issued results from one compatible invocation and scope." });
+            if (!isRecord(request) || !hasOnlyKeys(request, ["results", "client", "budget", "maxInputTokens", "maxOutputTokens",
+                "contextByQueryId", "limits", "maxEstimatedCostPerCall", "estimateCost", "signal", "deadlineAt", "providerRun"])
+                || !Array.isArray(request.results) || request.signal !== undefined && !(request.signal instanceof AbortSignal)
+                || request.deadlineAt !== undefined && !Number.isFinite(request.deadlineAt)
+                || request.contextByQueryId !== undefined && !isRecord(request.contextByQueryId))
+                throw invalidInput();
+            const limits = resolveSelectionLimits({ ...request.limits, maxInputTokens: request.maxInputTokens, maxOutputTokens: request.maxOutputTokens });
+            if (request.limits !== undefined && (!isRecord(request.limits) || !hasOnlyKeys(request.limits, ["maxTasks", "maxInputCharacters", "maxAttempts"])))
+                throw invalidInput();
+            if (request.results.length > SELECTION_HARD_LIMITS.maxTasks)
+                throw new DiscoveryError({ code: "input_limit_exceeded", message: "The selection batch exceeds the hard task limit." });
+            const records = Array.from(request.results, result => { const record = bindings.get(result); if (!record)
+                throw invalidInput(); return record; });
+            const queryIds = new Set(request.results.map(result => result.queryId));
+            if (queryIds.size !== request.results.length || Reflect.ownKeys(request.contextByQueryId ?? {}).some(id => typeof id !== "string" || !queryIds.has(id)))
+                throw invalidInput();
+            const projections = Object.getOwnPropertyDescriptors(request.contextByQueryId ?? {});
+            if (Object.values(projections).some(property => !property.enumerable || !("value" in property)))
+                throw invalidInput();
+            if (!records.length)
+                return deepFreeze({ discovery: [], outcomes: [], diagnostics: [], usage: aggregateDiscoveryUsage([], 0) });
+            const first = records[0];
+            if (records.some(record => !isDeepStrictEqual(record.context, first.context) || !isDeepStrictEqual(record.eligibility, first.eligibility)
+                || record.controls !== first.controls || record.providerRun !== first.providerRun))
+                throw invalidInput();
+            const providerRun = request.providerRun ?? first.providerRun;
+            if (request.providerRun && first.providerRun && request.providerRun !== first.providerRun)
+                throw invalidInput();
+            if (providerRun)
+                assertProviderRunScope(providerRun, first.context.runId, request.budget);
+            const budget = request.budget ?? providerRun?.budget;
+            if (!budget || !isRecord(budget) || !hasOnlyKeys(budget, ["ledger", "policy"]))
+                throw invalidInput();
+            const signals = [request.signal, providerRun?.signal, ...records.map(record => record.signal)].filter((signal) => signal !== undefined);
+            const signal = signals.length ? AbortSignal.any(signals) : undefined;
+            const deadlineAt = Math.min(request.deadlineAt ?? Infinity, providerRun?.deadlineAt ?? Infinity, ...records.map(record => record.deadlineAt));
+            const model = structuredClone(request.client.configuration), mock = request.client.mock, transportVersion = request.client.transportVersion;
+            let projectedContext;
+            try {
+                projectedContext = boundedJsonSnapshot(request.contextByQueryId ?? {}, SELECTION_HARD_LIMITS.maxInputCharacters * 4);
+            }
+            catch { /* The selector returns a bounded invalid-input outcome without reading accessors. */ }
+            const originalResults = [...request.results];
+            const current = () => records.every(record => isDeepStrictEqual(record.context, record.liveContext))
+                && isDeepStrictEqual(model, request.client.configuration) && mock === request.client.mock && transportVersion === request.client.transportVersion
+                && isDeepStrictEqual(projectedContext, request.contextByQueryId ?? {});
+            const batch = await new ModelCapabilitySelector().select({
+                tasks: request.results.map((result, index) => ({ queryId: result.queryId, requestText: records[index].taskText,
+                    ...(Object.hasOwn(projections, result.queryId) ? { context: projections[result.queryId].value } : {}), discovery: result })),
+                registry, routeRequest: { ...first.eligibility, controls: first.controls, registry, builtContext: first.builtContext,
+                    userInput: { text: first.taskText } }, runId: first.context.runId, requestId: first.context.requestId,
+                deadlineAt, signal, providerRun,
+                client: request.client, budget: budget.ledger, budgetPolicy: budget.policy, limits,
+                maxEstimatedCostPerCall: request.maxEstimatedCostPerCall, estimateCost: request.estimateCost,
+                isCurrent: current
+            });
+            batches.set(batch, { results: originalResults, current, deadlineAt, signal, providerRun });
+            providerRun?.record("selection.end", first.context.requestId, { taskCount: batch.outcomes.length, reasonCode: batch.diagnostics[0]?.code, outcome: batch.diagnostics.length ? "unavailable" : "completed" });
+            return batch;
+        },
+        routerFor(value, queryId) {
+            const batch = queryId === undefined ? undefined : value;
+            const selectionBinding = batch && batches.get(batch);
+            if (batch && !selectionBinding)
+                throw new DiscoveryError({ code: "invalid_input", message: "The selection batch was not issued by this facade." });
+            const result = batch ? selectionBinding.results.find(result => result.queryId === queryId) : value;
+            const binding = result && bindings.get(result);
+            if (!binding)
+                throw new DiscoveryError({ code: "invalid_input", message: "The result was not issued by this discovery instance." });
+            const routeWithDiagnostics = (request) => {
+                validateRouterLimit(request.maxCapabilities);
+                // A runner may omit search filters, but may never replace them with broader ones.
+                let current = request.registry === registry && (selectionBinding?.current() ?? true) && isDeepStrictEqual(binding.context, request.builtContext.runtimeContext)
+                    && isDeepStrictEqual(binding.context, binding.liveContext) && request.userInput.text === binding.taskText
+                    && (!binding.controls || !request.controls || request.controls === binding.controls)
+                    && (!request.providerRun || request.providerRun === (selectionBinding?.providerRun ?? binding.providerRun));
+                for (const key of eligibilityKeys) {
+                    if (key !== "maxCapabilities" && request[key] !== undefined && binding.eligibility[key] !== undefined
+                        && !isDeepStrictEqual(request[key], binding.eligibility[key]))
+                        current = false;
+                }
+                const limit = Math.min(request.maxCapabilities ?? 20, binding.eligibility.maxCapabilities ?? 20);
+                const signals = [request.signal, selectionBinding?.signal ?? binding.signal].filter((item) => !!item);
+                const routeRequest = { ...request, maxCapabilities: limit,
+                    controls: request.controls ?? binding.controls, signal: signals.length ? AbortSignal.any(signals) : undefined,
+                    deadlineAt: Math.min(request.deadlineAt ?? Infinity, selectionBinding?.deadlineAt ?? binding.deadlineAt) };
+                for (const key of eligibilityKeys) {
+                    if (key !== "maxCapabilities" && request[key] === undefined)
+                        Object.assign(routeRequest, { [key]: binding.eligibility[key] });
+                }
+                return batch ? exportSelectedResult(routeRequest, result, batch, binding.source, current)
+                    : exportDiscoveryResult(routeRequest, result, binding.source, current);
+            };
+            return Object.freeze({ providerRun: selectionBinding?.providerRun ?? binding.providerRun, routeWithDiagnostics, route: (request) => routeWithDiagnostics(request).slice,
+                revalidate: (request) => routeWithDiagnostics(request).slice });
+        }
+    });
+}

package/dist/discovery/fingerprint.d.ts

@@ -0,0 +1,71 @@
+import type { JsonObject } from "../types.js";
+import type { CapabilityCandidateCard, DiscoveryConfiguration, EmbeddingConfiguration, ProviderModelConfiguration, SelectionLimits } from "./types.js";
+export interface CapabilityVersionBinding {
+    capabilityId: string;
+    capabilityVersion: string;
+}
+export interface DiscoveryFingerprintPayloads {
+    registry_source: {
+        capabilities: readonly (CapabilityVersionBinding & {
+            sourceContentHash: string;
+        })[];
+    };
+    corpus: {
+        registrySourceFingerprint: string;
+        projectionVersion: string;
+        projectionConfiguration: JsonObject;
+        documents: readonly (CapabilityVersionBinding & {
+            documentHash: string;
+        })[];
+    };
+    embedding_configuration: EmbeddingConfiguration;
+    index: {
+        schemaVersion: "1.0";
+        projectionVersion: string;
+        mock: boolean;
+        registrySourceFingerprint: string;
+        corpusFingerprint: string;
+        embedding: EmbeddingConfiguration;
+        embeddingConfigurationFingerprint: string;
+        vectorDimension: number;
+        entries: readonly (CapabilityVersionBinding & {
+            documentHash: string;
+            vectorHash: string;
+        })[];
+    };
+    eligibility: {
+        capabilities: readonly (CapabilityVersionBinding & {
+            exposedOperations: readonly ("select" | "prepare")[];
+        })[];
+        /** Only explicit, nonsecret routing policy belongs in this projection. */
+        policy: JsonObject;
+    };
+    retrieval_policy: {
+        tokenizerVersion: string;
+        rankerVersion: string;
+        configuration: DiscoveryConfiguration;
+    };
+    candidate_cards: {
+        projectionVersion: string;
+        cards: readonly (Pick<CapabilityCandidateCard, "capabilityId" | "capabilityVersion"> & {
+            cardHash: string;
+        })[];
+    };
+    selector: {
+        transportVersion?: string;
+        promptVersion: string;
+        cardProjectionVersion: string;
+        outputSchemaVersion: string;
+        model: ProviderModelConfiguration;
+        mock: boolean;
+        limits: SelectionLimits;
+        maxEstimatedCostPerCall?: number;
+    };
+}
+export type DiscoveryFingerprintKind = keyof DiscoveryFingerprintPayloads;
+/** Strict JSON serialization with ordinal object-key order and unchanged arrays. */
+export declare function canonicalizeDiscoveryValue(value: unknown): string;
+/** Content digest for a source manifest or an explicitly projected retrieval document. */
+export declare function hashDiscoveryContent(value: unknown): string;
+export declare function fingerprintDiscoveryValue<K extends DiscoveryFingerprintKind>(kind: K, payload: DiscoveryFingerprintPayloads[K]): string;
+//# sourceMappingURL=fingerprint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fingerprint.d.ts","sourceRoot":"","sources":["../../src/discovery/fingerprint.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EACV,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,EACtB,0BAA0B,EAC1B,eAAe,EAChB,MAAM,YAAY,CAAC;AAIpB,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,4BAA4B;IAC3C,eAAe,EAAE;QACf,YAAY,EAAE,SAAS,CAAC,wBAAwB,GAAG;YAAE,iBAAiB,EAAE,MAAM,CAAA;SAAE,CAAC,EAAE,CAAC;KACrF,CAAC;IACF,MAAM,EAAE;QACN,yBAAyB,EAAE,MAAM,CAAC;QAClC,iBAAiB,EAAE,MAAM,CAAC;QAC1B,uBAAuB,EAAE,UAAU,CAAC;QACpC,SAAS,EAAE,SAAS,CAAC,wBAAwB,GAAG;YAAE,YAAY,EAAE,MAAM,CAAA;SAAE,CAAC,EAAE,CAAC;KAC7E,CAAC;IACF,uBAAuB,EAAE,sBAAsB,CAAC;IAChD,KAAK,EAAE;QACL,aAAa,EAAE,KAAK,CAAC;QACrB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,IAAI,EAAE,OAAO,CAAC;QACd,yBAAyB,EAAE,MAAM,CAAC;QAClC,iBAAiB,EAAE,MAAM,CAAC;QAC1B,SAAS,EAAE,sBAAsB,CAAC;QAClC,iCAAiC,EAAE,MAAM,CAAC;QAC1C,eAAe,EAAE,MAAM,CAAC;QACxB,OAAO,EAAE,SAAS,CAAC,wBAAwB,GAAG;YAAE,YAAY,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAC,EAAE,CAAC;KAC/F,CAAC;IACF,WAAW,EAAE;QACX,YAAY,EAAE,SAAS,CAAC,wBAAwB,GAAG;YAAE,iBAAiB,EAAE,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,EAAE,CAAA;SAAE,CAAC,EAAE,CAAC;QAC/G,0EAA0E;QAC1E,MAAM,EAAE,UAAU,CAAC;KACpB,CAAC;IACF,gBAAgB,EAAE;QAChB,gBAAgB,EAAE,MAAM,CAAC;QACzB,aAAa,EAAE,MAAM,CAAC;QACtB,aAAa,EAAE,sBAAsB,CAAC;KACvC,CAAC;IACF,eAAe,EAAE;QACf,iBAAiB,EAAE,MAAM,CAAC;QAC1B,KAAK,EAAE,SAAS,CAAC,IAAI,CAAC,uBAAuB,EAAE,cAAc,GAAG,mBAAmB,CAAC,GAAG;YAAE,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAC,EAAE,CAAC;KAChH,CAAC;IACF,QAAQ,EAAE;QACR,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,aAAa,EAAE,MAAM,CAAC;QACtB,qBAAqB,EAAE,MAAM,CAAC;QAC9B,mBAAmB,EAAE,MAAM,CAAC;QAC5B,KAAK,EAAE,0BAA0B,CAAC;QAClC,IAAI,EAAE,OAAO,CAAC;QACd,MAAM,EAAE,eAAe,CAAC;QACxB,uBAAuB,CAAC,EAAE,MAAM,CAAC;KAClC,CAAC;CACH;AAED,MAAM,MAAM,wBAAwB,GAAG,MAAM,4BAA4B,CAAC;AAE1E,oFAAoF;AACpF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEjE;AAED,0FAA0F;AAC1F,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE3D;AAED,wBAAgB,yBAAyB,CAAC,CAAC,SAAS,wBAAwB,EAC1E,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,4BAA4B,CAAC,CAAC,CAAC,GACvC,MAAM,CAMR"}

package/dist/discovery/fingerprint.js

@@ -0,0 +1,67 @@
+import { createHash } from "node:crypto";
+import { DiscoveryError } from "./diagnostics.js";
+import { DISCOVERY_BINDING_VERSIONS } from "./versions.js";
+/** Strict JSON serialization with ordinal object-key order and unchanged arrays. */
+export function canonicalizeDiscoveryValue(value) {
+    return serialize(value, new Set());
+}
+/** Content digest for a source manifest or an explicitly projected retrieval document. */
+export function hashDiscoveryContent(value) {
+    return "sha256:" + createHash("sha256").update(canonicalizeDiscoveryValue(value)).digest("hex");
+}
+export function fingerprintDiscoveryValue(kind, payload) {
+    if (!Object.prototype.hasOwnProperty.call(DISCOVERY_BINDING_VERSIONS, kind)) {
+        throw invalidPayload();
+    }
+    const envelope = { kind, version: DISCOVERY_BINDING_VERSIONS[kind], payload };
+    return "sha256:" + createHash("sha256").update(canonicalizeDiscoveryValue(envelope)).digest("hex");
+}
+function serialize(value, ancestors) {
+    if (value === null || typeof value === "string" || typeof value === "boolean") {
+        return JSON.stringify(value);
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return JSON.stringify(value);
+    }
+    if (typeof value !== "object" || value === null || ancestors.has(value)) {
+        throw invalidPayload();
+    }
+    const prototype = Object.getPrototypeOf(value);
+    const array = Array.isArray(value);
+    if ((!array && prototype !== Object.prototype && prototype !== null) || Object.getOwnPropertySymbols(value).length) {
+        throw invalidPayload();
+    }
+    ancestors.add(value);
+    try {
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        if (array) {
+            const elements = [];
+            if (Object.keys(descriptors).length !== value.length + 1)
+                throw invalidPayload();
+            for (let index = 0; index < value.length; index += 1) {
+                const descriptor = descriptors[String(index)];
+                if (!descriptor || !("value" in descriptor) || !descriptor.enumerable)
+                    throw invalidPayload();
+                elements.push(serialize(descriptor.value, ancestors));
+            }
+            return "[" + elements.join(",") + "]";
+        }
+        const entries = [];
+        for (const key of Object.keys(descriptors).sort()) {
+            const descriptor = descriptors[key];
+            if (!("value" in descriptor) || !descriptor.enumerable)
+                throw invalidPayload();
+            entries.push(JSON.stringify(key) + ":" + serialize(descriptor.value, ancestors));
+        }
+        return "{" + entries.join(",") + "}";
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function invalidPayload() {
+    return new DiscoveryError({
+        code: "invalid_fingerprint_payload",
+        message: "Discovery fingerprints require finite JSON data without accessors or cycles."
+    });
+}

package/dist/discovery/index-builder.d.ts

@@ -0,0 +1,3 @@
+import type { CapabilityEmbeddingIndexBuildRequest, CapabilityEmbeddingIndexBuildResult } from "./embedding-types.js";
+export declare function buildCapabilityEmbeddingIndex(request: CapabilityEmbeddingIndexBuildRequest): Promise<CapabilityEmbeddingIndexBuildResult>;
+//# sourceMappingURL=index-builder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-builder.d.ts","sourceRoot":"","sources":["../../src/discovery/index-builder.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,oCAAoC,EAAE,mCAAmC,EAAE,MAAM,sBAAsB,CAAC;AAStH,wBAAsB,6BAA6B,CAAC,OAAO,EAAE,oCAAoC,GAAG,OAAO,CAAC,mCAAmC,CAAC,CAmE/I"}

package/dist/discovery/index-builder.js

@@ -0,0 +1,129 @@
+import { performance } from "node:perf_hooks";
+import { CAPABILITY_CORPUS_PROJECTION_VERSION, ordinalCompare } from "./corpus.js";
+import { hasOnlyKeys, isRecord } from "./configuration.js";
+import { DiscoveryError } from "./diagnostics.js";
+import { checkEmbeddingTexts, inputLimit, invalidEmbeddingConfiguration, positiveInteger, resolveEmbeddingConfiguration, resolveEmbeddingExecution, resolveIndexLimits } from "./embedding-configuration.js";
+import { runEmbeddingAttempt, stopReason, validateProviderInvocation } from "./embeddings.js";
+import { canonicalizeDiscoveryValue, fingerprintDiscoveryValue, hashDiscoveryContent } from "./fingerprint.js";
+import { embeddingIndexFingerprint, validateCapabilityEmbeddingIndex } from "./index-validation.js";
+import { boundedJsonSnapshot, deepFreeze } from "./json-snapshot.js";
+import { LEXICAL_TOKENIZER_VERSION, tokenizeDiscoveryText } from "./lexical.js";
+import { aggregateDiscoveryUsage } from "./usage.js";
+export async function buildCapabilityEmbeddingIndex(request) {
+    validateProviderInvocation(request);
+    const started = performance.now();
+    const limits = resolveIndexLimits(request.limits);
+    const execution = resolveEmbeddingExecution(request.execution);
+    const configuration = resolveEmbeddingConfiguration(request.client.configuration);
+    if (typeof request.client.mock !== "boolean" || typeof request.client.embed !== "function"
+        || !positiveInteger(request.batchSize) || !positiveInteger(request.maxProviderCalls))
+        throw invalidEmbeddingConfiguration();
+    const corpus = snapshotCorpus(request.corpus, limits.maxEntries, limits.maxArtifactBytes, execution.limits.maxCharactersPerText);
+    const stages = [];
+    const failed = (code, message) => ({
+        status: code === "cancelled" || code === "deadline_exceeded" ? "cancelled" : "unavailable",
+        index: null, usage: aggregateDiscoveryUsage(stages, performance.now() - started), diagnostics: [{ code, message }]
+    });
+    if (!corpus.documents.length)
+        return failed("invalid_input", "An empty corpus cannot produce an embedding index.");
+    const calls = Math.ceil(corpus.documents.length / request.batchSize);
+    if (calls > request.maxProviderCalls || calls > execution.budgetPolicy.maxProviderCallsPerRun)
+        throw inputLimit();
+    if (configuration.dimensions !== undefined && configuration.dimensions > limits.maxVectorDimension)
+        throw inputLimit();
+    for (let start = 0; start < corpus.documents.length; start += request.batchSize) {
+        checkEmbeddingTexts(corpus.documents.slice(start, start + request.batchSize).map(document => document.text), execution.limits);
+    }
+    const base = {
+        schemaVersion: "1.0", projectionVersion: corpus.projectionVersion,
+        registrySourceFingerprint: corpus.registrySourceFingerprint, corpusFingerprint: corpus.corpusFingerprint,
+        embedding: configuration, embeddingConfigurationFingerprint: fingerprintDiscoveryValue("embedding_configuration", configuration),
+        mock: request.client.mock, vectorDimension: configuration.dimensions ?? limits.maxVectorDimension,
+        builtAt: new Date().toISOString(), indexFingerprint: "sha256:" + "0".repeat(64),
+        entries: corpus.documents.map(document => ({
+            capabilityId: document.capabilityId, capabilityVersion: document.capabilityVersion,
+            documentHash: document.documentHash, vector: [], vectorHash: "sha256:" + "0".repeat(64)
+        }))
+    };
+    // Conservative complete-artifact bound: JSON finite-number spelling takes at most 25 bytes plus a comma.
+    if (Buffer.byteLength(canonicalizeDiscoveryValue(base))
+        + corpus.documents.length * (base.vectorDimension * 26 + 1) > limits.maxArtifactBytes)
+        throw inputLimit();
+    let dimension = configuration.dimensions;
+    const entries = [];
+    for (let start = 0; start < corpus.documents.length; start += request.batchSize) {
+        const stopped = stopReason(request);
+        if (stopped)
+            return failed(stopped, "The embedding index build was cancelled or its deadline elapsed.");
+        const documents = corpus.documents.slice(start, start + request.batchSize);
+        const result = await runEmbeddingAttempt({
+            ...request, configuration, mock: base.mock, execution, texts: documents.map(document => document.text),
+            stage: "embedding_build", maxVectorDimension: limits.maxVectorDimension, expectedDimension: dimension
+        });
+        stages.push(...result.usage.stages);
+        if (result.status !== "completed")
+            return {
+                status: result.status, index: null, usage: aggregateDiscoveryUsage(stages, performance.now() - started),
+                diagnostics: result.diagnostics
+            };
+        dimension = result.vectorDimension;
+        for (const [offset, document] of documents.entries()) {
+            const vector = [...result.vectors[offset]];
+            entries.push({
+                capabilityId: document.capabilityId, capabilityVersion: document.capabilityVersion,
+                documentHash: document.documentHash, vector, vectorHash: hashDiscoveryContent(vector)
+            });
+        }
+    }
+    const stopped = stopReason(request);
+    if (stopped)
+        return failed(stopped, "The embedding index build was cancelled or its deadline elapsed.");
+    const artifact = { ...base, vectorDimension: dimension, entries };
+    artifact.indexFingerprint = embeddingIndexFingerprint(artifact);
+    const validated = validateCapabilityEmbeddingIndex(artifact, { corpus, configuration, mock: base.mock, limits });
+    if (!validated.valid)
+        return { status: "unavailable", index: null, diagnostics: validated.diagnostics,
+            usage: aggregateDiscoveryUsage(stages, performance.now() - started) };
+    return { status: "built", index: validated.index, diagnostics: [], usage: aggregateDiscoveryUsage(stages, performance.now() - started) };
+}
+function snapshotCorpus(value, maxEntries, maxBytes, maxText) {
+    try {
+        if (!isRecord(value) || !Array.isArray(value.documents) || value.documents.length > maxEntries)
+            throw inputLimit();
+        const corpus = boundedJsonSnapshot(value, Math.min(Number.MAX_SAFE_INTEGER, maxBytes + maxEntries * maxText * 16));
+        if (corpus.schemaVersion !== "1.0" || corpus.projectionVersion !== CAPABILITY_CORPUS_PROJECTION_VERSION
+            || !/^sha256:[a-f0-9]{64}$/.test(corpus.registrySourceFingerprint))
+            throw new Error();
+        const seen = new Set();
+        for (const document of corpus.documents) {
+            if (!isRecord(document) || !hasOnlyKeys(document, ["capabilityId", "capabilityVersion", "riskTier", "name", "summary", "aliases", "text", "tokens", "documentHash"])
+                || typeof document.capabilityId !== "string" || seen.has(document.capabilityId)
+                || typeof document.name !== "string" || typeof document.summary !== "string"
+                || !Array.isArray(document.aliases) || !document.aliases.every(alias => typeof alias === "string")
+                || !["none", "low", "medium", "high", "critical"].includes(document.riskTier))
+                throw new Error();
+            seen.add(document.capabilityId);
+            const { capabilityId, capabilityVersion, riskTier, name, summary, aliases } = document;
+            const fields = [capabilityId, name, summary, ...aliases];
+            if (document.text.length > maxText)
+                throw inputLimit();
+            if (document.text !== fields.join("\n")
+                || document.documentHash !== hashDiscoveryContent({ capabilityId, capabilityVersion, riskTier, name, summary, aliases })
+                || canonicalizeDiscoveryValue(document.tokens) !== canonicalizeDiscoveryValue([...new Set(fields.flatMap(tokenizeDiscoveryText))]))
+                throw new Error();
+        }
+        const documents = [...corpus.documents].sort((a, b) => ordinalCompare(a.capabilityId, b.capabilityId));
+        if (corpus.corpusFingerprint !== fingerprintDiscoveryValue("corpus", {
+            registrySourceFingerprint: corpus.registrySourceFingerprint, projectionVersion: corpus.projectionVersion,
+            projectionConfiguration: { tokenizerVersion: LEXICAL_TOKENIZER_VERSION },
+            documents: documents.map(({ capabilityId, capabilityVersion, documentHash }) => ({ capabilityId, capabilityVersion, documentHash }))
+        }))
+            throw new Error();
+        return deepFreeze({ ...corpus, documents });
+    }
+    catch (error) {
+        if (error instanceof DiscoveryError && error.code === "input_limit_exceeded")
+            throw error;
+        throw new DiscoveryError({ code: "invalid_input", message: "An index build requires a current approved-field corpus snapshot." });
+    }
+}

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

@@ -0,0 +1,12 @@
+import type { CapabilityEmbeddingIndexStore, EmbeddingIndexExpected, EmbeddingIndexValidationResult } from "./embedding-types.js";
+import { type DiscoveryFingerprintPayloads } from "./fingerprint.js";
+export declare function embeddingIndexFingerprint(index: DiscoveryFingerprintPayloads["index"]): string;
+export declare function validateCapabilityEmbeddingIndex(value: unknown, expected: EmbeddingIndexExpected): EmbeddingIndexValidationResult;
+export declare function serializeCapabilityEmbeddingIndex(value: unknown, expected: EmbeddingIndexExpected): string;
+export declare function parseCapabilityEmbeddingIndex(text: string, expected: EmbeddingIndexExpected): EmbeddingIndexValidationResult;
+export declare function loadCapabilityEmbeddingIndex(store: CapabilityEmbeddingIndexStore, key: string, expected: EmbeddingIndexExpected): Promise<EmbeddingIndexValidationResult>;
+export declare function publishCapabilityEmbeddingIndex(store: CapabilityEmbeddingIndexStore, key: string, value: unknown, expected: EmbeddingIndexExpected): Promise<{
+    published: boolean;
+    diagnostics: readonly import("./diagnostics.js").DiscoveryDiagnostic[];
+}>;
+//# sourceMappingURL=index-validation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index-validation.d.ts","sourceRoot":"","sources":["../../src/discovery/index-validation.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACgB,6BAA6B,EAAE,sBAAsB,EAAE,8BAA8B,EAChH,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAA+E,KAAK,4BAA4B,EAAE,MAAM,kBAAkB,CAAC;AAOlJ,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,4BAA4B,CAAC,OAAO,CAAC,GAAG,MAAM,CAS9F;AAED,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,sBAAsB,GAAG,8BAA8B,CAkDjI;AAED,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,sBAAsB,GAAG,MAAM,CAI1G;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,sBAAsB,GAAG,8BAA8B,CAQ5H;AAED,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,6BAA6B,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,sBAAsB,GAClF,OAAO,CAAC,8BAA8B,CAAC,CAOzC;AAED,wBAAsB,+BAA+B,CACnD,KAAK,EAAE,6BAA6B,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,sBAAsB,GAClG,OAAO,CAAC;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,WAAW,EAAE,SAAS,OAAO,kBAAkB,EAAE,mBAAmB,EAAE,CAAA;CAAE,CAAC,CASzG"}