Files

250 lines
11 KiB
TypeScript

import { canonicalize } from "@hypit/hypit/protocol";
import type { BlobRef, CanonicalValue, CapabilityRef } from "@hypit/hypit/protocol";
import { isMediaPort } from "./ports.js";
import type { GenerationMediaValue, GenerationPortTable } from "./ports.js";
import { presentPorts } from "./request.js";
import type { GenerationRequest } from "./request.js";
/** Per-reference fields consumed by the service's resource transport rather than its generation body. */
export type GenerationArtifactUrlResolver = (
artifact: BlobRef,
fields?: Readonly<Record<string, string | number | boolean>>,
) => Promise<string>;
/**
* How one service names the fields of one model's declared input ports.
*
* A mapping is data, not code, and it references its Capability by name. A
* Provider package therefore never imports a model package: the model owns what
* it eats, the service owns what it calls that on the wire.
*/
export type GenerationFieldMapping =
/** One scalar written as-is. */
| { readonly as: "value"; readonly field: string; readonly whenAbsent?: CanonicalValue }
/** One scalar coerced to its string form, for services that type it loosely. */
| { readonly as: "string"; readonly field: string; readonly whenAbsent?: CanonicalValue }
/** Several scalars written as one array. */
| { readonly as: "valueArray"; readonly field: string; readonly whenAbsent?: CanonicalValue }
/** One media item written as a resolved URL. */
| { readonly as: "url"; readonly field: string; readonly resourceFields?: readonly string[]; readonly whenAbsent?: CanonicalValue }
/** Several media items written as one array of resolved URLs. */
| { readonly as: "urlArray"; readonly field: string; readonly resourceFields?: readonly string[]; readonly whenAbsent?: CanonicalValue }
/** Media items written as objects carrying the resolved URL and their item fields. */
| {
readonly as: "itemObject";
readonly field: string;
readonly urlKey: string;
readonly resourceFields?: readonly string[];
readonly fieldKeys: Readonly<Record<string, string>>;
readonly whenAbsent?: CanonicalValue;
};
/** Selects the service-side model identifier. The first matching route wins. */
export type GenerationWireRoute = {
readonly model: string;
readonly whenPresent?: readonly string[];
};
export type GenerationWireMapping = {
/**
* The exact Capability implemented, named as data. Binding the module version
* here keeps a port change visible: a mapping written for one model version
* cannot silently serve another.
*/
readonly capability: CapabilityRef;
readonly result: "audio" | "image" | "video";
readonly routes: readonly GenerationWireRoute[];
readonly fields: Readonly<Record<string, GenerationFieldMapping>>;
readonly constants?: Readonly<Record<string, CanonicalValue>>;
};
export type GenerationWireRequest = {
readonly model: string;
readonly input: CanonicalValue;
};
function assert(condition: unknown, message: string): asserts condition {
if (!condition) throw new Error(message);
}
export function selectWireModel(mapping: GenerationWireMapping, present: ReadonlySet<string>): string {
for (const route of mapping.routes) {
if (route.whenPresent === undefined || route.whenPresent.every((name) => present.has(name))) {
return route.model;
}
}
throw new Error(`${mapping.capability.name} has no route for ports ${[...present].sort().join(", ")}`);
}
/**
* Select one service model from the authored request shape.
*
* During planning, `pendingPorts` names graph inputs the model package has
* already attached even though their Resource bytes do not exist yet. They are
* ordinary model port names, not graph traversal instructions.
*/
export function selectWireModelForRequest(
mapping: GenerationWireMapping,
request: GenerationRequest,
pendingPorts: readonly string[] = [],
): string {
const unsupported = unsupportedRequestField(mapping, request);
assert(unsupported === undefined,
`${mapping.capability.name} request contains ${unsupported} this Provider cannot map`);
const present = new Set(presentPorts(request));
for (const port of pendingPorts) {
assert(mapping.fields[port] !== undefined,
`${mapping.capability.name} request contains future port ${port} this Provider cannot map`);
present.add(port);
}
return selectWireModel(mapping, present);
}
function resourceFields(item: GenerationMediaValue, names: readonly string[] = []) {
return Object.fromEntries(names.filter((name) => item.fields?.[name] !== undefined)
.map((name) => [name, item.fields![name]!]));
}
/**
* Compile one port-shaped request into one service payload. The engine needs
* only the mapping and the request, never the model package.
*/
export async function compileWireRequest(
mapping: GenerationWireMapping,
request: GenerationRequest,
resolve: GenerationArtifactUrlResolver,
): Promise<GenerationWireRequest> {
const model = selectWireModelForRequest(mapping, request);
const input: Record<string, CanonicalValue> = { ...(mapping.constants ?? {}) };
for (const [port, field] of Object.entries(mapping.fields)) {
const supplied = request.ports[port];
if (supplied === undefined) {
if (field.whenAbsent !== undefined) input[field.field] = field.whenAbsent;
continue;
}
if (field.as === "value") {
input[field.field] = supplied[0] as CanonicalValue;
} else if (field.as === "string") {
input[field.field] = String(supplied[0]);
} else if (field.as === "valueArray") {
input[field.field] = supplied as readonly CanonicalValue[];
} else if (field.as === "url") {
const item = supplied[0] as GenerationMediaValue;
input[field.field] = await resolve(item.artifact, resourceFields(item, field.resourceFields));
} else if (field.as === "urlArray") {
input[field.field] = await Promise.all((supplied as readonly GenerationMediaValue[])
.map((item) => resolve(item.artifact, resourceFields(item, field.resourceFields))));
} else {
const media = supplied as readonly GenerationMediaValue[];
input[field.field] = await Promise.all(media.map(async (item) => ({
[field.urlKey]: await resolve(item.artifact, resourceFields(item, field.resourceFields)),
...Object.fromEntries(Object.entries(field.fieldKeys)
.filter(([source]) => item.fields?.[source] !== undefined)
.map(([source, target]) => [target, item.fields![source] as CanonicalValue])),
})));
}
}
return { model, input: canonicalize(input) };
}
/** Describe only a supplied value the mapping cannot carry; no model table or saved verdict. */
function unsupportedRequestField(mapping: GenerationWireMapping, value: unknown): string | undefined {
const request = value as GenerationRequest | undefined;
if (request === undefined || request === null || request.ports === null || typeof request.ports !== "object") {
return "invalid ports";
}
for (const [port, supplied] of Object.entries(request.ports)) {
const field = mapping.fields[port];
if (field === undefined) return `port ${port}`;
if (field.as !== "url" && field.as !== "urlArray" && field.as !== "itemObject") continue;
for (const item of supplied as readonly GenerationMediaValue[]) {
for (const name of Object.keys(item.fields ?? {})) {
if (!field.resourceFields?.includes(name)
&& !(field.as === "itemObject" && Object.hasOwn(field.fieldKeys, name))) {
return `field ${port}.${name}`;
}
}
}
}
return undefined;
}
/** Optional fields may be omitted by authors, but supplied fields must reach the service. */
export function mappingSupportsRequest(mapping: GenerationWireMapping, value: unknown): boolean {
return unsupportedRequestField(mapping, value) === undefined;
}
/**
* Check structural port coverage and required item fields against the model declaration.
*
* A service may omit optional item capabilities. mappingSupportsRequest and final compilation
* additionally refuse requests that actually supply such an unmapped field.
*/
export function assertMappingCoversPorts(
table: GenerationPortTable,
mapping: GenerationWireMapping,
): void {
assert(mapping.capability.name === table.model,
`mapping names Capability ${mapping.capability.name} but the port table declares ${table.model}`);
assert(mapping.result === table.result,
`${table.model} mapping result ${mapping.result} differs from the port table`);
const declared = new Map(table.ports.map((port) => [port.name, port]));
Object.keys(mapping.fields).forEach((name) => assert(declared.has(name),
`${table.model} mapping names undeclared port ${name}`));
for (const port of table.ports) {
const field = mapping.fields[port.name];
assert(field !== undefined, `${table.model} mapping does not cover port ${port.name}`);
const subject = `${table.model} mapping for port ${port.name}`;
if (isMediaPort(port)) {
const media = port.value;
const itemFields = media.itemFields ?? [];
assert(itemFields.length > 0 || media.accepts.length === 1,
`${subject} accepts ${media.accepts.join(", ")}; declare one port per media role so each maps to one wire field`);
assert(field.as === "url" || field.as === "urlArray" || field.as === "itemObject",
`${subject} must resolve media to a URL`);
if (field.as === "url") {
assert(port.maxItems === 1, `${subject} uses url but the port accepts up to ${port.maxItems} items`);
}
const mappedFields = [
...(field.resourceFields ?? []),
...(field.as === "itemObject" ? Object.keys(field.fieldKeys) : []),
];
for (const item of itemFields) {
if (item.optional !== true) assert(mappedFields.includes(item.name),
`${subject} does not map required item field ${item.name}`);
}
for (const name of mappedFields) assert(itemFields.some((item) => item.name === name),
`${subject} maps unknown item field ${name}`);
continue;
}
if (port.maxItems > 1) {
assert(field.as === "valueArray", `${subject} must use valueArray because the port accepts several values`);
continue;
}
// A single-value port may still be written as a wire array when the service types it that way.
assert(field.as === "value" || field.as === "string" || field.as === "valueArray",
`${subject} must write a scalar or a single-element array`);
}
const emitted = Object.values(mapping.fields).map((field) => field.field);
assert(new Set(emitted).size === emitted.length,
`${table.model} mapping writes one wire field from two ports`);
Object.keys(mapping.constants ?? {}).forEach((name) => assert(!emitted.includes(name),
`${table.model} mapping constant ${name} collides with a mapped port`));
assert(mapping.routes.length > 0, `${table.model} mapping declares no route`);
mapping.routes.forEach((route, index) => {
assert(route.model.trim().length > 0, `${table.model} route ${index} has an empty service model`);
(route.whenPresent ?? []).forEach((name) => assert(declared.has(name),
`${table.model} route ${index} names undeclared port ${name}`));
const unconditional = route.whenPresent === undefined || route.whenPresent.length === 0;
assert(unconditional === (index === mapping.routes.length - 1),
`${table.model} must end with exactly one unconditional route`);
});
}