@hypit/hypit 0.0.1 → 0.1.1

package/dist/public/model-kit.d.ts

@@ -0,0 +1,523 @@
+/** Opaque identity for one admitted byte resource. Equal bytes may have different identities. */
+type ResourceId = `res_${string}`;
+type RecordId = string;
+type LogicalOutputId = string;
+type NeedId = 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 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[];
+};
+type ResolvedModule = {
+    readonly manifest: ModuleManifest;
+};
+type ResolvedModuleClosure = {
+    readonly format: "hypit.closure@1";
+    readonly modules: readonly ResolvedModule[];
+};
+
+/** 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 Need = {
+    readonly id: NeedId;
+    readonly capability: CapabilityRef;
+    readonly returns: TypeRef;
+    readonly constraints: CanonicalValue;
+    readonly result: RecordId;
+};
+type NeedBinding = {
+    readonly id: NeedId;
+    readonly result: RecordId;
+};
+type BuildTarget = {
+    readonly output: LogicalOutputId;
+};
+type BuildOutputBinding = {
+    readonly output: LogicalOutputId;
+    readonly record: RecordId;
+    readonly type: TypeRef;
+};
+type ProducerStep = {
+    readonly id: StepId;
+    readonly producer: ProducerRef;
+    readonly inputs: Readonly<Record<string, RecordId>>;
+    readonly outputs: Readonly<Record<string, RecordId>>;
+    readonly needs: Readonly<Record<string, NeedBinding>>;
+};
+type BuildGoal = {
+    readonly record: RecordId;
+    readonly type: TypeRef;
+};
+type BuildPlan = {
+    readonly format: "hypit.plan@1";
+    readonly steps: readonly ProducerStep[];
+    readonly goals: readonly BuildGoal[];
+    /** Every Logical Output reached by the selected execution, independent of how it was supplied. */
+    readonly outputBindings: readonly BuildOutputBinding[];
+};
+type LinkedProgram = {
+    readonly closure: ResolvedModuleClosure;
+    readonly records: readonly TypedRecord[];
+};
+type StepState = {
+    readonly id: StepId;
+    readonly status: "pending" | "complete";
+};
+type InvokeProducerCommand = {
+    readonly kind: "invoke-producer";
+    readonly id: CommandId;
+    readonly step: StepId;
+    readonly producer: ProducerRef;
+    readonly inputs: Readonly<Record<string, RecordId>>;
+};
+type FulfillNeedCommand = {
+    readonly kind: "fulfill-need";
+    readonly id: CommandId;
+    readonly need: Need;
+};
+type CoreCommand = InvokeProducerCommand | FulfillNeedCommand;
+type BuildDiagnostic = {
+    readonly code: string;
+    readonly message: string;
+    readonly subject?: string;
+};
+/** Materialized read/execution view. Durable Stores persist Definition + Facts, never this object. */
+type BuildState = {
+    readonly format: "hypit.build@1";
+    readonly program: LinkedProgram;
+    readonly plan: BuildPlan;
+    readonly targets: readonly BuildTarget[];
+    readonly status: "active" | "complete" | "failed";
+    readonly records: readonly TypedRecord[];
+    readonly steps: readonly StepState[];
+    readonly needs: readonly Need[];
+    readonly outstanding: readonly CoreCommand[];
+    readonly diagnostics: readonly BuildDiagnostic[];
+};
+
+type FragmentInputRef = {
+    readonly kind: "fragment-input";
+    readonly name: string;
+};
+type FragmentOperationRef = {
+    readonly kind: "fragment-operation";
+    readonly operation: string;
+};
+type FragmentValueRef = FragmentInputRef | FragmentOperationRef;
+type FragmentOperationResult = {
+    readonly kind: "output";
+    readonly name: string;
+} | {
+    readonly kind: "need";
+    readonly name: string;
+};
+type FragmentOperation = {
+    readonly id: string;
+    readonly producer: ProducerRef;
+    readonly inputs: Readonly<Record<string, FragmentValueRef>>;
+    readonly result: FragmentOperationResult;
+};
+type FragmentExport = {
+    readonly name: string;
+    readonly type: TypeRef;
+    readonly root: FragmentOperationRef;
+};
+type GraphFragment = {
+    readonly format: "hypit.fragment@1";
+    readonly id: string;
+    readonly inputs: readonly {
+        readonly name: string;
+        readonly type: TypeRef;
+    }[];
+    readonly operations: readonly FragmentOperation[];
+    readonly exports: readonly FragmentExport[];
+};
+declare function sealGraphFragment(fragment: Omit<GraphFragment, "format" | "id">): GraphFragment;
+
+/** One package contribution understood only by the Host that owns its ABI. */
+type HostFacet = {
+    readonly abi: string;
+    readonly offers?: readonly string[];
+    readonly implementation: unknown;
+};
+
+type Awaitable<T> = T | Promise<T>;
+type TypeValidatorContext = {
+    readonly type: TypeRef;
+    readonly value: StoredValue;
+};
+type TypeValidatorHandler = (context: TypeValidatorContext) => void | Promise<void>;
+type ProducerHandlerResult = {
+    readonly outputs: Readonly<Record<string, StoredValue>>;
+    readonly needs: Readonly<Record<string, CanonicalValue>>;
+};
+/**
+ * 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>>;
+};
+type ProducerHandler = (context: ProducerHandlerContext) => Awaitable<ProducerHandlerResult>;
+/** Enumerable deterministic Producer handler owned by its package. */
+type ProducerFacet = {
+    readonly producer: ProducerRef;
+    readonly handler: ProducerHandler;
+};
+/** One input whose value will exist only after an upstream Build step has run. */
+type PlannedNeedInput = {
+    readonly input: string;
+    readonly record: string;
+    readonly sourceStep?: string;
+    /** Capability-owned semantic role when the value represents media, such as image or audio. */
+    readonly role?: string;
+};
+/**
+ * The complete support-relevant request known before external work starts. Values produced later
+ * are represented by input slots; their eventual StoredValues are execution bindings, not missing
+ * author intent. A slot may be a Resource or a structured value.
+ */
+type PlannedNeedSpecification = {
+    readonly constraints: CanonicalValue;
+    readonly pendingInputs: readonly PlannedNeedInput[];
+};
+/** Package-owned, presentation-neutral reading of one request. */
+type PlannedNeedPresentation = {
+    readonly fields: Readonly<Record<string, readonly CanonicalValue[]>>;
+    readonly references: Readonly<Record<string, number>>;
+};
+type PlannedNeedFacet = {
+    readonly producer: ProducerRef;
+    readonly port: string;
+    readonly capability: CapabilityRef;
+    plan(input: {
+        readonly state: BuildState;
+        readonly step: string;
+        readonly port: string;
+    }): PlannedNeedSpecification | undefined;
+    present?(specification: PlannedNeedSpecification): PlannedNeedPresentation;
+};
+/** Package-owned semantic validator. */
+type TypeValidatorFacet = {
+    readonly type: TypeRef;
+    readonly handler: TypeValidatorHandler;
+};
+/** Trusted deterministic implementation package; it selects no Provider or Runtime infrastructure. */
+type ComponentPackage = {
+    readonly producers?: readonly ProducerFacet[];
+    readonly validators?: readonly TypeValidatorFacet[];
+    /** Planning knowledge owned by the package that declares the external request. */
+    readonly plannedNeeds?: readonly PlannedNeedFacet[];
+};
+
+/**
+ * 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 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;
+
+/**
+ * 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>>;
+};
+
+type PlannedExactModelMediaReference = {
+    readonly port: string;
+    readonly role: GenerationMediaBinding["role"];
+    readonly fields?: GenerationMediaBinding["fields"];
+    readonly record: string;
+    readonly sourceStep?: string;
+    /** The Blob already exists in this disposable planning view. */
+    readonly available: boolean;
+};
+type PlannedExactModelRequest = {
+    readonly model: string;
+    /** Every authored scalar and Text port value, plus media values whose Blobs already exist. */
+    readonly ports: GenerationRequestDraft["ports"];
+    /** Declared media edges whose files will be produced by an upstream Build step. */
+    readonly pendingMedia: readonly PlannedExactModelMediaReference[];
+    /** True only when the executable Need already exists and has passed full request validation. */
+    readonly complete: boolean;
+};
+/**
+ * One exact model endpoint. The model declares which input ports it accepts;
+ * its request Schema and semantic validator are derived from that declaration,
+ * so the Capability name, the accepted media roles and the port cardinalities
+ * have exactly one source of truth.
+ */
+type ExactModelEndpointSpec = {
+    readonly key: string;
+    readonly requestTypeName: string;
+    readonly producerName: string;
+    readonly ports: GenerationPortTable;
+};
+type ExactModelEndpoint = {
+    readonly key: string;
+    readonly requestType: TypeRef;
+    readonly capability: CapabilityRef;
+    readonly producer: ProducerRef;
+    readonly returns: TypeRef;
+    readonly draftType: TypeRef;
+    readonly finalizeProducer: ProducerRef;
+    readonly mediaBindings: Readonly<Record<string, ExactModelMediaBindingEndpoint>>;
+    readonly textBindings: Readonly<Record<string, ExactModelTextBindingEndpoint>>;
+    readonly ports: GenerationPortTable;
+    readonly fragment: ReturnType<typeof sealGraphFragment>;
+};
+type ExactModelMediaBindingEndpoint = {
+    readonly port: string;
+    readonly type: TypeRef;
+    readonly producer: ProducerRef;
+};
+type ExactModelTextBindingEndpoint = {
+    readonly port: string;
+    readonly producer: ProducerRef;
+};
+type ExactModelMediaInput = {
+    /** Stable local input name inside this Fragment shape. */
+    readonly name: string;
+    /** Exact model media port receiving the artifact. */
+    readonly port: string;
+};
+type ExactModelTextInput = {
+    /** Stable local input name inside this Fragment shape. */
+    readonly name: string;
+    /** Exact model text port receiving the Text value. */
+    readonly port: string;
+};
+type ExactModelModule<Key extends string = string> = {
+    readonly module: ModuleRef;
+    readonly manifest: ModuleManifest;
+    /** Keyed by the endpoint keys declared by the module. */
+    readonly endpoints: Readonly<Record<Key, ExactModelEndpoint>>;
+    readonly component: ComponentPackage & {
+        readonly validators: readonly TypeValidatorFacet[];
+        readonly producers: readonly ProducerFacet[];
+        readonly plannedNeeds: readonly PlannedNeedFacet[];
+    };
+    /** Inert declaration of these exact models for Hosts that address one directly. */
+    readonly hostFacet: ExactModelHostFacet;
+};
+declare const exactModelHostAbi = "hypit.exact-model-host@1";
+/**
+ * What one installed package can generate, named exactly, for a Host that drives a
+ * single model without a Build. It carries no Provider choice and no Runtime state;
+ * the Host still resolves who fulfils the Capability.
+ */
+type ExactModelHostFacet = HostFacet & {
+    readonly abi: typeof exactModelHostAbi;
+    /** The exact model names this package declares, in declaration order. */
+    readonly offers: readonly string[];
+    readonly implementation: {
+        readonly endpoints: readonly ExactModelEndpoint[];
+    };
+};
+/** Read every exact model declared by one selected package's Host facets. */
+declare function exactModelsFromHostFacets(facets: readonly HostFacet[]): readonly ExactModelEndpoint[];
+type DefineExactModelModuleOptions<Key extends string = string> = {
+    readonly module: ModuleRef;
+    readonly endpoints: readonly (Omit<ExactModelEndpointSpec, "key"> & {
+        readonly key: Key;
+    })[];
+};
+/**
+ * Read one exact-model request from its declared assembly graph.
+ *
+ * This follows only the exact producers published by the model Host facet. It never searches for
+ * object shapes or guesses which upstream record "looks like" a request. Missing media stays a
+ * symbolic graph edge; scalar parameters and authored Text remain available before the file exists.
+ */
+declare function plannedExactModelRequest(state: BuildState, stepId: string, needPort: string, endpoint: ExactModelEndpoint): PlannedExactModelRequest | undefined;
+/**
+ * Builds the repetitive nominal shell around an exact model request. The model package still owns
+ * every field, constraint and model name; this helper only wires Type -> Producer -> Need -> Fragment.
+ */
+declare function defineExactModelModule<const Key extends string>(options: DefineExactModelModuleOptions<Key>): ExactModelModule<Key>;
+declare function exactModelMediaInputNames(name: string): {
+    readonly artifact: string;
+    readonly binding: string;
+};
+declare function exactModelTextInputName(name: string): string;
+/**
+ * Expand one exact-model invocation into a deterministic request-assembly
+ * graph. Every runtime-produced media artifact remains a real Fragment input;
+ * the fold only constructs the Provider-facing request after those inputs are
+ * available.
+ */
+declare function createExactModelPrimaryGenerationFragment(endpoint: ExactModelEndpoint, mediaInputs?: readonly ExactModelMediaInput[], textInputs?: readonly ExactModelTextInput[]): GraphFragment;
+
+export { createExactModelPrimaryGenerationFragment, defineExactModelModule, exactModelHostAbi, exactModelMediaInputNames, exactModelTextInputName, exactModelsFromHostFacets, plannedExactModelRequest };
+export type { DefineExactModelModuleOptions, ExactModelEndpoint, ExactModelEndpointSpec, ExactModelHostFacet, ExactModelMediaBindingEndpoint, ExactModelMediaInput, ExactModelModule, ExactModelTextBindingEndpoint, ExactModelTextInput, PlannedExactModelMediaReference, PlannedExactModelRequest };