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.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
fix: enforce model-owned request rules across entry points
kashorin5e27c83879ce
diff --git a/packages/model-kit/README.md b/packages/model-kit/README.mdindex 5952981e..b1ca6cfe 100644--- a/packages/model-kit/README.md+++ b/packages/model-kit/README.md@@ -50,3 +50,31 @@ exact fields, constraints, model identity, capability name and validator. The heProvider routing, fallback, credentials or Runtime authority.This is a package-authoring utility, not an author-importable model by itself.++## Model-owned request checks++An endpoint may supply two synchronous, pure functions in addition to its port table:++- `validateInputs(inputs)` checks values already supplied, both in drafts and complete requests.+ Text and media may still be missing from a draft. Use this for rules such as a reference's media+ type; do not require a future input to exist.+- `validateRequest(request)` checks additional relationships that require the complete request.+ It runs after the port table and `validateInputs`, when every required input is available.++Both return `void` and throw a useful error to reject. They read the supplied values only: no IO,+Provider selection, request mutation or saved validation result. Existing port rules remain in the+port table. The helper supplies structural validation before calling either function.++Register each rule once in the endpoint definition. The helper connects these functions to Type+validators, media/Text bindings, finalization, generation and planning. Planning checks the known+values and leaves future media on the existing graph edges. A directly supplied request or an+existing Need receives full validation, just as it does during execution.++For a public request builder, use `model.endpoints.image.sealRequest(ports)`: it canonicalizes the+request and applies all model rules. `endpoint.validateRequest(value)` checks an existing complete+request; `endpoint.validateDraft(value)` checks a partially assembled one. Calling the common+generation port helpers alone applies only the port table, not these model-owned functions.++Keep service-specific limits in the Provider. Its existing `supports` and pre-submission preparation+should share its own checks, rejecting known unsupported values before resource transfer. This does+not require the Provider to import the Model implementation or add any fields to the request.diff --git a/packages/model-kit/src/index.ts b/packages/model-kit/src/index.tsindex edda6bf9..bac86086 100644--- a/packages/model-kit/src/index.ts+++ b/packages/model-kit/src/index.ts@@ -13,13 +13,13 @@ import type { HostFacet } from "@hypit/host";import {bindGenerationMedia,bindGenerationText,- finalizeGenerationRequestDraft,generationModuleRef,generationProducers,generationTypes,mediaBindingSchemaFromPort,requestDraftSchemaFromPorts,requestSchemaFromPorts,+ sealGenerationPortRequest,verifyGenerationMediaBinding,verifyRequestDraftAgainstPorts,verifyRequestAgainstPorts,@@ -28,6 +28,7 @@ import type {GenerationMediaBinding,GenerationMediaPort,GenerationPortTable,+ GenerationRequest,GenerationRequestDraft,} from "@hypit/generation";import { textDependency, textTypes } from "@hypit/text";@@ -76,6 +77,10 @@ export type ExactModelEndpointSpec = {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 = {@@ -89,6 +94,9 @@ export type ExactModelEndpoint = {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>;};@@ -267,7 +275,7 @@ export function plannedExactModelRequest(const knownNeed = state.needs.find((need) => need.id === binding.id);if (knownNeed !== undefined) {- verifyRequestAgainstPorts(endpoint.ports, knownNeed.constraints);+ endpoint.validateRequest(knownNeed.constraints);return {model: endpoint.ports.model,ports: structuredClone((knownNeed.constraints as unknown as GenerationRequestDraft).ports),@@ -281,6 +289,12 @@ export function plannedExactModelRequest(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;@@ -295,7 +309,7 @@ export function plannedExactModelRequest(const record = records.get(recordId);if (record !== undefined) {const draft = inlineValue<GenerationRequestDraft>(record.value, `${endpoint.ports.model} request draft`);- verifyRequestDraftAgainstPorts(endpoint.ports, draft);+ endpoint.validateDraft(draft);return draft;}const step = producedBy.get(recordId);@@ -354,6 +368,8 @@ export function plannedExactModelRequest(};const draft = rebuildDraft(finalDraft);+ endpoint.validateDraft(draft);+ if (pendingMedia.length === 0) endpoint.validateRequest(draft);return {model: endpoint.ports.model,ports: structuredClone(draft.ports),@@ -502,6 +518,15 @@ export function defineExactModelModule<const Key extends string>(};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: [{@@ -527,6 +552,14 @@ export function defineExactModelModule<const Key extends string>(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];}));@@ -540,12 +573,12 @@ export function defineExactModelModule<const Key extends string>(validators: endpointData.flatMap((item) => [{type: item.requestType,handler({ value }) {- verifyRequestAgainstPorts(item.spec.ports, inlineRequest(value, item.spec.key));+ endpoints[item.spec.key]!.validateRequest(inlineRequest(value, item.spec.key));},}, {type: item.draftType,handler({ value }) {- verifyRequestDraftAgainstPorts(item.spec.ports, inlineRequest(value, `${item.spec.key} draft`));+ endpoints[item.spec.key]!.validateDraft(inlineRequest(value, `${item.spec.key} draft`));},}]),producers: endpointData.flatMap((item) => [@@ -555,7 +588,7 @@ export function defineExactModelModule<const Key extends string>(const requestRecord = inputs.request;assert(requestRecord !== undefined, `${item.spec.key} request input is missing`);const request = inlineRequest(requestRecord.value, item.spec.key);- verifyRequestAgainstPorts(item.spec.ports, request);+ endpoints[item.spec.key]!.validateRequest(request);return { outputs: {}, needs: { generation: request } };},},@@ -570,11 +603,13 @@ export function defineExactModelModule<const Key extends string>(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(bindGenerationMedia(item.spec.ports, draft, binding.port, value, artifact)),+ value: canonicalize(bound),},},needs: {},@@ -586,11 +621,13 @@ export function defineExactModelModule<const Key extends string>(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(bindGenerationText(item.spec.ports, draft, binding.port, text)),+ value: canonicalize(bound),},},needs: {},@@ -599,18 +636,20 @@ export function defineExactModelModule<const Key extends string>(})),{producer: item.finalizeProducer,- handler: ({ inputs }) => ({- outputs: {- request: {- kind: "inline" as const,- value: canonicalize(finalizeGenerationRequestDraft(- item.spec.ports,- inlineValue<GenerationRequestDraft>(inputs.draft!.value, `${item.spec.key} draft`),- )),+ 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: {},- }),+ needs: {},+ };+ },},]),plannedNeeds: Object.values(endpoints).map((endpoint) => exactModelPlannedNeedFacet(endpoint)),diff --git a/packages/model-kit/test/model-kit.test.ts b/packages/model-kit/test/model-kit.test.tsindex a2748123..e496184e 100644--- a/packages/model-kit/test/model-kit.test.ts+++ b/packages/model-kit/test/model-kit.test.ts@@ -166,3 +166,50 @@ test("planning follows the model's declared assembly edges and leaves an upstreareferences: { image: 2 },});});++test("model input rules run during assembly while complete-request rules wait for all inputs", async () => {+ const checked = defineExactModelModule({+ module: { name: "@test/compare-images", version: "1" },+ endpoints: [{+ key: "compare", requestTypeName: "CompareRequest", producerName: "compare", ports,+ validateInputs(request) {+ for (const value of request.ports.images ?? []) {+ if (typeof value === "object" && value.artifact.mediaType === "image/gif") {+ throw new Error("comparison references must be still images");+ }+ }+ },+ validateRequest(request) {+ if (request.ports.prompt?.[0] === "compare" && request.ports.images?.length !== 2) {+ throw new Error("compare requires two reference images");+ }+ },+ }],+ });+ const endpoint = checked.endpoints.compare;+ const bind = checked.component.producers.find((item) => item.producer.name === endpoint.mediaBindings.images!.producer.name)!;+ const finalize = checked.component.producers.find((item) => item.producer.name === endpoint.finalizeProducer.name)!;+ const artifact = { kind: "blob" as const, resource: fixtureResource("compare-image"), size: 4, mediaType: "image/png" };+ const initial = { kind: "inline" as const, value: sealGenerationRequestDraft(ports, { prompt: ["compare"] }) };+ const bindImage = async (draft: unknown, mediaType: string) => await bind.handler({ inputs: {+ draft: { value: draft }, binding: { value: { kind: "inline", value: { role: "image" } } },+ artifact: { value: { ...artifact, mediaType } },+ } } as never);++ const first = await bindImage(initial, "image/png");+ await assert.rejects(async () => finalize.handler({ inputs: { draft: { value: first.outputs.draft } } } as never), /two reference images/);+ await assert.rejects(bindImage(initial, "image/gif"), /must be still images/);+ assert.throws(() => endpoint.sealRequest({ prompt: ["compare"], images: [{ role: "image", artifact }] }), /two reference images/);+ assert.throws(() => endpoint.sealRequest({ prompt: ["draw"], images: [{ role: "image", artifact: { ...artifact, mediaType: "image/gif" } }] }), /must be still images/);++ const second = await bindImage(first.outputs.draft, "image/jpeg");+ const complete = await finalize.handler({ inputs: { draft: { value: second.outputs.draft } } } as never);+ assert.ok(complete.outputs.request);+ const requestValidator = checked.component.validators.find((item) => item.type.name === endpoint.requestType.name)!;+ await requestValidator.handler({ value: complete.outputs.request } as never);++ // Another model using the same common port vocabulary has not acquired this model's GIF rule.+ assert.doesNotThrow(() => definition.endpoints.image.sealRequest({+ prompt: ["draw"], images: [{ role: "image", artifact: { ...artifact, mediaType: "image/gif" } }],+ }));+});diff --git a/packages/provider-hypihub/README.md b/packages/provider-hypihub/README.mdindex f8c79093..bfd6fb1e 100644--- a/packages/provider-hypihub/README.md+++ b/packages/provider-hypihub/README.md@@ -118,6 +118,9 @@ Resource identity with the same declared person-reference classification is uplocross-Build cache. Seedance visual references can carry `personReference` in their media fields;the mapping declares it as a resource-transport field and the upload session receives`is_person_reference`, preserving true, false and omission. It stays out of the generation body.+This covers reference images, reference videos, and first/last frames for every declared Seedance+variant. Omission remains absent on the wire; HypiHub's upload API currently defaults it to false,+so omission does not enable detection or person-reference preparation.HypiHub stores the authored classification and prepares the applicable upstream person reference;this Provider does not detect faces or select an upstream private-avatar group.diff --git a/packages/provider-hypihub/test/routes.test.ts b/packages/provider-hypihub/test/routes.test.tsindex 340ed7d3..3fde808a 100644--- a/packages/provider-hypihub/test/routes.test.ts+++ b/packages/provider-hypihub/test/routes.test.ts@@ -2,16 +2,17 @@ import assert from "node:assert/strict";import test from "node:test";import type { GenerationArtifactUrlResolver } from "@hypit/generation";import type { EndpointSupport } from "@hypit/endpoint-kit";-import type { CanonicalValue } from "@hypit/protocol";+import type { BlobRef, CanonicalValue } from "@hypit/protocol";import { hypiHubRoutes } from "../src/routes.js";import type { HypiHubRoute } from "../src/routes.js";+import { sealGptImage2Request } from "../../gpt-image/src/index.js";async function compile(route: HypiHubRoute, constraints: CanonicalValue, resolve: GenerationArtifactUrlResolver) {return await route.prepare(constraints).compile(resolve);}-const image = {+const image: BlobRef = {kind: "blob" as const,resource: "res_hypihub-route-1",size: 3,@@ -21,6 +22,25 @@ const image = {const resolve = async () => "data:image/png;base64,AQID";const resolveAudio = async () => "data:audio/wav;base64,AQID";+test("service restrictions leave the model request valid and reject before resolving uploads", async () => {+ const route = hypiHubRoutes.find((item) => item.capability.name === "gpt-image-2")!;+ const request = sealGptImage2Request({+ prompt: ["edit the cutout"], aspectRatio: ["1:1"], resolution: ["2K"],+ background: ["opaque"], images: [{ role: "image", artifact: image }],+ });+ const constraints = request as unknown as CanonicalValue;+ assert.equal(route.supports!({ capability: route.capability, returns: route.returns, constraints }).status, "unsupported");+ let resolved = 0;+ const upload: GenerationArtifactUrlResolver = async () => { resolved++; return "https://example.test/reference.png"; };+ await assert.rejects(compile(route, constraints, upload), /background option only at 1K/);+ assert.equal(resolved, 0);++ const supported = sealGptImage2Request({ ...request.ports, resolution: ["1K"] }) as unknown as CanonicalValue;+ assert.equal(route.supports!({ capability: route.capability, returns: route.returns, constraints: supported }).status, "supported");+ await compile(route, supported, upload);+ assert.equal(resolved, 1);+});+test("HypiHub GPT image requests use canonical edit references and the authored resolution tier", async () => {const route = hypiHubRoutes.find((item) => item.capability.name === "gpt-image-2");assert.ok(route);@@ -214,19 +234,20 @@ test("HypiHub MiMo Speech mappings use the public audio speech fields", async ()});test("Seedance person metadata reaches resource transport without changing video request fields", async () => {- for (const port of ["referenceImage", "referenceVideo", "firstFrame", "lastFrame"] as const) {- const route = hypiHubRoutes.find((item) => item.capability.name === "seedance-2-mini")!;- for (const flag of [true, false, undefined]) {- const fields = flag === undefined ? {} : { personReference: flag };- const seen: unknown[] = [];- const result = await compile(route, { ports: {- prompt: ["animate"], duration: [5],- [port]: [{ role: port === "referenceVideo" ? "video" : "image", artifact: image, fields }],- } }, async (_artifact, metadata) => { seen.push(metadata); return "https://media.test/ref"; });- assert.deepEqual(seen, [fields]);- const wireField = { referenceImage: "reference_image_urls", referenceVideo: "reference_videos", firstFrame: "first_frame", lastFrame: "last_frame" }[port];- assert.deepEqual((result.input as Record<string, unknown>)[wireField], port.startsWith("reference") ? ["https://media.test/ref"] : "https://media.test/ref");- assert.equal(JSON.stringify(result.input).includes("person"), false);+ for (const route of hypiHubRoutes.filter((item) => item.capability.module.name === "@hypit/seedance")) {+ for (const port of ["referenceImage", "referenceVideo", "firstFrame", "lastFrame"] as const) {+ for (const flag of [true, false, undefined]) {+ const fields = flag === undefined ? {} : { personReference: flag };+ const seen: unknown[] = [];+ const result = await compile(route, { ports: {+ prompt: ["animate"], duration: [5],+ [port]: [{ role: port === "referenceVideo" ? "video" : "image", artifact: image, fields }],+ } }, async (_artifact, metadata) => { seen.push(metadata); return "https://media.test/ref"; });+ assert.deepEqual(seen, [fields]);+ const wireField = { referenceImage: "reference_image_urls", referenceVideo: "reference_videos", firstFrame: "first_frame", lastFrame: "last_frame" }[port];+ assert.deepEqual((result.input as Record<string, unknown>)[wireField], port.startsWith("reference") ? ["https://media.test/ref"] : "https://media.test/ref");+ assert.equal(JSON.stringify(result.input).includes("person"), false);+ }}}});diff --git a/packages/seedance/README.md b/packages/seedance/README.mdindex f0ca7c4f..64378910 100644--- a/packages/seedance/README.md+++ b/packages/seedance/README.md@@ -18,6 +18,20 @@ the author's literal, in whole seconds inside the model's declared range; measurwith `hypit measure` and write the number here. Nothing in the graph computes it, so a Build plan iscomplete before it starts.+## Reference audio++The Seedance package rejects reference audio declared as `audio/mp4` or `audio/x-m4a`. Convert the+audio to WAV or MP3 before using it; `media:ExtractAudio` produces WAV and can consume an upstream+component's media output. Renaming a file or changing its declared media type is not conversion.++Known imports are checked during Surface decoding. Future audio stays a graph input and is checked+when its Blob arrives. The same rule applies to drafts, complete requests, planning and direct+generation Producers. `sealSeedanceRequest` uses the endpoint's model-aware request builder;+`seedanceComponent` and `seedanceDefinition.component` expose the same implementation.++This checks the Blob's declared media type, not its bytes or codec. The selected Provider remains+responsible for any additional service-specific input limits.+## Visual reference metadataDeclare whether each image or video contains a person/avatar reference, including an AI-generated@@ -37,10 +51,38 @@ Inspect the actual reference when deciding the value. For `FrameVideo`, use`first-frame-person-reference` and `last-frame-person-reference` beside their respective frameinputs. A last-frame classification requires a last-frame input.+| Supplied visual input | Authored attribute | Request port |+| --- | --- | --- |+| Each `Reference image={...}` | `person-reference` | `referenceImage` |+| Each `Reference video={...}` | `person-reference` | `referenceVideo` |+| `FrameVideo` first frame | `first-frame-person-reference` | `firstFrame` |+| `FrameVideo` last frame | `last-frame-person-reference` | `lastFrame` |++These forms apply to `standard`, `fast`, `mini` and `2.5`. For example:++```xml+<seedance:FrameVideo id="turn" model="fast" prompt={direction} duration="5"+ first-frame={presenter.image} first-frame-person-reference="true"+ last-frame={empty-room.image} last-frame-person-reference="false"/>+```++Classify the material supplied to this request, not the intended result. A dance video with a person+still needs `true` when used only for motion, even if the prompt asks for a different performer.+An empty room stays `false` when the prompt asks to add a person. Inspect video across the selected+excerpt, not only its opening frame. This flag neither detects faces nor locks or names an identity.+Identity and action direction remain in the prompt and references.++The SVML author declares this parameter on each reference input. Admitted files, generated+images/videos and reused Results use the same attributes. For a future output, declare the intended+reference classification explicitly; if its contents are uncertain, generate and inspect that+material before using it downstream.+The model's media ports carry this as `fields.personReference`. Providers interpret it through theirservice's media handling; it is not a prompt sentence or a Core-level identity. HypiHub sends it as`is_person_reference` when uploading the file, then uses the returned URL in the ordinary videorequest. A project Provider maps it according to its own API.+Omission does not request automatic face detection. HypiHub currently treats omitted upload flags+as unmarked (`false`); declare `true` explicitly for a person reference that needs its preparation.Video references can carry motion or camera behavior while image references carry the targetappearance. Request duration and reference-clip duration are different limits. Check the selecteddiff --git a/packages/seedance/src/index.ts b/packages/seedance/src/index.tsindex 8c0112a1..2b045bd7 100644--- a/packages/seedance/src/index.ts+++ b/packages/seedance/src/index.ts@@ -1,7 +1,4 @@-import {- sealGenerationPortRequest,- sealGenerationPortTable,-} from "@hypit/generation";+import { sealGenerationPortTable } from "@hypit/generation";import type {GenerationPortTable,GenerationPortValue,@@ -12,6 +9,7 @@ import type { SurfaceAttributeVocabulary, SurfacePortVocabulary } from "@hypit/mimport { defineExactModelModule } from "@hypit/model-kit";import { textTypes } from "@hypit/text";import type { ResourceId } from "@hypit/protocol";+import { validateSeedanceInputs } from "./validation.js";export const seedanceModuleRef = { name: "@hypit/seedance", version: "1" } as const;export const seedanceModels = ["seedance-2", "seedance-2-fast", "seedance-2-mini", "seedance-2.5"] as const;@@ -93,7 +91,7 @@ export const seedancePorts: Readonly<Record<SeedanceModel, GenerationPortTable>>export type SeedancePortMap = Readonly<Record<string, readonly GenerationPortValue[]>>;export function sealSeedanceRequest(model: SeedanceModel, ports: SeedancePortMap): GenerationRequest {- return sealGenerationPortRequest(seedancePorts[model], ports);+ return seedanceEndpointsByModel[model].sealRequest(ports);}const seedanceBaseDefinition = defineExactModelModule({@@ -110,6 +108,7 @@ const seedanceBaseDefinition = defineExactModelModule({: `${model.split("-").map((part) => part[0]!.toUpperCase() + part.slice(1)).join("")}Request`,producerName: `request-${model}`,ports: seedancePorts[model],+ validateInputs: validateSeedanceInputs,})),});@@ -327,23 +326,7 @@ export const seedanceMarkupSurfaces = [/** The duration is an author literal on every Seedance Surface, so the manifest is the exact-model module's own. */export const seedanceManifest = seedanceBaseDefinition.manifest;-const referenceAudioProducers = new Set(Object.values(seedanceEndpoints)- .map((endpoint) => endpoint.mediaBindings["referenceAudio"]!.producer.name));--export const seedanceComponent = {- ...seedanceBaseDefinition.component,- producers: seedanceBaseDefinition.component.producers.map((facet) =>- referenceAudioProducers.has(facet.producer.name) ? {- ...facet,- handler: (context: Parameters<typeof facet.handler>[0]) => {- const artifact = context.inputs.artifact?.value;- if (artifact?.kind === "blob" && ["audio/mp4", "audio/x-m4a"].includes(artifact.mediaType)) {- throw new Error("Seedance reference audio does not accept m4a; convert to wav or mp3");- }- return facet.handler(context);- },- } : facet),-};+export const seedanceComponent = seedanceBaseDefinition.component;export const seedanceDefinition = seedanceBaseDefinition;export {diff --git a/packages/seedance/src/surface.ts b/packages/seedance/src/surface.tsindex 2912d656..1ac3cbc1 100644--- a/packages/seedance/src/surface.ts+++ b/packages/seedance/src/surface.ts@@ -23,6 +23,7 @@ import type {import { createSeedanceAssembledGenerationFragment } from "./fragment.js";import { seedanceEndpoints, seedancePorts } from "./index.js";import type { SeedanceModel, SeedancePortMap } from "./index.js";+import { validateSeedanceAudio } from "./validation.js";type MediaInput = {readonly port: "referenceImage" | "referenceVideo" | "referenceAudio" | "firstFrame" | "lastFrame";@@ -109,9 +110,7 @@ function mediaReference(if (value !== undefined && (value.kind !== "blob" || !value.mediaType.startsWith(`${role}/`))) {throw new Error(`${subject} must reference ${role} media`);}- if (value !== undefined && value.kind === "blob" && role === "audio" && ["audio/mp4", "audio/x-m4a"].includes(value.mediaType)) {- throw new Error(`${subject} references m4a audio, which Seedance does not accept; convert to wav or mp3 and admit that file`);- }+ if (value?.kind === "blob" && role === "audio") validateSeedanceAudio(value, subject);return reference;}diff --git a/packages/seedance/src/validation.ts b/packages/seedance/src/validation.tsnew file mode 100644index 00000000..ac98f0f0--- /dev/null+++ b/packages/seedance/src/validation.ts@@ -0,0 +1,16 @@+import type { GenerationRequestDraft } from "@hypit/generation";+import type { BlobRef } from "@hypit/protocol";++/** Seedance's reference-audio rule, shared by known imports and request assembly. */+export function validateSeedanceAudio(artifact: BlobRef, subject = "Seedance reference audio"): void {+ if (artifact.mediaType === "audio/mp4" || artifact.mediaType === "audio/x-m4a") {+ throw new Error(`${subject} does not accept m4a; convert the reference audio to WAV or MP3 before using it (media:ExtractAudio produces WAV)`);+ }+}++/** Missing references in a draft remain graph inputs; only supplied audio is checked. */+export function validateSeedanceInputs(request: GenerationRequestDraft): void {+ for (const value of request.ports.referenceAudio ?? []) {+ if (typeof value === "object" && value.role === "audio") validateSeedanceAudio(value.artifact);+ }+}diff --git a/packages/seedance/test/surface.test.ts b/packages/seedance/test/surface.test.tsindex 67547310..2c886761 100644--- a/packages/seedance/test/surface.test.ts+++ b/packages/seedance/test/surface.test.ts@@ -5,6 +5,7 @@ import { artifactTypes } from "@hypit/artifact";import { parseStructuredElement } from "@hypit/markup";import type { StructuredSurfaceHandler, SurfaceResolvedReference } from "@hypit/markup";import { textTypes } from "@hypit/text";+import { fixtureResource } from "../../../test/fixture-resource.js";import {decodeSeedanceFrameVideoSurface,@@ -25,12 +26,12 @@ const refs = new Map<string, SurfaceResolvedReference>([}] as const),]);-async function decode(source: string, handler: StructuredSurfaceHandler) {+async function decode(source: string, handler: StructuredSurfaceHandler, references = refs) {const element = parseStructuredElement({ name: "seedance.svml", text: source }, 0).element;return await handler({sourceName: "seedance.svml",element,- resolveReference: (path) => refs.get(path),+ resolveReference: (path) => references.get(path),resolveAsset: () => { throw new Error("no asset"); },});}@@ -47,6 +48,27 @@ test("TextVideo exposes prompt-only generation without inventing a usage", asyncassert.equal(Object.keys(result.components[0]?.inputs ?? {}).some((name) => name.includes("media")), false);});+test("admitted M4A audio is rejected at decode while future audio remains a graph reference", async () => {+ const source = '<seedance:ReferenceVideo id="speaker" model="mini" prompt={direction} duration="6"><seedance:Reference image={generated.image}/><seedance:Reference audio={voice.audio}/></seedance:ReferenceVideo>';+ for (const mediaType of ["audio/mp4", "audio/x-m4a", "audio/wav", "audio/mpeg"]) {+ const admitted = new Map(refs);+ admitted.set("voice.audio", {+ ...refs.get("voice.audio")!,+ record: {+ id: "voice", type: artifactTypes.blob,+ value: { kind: "blob", resource: fixtureResource("admitted-voice"), size: 4, mediaType },+ },+ });+ if (mediaType === "audio/mp4" || mediaType === "audio/x-m4a") {+ await assert.rejects(decode(source, decodeSeedanceReferenceVideoSurface, admitted), /m4a/);+ } else {+ assert.ok((await decode(source, decodeSeedanceReferenceVideoSurface, admitted)).components.length);+ }+ }+ const future = await decode(source, decodeSeedanceReferenceVideoSurface);+ assert.deepEqual(future.components[0]!.inputs["media-0002:artifact"], refs.get("voice.audio")!.ref);+});+test("Seedance 2.5 is an exact model with 1080p and auto or 4-30 second duration", async () => {const automatic = await decode('<seedance:TextVideo id="motion" model="2.5" prompt={direction} duration="-1" resolution="1080p" aspect-ratio="9:16"/>',diff --git a/packages/seedance/test/validation.test.ts b/packages/seedance/test/validation.test.tsnew file mode 100644index 00000000..8264bbfe--- /dev/null+++ b/packages/seedance/test/validation.test.ts@@ -0,0 +1,137 @@+import assert from "node:assert/strict";+import test from "node:test";+import { sealGenerationRequestDraft } from "@hypit/generation";+import type { GenerationRequest } from "@hypit/generation";+import { plannedExactModelRequest } from "@hypit/model-kit";+import type { ExactModelEndpoint } from "@hypit/model-kit";+import { canonicalize } from "@hypit/protocol";+import type { BlobRef, BuildState, ProducerRef, StoredValue } from "@hypit/protocol";+import { fixtureResource } from "../../../test/fixture-resource.js";+import {+ seedanceComponent, seedanceDefinition, seedanceEndpointsByModel, sealSeedanceRequest,+} from "../src/index.js";++const audio = (mediaType: string): BlobRef => ({+ kind: "blob", resource: fixtureResource("reference-audio"), size: 4, mediaType,+});+const settings = {+ prompt: ["A presenter explains the scene"], resolution: ["720p"], aspectRatio: ["9:16"],+ duration: [5], generateAudio: [true], webSearch: [false],+ referenceImage: [{ role: "image" as const, artifact: {+ kind: "blob" as const, resource: fixtureResource("reference-image"), size: 4, mediaType: "image/png",+ } }],+};+const inline = (value: unknown): StoredValue => ({ kind: "inline", value: canonicalize(value) });+const input = (value: StoredValue) => ({ value });+async function produce(producer: ProducerRef, inputs: Record<string, { value: StoredValue }>) {+ const facet = seedanceDefinition.component.producers.find((item) => item.producer.name === producer.name);+ assert.ok(facet);+ return await facet.handler({ inputs } as never);+}++function assembly(endpoint: ExactModelEndpoint, artifact?: BlobRef): BuildState {+ return {+ records: [+ { id: "draft", type: endpoint.draftType, value: inline(sealGenerationRequestDraft(endpoint.ports, settings)) },+ { id: "binding", type: endpoint.mediaBindings.referenceAudio!.type, value: inline({ role: "audio" }) },+ ...(artifact === undefined ? [] : [{ id: "audio", value: artifact }]),+ ],+ needs: [],+ plan: { steps: [+ { id: "upstream", producer: { module: { name: "@test/audio", version: "1" }, name: "generate" }, inputs: {}, outputs: { audio: "audio" }, needs: {} },+ { id: "bind", producer: endpoint.mediaBindings.referenceAudio!.producer, inputs: { draft: "draft", binding: "binding", artifact: "audio" }, outputs: { draft: "bound" }, needs: {} },+ { id: "finalize", producer: endpoint.finalizeProducer, inputs: { draft: "bound" }, outputs: { request: "request" }, needs: {} },+ { id: "generate", producer: endpoint.producer, inputs: { request: "request" }, outputs: {}, needs: { generation: { id: "need" } } },+ ] },+ } as unknown as BuildState;+}++test("Seedance activation and public definition share their component implementation", () => {+ assert.equal(seedanceComponent, seedanceDefinition.component);+});++for (const [model, endpoint] of Object.entries(seedanceEndpointsByModel)) {+ test(`${model}: visual classification survives runtime binding, finalization and generation`, async () => {+ const { referenceImage, ...scalars } = settings;+ for (const port of ["referenceImage", "referenceVideo", "firstFrame", "lastFrame"] as const) {+ const role = port === "referenceVideo" ? "video" : "image";+ const artifact = { ...referenceImage[0]!.artifact, mediaType: role === "video" ? "video/mp4" : "image/png" };+ const initial = { ...scalars, ...(port === "lastFrame" ? { firstFrame: referenceImage } : {}) };+ for (const flag of [true, false, undefined]) {+ const binding = { role, ...(flag === undefined ? {} : { fields: { personReference: flag } }) };+ const bound = await produce(endpoint.mediaBindings[port]!.producer, {+ draft: input(inline(sealGenerationRequestDraft(endpoint.ports, initial))),+ binding: input(inline(binding)), artifact: input(artifact),+ });+ const finalized = await produce(endpoint.finalizeProducer, { draft: input(bound.outputs.draft!) });+ const generated = await produce(endpoint.producer, { request: input(finalized.outputs.request!) });+ const request = generated.needs.generation as unknown as GenerationRequest;+ assert.deepEqual(request.ports[port], [{ ...binding, artifact }]);+ }+ }+ assert.throws(() => endpoint.sealRequest({ ...settings,+ referenceAudio: [{ role: "audio", artifact: audio("audio/wav"), fields: { personReference: true } }],+ }));+ });++ test(`${model}: M4A is rejected through runtime binding and complete request entry points`, async () => {+ for (const mediaType of ["audio/mp4", "audio/x-m4a"]) {+ const artifact = audio(mediaType);+ const ports = { ...settings, referenceAudio: [{ role: "audio" as const, artifact }] };+ // The generic envelope can represent this media; the exact model owns its restriction.+ const request = sealGenerationRequestDraft(endpoint.ports, ports);+ assert.throws(() => sealSeedanceRequest(endpoint.ports.model as keyof typeof seedanceEndpointsByModel, ports), /m4a/);+ assert.throws(() => endpoint.sealRequest(ports), /m4a/);+ const validator = seedanceComponent.validators.find((item) => item.type.name === endpoint.requestType.name)!;+ await assert.rejects(async () => validator.handler({ value: inline(request) } as never), /m4a/);+ await assert.rejects(produce(endpoint.finalizeProducer, { draft: input(inline(request)) }), /m4a/);+ await assert.rejects(produce(endpoint.producer, { request: input(inline(request)) }), /m4a/);+ await assert.rejects(produce(endpoint.mediaBindings.referenceAudio!.producer, {+ draft: input(inline(sealGenerationRequestDraft(endpoint.ports, settings))),+ binding: input(inline({ role: "audio" })), artifact: input(artifact),+ }), /m4a/);+ }+ });++ test(`${model}: supported audio still binds, finalizes and becomes a generation request`, async () => {+ for (const mediaType of ["audio/wav", "audio/mpeg"]) {+ const artifact = audio(mediaType);+ const bound = await produce(endpoint.mediaBindings.referenceAudio!.producer, {+ draft: input(inline(sealGenerationRequestDraft(endpoint.ports, settings))),+ binding: input(inline({ role: "audio" })), artifact: input(artifact),+ });+ const finalized = await produce(endpoint.finalizeProducer, { draft: input(bound.outputs.draft!) });+ const generated = await produce(endpoint.producer, { request: input(finalized.outputs.request!) });+ assert.deepEqual(generated.needs.generation, endpoint.sealRequest({+ ...settings, referenceAudio: [{ role: "audio", artifact }],+ }));+ }+ });++ test(`${model}: planning preserves future audio and rejects it when the actual unsupported value exists`, () => {+ const pending = plannedExactModelRequest(assembly(endpoint), "generate", "generation", endpoint)!;+ assert.equal(pending.complete, false);+ assert.equal(pending.ports.referenceAudio, undefined);+ assert.deepEqual(pending.pendingMedia, [{+ port: "referenceAudio", role: "audio", record: "audio", sourceStep: "upstream", available: false,+ }]);+ assert.throws(() => plannedExactModelRequest(assembly(endpoint, audio("audio/mp4")), "generate", "generation", endpoint), /m4a/);+ const known = plannedExactModelRequest(assembly(endpoint, audio("audio/wav")), "generate", "generation", endpoint)!;+ assert.deepEqual(known.pendingMedia, []);+ assert.deepEqual(known.ports.referenceAudio, [{ role: "audio", artifact: audio("audio/wav") }]);+ });++ test(`${model}: planning validates directly supplied requests and already formed Needs`, () => {+ for (const mediaType of ["audio/mp4", "audio/wav"]) {+ const request = { ports: { ...settings, referenceAudio: [{ role: "audio", artifact: audio(mediaType) }] } };+ const state = assembly(endpoint);+ const direct = { ...state, records: [...state.records, { id: "request", type: endpoint.requestType, value: inline(request) }] } as BuildState;+ const withNeed = { ...state, needs: [{ id: "need", constraints: request }] } as unknown as BuildState;+ for (const candidate of [direct, withNeed]) {+ const plan = () => plannedExactModelRequest(candidate, "generate", "generation", endpoint);+ if (mediaType === "audio/mp4") assert.throws(plan, /m4a/);+ else assert.deepEqual(plan()!.ports, request.ports);+ }+ }+ });+}