Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
feat(runtime): Profile bindings decide contested capabilities; one resolver for plan, invoke and Build
kashorin0df5e1ff9b8e
diff --git a/docs/guide/runtime.md b/docs/guide/runtime.mdindex bc341498..ce9e059f 100644--- a/docs/guide/runtime.md+++ b/docs/guide/runtime.md@@ -35,12 +35,16 @@ The Profile contains only environmental choices that genuinely vary:},"endpoints": {"media": { "use": "@hypit/provider-media-local" }- }+ },+ "bindings": {}}```* `credentials` selects stores for explicit credential references.* `endpoints` selects exact Provider implementations and their configuration.+* `bindings` says which Endpoint serves a capability that several selected Endpoints offer, keyed by+ `name@version#capability` and naming an Endpoint instance. Providers never hide what they can do;+ this is the deployment's decision, and `doctor` reports a contested capability that lacks one.The official video Distribution selects the local Runtime before opening this file. The Profiledoes not repeat a `runtime.use` selector that cannot make another choice. Another application maydiff --git a/packages/cli/src/build-planning.ts b/packages/cli/src/build-planning.tsindex d7362261..2e1c38d4 100644--- a/packages/cli/src/build-planning.ts+++ b/packages/cli/src/build-planning.ts@@ -50,6 +50,7 @@ export type PlanProviderView = {readonly use?: string;readonly pricing?: { readonly kind: "page"; readonly url: string } | { readonly kind: "local" };readonly endpoints?: readonly string[];+ readonly binding?: string;};/** Which Endpoint and price page stand behind each demanded capability; reads the Profile only. */@@ -62,6 +63,7 @@ export async function describePlanProviders(host: NodeRuntimeHost, state: BuildS...(item.use === undefined ? {} : { use: item.use }),...(item.pricing === undefined ? {} : { pricing: item.pricing }),...(item.endpoints === undefined ? {} : { endpoints: item.endpoints }),+ ...(item.binding === undefined ? {} : { binding: item.binding }),}));}diff --git a/packages/cli/src/output.ts b/packages/cli/src/output.tsindex 564bdafd..395c8e8e 100644--- a/packages/cli/src/output.ts+++ b/packages/cli/src/output.ts@@ -102,6 +102,7 @@ export type PlanProvider = {readonly use?: string;readonly pricing?: { readonly kind: "page"; readonly url: string } | { readonly kind: "local" };readonly endpoints?: readonly string[];+ readonly binding?: string;};export type PlanOutput = {@@ -359,10 +360,12 @@ function renderPlan(if (view.machine.providers.length > 0) lines.push("", colors.strong("Providers and price pages"));for (const item of view.machine.providers) {const where = item.status === "resolved"- ? `${item.endpoint ?? ""} ${colors.dim(`(${item.use ?? "?"})`)}`+ ? `${item.endpoint ?? ""} ${colors.dim(`(${item.use ?? "?"})${item.binding === undefined ? "" : ", bound in the Profile"}`)}`: item.status === "ambiguous"- ? colors.warning(`several selected Endpoints: ${(item.endpoints ?? []).join(", ")}`)- : colors.error("no selected Endpoint");+ ? colors.warning(`${(item.endpoints ?? []).join(", ")} all offer it; add "bindings": { "${item.capability}": "<instance>" } to the Profile`)+ : item.binding === undefined+ ? colors.error("no selected Endpoint")+ : colors.error(`bound to ${item.binding}, which does not offer it`);const price = item.pricing === undefined? (item.status === "resolved" ? colors.warning("price source unknown") : undefined): item.pricing.kind === "local"diff --git a/packages/cli/test/output.test.ts b/packages/cli/test/output.test.tsindex 411001d4..456b9f05 100644--- a/packages/cli/test/output.test.ts+++ b/packages/cli/test/output.test.ts@@ -129,7 +129,7 @@ test("plan names the Provider and price page behind each request, and points atconst verbose = capture({ ...human, verbose: true }, { kind: "plan", machine: { ...base, providers: [{ capability: "@hypit/seedance@1#seedance-2-mini", status: "ambiguous", endpoints: ["hypihub.default", "kie.default"] },] } });- assert.match(verbose, /@hypit\/seedance@1#seedance-2-mini\n\s+several selected Endpoints: hypihub\.default, kie\.default/u);+ assert.match(verbose, /@hypit\/seedance@1#seedance-2-mini\n\s+hypihub\.default, kie\.default all offer it/u);});test("run check treats historical reuse as a normal summary", () => {diff --git a/packages/driver-node/src/index.ts b/packages/driver-node/src/index.tsindex 8894b6e7..91db7641 100644--- a/packages/driver-node/src/index.ts+++ b/packages/driver-node/src/index.ts@@ -4,4 +4,5 @@ export {ProducerRegistry,EndpointRegistry,} from "./registry.js";+export type { ResolvableNeed } from "./registry.js";export type * from "./types.js";diff --git a/packages/driver-node/src/registry.ts b/packages/driver-node/src/registry.tsindex c70de342..c81b40e9 100644--- a/packages/driver-node/src/registry.ts+++ b/packages/driver-node/src/registry.ts@@ -94,10 +94,46 @@ function verifyEndpointOptions(options: EndpointOptions): void {}}+/**+ * A Need, or the declared shape of one before its constraints exist.+ *+ * `plan` resolves capabilities before any request has been built, so it may leave `constraints`+ * out; an Endpoint's `supports` refinement is then not consulted and several candidates stay+ * ambiguous until the Profile binds one or the constraints arrive.+ */+export type ResolvableNeed = Pick<Need, "capability"> & Partial<Omit<Need, "capability">>;+export class EndpointRegistry implements EndpointRegistrar {readonly #registrations: EndpointRegistration[] = [];readonly #registrationKeys = new Set<string>();readonly #registrationsByCapability = new Map<string, EndpointRegistration[]>();+ readonly #bindings = new Map<string, string>();++ /**+ * Decide which Endpoint serves a capability that several Endpoints offer. Providers declare+ * everything they can do; the deployment that selected them says who does it.+ */+ bind(capability: CapabilityRef, endpointId: string): void {+ if (!endpointId.trim()) throw new Error("binding endpoint id must not be empty");+ this.#bindings.set(endpointCapabilityKey(capability), endpointId);+ }++ /** Endpoint instance ids that registered at least one capability. */+ endpointIds(): readonly string[] {+ return [...new Set(this.#registrations.map((registration) => registration.id))].sort();+ }++ /** Capabilities offered by more than one Endpoint, with the ids, for a deployment to bind. */+ contested(): readonly { readonly capability: CapabilityRef; readonly endpointIds: readonly string[]; readonly bound?: string }[] {+ const found: { readonly capability: CapabilityRef; readonly endpointIds: readonly string[]; readonly bound?: string }[] = [];+ for (const [key, registrations] of this.#registrationsByCapability) {+ const ids = [...new Set(registrations.map((registration) => registration.id))].sort();+ if (ids.length < 2) continue;+ const bound = this.#bindings.get(key);+ found.push({ capability: registrations[0]!.capability, endpointIds: ids, ...(bound === undefined ? {} : { bound }) });+ }+ return found.sort((left, right) => endpointCapabilityKey(left.capability).localeCompare(endpointCapabilityKey(right.capability)));+ }registerImmediateEndpoint(id: string,@@ -137,16 +173,23 @@ export class EndpointRegistry implements EndpointRegistrar {this.#registrationsByCapability.set(endpointCapabilityKey(capability), registrations);}- resolve(need: Need): EndpointResolution {+ resolve(need: ResolvableNeed): EndpointResolution {const key = endpointCapabilityKey(need.capability);const registrations = (this.#registrationsByCapability.get(key) ?? []).filter((registration) =>- sameRef(registration.returns, need.returns)- && (registration.supports?.(need) ?? true));+ (need.returns === undefined || sameRef(registration.returns, need.returns))+ && (need.constraints === undefined || (registration.supports?.(need as Need) ?? true)));+ const bound = this.#bindings.get(key);+ if (bound !== undefined) {+ const chosen = registrations.find((registration) => registration.id === bound);+ // A binding names the Endpoint; an Endpoint that cannot serve this request is a missing one,+ // reported with the id so the deployment sees which binding to revisit.+ return chosen === undefined ? { status: "missing", endpointId: bound } : { status: "resolved", registration: chosen };+ }if (registrations.length === 0) return { status: "missing" };if (registrations.length > 1) {return {status: "ambiguous",- endpointIds: registrations.map((registration) => registration.id).sort(),+ endpointIds: [...new Set(registrations.map((registration) => registration.id))].sort(),};}return { status: "resolved", registration: registrations[0]! };diff --git a/packages/provider-hypihub/README.md b/packages/provider-hypihub/README.mdindex 2d8491d6..7c64cfb6 100644--- a/packages/provider-hypihub/README.md+++ b/packages/provider-hypihub/README.md@@ -50,5 +50,7 @@ declares HypiHub's public pricing page, `https://hypit.ai/commercial/pricing/`,`hypit plan --runtime <profile>` prints it beside each request this Endpoint would serve. Per-modelcredit costs are never copied into Hypit.-HypiHub exposes MiMo VoiceDesign by default. Set `audio: false` only when the user explicitly selects-another VoiceDesign Provider. Hypit does not expose MiMo preset-voice or voice-cloning models.+HypiHub declares MiMo VoiceDesign together with every other capability it serves; it never hides+one. When another selected Endpoint offers the same capability (a local WhisperX, a Vertex Gemini,+the official MiMo Provider), the Runtime Profile's `bindings` say which Endpoint serves it. Hypit does+not expose MiMo preset-voice or voice-cloning models.diff --git a/packages/provider-hypihub/src/activation.ts b/packages/provider-hypihub/src/activation.tsindex 967a5021..129915a0 100644--- a/packages/provider-hypihub/src/activation.ts+++ b/packages/provider-hypihub/src/activation.ts@@ -2,7 +2,6 @@ import {createRuntimeEndpointAdapterFacet,runtimeConfigCredentialRef,runtimeConfigExact,- runtimeConfigBoolean,runtimeConfigObject,runtimeConfigPositiveInteger,runtimeConfigString,@@ -16,8 +15,7 @@ const adapter = createRuntimeEndpointAdapterFacet({if (context.pool === undefined) throw new Error("HypiHub Provider Pool is required");const config = runtimeConfigObject(context.config, "HypiHub");runtimeConfigExact(config, [- "baseUrl", "apiKey", "defaultConcurrency", "pollIntervalMs", "requestTimeoutMs", "audio",- "transcriptionModel",+ "baseUrl", "apiKey", "defaultConcurrency", "pollIntervalMs", "requestTimeoutMs", "transcriptionModel",], "HypiHub");const baseUrl = runtimeConfigString(config.baseUrl, "HypiHub baseUrl");if (baseUrl !== undefined) {@@ -31,7 +29,6 @@ const adapter = createRuntimeEndpointAdapterFacet({const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "HypiHub defaultConcurrency");const pollIntervalMs = runtimeConfigPositiveInteger(config.pollIntervalMs, "HypiHub pollIntervalMs");const requestTimeoutMs = runtimeConfigPositiveInteger(config.requestTimeoutMs, "HypiHub requestTimeoutMs");- const audio = runtimeConfigBoolean(config.audio, "HypiHub audio");const transcriptionModel = runtimeConfigString(config.transcriptionModel, "HypiHub transcriptionModel");const options = {instance: context.instance,@@ -41,7 +38,6 @@ const adapter = createRuntimeEndpointAdapterFacet({...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),...(pollIntervalMs === undefined ? {} : { pollIntervalMs }),...(requestTimeoutMs === undefined ? {} : { requestTimeoutMs }),- ...(audio === undefined ? {} : { audio }),...(transcriptionModel === undefined ? {} : { transcriptionModel }),};return {diff --git a/packages/provider-hypihub/src/provider.ts b/packages/provider-hypihub/src/provider.tsindex 6ceee90c..989e5ccf 100644--- a/packages/provider-hypihub/src/provider.ts+++ b/packages/provider-hypihub/src/provider.ts@@ -30,8 +30,6 @@ export type CreateHypiHubProviderOptions = {readonly defaultConcurrency?: number;readonly pollIntervalMs?: number;readonly requestTimeoutMs?: number;- /** Expose HypiHub VoiceDesign. Defaults to enabled; set false only for an explicit alternate Provider. */- readonly audio?: boolean;/** HypiHub model used for the Provider-neutral WhisperX alignment capability. */readonly transcriptionModel?: string;readonly fetch?: typeof globalThis.fetch;@@ -371,7 +369,6 @@ export function createHypiHubProvider(options: CreateHypiHubProviderOptions = {}defaultConcurrency: options.defaultConcurrency ?? 4,capabilities: [...hypiHubRoutes- .filter((route) => options.audio !== false || route.media !== "audio").map((route) => route.media === "audio"? { capability: route.capability, returns: route.returns, lifecycle: "immediate" as const, handler: audioEndpoint, lane: route.capability.name }: { capability: route.capability, returns: route.returns, lifecycle: "asynchronous" as const, endpoint: asyncEndpoint, lane: route.capability.name }),diff --git a/packages/provider-hypihub/test/provider.test.ts b/packages/provider-hypihub/test/provider.test.tsindex b2436618..8b315536 100644--- a/packages/provider-hypihub/test/provider.test.ts+++ b/packages/provider-hypihub/test/provider.test.ts@@ -2,6 +2,7 @@ import assert from "node:assert/strict";import test from "node:test";import { EndpointRegistry, MemoryResourceStore } from "@hypit/driver-node";+import { defineEndpointPackage } from "@hypit/endpoint-kit";import type { AsyncEndpoint } from "@hypit/endpoint-kit";import { geminiCapabilities, sealGeminiRequest } from "@hypit/gemini";import type { CanonicalValue, Need } from "@hypit/protocol";@@ -77,26 +78,37 @@ test("HypiHub doctor checks the authenticated catalogue only when actively invokassert.deepEqual(diagnostics, []);});-test("HypiHub exposes VoiceDesign by default and permits an explicit alternate audio Provider", async () => {+test("HypiHub declares VoiceDesign like everything else it can do; who serves it is the Profile's binding", async () => {const registry = new EndpointRegistry();await createHypiHubProvider({ fetch: async () => { throw new Error("audio must not call fetch"); } }).install(registry);- assert.equal(registry.resolve({+ const need = {id: "need:hypihub-audio-default",capability: mimoTtsEndpoints.voiceDesign.capability,returns: mimoTtsEndpoints.voiceDesign.returns,constraints: { ports: {} },result: "record:hypihub-audio-default",- }).status, "resolved");+ };+ assert.equal(registry.resolve(need).status, "resolved");- const optedOut = new EndpointRegistry();- await createHypiHubProvider({ audio: false, fetch: async () => { throw new Error("not reached"); } }).install(optedOut);- assert.equal(optedOut.resolve({- id: "need:hypihub-audio-opt-in",- capability: mimoTtsEndpoints.voiceDesign.capability,- returns: mimoTtsEndpoints.voiceDesign.returns,- constraints: { ports: {} },- result: "record:hypihub-audio-opt-in",- }).status, "missing");+ // A second Endpoint offering the same capability makes the choice the deployment's, not the Provider's.+ const other = defineEndpointPackage({+ module: { name: "example.tts", version: "1" },+ facet: "tts",+ instance: "mimo.official",+ pool: "mimo.official",+ capabilities: [{+ capability: mimoTtsEndpoints.voiceDesign.capability,+ returns: mimoTtsEndpoints.voiceDesign.returns,+ lifecycle: "immediate",+ handler: () => ({ value: { kind: "inline", value: null } }),+ }],+ });+ await other.install(registry);+ assert.equal(registry.resolve(need).status, "ambiguous");+ registry.bind(mimoTtsEndpoints.voiceDesign.capability, "mimo.official");+ const resolved = registry.resolve(need);+ assert.equal(resolved.status, "resolved");+ assert.equal(resolved.status === "resolved" ? resolved.registration.id : undefined, "mimo.official");});test("HypiHub uploads referenced Artifacts once, submits their HTTPS URLs, and persists the result", async () => {diff --git a/packages/runtime-host-node/src/index.ts b/packages/runtime-host-node/src/index.tsindex 891ab7fe..302db859 100644--- a/packages/runtime-host-node/src/index.ts+++ b/packages/runtime-host-node/src/index.ts@@ -140,6 +140,8 @@ export type RuntimeHostCapabilityProvider = {readonly pricing?: { readonly kind: "page"; readonly url: string } | { readonly kind: "local" };/** Every matching Endpoint instance when the selection is ambiguous. */readonly endpoints?: readonly string[];+ /** The Endpoint instance the Profile's `bindings` name for this capability, when it names one. */+ readonly binding?: string;};export type ManagedProgramProgress = {diff --git a/packages/runtime-local/README.md b/packages/runtime-local/README.mdindex f656bcb9..03c5dbfc 100644--- a/packages/runtime-local/README.md+++ b/packages/runtime-local/README.md@@ -12,13 +12,29 @@ A Runtime Profile selects only the environmental parts that genuinely vary:"credentials": {"env": { "use": "@hypit/credential-store-env" }},- "endpoints": {}+ "endpoints": {},+ "bindings": {}}```The official video Distribution selects this Runtime implementation before it opens the file. TheProfile therefore describes only local execution and does not repeat a fake Runtime Host selector.+Providers declare everything they can do and never hide a capability. When two selected Endpoints+offer the same capability, `bindings` says which one serves it, keyed by the capability+(`name@version#capability`) and naming an Endpoint instance of this Profile:++```json+"bindings": {+ "@hypit/whisperx@1#whisperx-alignment": "whisperx.local"+}+```++A capability offered by exactly one Endpoint needs no binding. A contested capability without one is+reported by `doctor` and `plan` and blocks the Need at Build time; a binding to an Endpoint that does+not offer the capability is an error. `plan`, creation-time tools and the Build resolve Endpoints+through the same registry with the same bindings.+A project that wants a non-default Result repository owns a separate `hypit.results.json`:```json@@ -30,8 +46,8 @@ A project that wants a non-default Result repository owns a separate `hypit.resu```Submitting a Build stores it and returns. The Worker may advance unrelated Builds together; only the-resources declared by their Commands constrain execution. Endpoint packages declare the Provider-pool and model-lane limits that govern actual external work. Build identity is not a capacity+resources declared by their Commands constrain execution. The Profile names each Endpoint's+pool; Endpoint packages declare the model lanes inside it, and those limits govern actual external work. Build identity is not a capacityresource and creates no second queue.Cancellation prevents new work and makes a best effort to cancel an external operation already submitted;completed output is never rolled back.diff --git a/packages/runtime-local/src/config.ts b/packages/runtime-local/src/config.tsindex 0e0bdf1d..d68c89a2 100644--- a/packages/runtime-local/src/config.ts+++ b/packages/runtime-local/src/config.ts@@ -49,7 +49,7 @@ import {import type { HostPackageProgress, HostPackageReport, RuntimeHostCapabilityProvider } from "@hypit/runtime-host-node";import { SqliteRuntimeState } from "@hypit/store-sqlite";-import { createLocalRuntime } from "./runtime.js";+import { applyEndpointBindings, createLocalRuntime, parseCapabilityKey } from "./runtime.js";import {createLocalRuntimeControl,} from "./control.js";@@ -74,6 +74,12 @@ export type LocalRuntimeProfile = {readonly dataRoot: string;readonly credentials: readonly LocalRuntimeAdapterSelection[];readonly endpoints: readonly LocalRuntimeAdapterSelection[];+ /**+ * Capability key (`name@version#capability`) to Endpoint instance, for capabilities that several+ * selected Endpoints offer. Providers declare everything they can do; this is where the deployment+ * says who does it.+ */+ readonly bindings: Readonly<Record<string, string>>;};export type ProjectBuildResultConfig = {@@ -133,7 +139,9 @@ function object(value: unknown, subject: string): Record<string, unknown> {function exactKeys(value: Record<string, unknown>, allowed: readonly string[], subject: string): void {const unknown = Object.keys(value).filter((key) => !allowed.includes(key));- if (unknown.length > 0) throw new Error(`${subject} does not accept ${unknown[0]}`);+ if (unknown.length > 0) {+ throw new Error(`${subject} does not accept ${unknown.join(", ")}; it accepts ${allowed.join(", ")}`);+ }}function requiredString(value: unknown, subject: string): string {@@ -161,9 +169,28 @@ function entries(value: unknown, subject: string, poolAllowed = false): readonly});}+function bindings(value: unknown, endpoints: readonly LocalRuntimeAdapterSelection[]): Readonly<Record<string, string>> {+ const values = object(value ?? {}, "$runtime.bindings");+ const instances = new Set(endpoints.map((item) => item.instance));+ const result: Record<string, string> = {};+ for (const [key, target] of Object.entries(values).sort(([left], [right]) => left.localeCompare(right))) {+ parseCapabilityKey(key);+ const instance = requiredString(target, `$runtime.bindings.${key}`);+ if (!instances.has(instance)) {+ throw new Error(`$runtime.bindings.${key} names ${instance}, which is not an Endpoint instance of this Profile (${[...instances].sort().join(", ")})`);+ }+ result[key] = instance;+ }+ return result;+}+export function parseLocalRuntimeProfile(value: unknown): LocalRuntimeProfile {const item = object(value, "$runtime");- exactKeys(item, ["format", "dataRoot", "credentials", "endpoints"], "$runtime");+ if (item.runtime !== undefined && item.format === "hypit.runtime-profile@1") {+ throw new Error("This Runtime Profile uses the retired hypit.runtime-profile@1 shape with a nested runtime object. "+ + "Move runtime.config.dataRoot, credentials and endpoints to the top level and set format to hypit.runtime-local@1.");+ }+ exactKeys(item, ["format", "dataRoot", "credentials", "endpoints", "bindings"], "$runtime");if (item.format !== "hypit.runtime-local@1") {throw new Error("$runtime.format must be hypit.runtime-local@1");}@@ -176,6 +203,7 @@ export function parseLocalRuntimeProfile(value: unknown): LocalRuntimeProfile {dataRoot: requiredString(item.dataRoot, "$runtime.dataRoot"),credentials,endpoints,+ bindings: bindings(item.bindings, endpoints),};}@@ -442,6 +470,20 @@ export async function declaredManagedPrograms(return { dataRoot: root, programs };}+/**+ * A registry of every selected Endpoint with the Profile's bindings applied: the one resolver that+ * `plan`, creation-time `invoke` and a Build share, so all three see the same Endpoint for a Need.+ */+async function installedEndpointRegistry(+ document: LocalRuntimeProfile,+ activations: readonly { readonly entry: LocalRuntimeAdapterSelection; readonly activation: RuntimeEndpointActivation }[],+): Promise<EndpointRegistry> {+ const endpoints = new EndpointRegistry();+ for (const { activation } of activations) await activation.endpoint.install(endpoints);+ applyEndpointBindings(endpoints, document.bindings);+ return endpoints;+}+/** Static Endpoint selection per capability. Reads the Profile and activations only; never a credential or a service. */export async function describeRuntimeConfigProviders(path: string,@@ -453,23 +495,24 @@ export async function describeRuntimeConfigProviders(const hostStateRoot = resolve(options.hostStateRoot ?? hypitHostStateRoot());const registry = options.registry ?? new RuntimeAdapterRegistry();await installRuntimeAdapters(registry, packageRoot, endpointPackageSelection(document), options.distributionPackageRoot);- const endpoints = await activatedEndpoints(document, root, hostStateRoot, registry);+ const activations = await activatedEndpoints(document, root, hostStateRoot, registry);+ const endpoints = await installedEndpointRegistry(document, activations);return capabilities.map((capability): RuntimeHostCapabilityProvider => {- const matches = endpoints.filter(({ activation }) =>- activation.endpoint.offers.some((offer) => sameRef(offer.capability, capability)));const base = { capability: structuredClone(capability) };- if (matches.length === 0) return { ...base, status: "unresolved" };- if (matches.length > 1) {- return { ...base, status: "ambiguous", endpoints: matches.map((item) => item.entry.instance).sort() };- }- const match = matches[0]!;- const pricing = match.activation.endpoint.pricing;+ const binding = document.bindings[capabilityKey(capability)];+ const bound = binding === undefined ? {} : { binding };+ const resolution = endpoints.resolve({ capability });+ if (resolution.status === "missing") return { ...base, status: "unresolved", ...bound };+ if (resolution.status === "ambiguous") return { ...base, status: "ambiguous", endpoints: resolution.endpointIds, ...bound };+ const match = activations.find(({ activation }) => activation.endpoint.instance.id === resolution.registration.id);+ const pricing = match?.activation.endpoint.pricing;return {...base,status: "resolved",- endpoint: match.entry.instance,- use: match.entry.use,+ endpoint: resolution.registration.id,+ ...(match === undefined ? {} : { use: match.entry.use }),...(pricing === undefined ? {} : { pricing: structuredClone(pricing) }),+ ...bound,};});}@@ -493,15 +536,17 @@ export async function invokeRuntimeConfigNeed(const registry = options.registry ?? new RuntimeAdapterRegistry();await installRuntimeAdapters(registry, packageRoot, runtimePackageSelection(document), options.distributionPackageRoot);const activations = await activatedEndpoints(document, root, hostStateRoot, registry);- const endpoints = new EndpointRegistry();- for (const { activation } of activations) await activation.endpoint.install(endpoints);+ const endpoints = await installedEndpointRegistry(document, activations);const subject = capabilityKey(need.capability);const resolution = endpoints.resolve(need);if (resolution.status === "missing") {- throw new Error(`No Endpoint in ${absolute} serves ${subject}; hypit plan --runtime ${absolute} shows which Endpoint each capability needs`);+ throw new Error(resolution.endpointId === undefined+ ? `No Endpoint in ${absolute} serves ${subject}; hypit plan --runtime ${absolute} shows which Endpoint each capability needs`+ : `${absolute} binds ${subject} to ${resolution.endpointId}, which does not serve this request; change that binding`);}if (resolution.status === "ambiguous") {- throw new Error(`Several Endpoints in ${absolute} serve ${subject}: ${resolution.endpointIds.join(", ")}; keep exactly one`);+ throw new Error(`Several Endpoints in ${absolute} serve ${subject}: ${resolution.endpointIds.join(", ")}. `+ + `Say which one does it: add "bindings": { "${subject}": "<instance>" } to the Profile`);}const registration = resolution.registration;if (registration.kind !== "immediate") {@@ -515,7 +560,10 @@ export async function invokeRuntimeConfigNeed(for (const slot of activation.endpoint.credentials) {const value = await stores.store.resolve(slot.ref);if (value === undefined) {- throw new Error(`${slot.label} for Endpoint ${slot.endpoint} is not configured. Configure it with: hypit auth login ${slot.endpoint} --runtime ${absolute}`);+ throw new Error(`${slot.label} for Endpoint ${slot.endpoint} is not configured. ${+ slot.ref.store === "env"+ ? `Set ${slot.ref.key} in this process environment.`+ : `Configure it with: hypit auth login ${slot.endpoint} --runtime ${absolute}`}`);}credentials[slot.slot] = value;}@@ -615,6 +663,7 @@ async function inspectRuntimeConfig(? undefined: new Set(options.capabilities.map(capabilityKey));const covered = new Set<string>();+ const activated: Array<{ readonly item: LocalRuntimeAdapterSelection; readonly activation: RuntimeEndpointActivation }> = [];const selectedEndpoints: Array<{ readonly item: LocalRuntimeAdapterSelection; readonly activation: RuntimeEndpointActivation }> = [];for (const item of document.endpoints) {let activation: RuntimeEndpointActivation;@@ -627,6 +676,7 @@ async function inspectRuntimeConfig(diagnostics.push(diagnostic(error, "RUNTIME_ENDPOINT_CONFIG_INVALID", item.instance));continue;}+ activated.push({ item, activation });if (requested !== undefined && !activation.endpoint.offers.some((offer) => requested.has(capabilityKey(offer.capability)))) continue;for (const offer of activation.endpoint.offers) covered.add(capabilityKey(offer.capability));selectedEndpoints.push({ item, activation });@@ -656,6 +706,34 @@ async function inspectRuntimeConfig(subject: capabilityKey(capability),});}+ // Who serves a capability that several selected Endpoints offer is the Profile's decision. An+ // unbound contest is an error for a demanded capability and a warning otherwise; a binding to an+ // Endpoint that does not offer the capability is always an error.+ try {+ const endpoints = await installedEndpointRegistry(document, activated.map(({ item, activation }) => ({ entry: item, activation })));+ for (const [key, instance] of Object.entries(document.bindings)) {+ const offered = activated.some(({ item, activation }) =>+ item.instance === instance && activation.endpoint.offers.some((offer) => capabilityKey(offer.capability) === key));+ if (!offered && activated.some(({ item }) => item.instance === instance)) diagnostics.push({+ severity: "error",+ code: "RUNTIME_BINDING_INVALID",+ message: `bindings names ${instance} for ${key}, but that Endpoint does not offer it`,+ subject: key,+ });+ }+ for (const contest of endpoints.contested()) {+ if (contest.bound !== undefined) continue;+ const key = capabilityKey(contest.capability);+ diagnostics.push({+ severity: requested !== undefined && requested.has(key) ? "error" : "warning",+ code: "RUNTIME_CAPABILITY_AMBIGUOUS",+ message: `${contest.endpointIds.join(", ")} all offer ${key}. Say which one does it: add "bindings": { "${key}": "<instance>" } to the Profile`,+ subject: key,+ });+ }+ } catch (error) {+ diagnostics.push(diagnostic(error, "RUNTIME_ENDPOINT_INSTALL_FAILED"));+ }if (selectedEndpoints.length > 0) {let stores: Awaited<ReturnType<typeof openCredentialStores>> | undefined;try {@@ -737,6 +815,7 @@ export async function createRuntimeFromConfig(const environmentConfig = canonicalStringify({credentials: document.credentials,endpoints: document.endpoints,+ bindings: document.bindings,});let credentials: Awaited<ReturnType<typeof openCredentialStores>> | undefined;try {@@ -774,6 +853,7 @@ export async function createRuntimeFromConfig(return collectLoadedNodePackageComponents(loaded);},endpoints,+ bindings: document.bindings,close: async () => {await credentials?.close();state.close();diff --git a/packages/runtime-local/src/runtime.ts b/packages/runtime-local/src/runtime.tsindex 705f613a..49fd7548 100644--- a/packages/runtime-local/src/runtime.ts+++ b/packages/runtime-local/src/runtime.ts@@ -94,6 +94,18 @@ async function wait(delayMs: number, signal: AbortSignal | undefined): Promise<v});}+/** Capability keys are `name@version#capability`; the registry binds by CapabilityRef. */+export function parseCapabilityKey(key: string): { readonly module: { readonly name: string; readonly version: string }; readonly name: string } {+ const match = /^(.+)@([^@#]+)#(.+)$/u.exec(key);+ if (match === null) throw new Error(`${key} is not a capability key of the form name@version#capability`);+ return { module: { name: match[1]!, version: match[2]! }, name: match[3]! };+}++/** Providers declare everything they can do; the Profile that selected them says who does it. */+export function applyEndpointBindings(registry: EndpointRegistry, bindings: Readonly<Record<string, string>> | undefined): void {+ for (const [key, endpointId] of Object.entries(bindings ?? {})) registry.bind(parseCapabilityKey(key), endpointId);+}+export async function createLocalRuntime(options: CreateLocalRuntimeOptions,): Promise<LocalRuntime> {@@ -107,6 +119,7 @@ export async function createLocalRuntime(registerProducerFacets(producers, component.producers ?? []);}for (const endpoint of options.endpoints ?? []) await endpoint.install(endpoints);+ applyEndpointBindings(endpoints, options.bindings);const loadedComponentPackages = new Set<string>();let componentInstallation = Promise.resolve();const installComponentPackages = async (specifiers: readonly string[]): Promise<void> => {diff --git a/packages/runtime-local/src/types.ts b/packages/runtime-local/src/types.tsindex 0d52cbb6..44c79898 100644--- a/packages/runtime-local/src/types.ts+++ b/packages/runtime-local/src/types.ts@@ -43,6 +43,8 @@ export type CreateLocalRuntimeOptions = {/** Load the complete physical package closure named by a claimed Build. */readonly loadComponentPackages?: (specifiers: readonly string[]) => Awaitable<readonly LoadedComponentPackage[]>;readonly endpoints?: readonly EndpointPackage[];+ /** Which Endpoint instance serves each capability that several selected Endpoints offer. */+ readonly bindings?: Readonly<Record<string, string>>;readonly close?: () => Awaitable<void>;};diff --git a/packages/runtime-local/test/config.test.ts b/packages/runtime-local/test/config.test.tsindex 61053df6..205beb9d 100644--- a/packages/runtime-local/test/config.test.ts+++ b/packages/runtime-local/test/config.test.ts@@ -14,6 +14,7 @@ import {createBuildResultRepositoryHostFacet,} from "@hypit/build-result-kit";import { FileBuildResultRepository } from "@hypit/build-result";+import { MemoryResourceStore } from "@hypit/driver-node";import { defineEndpointPackage } from "@hypit/endpoint-kit";import { credentialRef } from "@hypit/runtime";import { SqliteRuntimeState } from "@hypit/store-sqlite";@@ -33,12 +34,14 @@ function profile(config: {readonly dataRoot?: string;readonly credentials?: Readonly<Record<string, unknown>>;readonly endpoints?: Readonly<Record<string, unknown>>;+ readonly bindings?: Readonly<Record<string, string>>;} = {}) {return {format: "hypit.runtime-local@1",dataRoot: config.dataRoot ?? ".hypit/runtimes/local",credentials: config.credentials ?? {},endpoints: config.endpoints ?? {},+ ...(config.bindings === undefined ? {} : { bindings: config.bindings }),};}@@ -399,3 +402,90 @@ test("Runtime invoke executes one immediate Need through the selected Endpoint a}});++test("a Profile binds a contested capability to one of its Endpoints, and says so when it cannot", () => {+ const generateKey = "example.model@1#generate";+ assert.deepEqual(parseLocalRuntimeProfile(profile({+ endpoints: { paid: { use: "example.paid" }, local: { use: "example.local" } },+ bindings: { [generateKey]: "local" },+ })).bindings, { [generateKey]: "local" });+ assert.throws(() => parseLocalRuntimeProfile(profile({+ endpoints: { paid: { use: "example.paid" } },+ bindings: { [generateKey]: "nowhere" },+ })), /names nowhere, which is not an Endpoint instance of this Profile \(paid\)/u);+ assert.throws(() => parseLocalRuntimeProfile(profile({ bindings: { "not a key": "paid" } })), /capability key/u);+ assert.throws(() => parseLocalRuntimeProfile({ ...profile(), stale: 1, older: 2 }), /does not accept stale, older; it accepts/u);+ assert.throws(() => parseLocalRuntimeProfile({+ format: "hypit.runtime-profile@1",+ runtime: { use: "@hypit/runtime-local", config: {} },+ }), /retired hypit.runtime-profile@1 shape/u);+});++test("providers, doctor and invoke share one resolver: a contested capability is ambiguous until the Profile binds it", async () => {+ const root = await mkdtemp(join(tmpdir(), "hypit-runtime-bindings-"));+ const generate = { module: { name: "example.model", version: "1" }, name: "generate" } as const;+ const render = { module: { name: "example.render", version: "1" }, name: "render" } as const;+ const returns = { module: { name: "example.value", version: "1" }, name: "Output" } as const;+ const generateKey = "example.model@1#generate";+ const registry = new RuntimeAdapterRegistry();+ for (const [use, instanceLabel, capability, answer] of [+ ["example.paid", "paid", generate, "paid"],+ ["example.other", "other", generate, "other"],+ ["example.local", "local", render, "local"],+ ] as const) {+ registry.registerFacet(createRuntimeEndpointAdapterFacet({+ use,+ activate: (context) => ({+ endpoint: defineEndpointPackage({+ module: { name: `example.provider.${instanceLabel}`, version: "1" },+ facet: instanceLabel,+ instance: context.instance,+ pool: context.pool ?? context.instance,+ pricing: { kind: "local" },+ capabilities: [{ capability, returns, lifecycle: "immediate", handler: () => ({ value: { kind: "inline" as const, value: answer } }) }],+ }),+ }),+ }));+ }+ const endpoints = { paid: { use: "example.paid" }, other: { use: "example.other" }, local: { use: "example.local" } };+ const need = { id: "need:1", capability: generate, returns, constraints: null, result: "record:1" };+ try {+ const unbound = join(root, "unbound.json");+ await writeFile(unbound, JSON.stringify(profile({ dataRoot: ".", endpoints })));+ assert.deepEqual(await describeRuntimeConfigProviders(unbound, [generate, render], { registry }), [+ { capability: generate, status: "ambiguous", endpoints: ["other", "paid"] },+ { capability: render, status: "resolved", endpoint: "local", use: "example.local", pricing: { kind: "local" } },+ ]);+ const contested = (await preflightRuntimeConfig(unbound, { registry, capabilities: [generate] })).diagnostics+ .filter((item) => item.code === "RUNTIME_CAPABILITY_AMBIGUOUS");+ assert.equal(contested.length, 1);+ assert.equal(contested[0]!.severity, "error");+ assert.match(contested[0]!.message, /add "bindings": \{ "example\.model@1#generate": "<instance>" \}/u);+ // Without a Run, doctor looks at every selected Endpoint and reports the contest as a warning.+ const idle = (await preflightRuntimeConfig(unbound, { registry })).diagnostics+ .find((item) => item.code === "RUNTIME_CAPABILITY_AMBIGUOUS");+ assert.equal(idle?.severity, "warning");+ await assert.rejects(invokeRuntimeConfigNeed(unbound, need, new MemoryResourceStore(), { registry }), /Say which one does it/u);++ const bound = join(root, "bound.json");+ await writeFile(bound, JSON.stringify(profile({ dataRoot: ".", endpoints, bindings: { [generateKey]: "other" } })));+ assert.deepEqual(await describeRuntimeConfigProviders(bound, [generate], { registry }), [+ { capability: generate, status: "resolved", endpoint: "other", use: "example.other", pricing: { kind: "local" }, binding: "other" },+ ]);+ assert.equal((await preflightRuntimeConfig(bound, { registry, capabilities: [generate] })).diagnostics+ .some((item) => item.code === "RUNTIME_CAPABILITY_AMBIGUOUS"), false);+ const fulfilled = await invokeRuntimeConfigNeed(bound, need, new MemoryResourceStore(), { registry });+ assert.deepEqual(fulfilled.value, { kind: "inline", value: "other" });++ const wrong = join(root, "wrong.json");+ await writeFile(wrong, JSON.stringify(profile({ dataRoot: ".", endpoints, bindings: { [generateKey]: "local" } })));+ assert.deepEqual(await describeRuntimeConfigProviders(wrong, [generate], { registry }), [+ { capability: generate, status: "unresolved", binding: "local" },+ ]);+ assert.ok((await preflightRuntimeConfig(wrong, { registry, capabilities: [generate] })).diagnostics+ .some((item) => item.code === "RUNTIME_BINDING_INVALID"));+ await assert.rejects(invokeRuntimeConfigNeed(wrong, need, new MemoryResourceStore(), { registry }), /binds example\.model@1#generate to local, which does not serve/u);+ } finally {+ await rm(root, { recursive: true, force: true });+ }+});