Skip to content

armgit / hypit

Public Imported from GitHub
0

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.

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.md
index 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 Profile
does not repeat a `runtime.use` selector that cannot make another choice. Another application may
diff --git a/packages/cli/src/build-planning.ts b/packages/cli/src/build-planning.ts
index 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.ts
index 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.ts
index 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 at
const 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.ts
index 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.ts
index 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.md
index 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-model
credit 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.ts
index 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.ts
index 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.ts
index 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 invok
assert.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.ts
index 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.md
index 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. The
Profile 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 capacity
resource 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 });
+ }
+});