ai-capability-framework 1.0.3 → 1.1.0

package/CHANGELOG.md

@@ -4,6 +4,48 @@ All notable public changes to AI Capability Framework are documented here.
 
 ## Unreleased
 
+## 1.1.0 - 2026-10-17
+
+- Fixed the installed CLI's POSIX symlink entrypoint so `npx aicf` runs commands instead
+  of silently returning. Programmatic CLI imports remain side-effect-free.
+
+- Stabilized the recommended lexical/native search-to-tool workflow and its named
+  runtime/provider contracts. Advanced APIs retain their documented maturity; hybrid
+  remains experimental and dedicated selection optional.
+- Made installed-package onboarding primary, with a complete manifest and mock app
+  checked directly from the published documentation in fresh consumers.
+- Corrected obsolete checkout-only guidance and a nonexistent registry-helper import.
+  Retrieval behavior, authorization, approval boundaries and model configuration are
+  unchanged. Frozen qualification evidence is reused without new live trials.
+
+## 1.1.0-rc.1 - 2026-10-17
+
+- Published discovery as release-candidate public, with lexical retrieval and ordinary
+  model tool selection as the recommended default. Dedicated selection is optional.
+- Documented the tested synthetic configuration: both lexical modes qualify after a
+  separately versioned offline wording correction; hybrid remains experimental and
+  opt-in because its incremental-gain gate was not met. See the
+  [qualification report](docs/evals/discovery-qualification.md).
+- Tightened registry-error handling and retained tag-only OIDC publication to next. No
+  model defaults, retrieval scoring or application deployment changed.
+
+- Corrected the synthetic workflow app's planning, terminal dependency states and
+  response grading. Added versioned readiness fixtures, fresh qualification families,
+  and a remaining-budget continuation protocol. These offline changes preserve
+  historical live results and do not qualify a model or change framework defaults.
+
+- Added scoped discovery evaluation reports, corrected versioned domain fixtures, and
+  opt-in live campaign tooling with durable budgets and independent per-mode gates.
+  Default invocation validates offline; synthetic campaign results do not qualify
+  models.
+
+- Added the optional release-candidate discovery subpath with task search, reusable
+  task-bound routers, explicit hybrid retrieval and dedicated selection, shared-run
+  accounting, metadata tracing, and bounded replay. Default routing remains unchanged.
+- Added portable no-key customer-request examples, public discovery schemas, and frozen
+  synthetic evaluation fixtures. Mock integration and offline metrics do not qualify
+  real-model retrieval or selection quality.
+
 ## 1.0.3 - 2026-09-07
 
 - Updated the resolved `fast-uri` dependency to `3.1.7` to address the high-severity

package/README.md

@@ -110,40 +110,23 @@ In plain terms:
 
 ## Try It
 
-Install and validate the public examples:
+Start in a new project:
 
-```bash
-npm install
-npm run validate
-```
-
-Build the CLI and inspect the example registry:
-
-```bash
-npm run build
-node dist/cli.js inspect examples
+```sh
+npm init -y
+npm install ai-capability-framework
+node node_modules/ai-capability-framework/examples/12-capability-discovery-selection/run-customer-mock.mjs
 ```
 
-Export OpenAI Responses function tools without calling a model:
-
-```bash
-node dist/cli.js openai-tools examples --context examples/support/openai/context.support_agent.json
-```
+The mock flow reads a ticket, carries its order ID into refund preparation, and returns
+a preview awaiting approval. It exposes no commit and makes no real provider calls. No
+repository checkout, framework build or optional provider SDK is required.
 
-Run the public mock runtime flow:
-
-```bash
-node examples/runtime-support-billing/run-mock.mjs
-```
-
-Run deterministic evals:
-
-```bash
-node dist/cli.js eval examples --results examples/eval-results/public.results.passing.json
-```
-
-For expected output excerpts and what each command proves, use
-[Start here](docs/start-here.md).
+Follow the
+[complete first-app walkthrough](docs/getting-started/provider-neutral-quickstart.md) to
+author a capability, load a registry, register a handler and use the stable
+lexical/native workflow. [Repository development](docs/development.md) has separate
+build and validation commands.
 
 ## Documentation Map
 
@@ -297,3 +280,28 @@ certification is documented in
 ## License
 
 MIT
+
+## Find capabilities for a task
+
+Install the stable framework:
+
+```sh
+npm install ai-capability-framework
+```
+
+Lexical retrieval with the ordinary model/tool loop is the recommended default. The
+[qualification report](docs/evals/discovery-qualification.md) records the tested lexical
+results and the unmet hybrid incremental-gain gate. Hybrid remains experimental and
+opt-in; dedicated selection remains optional.
+
+Use the [stable lexical/native workflow](docs/api/stable-workflow.md) and optional
+[discovery API](docs/discovery.md) when your application AI decomposes a customer
+request into tasks. Search each ready task and pass its result-bound router to the
+ordinary model/tool loop. Lexical search needs only a registry, task IDs/text, and
+existing runtime context. Hybrid retrieval and dedicated selection are optional and
+require caller-supplied model access and budgets.
+
+Run the
+[complete customer-request example](examples/12-capability-discovery-selection/README.md)
+with deterministic mocks and no provider key. Retrieval scores never authorize execution
+or guarantee a suitable first candidate.

package/ROADMAP.md

@@ -24,3 +24,17 @@ signing implementation.
 Future work should be driven by real adopter feedback and should preserve the same
 architecture: AICF owns capability safety contracts and host applications own production
 systems, credentials, side effects, and deployment.
+
+## Capability Discovery
+
+The stable lexical/native workflow supports application-produced tasks, eligible
+shortlists, and ordinary model tool selection. Hybrid retrieval and dedicated selection
+remain explicit. No-key examples, a frozen synthetic dataset, and packed consumer checks
+cover integration. The tested synthetic configuration qualifies both lexical modes after
+an offline wording correction. Lexical/native is recommended; hybrid remains
+experimental because incremental benefit was not qualified. See the
+[qualification report](docs/evals/discovery-qualification.md). Application-specific
+qualification and adoption remain separate from framework publication. Normal npm
+installation includes the stable workflow; advanced features retain their own maturity
+labels. The active framework roadmap is complete when installed-package usability and
+verified stable publication pass; application migrations are outside its scope.

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAuGA,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC7C,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;CAC9C;AA4BD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsRzF"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAwGA,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC7C,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;CAC9C;AA4BD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+SzF"}

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import YAML from "yaml";
@@ -91,6 +92,31 @@ export async function runCli(argv, options = {}) {
     const validation = validateManifests(loadResult.manifests);
     const fixtureValidation = validatePublicFixtures(loadResult.fixtures);
     const errors = [...loadResult.errors, ...validation.errors, ...fixtureValidation.errors];
+    if (!errors.length && loadResult.fixtures.some(fixture => fixture.kind === "discovery_eval_suite" || fixture.kind === "discovery_eval_observations")) {
+        const { validateDiscoveryEvaluationSuite, evaluateCapabilityDiscovery } = await import("./discovery/evaluation.js");
+        const suites = loadResult.fixtures.filter(fixture => fixture.kind === "discovery_eval_suite");
+        for (const fixture of suites) {
+            for (const diagnostic of validateDiscoveryEvaluationSuite(fixture.fixture)) {
+                errors.push({ code: "invalid_fixture", message: diagnostic.code, path: fixture.path, id: diagnostic.caseId });
+            }
+        }
+        for (const fixture of loadResult.fixtures.filter(fixture => fixture.kind === "discovery_eval_observations")) {
+            const observations = fixture.fixture;
+            const matches = suites.filter(candidate => candidate.fixture.id === observations.suite_id);
+            if (matches.length !== 1) {
+                errors.push({ code: "invalid_fixture", message: "discovery_evaluation_suite_required", path: fixture.path });
+                continue;
+            }
+            const suite = matches[0].fixture;
+            const registry = buildRegistry(suite.capabilities.map(manifest => ({ kind: "capability", manifest,
+                path: `synthetic/${manifest.id}.yaml`, absolutePath: `/synthetic/${manifest.id}.yaml` })));
+            const result = evaluateCapabilityDiscovery({ suite, registry, observations });
+            if (!result.valid)
+                for (const diagnostic of result.diagnostics) {
+                    errors.push({ code: "invalid_fixture", message: diagnostic.code, path: fixture.path, id: diagnostic.caseId });
+                }
+        }
+    }
     if (errors.length > 0) {
         stderr.write(formatDiagnostics(errors));
         return 1;
@@ -2140,5 +2166,10 @@ function isDirectCliRun() {
     if (!invokedPath) {
         return false;
     }
-    return path.resolve(invokedPath) === fileURLToPath(import.meta.url);
+    try {
+        return realpathSync(invokedPath) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
 }

package/dist/discovery/bindings.d.ts

@@ -0,0 +1,7 @@
+import type { CapabilityRouteRequest } from "../runtime/types.js";
+export declare function captureEligibility(request: CapabilityRouteRequest): {
+    fingerprint: string;
+    eligible: import("../types.js").LoadedCapabilityManifest[];
+    excluded: import("../runtime/types.js").RuntimeCapabilitySlice["excluded"];
+};
+//# sourceMappingURL=bindings.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bindings.d.ts","sourceRoot":"","sources":["../../src/discovery/bindings.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAIlE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,sBAAsB;;;;EAoBjE"}

package/dist/discovery/bindings.js

@@ -0,0 +1,24 @@
+import { filterEligibleCapabilities } from "../runtime/eligibility.js";
+import { ordinalCompare } from "./corpus.js";
+import { fingerprintDiscoveryValue } from "./fingerprint.js";
+export function captureEligibility(request) {
+    const result = filterEligibleCapabilities(request);
+    const sorted = (values) => values === undefined ? null : [...new Set(values)].sort(ordinalCompare);
+    return {
+        ...result,
+        fingerprint: fingerprintDiscoveryValue("eligibility", {
+            capabilities: result.eligible.map(({ manifest }) => ({
+                capabilityId: manifest.id, capabilityVersion: manifest.version,
+                exposedOperations: manifest.lifecycle.prepare ? ["select", "prepare"] : ["select"]
+            })).sort((left, right) => ordinalCompare(left.capabilityId, right.capabilityId)),
+            policy: {
+                allowedCapabilityTypes: sorted(request.allowedCapabilityTypes), allowedDomains: sorted(request.allowedDomains),
+                includeCapabilityIds: sorted(request.includeCapabilityIds), excludeCapabilityIds: sorted(request.excludeCapabilityIds),
+                maxRiskTier: request.maxRiskTier ?? request.builtContext.runtimeContext.autonomy.maxRiskTier,
+                includeRestricted: request.includeRestricted ?? false, includeDraft: request.includeDraft ?? false,
+                includeExperimental: request.includeExperimental ?? false, includeDeprecated: request.includeDeprecated ?? false,
+                includeDisabledForTests: request.includeDisabledForTests ?? false
+            }
+        })
+    };
+}

package/dist/discovery/budget.d.ts

@@ -0,0 +1,17 @@
+import type { BudgetPolicy } from "../controls/types.js";
+import type { DiscoveryBudgetLedger } from "./types.js";
+/** A host may supply its own ledger and existing budget policy instead. */
+export interface DiscoveryBudgetScope {
+    ledger: DiscoveryBudgetLedger;
+    policy: BudgetPolicy;
+}
+export interface InMemoryDiscoveryBudgetOptions {
+    runId: string;
+    maxProviderCalls: number;
+    maxInputTokens: number;
+    maxEstimatedCost?: number;
+    maxOutputTokens?: number;
+}
+/** Single-process, single-run accounting. Outstanding and unknown consumption retain allowance. */
+export declare function createInMemoryDiscoveryBudget(options: InMemoryDiscoveryBudgetOptions): DiscoveryBudgetScope;
+//# sourceMappingURL=budget.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/discovery/budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAe,MAAM,sBAAsB,CAAC;AAKtE,OAAO,KAAK,EAAE,qBAAqB,EAA6B,MAAM,YAAY,CAAC;AAGnF,2EAA2E;AAC3E,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,8BAA8B;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,mGAAmG;AACnG,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,8BAA8B,GAAG,oBAAoB,CAmE3G"}

package/dist/discovery/budget.js

@@ -0,0 +1,77 @@
+import { hasOnlyKeys, isRecord, nonblank } from "./configuration.js";
+import { DiscoveryError } from "./diagnostics.js";
+import { nonnegative, positiveInteger } from "./embedding-configuration.js";
+import { stopReason } from "./embeddings.js";
+import { knownUsage } from "./usage.js";
+/** Single-process, single-run accounting. Outstanding and unknown consumption retain allowance. */
+export function createInMemoryDiscoveryBudget(options) {
+    if (!isRecord(options) || !hasOnlyKeys(options, ["runId", "maxProviderCalls", "maxInputTokens", "maxOutputTokens", "maxEstimatedCost"])
+        || !nonblank(options.runId) || !positiveInteger(options.maxProviderCalls) || !positiveInteger(options.maxInputTokens)
+        || options.maxOutputTokens !== undefined && !positiveInteger(options.maxOutputTokens)
+        || options.maxEstimatedCost !== undefined && !nonnegative(options.maxEstimatedCost)) {
+        throw new DiscoveryError({ code: "invalid_configuration", message: "An in-memory budget requires a run ID and positive finite call and input-token limits." });
+    }
+    const runId = options.runId;
+    const policy = Object.freeze({
+        id: "discovery.in-memory.v1", scope: Object.freeze({ type: "global" }), mode: "hard",
+        maxProviderCallsPerRun: options.maxProviderCalls, maxInputTokensPerRun: options.maxInputTokens,
+        ...(options.maxOutputTokens === undefined ? {} : { maxOutputTokensPerRun: options.maxOutputTokens }),
+        ...(options.maxEstimatedCost === undefined ? {} : { maxEstimatedCostPerRun: options.maxEstimatedCost })
+    });
+    const pending = new Map();
+    const charged = { providerCalls: 0, inputTokens: 0, outputTokens: 0, estimatedCost: 0 };
+    const held = { providerCalls: 0, inputTokens: 0, outputTokens: 0, estimatedCost: 0 };
+    let sequence = 0;
+    const ledger = {
+        async reserve(input) {
+            const denied = () => ({ status: "denied", diagnostic: {
+                    code: "budget_denied", message: "The in-memory run budget denied this reservation."
+                } });
+            const usage = input.requestedUsage;
+            if (input.runId !== runId || !nonblank(input.requestId) || !Number.isFinite(input.deadlineAt)
+                || stopReason(input) || !isRecord(usage) || !positiveInteger(usage.providerCalls)
+                || !positiveInteger(usage.inputTokens)
+                || usage.outputTokens !== undefined && (typeof usage.outputTokens !== "number" || !Number.isSafeInteger(usage.outputTokens) || usage.outputTokens < 0)
+                || policy.maxOutputTokensPerRun !== undefined && !["embedding_build", "query_embedding"].includes(input.stage) && !positiveInteger(usage.outputTokens)
+                || usage.estimatedCost !== undefined && !nonnegative(usage.estimatedCost)
+                || policy.maxEstimatedCostPerRun !== undefined && usage.estimatedCost === undefined)
+                return denied();
+            const amounts = { providerCalls: usage.providerCalls, inputTokens: usage.inputTokens, outputTokens: usage.outputTokens ?? 0, estimatedCost: usage.estimatedCost ?? 0 };
+            if (charged.providerCalls + held.providerCalls + amounts.providerCalls > policy.maxProviderCallsPerRun
+                || charged.inputTokens + held.inputTokens + amounts.inputTokens > policy.maxInputTokensPerRun
+                || policy.maxOutputTokensPerRun !== undefined && charged.outputTokens + held.outputTokens + amounts.outputTokens > policy.maxOutputTokensPerRun
+                || policy.maxEstimatedCostPerRun !== undefined
+                    && charged.estimatedCost + held.estimatedCost + amounts.estimatedCost > policy.maxEstimatedCostPerRun)
+                return denied();
+            // No await between checking capacity and recording the reservation.
+            const id = "discovery-reservation-" + ++sequence;
+            pending.set(id, amounts);
+            for (const key of ["providerCalls", "inputTokens", "outputTokens", "estimatedCost"])
+                held[key] += amounts[key];
+            return { status: "reserved", reservationId: id };
+        },
+        async settle(id, result) {
+            const reserved = pending.get(id);
+            if (!reserved || !isRecord(result) || !Number.isSafeInteger(result.providerAttempts) || result.providerAttempts < 0
+                || !Number.isSafeInteger(result.completedResponses) || result.completedResponses < 0
+                || !["completed", "failed", "cancelled", "discarded"].includes(result.outcome)) {
+                throw new DiscoveryError({ code: "accounting_unavailable", message: "The budget settlement is invalid or its reservation was already settled." });
+            }
+            const usage = knownUsage(result.usage);
+            // A completed response establishes an attempt even if a malformed client reports zero.
+            const attempts = Math.max(result.providerAttempts, result.completedResponses);
+            const actual = {
+                providerCalls: attempts,
+                inputTokens: usage.inputTokens ?? (attempts ? reserved.inputTokens : 0),
+                outputTokens: usage.outputTokens ?? (attempts ? reserved.outputTokens : 0),
+                estimatedCost: usage.estimatedCost ?? (attempts ? reserved.estimatedCost : 0)
+            };
+            pending.delete(id);
+            for (const key of ["providerCalls", "inputTokens", "outputTokens", "estimatedCost"]) {
+                held[key] = Math.max(0, held[key] - reserved[key]);
+                charged[key] += actual[key];
+            }
+        }
+    };
+    return Object.freeze({ ledger: Object.freeze(ledger), policy });
+}

package/dist/discovery/configuration.d.ts

@@ -0,0 +1,10 @@
+import type { DiscoveryConfiguration, ResolvedDiscoveryConfiguration, ResolvedLexicalDiscoveryConfiguration } from "./types.js";
+export declare const HYBRID_WEIGHT_TOLERANCE = 1e-12;
+export declare function resolveDiscoveryConfiguration(value: DiscoveryConfiguration): ResolvedDiscoveryConfiguration;
+export declare function lexicalConfiguration(value: ResolvedDiscoveryConfiguration): ResolvedLexicalDiscoveryConfiguration;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function hasOnlyKeys(value: Record<string, unknown>, keys: readonly string[]): boolean;
+export declare function nonblank(value: unknown): value is string;
+export declare function unitScore(value: unknown): value is number;
+export declare function resolveLexicalConfiguration(value: DiscoveryConfiguration): ResolvedLexicalDiscoveryConfiguration;
+//# sourceMappingURL=configuration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../../src/discovery/configuration.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,sBAAsB,EAAE,8BAA8B,EAAE,qCAAqC,EAAE,MAAM,YAAY,CAAC;AAEhI,eAAO,MAAM,uBAAuB,QAAQ,CAAC;AAE7C,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,sBAAsB,GAAG,8BAA8B,CAgB3G;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,8BAA8B,GAAG,qCAAqC,CAGjH;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAGzE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAE5F;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAExD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEzD;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,sBAAsB,GAAG,qCAAqC,CAsBhH"}

package/dist/discovery/configuration.js

@@ -0,0 +1,63 @@
+import { DiscoveryError } from "./diagnostics.js";
+import { DISCOVERY_DEFAULT_LIMITS, DISCOVERY_HARD_LIMITS } from "./versions.js";
+export const HYBRID_WEIGHT_TOLERANCE = 1e-12;
+export function resolveDiscoveryConfiguration(value) {
+    if (isRecord(value) && value.mode === "hybrid") {
+        if (!hasOnlyKeys(value, ["mode", "policyVersion", "limits", "aliasWeight", "minRetrievalScore", "weights", "failurePolicy"])
+            || !isRecord(value.weights) || !hasOnlyKeys(value.weights, ["semantic", "lexical"])
+            || !unitScore(value.weights.semantic) || !unitScore(value.weights.lexical)
+            || Math.abs(value.weights.semantic + value.weights.lexical - 1) > HYBRID_WEIGHT_TOLERANCE
+            || value.failurePolicy !== "unavailable" && value.failurePolicy !== "lexical_fallback") {
+            throw new DiscoveryError({ code: "invalid_configuration", message: "Hybrid discovery requires explicit unit weights and a failure policy." });
+        }
+        const lexical = resolveLexicalConfiguration({
+            mode: "lexical", policyVersion: value.policyVersion,
+            limits: value.limits, aliasWeight: value.aliasWeight, minRetrievalScore: value.minRetrievalScore
+        });
+        return Object.freeze({ ...lexical, mode: "hybrid", weights: Object.freeze({ ...value.weights }), failurePolicy: value.failurePolicy });
+    }
+    return resolveLexicalConfiguration(value);
+}
+export function lexicalConfiguration(value) {
+    return Object.freeze({ mode: "lexical", policyVersion: value.policyVersion, limits: value.limits,
+        aliasWeight: value.aliasWeight, minRetrievalScore: value.minRetrievalScore });
+}
+export function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+}
+export function hasOnlyKeys(value, keys) {
+    return Reflect.ownKeys(value).every((key) => typeof key === "string" && keys.includes(key));
+}
+export function nonblank(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+export function unitScore(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+export function resolveLexicalConfiguration(value) {
+    const invalid = () => new DiscoveryError({
+        code: "invalid_configuration", message: "Discovery requires a valid, explicit lexical configuration."
+    });
+    if (!isRecord(value) || !hasOnlyKeys(value, ["mode", "policyVersion", "limits", "aliasWeight", "minRetrievalScore"])
+        || value.mode !== "lexical" || !nonblank(value.policyVersion))
+        throw invalid();
+    if (value.limits !== undefined && (!isRecord(value.limits)
+        || !hasOnlyKeys(value.limits, Object.keys(DISCOVERY_DEFAULT_LIMITS))))
+        throw invalid();
+    const limits = { ...DISCOVERY_DEFAULT_LIMITS, ...value.limits };
+    for (const key of Object.keys(limits)) {
+        const minimum = key === "aliasDiversitySlots" ? 0 : 1;
+        if (!Number.isInteger(limits[key]) || limits[key] < minimum || limits[key] > DISCOVERY_HARD_LIMITS[key]) {
+            throw invalid();
+        }
+    }
+    if (limits.aliasDiversitySlots >= limits.maxCandidates
+        || (value.aliasWeight !== undefined && !unitScore(value.aliasWeight))
+        || (value.minRetrievalScore !== undefined && !unitScore(value.minRetrievalScore)))
+        throw invalid();
+    return Object.freeze({
+        mode: "lexical", policyVersion: value.policyVersion, limits: Object.freeze(limits),
+        aliasWeight: value.aliasWeight ?? 0, minRetrievalScore: value.minRetrievalScore ?? 0
+    });
+}

package/dist/discovery/corpus.d.ts

@@ -0,0 +1,8 @@
+import type { ManifestRegistry } from "../types.js";
+import type { CapabilitySearchCorpus } from "./types.js";
+export declare const CAPABILITY_CORPUS_PROJECTION_VERSION = "approved-retrieval-fields.v1";
+/** Rechecks definitions and map/list consistency without projecting another corpus. */
+export declare function registrySourceFingerprint(registry: ManifestRegistry): string;
+export declare function buildCapabilitySearchCorpus(registry: ManifestRegistry): CapabilitySearchCorpus;
+export declare function ordinalCompare(left: string, right: string): number;
+//# sourceMappingURL=corpus.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"corpus.d.ts","sourceRoot":"","sources":["../../src/discovery/corpus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAMpD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,eAAO,MAAM,oCAAoC,iCAAiC,CAAC;AAEnF,uFAAuF;AACvF,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAmB5E;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,gBAAgB,GAAG,sBAAsB,CA0B9F;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAElE"}

package/dist/discovery/corpus.js

@@ -0,0 +1,64 @@
+import { validateManifests } from "../validator.js";
+import { DiscoveryError } from "./diagnostics.js";
+import { fingerprintDiscoveryValue, hashDiscoveryContent } from "./fingerprint.js";
+import { tokenizeDiscoveryText, LEXICAL_TOKENIZER_VERSION } from "./lexical.js";
+import { resolveDiscoveryMetadata } from "./metadata.js";
+export const CAPABILITY_CORPUS_PROJECTION_VERSION = "approved-retrieval-fields.v1";
+/** Rechecks definitions and map/list consistency without projecting another corpus. */
+export function registrySourceFingerprint(registry) {
+    try {
+        const ids = new Set();
+        for (const entry of registry.capabilities) {
+            const id = entry.manifest.id;
+            if (entry.kind !== "capability" || ids.has(id) || registry.capabilityById.get(id) !== entry)
+                throw invalidRegistry();
+            ids.add(id);
+        }
+        if (registry.capabilityById.size !== ids.size)
+            throw invalidRegistry();
+        const validation = validateManifests([...registry.capabilities, ...registry.entities, ...registry.evals]);
+        if (!validation.valid)
+            throw invalidRegistry();
+        return fingerprintDiscoveryValue("registry_source", {
+            capabilities: registry.capabilities.map(({ manifest }) => ({
+                capabilityId: manifest.id, capabilityVersion: manifest.version, sourceContentHash: hashDiscoveryContent(manifest)
+            })).sort((left, right) => ordinalCompare(left.capabilityId, right.capabilityId))
+        });
+    }
+    catch {
+        throw invalidRegistry();
+    }
+}
+export function buildCapabilitySearchCorpus(registry) {
+    const source = registrySourceFingerprint(registry);
+    const documents = registry.capabilities.map(({ manifest }) => {
+        const metadata = resolveDiscoveryMetadata(manifest);
+        const content = {
+            capabilityId: manifest.id, capabilityVersion: manifest.version, riskTier: manifest.risk_tier,
+            name: manifest.name, summary: metadata.summary, aliases: [...metadata.aliases]
+        };
+        const fields = [content.capabilityId, content.name, content.summary, ...content.aliases];
+        return Object.freeze({
+            ...content, aliases: Object.freeze(content.aliases), text: fields.join("\n"),
+            tokens: Object.freeze([...new Set(fields.flatMap(tokenizeDiscoveryText))]),
+            documentHash: hashDiscoveryContent(content)
+        });
+    }).sort((left, right) => ordinalCompare(left.capabilityId, right.capabilityId));
+    return Object.freeze({
+        schemaVersion: "1.0", projectionVersion: CAPABILITY_CORPUS_PROJECTION_VERSION,
+        registrySourceFingerprint: source, documents: Object.freeze(documents),
+        corpusFingerprint: fingerprintDiscoveryValue("corpus", {
+            registrySourceFingerprint: source, projectionVersion: CAPABILITY_CORPUS_PROJECTION_VERSION,
+            projectionConfiguration: { tokenizerVersion: LEXICAL_TOKENIZER_VERSION },
+            documents: documents.map(({ capabilityId, capabilityVersion, documentHash }) => ({
+                capabilityId, capabilityVersion, documentHash
+            }))
+        })
+    });
+}
+export function ordinalCompare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function invalidRegistry() {
+    return new DiscoveryError({ code: "invalid_input", message: "Discovery requires a valid, consistent capability registry." });
+}

package/dist/discovery/diagnostics.d.ts

@@ -0,0 +1,15 @@
+export type DiscoveryDiagnosticCode = "invalid_configuration" | "invalid_metadata" | "invalid_input" | "input_limit_exceeded" | "empty_query" | "no_eligible_capabilities" | "no_matching_candidates" | "invalid_ranker_output" | "invalid_index" | "embedding_configuration_mismatch" | "invalid_embedding" | "provider_unavailable" | "invalid_selection_output" | "invalid_selection_input" | "selection_configuration_mismatch" | "stale_binding" | "budget_denied" | "control_denied" | "accounting_unavailable" | "deadline_exceeded" | "cancelled" | "lexical_fallback" | "invalid_fingerprint_payload" | "replay_inputs_unavailable";
+export interface DiscoveryDiagnostic {
+    code: DiscoveryDiagnosticCode;
+    message: string;
+    queryId?: string;
+    capabilityId?: string;
+    path?: string;
+}
+/** Configuration/contract errors only; operational outcomes use result statuses. */
+export declare class DiscoveryError extends Error {
+    readonly code: DiscoveryDiagnosticCode;
+    readonly diagnostic: Readonly<DiscoveryDiagnostic>;
+    constructor(diagnostic: DiscoveryDiagnostic);
+}
+//# sourceMappingURL=diagnostics.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/discovery/diagnostics.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,uBAAuB,GAC/B,uBAAuB,GACvB,kBAAkB,GAClB,eAAe,GACf,sBAAsB,GACtB,aAAa,GACb,0BAA0B,GAC1B,wBAAwB,GACxB,uBAAuB,GACvB,eAAe,GACf,kCAAkC,GAClC,mBAAmB,GACnB,sBAAsB,GACtB,0BAA0B,GAC1B,yBAAyB,GACzB,kCAAkC,GAClC,eAAe,GACf,eAAe,GACf,gBAAgB,GAChB,wBAAwB,GACxB,mBAAmB,GACnB,WAAW,GACX,kBAAkB,GAClB,6BAA6B,GAC7B,2BAA2B,CAAC;AAEhC,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,uBAAuB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,oFAAoF;AACpF,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,mBAAmB,CAAC,CAAC;gBAEvC,UAAU,EAAE,mBAAmB;CAM5C"}

package/dist/discovery/diagnostics.js

@@ -0,0 +1,11 @@
+/** Configuration/contract errors only; operational outcomes use result statuses. */
+export class DiscoveryError extends Error {
+    code;
+    diagnostic;
+    constructor(diagnostic) {
+        super(diagnostic.message);
+        this.name = "DiscoveryError";
+        this.code = diagnostic.code;
+        this.diagnostic = Object.freeze({ ...diagnostic });
+    }
+}

package/dist/discovery/discoverer.d.ts

@@ -0,0 +1,23 @@
+import { type DiscoveryDiagnosticCode } from "./diagnostics.js";
+import type { HybridDiscoveryDependencies } from "./embedding-types.js";
+import type { CapabilityDiscoveryRequest, CapabilityDiscoveryResult, CapabilityLexicalRanker, DiscoveryConfiguration, DiscoveryQuery, DiscoveryUsage, ResolvedDiscoveryConfiguration } from "./types.js";
+export { HYBRID_RANKER_VERSION, QUERY_EMBEDDING_PROJECTION_VERSION } from "./retrieval-policy.js";
+export interface CapabilityDiscovererOptions {
+    ranker?: CapabilityLexicalRanker;
+    embedding?: HybridDiscoveryDependencies;
+}
+export declare class CapabilityDiscoverer {
+    readonly configuration: ResolvedDiscoveryConfiguration;
+    private readonly ranker?;
+    private readonly embedding?;
+    constructor(configuration: DiscoveryConfiguration, options?: CapabilityDiscovererOptions);
+    discover(request: CapabilityDiscoveryRequest): Promise<readonly CapabilityDiscoveryResult[]>;
+    private invocationConfiguration;
+}
+export declare function validateQueries(request: Pick<CapabilityDiscoveryRequest, "queries">, configuration: ResolvedDiscoveryConfiguration): readonly DiscoveryQuery[];
+export declare function discoveryStopReason(request: {
+    signal?: AbortSignal;
+    deadlineAt?: number;
+}): DiscoveryDiagnosticCode | undefined;
+export declare function zeroDiscoveryUsage(elapsedMs: number): DiscoveryUsage;
+//# sourceMappingURL=discoverer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discoverer.d.ts","sourceRoot":"","sources":["../../src/discovery/discoverer.ts"],"names":[],"mappings":"AAMA,OAAO,EAAkB,KAAK,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAIhF,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AAMxE,OAAO,KAAK,EACV,0BAA0B,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,sBAAsB,EACtG,cAAc,EAAE,cAAc,EAAE,8BAA8B,EAC/D,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,qBAAqB,EAAE,kCAAkC,EAAE,MAAM,uBAAuB,CAAC;AAClG,MAAM,WAAW,2BAA2B;IAC1C,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,SAAS,CAAC,EAAE,2BAA2B,CAAC;CACzC;AAED,qBAAa,oBAAoB;IAC/B,QAAQ,CAAC,aAAa,EAAE,8BAA8B,CAAC;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAEzB;gBAEU,aAAa,EAAE,sBAAsB,EAAE,OAAO,GAAE,2BAAgC;IA0BtF,QAAQ,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,SAAS,yBAAyB,EAAE,CAAC;IAsHlG,OAAO,CAAC,uBAAuB;CAchC;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,IAAI,CAAC,0BAA0B,EAAE,SAAS,CAAC,EAAE,aAAa,EAAE,8BAA8B,GAAG,SAAS,cAAc,EAAE,CAqB9J;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAAE,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,uBAAuB,GAAG,SAAS,CAE/H;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAEpE"}