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.

29.7 KB
Raw Blame
import type { AdmissionPackage, TypeValidatorFacet } from "@hypit/hypit/admission";
import type {
  ProducerPackage,
  PlannedNeedFacet,
  PlannedNeedPresentation,
  PlannedNeedSpecification,
  ProducerFacet,
  ProducerHandlerContext,
} from "@hypit/hypit/producer";
import { blobDependency, blobTypes } from "@hypit/hypit/blob";
import { sealGraphFragment } from "@hypit/hypit/author";
import type { Facet } from "@hypit/hypit/facet";
import {
  bindGenerationMedia,
  bindGenerationText,
  generationModuleRef,
  generationProducers,
  generationTypes,
  mediaBindingSchemaFromPort,
  requestDraftSchemaFromPorts,
  requestSchemaFromPorts,
  sealGenerationPortRequest,
  verifyGenerationMediaBinding,
  verifyRequestDraftAgainstPorts,
  verifyRequestAgainstPorts,
} from "@hypit/generation";
import type {
  GenerationMediaBinding,
  GenerationMediaPort,
  GenerationPortTable,
  GenerationRequest,
  GenerationRequestDraft,
} from "@hypit/generation";
import { textDependency, textTypes } from "@hypit/hypit/text";
import type { Text } from "@hypit/hypit/text";
import {
  canonicalize,
} from "@hypit/hypit/protocol";
import type {
  CanonicalValue,
  CapabilityRef,
  BuildState,
  ModuleManifest,
  ModuleRef,
  ProducerRef,
  TypeRef,
} from "@hypit/hypit/protocol";

export 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;
};

export 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.
 */
export type ExactModelEndpointSpec = {
  readonly key: string;
  readonly requestTypeName: string;
  readonly producerName: string;
  readonly ports: GenerationPortTable;
  /** Additional complete-request rules, after port and supplied-input validation. */
  readonly validateRequest?: (request: GenerationRequest) => void;
  /** Pure, synchronous checks of supplied values, in drafts and complete requests; throw to reject. */
  readonly validateInputs?: (inputs: GenerationRequestDraft) => void;
};

export 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 validateRequest: (request: unknown) => void;
  readonly validateDraft: (draft: unknown) => void;
  readonly sealRequest: (ports: GenerationRequest["ports"]) => GenerationRequest;
  readonly fragment: ReturnType<typeof sealGraphFragment>;
};

export type ExactModelMediaBindingEndpoint = {
  readonly port: string;
  readonly type: TypeRef;
  readonly producer: ProducerRef;
};

export type ExactModelTextBindingEndpoint = {
  readonly port: string;
  readonly producer: ProducerRef;
};

export type ExactModelMediaInput = {
  /** Stable local input name inside this Fragment shape. */
  readonly name: string;
  /** Exact model media port receiving the artifact. */
  readonly port: string;
};

export type ExactModelTextInput = {
  /** Stable local input name inside this Fragment shape. */
  readonly name: string;
  /** Exact model text port receiving the Text value. */
  readonly port: string;
};

export 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: (ProducerPackage & AdmissionPackage) & {
    readonly validators: readonly TypeValidatorFacet[];
    readonly producers: readonly ProducerFacet[];
    readonly plannedNeeds: readonly PlannedNeedFacet[];
  };
  /** Inert declaration of these exact models for consumers that address one directly. */
  readonly facet: ExactModelFacet;
};

export const exactModelFacetAbi = "hypit.exact-model@1";

/**
 * What one installed package can generate, named exactly, for a caller 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.
 */
export type ExactModelFacet = Facet & {
  readonly abi: typeof exactModelFacetAbi;
  /** The exact model names this package declares, in declaration order. */
  readonly offers: readonly string[];
  readonly implementation: { readonly endpoints: readonly ExactModelEndpoint[] };
};

function createExactModelFacet(endpoints: readonly ExactModelEndpoint[]): ExactModelFacet {
  assert(endpoints.length > 0, "an exact model facet declares no endpoint");
  return {
    abi: exactModelFacetAbi,
    offers: endpoints.map((item) => item.ports.model),
    implementation: { endpoints },
  };
}

/** Read every exact model declared by one selected package's exact-model facets. */
export function exactModelsFromFacets(
  facets: readonly Facet[],
): readonly ExactModelEndpoint[] {
  const found: ExactModelEndpoint[] = [];
  for (const facet of facets) {
    if (facet.abi !== exactModelFacetAbi) continue;
    const implementation = facet.implementation as { readonly endpoints?: unknown } | null;
    const declared = implementation === null ? undefined : implementation.endpoints;
    assert(Array.isArray(declared), `${exactModelFacetAbi} facet has an invalid implementation`);
    for (const item of declared as readonly unknown[]) {
      const endpoint = item as ExactModelEndpoint | null;
      assert(endpoint !== null && typeof endpoint === "object"
        && typeof endpoint.key === "string" && typeof endpoint.ports?.model === "string",
        `${exactModelFacetAbi} facet declares an invalid exact model`);
      found.push(endpoint);
    }
  }
  return found;
}

export type DefineExactModelModuleOptions<Key extends string = string> = {
  readonly module: ModuleRef;
  readonly endpoints: readonly (Omit<ExactModelEndpointSpec, "key"> & { readonly key: Key })[];
};

function assert(condition: unknown, message: string): asserts condition {
  if (!condition) throw new Error(message);
}

function endpointRef(module: ModuleRef, spec: ExactModelEndpointSpec) {
  const requestType = { module, name: spec.requestTypeName };
  const draftType = { module, name: `${spec.requestTypeName}Draft` };
  const capability = { module, name: spec.ports.model };
  const producer = { module, name: spec.producerName };
  const returns = spec.ports.result === "audio"
    ? generationTypes.audioSet
    : spec.ports.result === "image" ? generationTypes.imageSet : generationTypes.videoSet;
  const finalizeProducer = { module, name: `finalize-${spec.producerName}` };
  const mediaBindings = Object.fromEntries(spec.ports.ports
    .filter((port): port is GenerationMediaPort => port.value.kind === "media")
    .map((port) => [port.name, {
      port: port.name,
      type: { module, name: `${spec.requestTypeName}${pascal(port.name)}Binding` },
      producer: { module, name: `bind-${spec.producerName}-${port.name}` },
    } satisfies ExactModelMediaBindingEndpoint]));
  const textBindings = Object.fromEntries(spec.ports.ports
    .filter((port) => port.value.kind === "text")
    .map((port) => [port.name, {
      port: port.name,
      producer: { module, name: `bind-${spec.producerName}-${port.name}-text` },
    } satisfies ExactModelTextBindingEndpoint]));
  return {
    requestType,
    draftType,
    capability,
    producer,
    returns,
    finalizeProducer,
    mediaBindings,
    textBindings,
  };
}

function pascal(value: string): string {
  return value.replace(/(^|[^a-zA-Z0-9]+)([a-zA-Z0-9])/gu, (_whole, _boundary, letter: string) => letter.toUpperCase());
}

function inlineRequest(
  value: { readonly kind: string; readonly value?: CanonicalValue },
  subject: string,
): CanonicalValue {
  assert(value.kind === "inline" && value.value !== undefined, `${subject} must be an inline request`);
  return canonicalize(value.value);
}

function inlineValue<T>(
  value: { readonly kind: string; readonly value?: CanonicalValue },
  subject: string,
): T {
  assert(value.kind === "inline" && value.value !== undefined, `${subject} must be inline`);
  return canonicalize(value.value) as unknown as T;
}

function sameReference(
  left: { readonly module: ModuleRef; readonly name: string },
  right: { readonly module: ModuleRef; readonly name: string },
): boolean {
  return left.module.name === right.module.name
    && left.module.version === right.module.version
    && left.name === right.name;
}

/**
 * Read one exact-model request from its declared assembly graph.
 *
 * This follows only the exact producers published by the exact-model 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.
 */
export function plannedExactModelRequest(
  state: BuildState,
  stepId: string,
  needPort: string,
  endpoint: ExactModelEndpoint,
): PlannedExactModelRequest | undefined {
  const generationStep = state.plan.steps.find((step) => step.id === stepId);
  if (generationStep === undefined || !sameReference(generationStep.producer, endpoint.producer)) return undefined;
  const binding = generationStep.needs[needPort];
  if (binding === undefined) return undefined;

  const knownNeed = state.needs.find((need) => need.id === binding.id);
  if (knownNeed !== undefined) {
    endpoint.validateRequest(knownNeed.constraints);
    return {
      model: endpoint.ports.model,
      ports: structuredClone((knownNeed.constraints as unknown as GenerationRequestDraft).ports),
      pendingMedia: [],
      complete: true,
    };
  }

  const records = new Map(state.records.map((record) => [record.id, record]));
  const producedBy = new Map(state.plan.steps.flatMap((step) =>
    Object.values(step.outputs).map((record) => [record, step] as const)));
  const requestRecord = generationStep.inputs.request;
  if (requestRecord === undefined) return undefined;
  const knownRequest = records.get(requestRecord);
  if (knownRequest !== undefined) {
    const request = inlineValue<GenerationRequest>(knownRequest.value, `${endpoint.ports.model} request`);
    endpoint.validateRequest(request);
    return { model: endpoint.ports.model, ports: structuredClone(request.ports), pendingMedia: [], complete: false };
  }
  const finalize = producedBy.get(requestRecord);
  if (finalize === undefined || !sameReference(finalize.producer, endpoint.finalizeProducer)) return undefined;
  const finalDraft = finalize.inputs.draft;
  if (finalDraft === undefined) return undefined;

  const pendingMedia: PlannedExactModelMediaReference[] = [];
  const visiting = new Set<string>();
  const rebuildDraft = (recordId: string): GenerationRequestDraft => {
    if (visiting.has(recordId)) throw new Error(`${endpoint.ports.model} request assembly contains a cycle at ${recordId}`);
    visiting.add(recordId);
    try {
      const record = records.get(recordId);
      if (record !== undefined) {
        const draft = inlineValue<GenerationRequestDraft>(record.value, `${endpoint.ports.model} request draft`);
        endpoint.validateDraft(draft);
        return draft;
      }
      const step = producedBy.get(recordId);
      if (step === undefined) throw new Error(`${endpoint.ports.model} request draft ${recordId} has no source`);
      const previousId = step.inputs.draft;
      if (previousId === undefined) throw new Error(`${step.id} does not declare its request draft input`);
      let draft = rebuildDraft(previousId);

      const textBinding = Object.values(endpoint.textBindings)
        .find((candidate) => sameReference(step.producer, candidate.producer));
      if (textBinding !== undefined) {
        const textId = step.inputs.text;
        const text = textId === undefined ? undefined : records.get(textId);
        if (text === undefined) throw new Error(`${step.id} has no authored Text input`);
        return bindGenerationText(
          endpoint.ports,
          draft,
          textBinding.port,
          inlineValue<Text>(text.value, `${step.id} Text`),
        );
      }

      const mediaBinding = Object.values(endpoint.mediaBindings)
        .find((candidate) => sameReference(step.producer, candidate.producer));
      if (mediaBinding === undefined) {
        throw new Error(`${step.id} is not part of ${endpoint.ports.model}'s declared request assembly`);
      }
      const bindingId = step.inputs.binding;
      const artifactId = step.inputs.artifact;
      const authoredBinding = bindingId === undefined ? undefined : records.get(bindingId);
      if (authoredBinding === undefined || artifactId === undefined) {
        throw new Error(`${step.id} is missing its authored media binding`);
      }
      const value = inlineValue<GenerationMediaBinding>(authoredBinding.value, `${step.id} media binding`);
      const port = endpoint.ports.ports.find((candidate): candidate is GenerationMediaPort =>
        candidate.name === mediaBinding.port && candidate.value.kind === "media");
      if (port === undefined) throw new Error(`${step.id} names undeclared media port ${mediaBinding.port}`);
      verifyGenerationMediaBinding(port, value);
      const artifact = records.get(artifactId);
      if (artifact?.value.kind === "blob") {
        draft = bindGenerationMedia(endpoint.ports, draft, mediaBinding.port, value, artifact.value);
      } else {
        pendingMedia.push({
          port: mediaBinding.port,
          role: value.role,
          ...(value.fields === undefined ? {} : { fields: structuredClone(value.fields) }),
          record: artifactId,
          ...(producedBy.get(artifactId) === undefined ? {} : { sourceStep: producedBy.get(artifactId)!.id }),
          available: false,
        });
      }
      return draft;
    } finally {
      visiting.delete(recordId);
    }
  };

  const draft = rebuildDraft(finalDraft);
  endpoint.validateDraft(draft);
  if (pendingMedia.length === 0) endpoint.validateRequest(draft);
  return {
    model: endpoint.ports.model,
    ports: structuredClone(draft.ports),
    pendingMedia,
    complete: false,
  };
}

function exactModelSpecification(planned: PlannedExactModelRequest): PlannedNeedSpecification {
  const ports = structuredClone(planned.ports) as Record<string, CanonicalValue[]>;
  for (const resource of planned.pendingMedia) {
    const items = ports[resource.port] ?? [];
    items.push(canonicalize({
      role: resource.role,
      slot: resource.record,
      ...(resource.fields === undefined ? {} : { fields: resource.fields }),
    }));
    ports[resource.port] = items;
  }
  return {
    constraints: canonicalize({ ports }),
    pendingInputs: planned.pendingMedia.map((resource) => ({
      input: resource.port,
      record: resource.record,
      ...(resource.sourceStep === undefined ? {} : { sourceStep: resource.sourceStep }),
      role: resource.role,
    })),
  };
}

function exactModelPresentation(
  endpoint: ExactModelEndpoint,
  specification: PlannedNeedSpecification,
): PlannedNeedPresentation {
  const request = specification.constraints as { readonly ports?: Readonly<Record<string, readonly CanonicalValue[]>> };
  const fields: Record<string, readonly CanonicalValue[]> = {};
  const references: Record<string, number> = {};
  for (const port of endpoint.ports.ports) {
    const values = request.ports?.[port.name] ?? [];
    if (port.value.kind !== "media") {
      if (values.length > 0) fields[port.name] = structuredClone(values);
      continue;
    }
    for (const value of values) {
      if (value === null || typeof value !== "object" || Array.isArray(value)) continue;
      const role = (value as { readonly role?: unknown }).role;
      if (typeof role === "string") references[role] = (references[role] ?? 0) + 1;
    }
  }
  return { fields, references };
}

function exactModelPlannedNeedFacet(endpoint: ExactModelEndpoint): PlannedNeedFacet {
  return {
    producer: endpoint.producer,
    port: "generation",
    capability: endpoint.capability,
    plan({ state, step, port }) {
      const planned = plannedExactModelRequest(state, step, port, endpoint);
      return planned === undefined ? undefined : exactModelSpecification(planned);
    },
    present: (specification) => exactModelPresentation(endpoint, specification),
  };
}

/**
 * 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.
 */
export function defineExactModelModule<const Key extends string>(
  options: DefineExactModelModuleOptions<Key>,
): ExactModelModule<Key> {
  assert(options.module.name.trim().length > 0 && options.module.version.trim().length > 0,
    "Exact model module identity is invalid");
  assert(options.endpoints.length > 0, `${options.module.name} declares no exact model endpoint`);
  const keys = options.endpoints.map((item) => item.key);
  assert(new Set(keys).size === keys.length, `${options.module.name} repeats an endpoint key`);
  const models = options.endpoints.map((item) => item.ports.model);
  assert(new Set(models).size === models.length, `${options.module.name} repeats an exact model`);
  const endpointData = options.endpoints.map((spec) => ({ spec, ...endpointRef(options.module, spec) }));

  const manifest: ModuleManifest = {
    format: "hypit.module@1",
    name: options.module.name,
    version: options.module.version,
    dependencies: [
      { module: generationModuleRef },
      blobDependency,
      textDependency,
    ],
    types: endpointData.flatMap((item) => [
      {
        name: item.requestType.name,
      },
      {
        name: item.draftType.name,
      },
      ...Object.values(item.mediaBindings).map((binding) => {
        const port = item.spec.ports.ports.find((candidate): candidate is GenerationMediaPort =>
          candidate.name === binding.port && candidate.value.kind === "media");
        assert(port !== undefined, `${item.spec.key} media binding ${binding.port} has no port`);
        return { name: binding.type.name };
      }),
    ]),
    capabilities: endpointData.map((item) => ({
      name: item.capability.name,
      returns: item.returns,
    })),
    producers: endpointData.flatMap((item) => [
      {
        name: item.producer.name,
        inputs: [{ name: "request", type: item.requestType }],
        outputs: [],
        needs: [{
          name: "generation",
          capability: item.capability,
          returns: item.returns,
        }],
      },
      ...Object.values(item.mediaBindings).map((binding) => ({
        name: binding.producer.name,
        inputs: [
          { name: "draft", type: item.draftType },
          { name: "binding", type: binding.type },
          { name: "artifact", type: blobTypes.blob },
        ],
        outputs: [{ name: "draft", type: item.draftType }],
        needs: [],
      })),
      ...Object.values(item.textBindings).map((binding) => ({
        name: binding.producer.name,
        inputs: [
          { name: "draft", type: item.draftType },
          { name: "text", type: textTypes.text },
        ],
        outputs: [{ name: "draft", type: item.draftType }],
        needs: [],
      })),
      {
        name: item.finalizeProducer.name,
        inputs: [{ name: "draft", type: item.draftType }],
        outputs: [{ name: "request", type: item.requestType }],
        needs: [],
      },
    ]),
  };

  const endpoints = Object.fromEntries(endpointData.map((item): [Key, ExactModelEndpoint] => {
    const validateRequest = (request: unknown): void => {
      verifyRequestAgainstPorts(item.spec.ports, request);
      item.spec.validateInputs?.(request);
      item.spec.validateRequest?.(request);
    };
    const validateDraft = (draft: unknown): void => {
      verifyRequestDraftAgainstPorts(item.spec.ports, draft);
      item.spec.validateInputs?.(draft);
    };
    const fragment = sealGraphFragment({
      inputs: [{ name: "request", type: item.requestType }],
      operations: [{
        id: "generate",
        producer: item.producer,
        inputs: { request: { kind: "fragment-input", name: "request" } },
        result: { kind: "need", name: "generation" },
      }],
      exports: [{
        name: "result",
        type: item.returns,
        root: { kind: "fragment-operation", operation: "generate" },
      }],
    });
    return [item.spec.key, {
      key: item.spec.key,
      requestType: item.requestType,
      capability: item.capability,
      producer: item.producer,
      returns: item.returns,
      draftType: item.draftType,
      finalizeProducer: item.finalizeProducer,
      mediaBindings: item.mediaBindings,
      textBindings: item.textBindings,
      ports: item.spec.ports,
      validateRequest,
      validateDraft,
      sealRequest(ports) {
        const request = sealGenerationPortRequest(item.spec.ports, ports);
        item.spec.validateInputs?.(request);
        item.spec.validateRequest?.(request);
        return request;
      },
      fragment,
    } satisfies ExactModelEndpoint];
  }));

  return {
    module: { ...options.module },
    manifest,
    endpoints: endpoints as Readonly<Record<Key, ExactModelEndpoint>>,
    facet: createExactModelFacet(Object.values(endpoints) as readonly ExactModelEndpoint[]),
    component: {
      validators: endpointData.flatMap((item) => [{
        type: item.requestType,
        handler({ value }) {
          endpoints[item.spec.key]!.validateRequest(inlineRequest(value, item.spec.key));
        },
      }, {
        type: item.draftType,
        handler({ value }) {
          endpoints[item.spec.key]!.validateDraft(inlineRequest(value, `${item.spec.key} draft`));
        },
      }]),
      producers: endpointData.flatMap((item) => [
        {
          producer: item.producer,
          handler: ({ inputs }: ProducerHandlerContext) => {
            const requestRecord = inputs.request;
            assert(requestRecord !== undefined, `${item.spec.key} request input is missing`);
            const request = inlineRequest(requestRecord.value, item.spec.key);
            endpoints[item.spec.key]!.validateRequest(request);
            return { outputs: {}, needs: { generation: request } };
          },
        },
        ...Object.values(item.mediaBindings).map((binding) => ({
          producer: binding.producer,
          handler: ({ inputs }: ProducerHandlerContext) => {
            const draft = inlineValue<GenerationRequestDraft>(inputs.draft!.value, `${item.spec.key} draft`);
            const value = inlineValue<GenerationMediaBinding>(inputs.binding!.value, `${binding.port} binding`);
            const port = item.spec.ports.ports.find((candidate): candidate is GenerationMediaPort =>
              candidate.name === binding.port && candidate.value.kind === "media");
            assert(port !== undefined, `${item.spec.key} media binding ${binding.port} has no port`);
            verifyGenerationMediaBinding(port, value);
            const artifact = inputs.artifact!.value;
            assert(artifact.kind === "blob", `${binding.port} artifact must be a Blob`);
            const bound = bindGenerationMedia(item.spec.ports, draft, binding.port, value, artifact);
            endpoints[item.spec.key]!.validateDraft(bound);
            return {
              outputs: {
                draft: {
                  kind: "inline" as const,
                  value: canonicalize(bound),
                },
              },
              needs: {},
            };
          },
        })),
        ...Object.values(item.textBindings).map((binding) => ({
          producer: binding.producer,
          handler: ({ inputs }: ProducerHandlerContext) => {
            const draft = inlineValue<GenerationRequestDraft>(inputs.draft!.value, `${item.spec.key} draft`);
            const text = inlineValue<Text>(inputs.text!.value, `${binding.port} Text`);
            const bound = bindGenerationText(item.spec.ports, draft, binding.port, text);
            endpoints[item.spec.key]!.validateDraft(bound);
            return {
              outputs: {
                draft: {
                  kind: "inline" as const,
                  value: canonicalize(bound),
                },
              },
              needs: {},
            };
          },
        })),
        {
          producer: item.finalizeProducer,
          handler: ({ inputs }) => {
            const endpoint = endpoints[item.spec.key]!;
            const draft = inlineValue<GenerationRequestDraft>(inputs.draft!.value, `${item.spec.key} draft`);
            endpoint.validateDraft(draft);
            return {
              outputs: {
                request: {
                  kind: "inline" as const,
                  value: canonicalize(endpoint.sealRequest(draft.ports)),
                },
              },
              needs: {},
            };
          },
        },
      ]),
      plannedNeeds: Object.values(endpoints).map((endpoint) => exactModelPlannedNeedFacet(endpoint)),
    },
  };
}

export function exactModelMediaInputNames(name: string): {
  readonly artifact: string;
  readonly binding: string;
} {
  assert(name.trim().length > 0, "Exact model media input name is empty");
  return { artifact: `${name}:artifact`, binding: `${name}:binding` };
}

export function exactModelTextInputName(name: string): string {
  assert(name.trim().length > 0, "Exact model text input name is empty");
  return `${name}:text`;
}

/**
 * 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.
 */
export function createExactModelPrimaryGenerationFragment(
  endpoint: ExactModelEndpoint,
  mediaInputs: readonly ExactModelMediaInput[] = [],
  textInputs: readonly ExactModelTextInput[] = [],
) {
  const names = [...mediaInputs, ...textInputs].map((item) => item.name);
  assert(new Set(names).size === names.length, "Exact model input names must be unique");
  const inputs = [{ name: "draft", type: endpoint.draftType }];
  const operations: Array<{
    readonly id: string;
    readonly producer: ProducerRef;
    readonly inputs: Readonly<Record<string, { readonly kind: "fragment-input"; readonly name: string } | { readonly kind: "fragment-operation"; readonly operation: string }>>;
    readonly result: { readonly kind: "output"; readonly name: string } | { readonly kind: "need"; readonly name: string };
  }> = [];
  const input = (name: string) => ({ kind: "fragment-input" as const, name });
  const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
  let draft = input("draft") as ReturnType<typeof input> | ReturnType<typeof operation>;

  for (const [index, item] of textInputs.entries()) {
    const binding = endpoint.textBindings[item.port];
    assert(binding !== undefined, `${endpoint.ports.model} has no text port ${item.port}`);
    const inputName = exactModelTextInputName(item.name);
    inputs.push({ name: inputName, type: textTypes.text });
    const id = `bind-text:${String(index + 1).padStart(4, "0")}:${item.port}`;
    operations.push({
      id,
      producer: binding.producer,
      inputs: { draft, text: input(inputName) },
      result: { kind: "output", name: "draft" },
    });
    draft = operation(id);
  }

  for (const [index, item] of mediaInputs.entries()) {
    const binding = endpoint.mediaBindings[item.port];
    assert(binding !== undefined, `${endpoint.ports.model} has no media port ${item.port}`);
    const inputNames = exactModelMediaInputNames(item.name);
    inputs.push({ name: inputNames.binding, type: binding.type });
    inputs.push({ name: inputNames.artifact, type: blobTypes.blob });
    const id = `bind:${String(index + 1).padStart(4, "0")}:${item.port}`;
    operations.push({
      id,
      producer: binding.producer,
      inputs: {
        draft,
        binding: input(inputNames.binding),
        artifact: input(inputNames.artifact),
      },
      result: { kind: "output", name: "draft" },
    });
    draft = operation(id);
  }

  operations.push({
    id: "finalize-request",
    producer: endpoint.finalizeProducer,
    inputs: { draft },
    result: { kind: "output", name: "request" },
  });
  operations.push({
    id: "generate",
    producer: endpoint.producer,
    inputs: { request: operation("finalize-request") },
    result: { kind: "need", name: "generation" },
  });
  const result = endpoint.ports.result;
  const primaryProducer = result === "audio"
    ? generationProducers.primaryAudio
    : result === "image" ? generationProducers.primaryImage : generationProducers.primaryVideo;
  operations.push({
    id: `select-primary-${result}`,
    producer: primaryProducer,
    inputs: { set: operation("generate") },
    result: { kind: "output", name: result },
  });
  const shape = [
    ...textInputs.map((item) => `${item.name}=${item.port}:text`),
    ...mediaInputs.map((item) => `${item.name}=${item.port}:media`),
  ].join(",") || "no-dynamic-inputs";
  return sealGraphFragment({
    inputs,
    operations,
    exports: [{
      name: result,
      type: blobTypes.blob,
      root: operation(`select-primary-${result}`),
    }],
  });
}