@hypit/hypit 0.0.1 → 0.1.0

package/dist/public/generation.d.ts

@@ -0,0 +1,591 @@
+/** Opaque identity for one admitted byte resource. Equal bytes may have different identities. */
+type ResourceId = `res_${string}`;
+type RecordId = string;
+type StepId = string;
+type CommandId = string;
+type ModuleRef = {
+    readonly name: string;
+    readonly version: string;
+};
+/**
+ * A Type is its owning Module and its name, and nothing else is compared. Two Types whose values
+ * carry identical shapes are distinct, so one is refused where the other is declared — there is no
+ * structural fallback to fall back to.
+ */
+type TypeRef = {
+    readonly module: ModuleRef;
+    readonly name: string;
+};
+type ProducerRef = {
+    readonly module: ModuleRef;
+    readonly name: string;
+};
+type CapabilityRef = {
+    readonly module: ModuleRef;
+    readonly name: string;
+};
+
+type CanonicalValue = null | boolean | number | string | readonly CanonicalValue[] | {
+    readonly [key: string]: CanonicalValue;
+};
+type BlobRef = {
+    readonly kind: "blob";
+    /** One admitted resource instance. Equal bytes admitted twice keep distinct identities. */
+    readonly resource: ResourceId;
+    readonly size: number;
+    readonly mediaType: string;
+};
+type StoredValue = {
+    readonly kind: "inline";
+    readonly value: CanonicalValue;
+} | BlobRef;
+type ValueSchema = {
+    readonly kind: "null";
+} | {
+    readonly kind: "boolean";
+} | {
+    readonly kind: "number";
+    readonly integer?: boolean;
+    readonly minimum?: number;
+    readonly maximum?: number;
+} | {
+    readonly kind: "string";
+    readonly enum?: readonly string[];
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    /** UI-neutral semantic format shared by authoring, validation and tools. */
+    readonly format?: "color";
+} | {
+    readonly kind: "literal";
+    readonly value: CanonicalValue;
+} | {
+    readonly kind: "array";
+    readonly items: ValueSchema;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+} | {
+    readonly kind: "object";
+    readonly fields: Readonly<Record<string, ObjectFieldSchema>>;
+    readonly allowUnknown?: boolean;
+} | {
+    readonly kind: "oneOf";
+    readonly variants: readonly ValueSchema[];
+} | {
+    readonly kind: "blob";
+    readonly mediaTypes?: readonly string[];
+    readonly maxBytes?: number;
+};
+type ObjectFieldSchema = {
+    readonly schema: ValueSchema;
+    readonly optional?: boolean;
+};
+
+type ModuleDependency = {
+    readonly module: ModuleRef;
+};
+type TypeDeclaration = {
+    readonly name: string;
+};
+type PortDeclaration = {
+    readonly name: string;
+    readonly type: TypeRef;
+};
+type NeedPortDeclaration = {
+    readonly name: string;
+    readonly capability: CapabilityRef;
+    readonly returns: TypeRef;
+};
+type CapabilityDeclaration = {
+    readonly name: string;
+    readonly returns: TypeRef;
+};
+type ProducerDeclaration = {
+    readonly name: string;
+    readonly inputs: readonly PortDeclaration[];
+    readonly outputs: readonly PortDeclaration[];
+    readonly needs: readonly NeedPortDeclaration[];
+};
+type ModuleManifest = {
+    readonly format: "hypit.module@1";
+    readonly name: string;
+    readonly version: string;
+    readonly dependencies: readonly ModuleDependency[];
+    readonly types: readonly TypeDeclaration[];
+    readonly capabilities: readonly CapabilityDeclaration[];
+    readonly producers: readonly ProducerDeclaration[];
+};
+
+/** One typed value in the graph; semantic validation happens at the Host admission boundary. */
+type TypedRecord = {
+    readonly id: RecordId;
+    readonly type: TypeRef;
+    readonly value: StoredValue;
+};
+type InvokeProducerCommand = {
+    readonly kind: "invoke-producer";
+    readonly id: CommandId;
+    readonly step: StepId;
+    readonly producer: ProducerRef;
+    readonly inputs: Readonly<Record<string, RecordId>>;
+};
+
+type TypeValidatorContext = {
+    readonly type: TypeRef;
+    readonly value: StoredValue;
+};
+/**
+ * Pure compute context. Artifact bytes, credentials, network and stores are deliberately absent;
+ * those effects must cross an explicit Need into a Provider.
+ */
+type ProducerHandlerContext = {
+    readonly command: InvokeProducerCommand;
+    readonly producer: ProducerRef;
+    readonly inputs: Readonly<Record<string, TypedRecord>>;
+};
+
+/** Host-side semantic refinements for the shared generated-media contracts. */
+declare const generationComponent: {
+    producers: ({
+        producer: {
+            module: {
+                readonly name: "@hypit/generation";
+                readonly version: "1";
+            };
+            name: string;
+        };
+        handler: ({ inputs }: ProducerHandlerContext) => {
+            outputs: {
+                audio: BlobRef;
+            };
+            needs: {};
+        };
+    } | {
+        producer: {
+            module: {
+                readonly name: "@hypit/generation";
+                readonly version: "1";
+            };
+            name: string;
+        };
+        handler: ({ inputs }: ProducerHandlerContext) => {
+            outputs: {
+                image: BlobRef;
+            };
+            needs: {};
+        };
+    } | {
+        producer: {
+            module: {
+                readonly name: "@hypit/generation";
+                readonly version: "1";
+            };
+            name: string;
+        };
+        handler: ({ inputs }: ProducerHandlerContext) => {
+            outputs: {
+                video: BlobRef;
+            };
+            needs: {};
+        };
+    })[];
+    validators: {
+        type: {
+            module: {
+                readonly name: "@hypit/generation";
+                readonly version: "1";
+            };
+            name: string;
+        };
+        handler: ({ value }: TypeValidatorContext) => void;
+    }[];
+};
+
+type GeneratedImageSet = {
+    readonly images: readonly BlobRef[];
+};
+type GeneratedVideoSet = {
+    readonly videos: readonly BlobRef[];
+};
+type GeneratedAudioSet = {
+    readonly audios: readonly BlobRef[];
+};
+type GeneratedImageSetContent = GeneratedImageSet;
+type GeneratedVideoSetContent = GeneratedVideoSet;
+type GeneratedAudioSetContent = GeneratedAudioSet;
+
+declare function assertGenerationBlobRef(value: unknown, mediaPrefix?: "image/" | "video/" | "audio/"): asserts value is BlobRef;
+/** Canonical request value; Core supplies the enclosing Need identity. */
+declare function sealGenerationRequest<T extends object>(content: T): T;
+declare function sealGeneratedImageSet(content: GeneratedImageSetContent): GeneratedImageSet;
+declare function verifyGeneratedImageSet(value: unknown): asserts value is GeneratedImageSet;
+declare function sealGeneratedVideoSet(content: GeneratedVideoSetContent): GeneratedVideoSet;
+declare function verifyGeneratedVideoSet(value: unknown): asserts value is GeneratedVideoSet;
+declare function sealGeneratedAudioSet(content: GeneratedAudioSetContent): GeneratedAudioSet;
+declare function verifyGeneratedAudioSet(value: unknown): asserts value is GeneratedAudioSet;
+
+declare const generationModuleRef: {
+    readonly name: "@hypit/generation";
+    readonly version: "1";
+};
+declare const generationTypes: {
+    audioSet: {
+        module: {
+            readonly name: "@hypit/generation";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    imageSet: {
+        module: {
+            readonly name: "@hypit/generation";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    videoSet: {
+        module: {
+            readonly name: "@hypit/generation";
+            readonly version: "1";
+        };
+        name: string;
+    };
+};
+declare const generationProducers: {
+    primaryAudio: {
+        module: {
+            readonly name: "@hypit/generation";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    primaryImage: {
+        module: {
+            readonly name: "@hypit/generation";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    primaryVideo: {
+        module: {
+            readonly name: "@hypit/generation";
+            readonly version: "1";
+        };
+        name: string;
+    };
+};
+declare const generationManifest: ModuleManifest;
+
+/**
+ * The closed vocabulary describing what one exact generation model accepts.
+ *
+ * A model's input ports are decided when the model is trained: which reference
+ * images, audio, video or text it can consume is a property of the model, not
+ * of the service reselling it. A Provider therefore never redeclares this
+ * shape; it only maps each declared port onto its own wire fields.
+ *
+ * Adding a port kind changes this package's public vocabulary, not one model's table.
+ */
+type GenerationMediaRole = "image" | "video" | "audio";
+type GenerationPortScalarKind = {
+    readonly kind: "text";
+    readonly maxChars?: number;
+} | {
+    readonly kind: "token";
+    readonly minLength: number;
+    readonly maxLength: number;
+} | {
+    readonly kind: "enum";
+    readonly values: readonly (string | number)[];
+} | {
+    readonly kind: "number";
+    readonly integer?: boolean;
+    readonly minimum?: number;
+    readonly maximum?: number;
+} | {
+    readonly kind: "boolean";
+};
+/** A scalar carried alongside one media item, such as a trimmed excerpt boundary. */
+type GenerationPortItemField = {
+    readonly name: string;
+    readonly value: GenerationPortScalarKind;
+    readonly optional?: boolean;
+};
+/** Relation between two item fields of the same media item, such as a trim window. */
+type GenerationItemRequirement = {
+    readonly kind: "strictlyIncreasing";
+    readonly fields: readonly string[];
+};
+type GenerationMediaPortKind = {
+    readonly kind: "media";
+    readonly accepts: readonly GenerationMediaRole[];
+    readonly itemFields?: readonly GenerationPortItemField[];
+    readonly itemRequires?: readonly GenerationItemRequirement[];
+};
+type GenerationPortKind = GenerationPortScalarKind | GenerationMediaPortKind;
+type GenerationPortBase = {
+    readonly name: string;
+    readonly minItems: number;
+    readonly maxItems: number;
+};
+type GenerationScalarPort = GenerationPortBase & {
+    readonly value: GenerationPortScalarKind;
+};
+type GenerationMediaPort = GenerationPortBase & {
+    readonly value: GenerationMediaPortKind;
+};
+/**
+ * One named input port. `minItems: 0` means the model works without it;
+ * `maxItems: 1` means the port carries a single value rather than a list.
+ */
+type GenerationPort = GenerationScalarPort | GenerationMediaPort;
+type GenerationPortRequirement = {
+    readonly kind: "atMostOneOf";
+    readonly ports: readonly string[];
+} | {
+    readonly kind: "requiresPresent";
+    readonly port: string;
+    readonly needs: readonly string[];
+}
+/** This port needs company, but any one of several will do — reference audio needs a visual. */
+ | {
+    readonly kind: "requiresAnyOf";
+    readonly port: string;
+    readonly anyOf: readonly string[];
+}
+/** A shared budget several ports draw from, such as a total reference quota. */
+ | {
+    readonly kind: "weightedTotal";
+    readonly weights: Readonly<Record<string, number>>;
+    readonly maximum: number;
+};
+type GenerationPortTable = {
+    /** Exact model identity; this is also the Capability name. */
+    readonly model: string;
+    readonly result: "audio" | "image" | "video";
+    readonly ports: readonly GenerationPort[];
+    readonly requires: readonly GenerationPortRequirement[];
+};
+type GenerationMediaValue = {
+    readonly role: GenerationMediaRole;
+    readonly artifact: BlobRef;
+    readonly fields?: Readonly<Record<string, string | number | boolean>>;
+};
+type GenerationPortValue = string | number | boolean | GenerationMediaValue;
+declare function isMediaPort(port: GenerationPort): port is GenerationMediaPort;
+declare function assertGenerationPortTable(value: GenerationPortTable): void;
+declare function sealGenerationPortTable(value: GenerationPortTable): GenerationPortTable;
+declare function generationPort(table: GenerationPortTable, name: string): GenerationPort;
+
+type Text = {
+    readonly value: string;
+};
+
+/**
+ * The one request envelope every exact model uses. A Provider reads ports by
+ * name and never learns a model-specific field layout, so the same wire mapping
+ * mechanism serves every model and every service reselling it.
+ */
+type GenerationRequest = {
+    /** An absent port is an omitted key. A present port always carries at least one value. */
+    readonly ports: Readonly<Record<string, readonly GenerationPortValue[]>>;
+};
+/**
+ * A request while graph inputs are still being attached. It is deliberately a
+ * Providers can only receive the finalized request after the exact model
+ * package has checked every port rule.
+ */
+type GenerationRequestDraft = {
+    readonly ports: Readonly<Record<string, readonly GenerationPortValue[]>>;
+};
+/** Authored instructions for attaching one graph Blob edge to one media port. */
+type GenerationMediaBinding = {
+    readonly role: GenerationMediaRole;
+    readonly fields?: Readonly<Record<string, string | number | boolean>>;
+};
+/** Schema for the non-artifact half of one media-port attachment. */
+declare function mediaBindingSchemaFromPort(port: GenerationMediaPort): ValueSchema;
+type GenerationPortSubset = {
+    /**
+     * Ports supplied later rather than by this value. A duration-dependent
+     * compilation authors everything else first and completes the request when
+     * the missing fact exists.
+     */
+    readonly omit?: readonly string[];
+    /**
+     * Ports that may be absent while a graph is still attaching values. If they
+     * are present, their item and cardinality rules are still checked. Exact
+     * Result writing never uses this escape hatch.
+     */
+    readonly defer?: readonly string[];
+};
+/** Derive the Schema of the port map alone, optionally leaving some ports for later. */
+declare function portsObjectSchema(table: GenerationPortTable, options?: GenerationPortSubset): ValueSchema;
+/** Derive the structural Schema of one model's request from its port table. */
+declare function requestSchemaFromPorts(table: GenerationPortTable): ValueSchema;
+/** Structural schema for the model-owned request draft used by graph assembly. */
+declare function requestDraftSchemaFromPorts(table: GenerationPortTable): ValueSchema;
+/**
+ * Full standalone verification against the port table. Core's generic schema
+ * admission runs first; this adds the facts a Schema cannot state, such as the
+ * media type each role demands and the model's port combination rules.
+ */
+declare function verifyPortsAgainstTable(table: GenerationPortTable, value: unknown, options?: GenerationPortSubset): void;
+declare function verifyRequestDraftAgainstPorts(table: GenerationPortTable, value: unknown): asserts value is GenerationRequestDraft;
+declare function sealGenerationRequestDraft(table: GenerationPortTable, ports: Readonly<Record<string, readonly GenerationPortValue[]>>): GenerationRequestDraft;
+declare function verifyGenerationMediaBinding(port: GenerationMediaPort, value: unknown): asserts value is GenerationMediaBinding;
+declare function sealGenerationMediaBinding(port: GenerationMediaPort, value: GenerationMediaBinding): GenerationMediaBinding;
+/**
+ * Attach one Blob supplied by a real graph edge. The returned draft contains
+ * the Provider-facing value, while the Graph preserves where that Blob came
+ * from; no lineage or project metadata is copied through the payload.
+ */
+declare function bindGenerationMedia(table: GenerationPortTable, draft: GenerationRequestDraft, portName: string, binding: GenerationMediaBinding, artifact: BlobRef): GenerationRequestDraft;
+/** Attach one graph Text edge to an exact text port without hiding it in metadata. */
+declare function bindGenerationText(table: GenerationPortTable, draft: GenerationRequestDraft, portName: string, text: Text): GenerationRequestDraft;
+declare function finalizeGenerationRequestDraft(table: GenerationPortTable, draft: GenerationRequestDraft): GenerationRequest;
+declare function verifyRequestAgainstPorts(table: GenerationPortTable, value: unknown): asserts value is GenerationRequest;
+/** Build one canonical request for a model from its declared ports. */
+declare function sealGenerationPortRequest(table: GenerationPortTable, ports: Readonly<Record<string, readonly GenerationPortValue[]>>): GenerationRequest;
+
+/**
+ * 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.
+ */
+type GenerationArtifactUrlResolver = (artifact: BlobRef) => Promise<string>;
+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 whenAbsent?: CanonicalValue;
+}
+/** Several media items written as one array of resolved URLs. */
+ | {
+    readonly as: "urlArray";
+    readonly field: 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 fieldKeys: Readonly<Record<string, string>>;
+    readonly whenAbsent?: CanonicalValue;
+};
+/** Selects the service-side model identifier. The first matching route wins. */
+type GenerationWireRoute = {
+    readonly model: string;
+    readonly whenPresent?: readonly string[];
+};
+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>>;
+};
+type GenerationWireRequest = {
+    readonly model: string;
+    readonly input: CanonicalValue;
+};
+declare function selectWireModel(mapping: GenerationWireMapping, present: ReadonlySet<string>): string;
+/**
+ * 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.
+ */
+declare function selectWireModelForRequest(mapping: GenerationWireMapping, request: GenerationRequest, pendingPorts?: readonly string[]): string;
+/**
+ * Compile one port-shaped request into one service payload. The engine needs
+ * only the mapping and the request, never the model package.
+ */
+declare function compileWireRequest(mapping: GenerationWireMapping, request: GenerationRequest, resolve: GenerationArtifactUrlResolver): Promise<GenerationWireRequest>;
+/** Does this request only use ports this mapping can write? Needs no model package. */
+declare function mappingSupportsRequest(mapping: GenerationWireMapping, value: unknown): boolean;
+/**
+ * Prove one service mapping covers every port the model declares.
+ *
+ * This is the check the old hand-written per-model translators could not have:
+ * a forgotten reference role or item field used to surface only after a paid
+ * generation returned the wrong result.
+ */
+declare function assertMappingCoversPorts(table: GenerationPortTable, mapping: GenerationWireMapping): void;
+
+declare const generationResourceSchema: {
+    readonly kind: "string";
+    readonly minLength: 71;
+    readonly maxLength: 71;
+};
+declare const generationPromptSchema: {
+    readonly kind: "string";
+    readonly minLength: 1;
+    readonly maxLength: 20000;
+};
+declare const generationBlobRefSchema: {
+    readonly kind: "object";
+    readonly fields: {
+        readonly kind: {
+            readonly schema: {
+                readonly kind: "literal";
+                readonly value: "blob";
+            };
+        };
+        readonly resource: {
+            readonly schema: {
+                readonly kind: "string";
+                readonly minLength: 71;
+                readonly maxLength: 71;
+            };
+        };
+        readonly size: {
+            readonly schema: {
+                readonly kind: "number";
+                readonly integer: true;
+                readonly minimum: 0;
+            };
+        };
+        readonly mediaType: {
+            readonly schema: {
+                readonly kind: "string";
+                readonly minLength: 1;
+                readonly maxLength: 255;
+            };
+        };
+    };
+};
+declare function generationObjectSchema(fields: Readonly<Record<string, ObjectFieldSchema>>): ValueSchema;
+declare const generatedImageSetSchema: ValueSchema;
+declare const generatedVideoSetSchema: ValueSchema;
+declare const generatedAudioSetSchema: ValueSchema;
+
+export { assertGenerationBlobRef, assertGenerationPortTable, assertMappingCoversPorts, bindGenerationMedia, bindGenerationText, compileWireRequest, finalizeGenerationRequestDraft, generatedAudioSetSchema, generatedImageSetSchema, generatedVideoSetSchema, generationBlobRefSchema, generationComponent, generationManifest, generationModuleRef, generationObjectSchema, generationPort, generationProducers, generationPromptSchema, generationResourceSchema, generationTypes, isMediaPort, mappingSupportsRequest, mediaBindingSchemaFromPort, portsObjectSchema, requestDraftSchemaFromPorts, requestSchemaFromPorts, sealGeneratedAudioSet, sealGeneratedImageSet, sealGeneratedVideoSet, sealGenerationMediaBinding, sealGenerationPortRequest, sealGenerationPortTable, sealGenerationRequest, sealGenerationRequestDraft, selectWireModel, selectWireModelForRequest, verifyGeneratedAudioSet, verifyGeneratedImageSet, verifyGeneratedVideoSet, verifyGenerationMediaBinding, verifyPortsAgainstTable, verifyRequestAgainstPorts, verifyRequestDraftAgainstPorts };
+export type { GeneratedAudioSet, GeneratedAudioSetContent, GeneratedImageSet, GeneratedImageSetContent, GeneratedVideoSet, GeneratedVideoSetContent, GenerationArtifactUrlResolver, GenerationFieldMapping, GenerationItemRequirement, GenerationMediaBinding, GenerationMediaPort, GenerationMediaPortKind, GenerationMediaRole, GenerationMediaValue, GenerationPort, GenerationPortItemField, GenerationPortKind, GenerationPortRequirement, GenerationPortScalarKind, GenerationPortSubset, GenerationPortTable, GenerationPortValue, GenerationRequest, GenerationRequestDraft, GenerationScalarPort, GenerationWireMapping, GenerationWireRequest, GenerationWireRoute };