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
refactor: let models declare their input ports
kashorin327d9cfa2990
diff --git a/README.md b/README.mdindex 532aa1f8..961eb4c0 100644--- a/README.md+++ b/README.md@@ -69,7 +69,7 @@ The repository implements:- recoverable Runtime scheduling with concurrency lanes, retries and cancellation;- SQLite Build/Operation stores and filesystem/S3 Artifact stores;- exact Endpoint binding and scoped credentials;-- seven explicit image/video model families through the KIE Provider;+- eleven exact image/video models declaring their own input ports, reached through the KIE Provider;- local ffprobe/ffmpeg media processing;- local pinned WhisperX service;- Vertex Gemini display-only Caption planning;diff --git a/docs/README.md b/docs/README.mdindex ba770cf1..7c1958bb 100644--- a/docs/README.md+++ b/docs/README.md@@ -20,6 +20,8 @@ the working tree contains only documents that should inform current implementati- [`graph-first-value-boundary.md`](./graph-first-value-boundary.md) — graph edges owndependency truth; values contain only intrinsic meaning.+- [`model-input-ports.md`](./model-input-ports.md) — models declare the inputs they accept;+ Providers only map those ports onto their own wire.- [`node-package-activation.md`](./node-package-activation.md) — trusted installed packagelocking, contributions and Host-selected facet activation.- [`local-developer-runtime.md`](./local-developer-runtime.md) — local SQLite/filesystemdiff --git a/examples/echo-pro-aroll/svml.packages.lock b/examples/echo-pro-aroll/svml.packages.lockindex 45fce0d4..2cbe3256 100644--- a/examples/echo-pro-aroll/svml.packages.lock+++ b/examples/echo-pro-aroll/svml.packages.lock@@ -49,7 +49,7 @@{"name": "@narratage/generation","version": "0.0.0-dev",- "digest": "sha256:280b7f009d0f5c93c171cbf167d21e5ee2cf415fbb0ce885f1b9fa05b1833c29"+ "digest": "sha256:517aa8e72c832175bd09fb711a091fcab5e8d16af3fa0e6c302dc4b73afe277f"},{"name": "@narratage/host",@@ -74,7 +74,7 @@{"name": "@narratage/model-kit","version": "0.0.0-dev",- "digest": "sha256:195208129c357c8b48dd38977557a8c9f87e3bbd3c162e2e51e17db0f56bf874"+ "digest": "sha256:71b23848a90535e0cd74b25f4ef74a9827ce1aa0abdfe4eb34cc1dc3d907ce13"},{"name": "@narratage/narrative",@@ -119,12 +119,12 @@{"name": "@narratage/seedance-speaker","version": "0.0.0-dev",- "digest": "sha256:35c343bb6bee8cab1ac6d579231b74cf44c946ba634f9029b2c2647770f95390"+ "digest": "sha256:3f17790a7be2768aeed20d53a9db9bec47088425d0c2303ec80f0ceeb787bc14"},{"name": "@narratage/seedance","version": "0.0.0-dev",- "digest": "sha256:872fe63f9a1d36d071aec4baa4764cc14e99e807a21a446f0a19788ef37a48ec"+ "digest": "sha256:f550f1f9278056b349c6f4f536e8d8694ff3cc1d01395c30a1384332fc034f5d"},{"name": "@narratage/semantic-map",@@ -249,7 +249,7 @@"version": "0.0.0-dev"},"facetsDigest": "sha256:c52730036a392448eb17cada1dd16b22be9ecb721ba47fb8d8a8633f74e4e039",- "closureDigest": "sha256:ab382976a8fd6caed8cc59060774edae9a4158c8a341073d80b3bcd9c50640e1"+ "closureDigest": "sha256:74985d499a527c256c23191b188ca3d061d25f1e5fae91136460918438090b5b"},{"specifier": "@narratage/hyperframes",@@ -338,8 +338,8 @@"name": "@narratage/seedance","version": "0.0.0-dev"},- "facetsDigest": "sha256:aca85f68a54101516b734a0aafa7e819ac2ce670f595ae1084ac493b2bdafb95",- "closureDigest": "sha256:023e18468d9a78f1f32ea42ea087176e1c7d076a2908f2bff78397ad01ccdbd4"+ "facetsDigest": "sha256:33c8544ab99b77c94af25a4620bf17e0b1b994cc505616933878c8ece586f666",+ "closureDigest": "sha256:4afcf602ed33934feaaec18babbcebe016b51a310ef6c56f5a94363201cfd393"},{"specifier": "@narratage/seedance-speaker",@@ -347,8 +347,8 @@"name": "@narratage/seedance-speaker","version": "0.0.0-dev"},- "facetsDigest": "sha256:1e3d927202604abb930a2ab11faf7a7baa25842ccc36265ec76357aefdc52413",- "closureDigest": "sha256:6a521923e295045e19cd1d4b401026a665ea8621091928fd87b6278dfaf71766"+ "facetsDigest": "sha256:7e53dd24fcc24b2cf3aff7bb10671132251c37a38d20223e33c95f129a8213a9",+ "closureDigest": "sha256:343324cedfb20314deee174feec7d1b7ba9c3e19595d11ab106a5b9ead391fa4"},{"specifier": "@narratage/semantic-map",@@ -432,5 +432,5 @@"closureDigest": "sha256:777e0f036d3213461c2d441c30869e26206e1cbaea318dc213244a224444fcf3"}],- "digest": "sha256:9275d7c9c622473cab556abf9806dc61e438ca607d4455517246fe173d6a61e1"+ "digest": "sha256:497a10ed9bc11fe41f65ad78816fd352e521eaf429c52c45c336d31a60b6a2cf"}diff --git a/examples/echo-pro-aroll/svml.runtime-packages.lock b/examples/echo-pro-aroll/svml.runtime-packages.lockindex ad062cc8..7497ae98 100644--- a/examples/echo-pro-aroll/svml.runtime-packages.lock+++ b/examples/echo-pro-aroll/svml.runtime-packages.lock@@ -66,25 +66,10 @@"version": "0.0.0-dev","digest": "sha256:2f377c58c0dbec426d90adcb4794356507b3b4c55eb3d2533f54b44fcc20be03"},- {- "name": "@narratage/gemini-omni",- "version": "0.0.0-dev",- "digest": "sha256:81a6cf3606f087085eb539a107a2d0f944a10bfd54ac6b8d0c5eae540d73b252"- },{"name": "@narratage/generation","version": "0.0.0-dev",- "digest": "sha256:280b7f009d0f5c93c171cbf167d21e5ee2cf415fbb0ce885f1b9fa05b1833c29"- },- {- "name": "@narratage/gpt-image",- "version": "0.0.0-dev",- "digest": "sha256:03888009b4ecf8be1c31ce0b8e54a5e8ba72073828833ea60ba8975f89ce6809"- },- {- "name": "@narratage/grok-imagine",- "version": "0.0.0-dev",- "digest": "sha256:3aa49200686fb185442e52871f1e32ec58ce733e30567cc929fe39b92e91439f"+ "digest": "sha256:517aa8e72c832175bd09fb711a091fcab5e8d16af3fa0e6c302dc4b73afe277f"},{"name": "@narratage/host",@@ -106,21 +91,6 @@"version": "0.0.0-dev","digest": "sha256:d92f53d5060df53a7a671b58b8c0d1305be99384bd34e71bda0f7f1296550f4b"},- {- "name": "@narratage/minimax-h3",- "version": "0.0.0-dev",- "digest": "sha256:2662e852ca9d8c61cefdf33895220c7adeedfede13973513e4c9ae3e5940b4de"- },- {- "name": "@narratage/model-kit",- "version": "0.0.0-dev",- "digest": "sha256:195208129c357c8b48dd38977557a8c9f87e3bbd3c162e2e51e17db0f56bf874"- },- {- "name": "@narratage/nano-banana",- "version": "0.0.0-dev",- "digest": "sha256:254cd027bfc5937a5d09865f574f7512bfcc2070056e842068061f1fc61cce6f"- },{"name": "@narratage/narrative","version": "0.0.0-dev",@@ -149,7 +119,7 @@{"name": "@narratage/provider-kie","version": "0.0.0-dev",- "digest": "sha256:1333e4b33f80224db0052765ce0f3a9c3f47c9bc03eede4becaea53d5d15f24a"+ "digest": "sha256:9dde6cc353d5d3af0a6c3b857b9a4ddb18c2b5a0c1b3642642b7772e74e1144c"},{"name": "@narratage/provider-media-local",@@ -181,16 +151,6 @@"version": "0.0.0-dev","digest": "sha256:3d5bd79233f3f78633b427740e2efa4ce2720195a91cd50e0ced94f054471c2a"},- {- "name": "@narratage/seedance",- "version": "0.0.0-dev",- "digest": "sha256:872fe63f9a1d36d071aec4baa4764cc14e99e807a21a446f0a19788ef37a48ec"- },- {- "name": "@narratage/seedream",- "version": "0.0.0-dev",- "digest": "sha256:6ca275e237cd04b0a15d10c690abfe54d08b1cbe458c45bb564a3af1a9aebc7b"- },{"name": "@narratage/semantic-map","version": "0.0.0-dev",@@ -908,7 +868,7 @@"version": "0.0.0-dev"},"facetsDigest": "sha256:e61ebb911a33d4c5d0e4e4ee4fb69cdb790f4ced050ef35f7472bfbd72013d9b",- "closureDigest": "sha256:af79dec340e8f700efbe31c8925af468bab09bd5153831ba89516f8b96193eed"+ "closureDigest": "sha256:b68e74e3a4c97b465610a137d221af97a5cf2c4b0cec535657d74922242d5bbd"},{"specifier": "@narratage/provider-media-local",@@ -929,5 +889,5 @@"closureDigest": "sha256:723c10f0112c7b9d2dff11ba214ae3d595bfcebdf09644703401972818375de0"}],- "digest": "sha256:e04400ffa7fc06fee8659853b74468b9cb300c0d07758f5c4d3b5480a53e35c1"+ "digest": "sha256:04a5e7e90430a98090200a05e5d53e3fe7c552f6a5e790c090f8ab111db4c832"}diff --git a/examples/talking-film-graph-check/svml.packages.lock b/examples/talking-film-graph-check/svml.packages.lockindex 809322bc..74d69984 100644--- a/examples/talking-film-graph-check/svml.packages.lock+++ b/examples/talking-film-graph-check/svml.packages.lock@@ -49,7 +49,7 @@{"name": "@narratage/generation","version": "0.0.0-dev",- "digest": "sha256:280b7f009d0f5c93c171cbf167d21e5ee2cf415fbb0ce885f1b9fa05b1833c29"+ "digest": "sha256:517aa8e72c832175bd09fb711a091fcab5e8d16af3fa0e6c302dc4b73afe277f"},{"name": "@narratage/host",@@ -74,7 +74,7 @@{"name": "@narratage/model-kit","version": "0.0.0-dev",- "digest": "sha256:195208129c357c8b48dd38977557a8c9f87e3bbd3c162e2e51e17db0f56bf874"+ "digest": "sha256:71b23848a90535e0cd74b25f4ef74a9827ce1aa0abdfe4eb34cc1dc3d907ce13"},{"name": "@narratage/narrative",@@ -114,7 +114,7 @@{"name": "@narratage/seedance","version": "0.0.0-dev",- "digest": "sha256:872fe63f9a1d36d071aec4baa4764cc14e99e807a21a446f0a19788ef37a48ec"+ "digest": "sha256:f550f1f9278056b349c6f4f536e8d8694ff3cc1d01395c30a1384332fc034f5d"},{"name": "@narratage/semantic-map",@@ -244,7 +244,7 @@"version": "0.0.0-dev"},"facetsDigest": "sha256:c52730036a392448eb17cada1dd16b22be9ecb721ba47fb8d8a8633f74e4e039",- "closureDigest": "sha256:ab382976a8fd6caed8cc59060774edae9a4158c8a341073d80b3bcd9c50640e1"+ "closureDigest": "sha256:74985d499a527c256c23191b188ca3d061d25f1e5fae91136460918438090b5b"},{"specifier": "@narratage/hyperframes",@@ -324,8 +324,8 @@"name": "@narratage/seedance","version": "0.0.0-dev"},- "facetsDigest": "sha256:aca85f68a54101516b734a0aafa7e819ac2ce670f595ae1084ac493b2bdafb95",- "closureDigest": "sha256:023e18468d9a78f1f32ea42ea087176e1c7d076a2908f2bff78397ad01ccdbd4"+ "facetsDigest": "sha256:33c8544ab99b77c94af25a4620bf17e0b1b994cc505616933878c8ece586f666",+ "closureDigest": "sha256:4afcf602ed33934feaaec18babbcebe016b51a310ef6c56f5a94363201cfd393"},{"specifier": "@narratage/semantic-map",@@ -418,5 +418,5 @@"closureDigest": "sha256:777e0f036d3213461c2d441c30869e26206e1cbaea318dc213244a224444fcf3"}],- "digest": "sha256:368f3a799ac566877e1625fa1c97594a9850dfb1343bb721d3e41745c4796eb9"+ "digest": "sha256:1a445f5c6c074683776245b048ce1ad4fec53e1e0d7b178560fff431a9e3b77b"}diff --git a/packages/gemini-omni/src/index.ts b/packages/gemini-omni/src/index.tsindex 75d736f4..ae61a2aa 100644--- a/packages/gemini-omni/src/index.ts+++ b/packages/gemini-omni/src/index.ts@@ -1,118 +1,54 @@-import {- assertGenerationBlobRef,- generationBlobRefSchema,- generationObjectSchema,- generationPromptSchema,- sealGenerationRequest,-} from "@narratage/generation";+import { sealGenerationPortRequest, sealGenerationPortTable } from "@narratage/generation";+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@narratage/generation";import { defineExactModelModule } from "@narratage/model-kit";-import type { BlobRef, ValueSchema } from "@narratage/protocol";export const geminiOmniModuleRef = { name: "@narratage/gemini-omni", version: "0.0.0-dev" } as const;-export type GeminiOmniVideoReference = {- readonly artifact: BlobRef;- readonly startSec: number;- readonly endSec: number;-};--export type GeminiOmniRequestContent = {- readonly contract: "svml.gemini-omni-request@1";- readonly model: "gemini-omni-video";- readonly prompt: string;- readonly durationSec: 4 | 6 | 8 | 10;- readonly aspectRatio: "16:9" | "9:16";- readonly resolution: "720p" | "1080p" | "4k";- readonly seed?: number;- readonly images?: readonly BlobRef[];- /** KIE Gemini Omni opaque audio assets; ordinary audio BlobRefs are deliberately not disguised as these IDs. */- readonly audioIds?: readonly string[];- readonly videos?: readonly GeminiOmniVideoReference[];- readonly characterIds?: readonly string[];-};-export type GeminiOmniRequest = GeminiOmniRequestContent;--const idSchema = { kind: "string", minLength: 1, maxLength: 255 } as const satisfies ValueSchema;-export const geminiOmniRequestSchema = generationObjectSchema({- contract: { schema: { kind: "literal", value: "svml.gemini-omni-request@1" } },- model: { schema: { kind: "literal", value: "gemini-omni-video" } },- prompt: { schema: generationPromptSchema },- durationSec: {- schema: {- kind: "oneOf",- variants: [4, 6, 8, 10].map((value) => ({ kind: "literal" as const, value })),+export const geminiOmniVideoPorts: GenerationPortTable = sealGenerationPortTable({+ contract: "svml.generation-ports@1",+ model: "gemini-omni-video",+ result: "video",+ ports: [+ { name: "prompt", value: { kind: "text", maxChars: 20_000 }, minItems: 1, maxItems: 1 },+ { name: "duration", value: { kind: "enum", values: [4, 6, 8, 10] }, minItems: 1, maxItems: 1 },+ { name: "aspectRatio", value: { kind: "enum", values: ["16:9", "9:16"] }, minItems: 1, maxItems: 1 },+ { name: "resolution", value: { kind: "enum", values: ["720p", "1080p", "4k"] }, minItems: 1, maxItems: 1 },+ {+ name: "seed",+ value: { kind: "number", integer: true, minimum: 0, maximum: 2_147_483_647 },+ minItems: 0,+ maxItems: 1,},- },- aspectRatio: { schema: { kind: "string", enum: ["16:9", "9:16"] } },- resolution: { schema: { kind: "string", enum: ["720p", "1080p", "4k"] } },- seed: { schema: { kind: "number", integer: true, minimum: 0, maximum: 2_147_483_647 }, optional: true },- images: {- schema: { kind: "array", minItems: 1, maxItems: 7, items: generationBlobRefSchema },- optional: true,- },- audioIds: { schema: { kind: "array", minItems: 1, maxItems: 1, items: idSchema }, optional: true },- videos: {- schema: {- kind: "array",- minItems: 1,+ { name: "images", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 7 },+ {+ name: "excerpts",+ value: {+ kind: "media",+ accepts: ["video"],+ itemFields: [+ { name: "startSec", value: { kind: "number", minimum: 0 } },+ { name: "endSec", value: { kind: "number", minimum: 0 } },+ ],+ itemRequires: [{ kind: "strictlyIncreasing", fields: ["startSec", "endSec"] }],+ },+ minItems: 0,maxItems: 1,- items: generationObjectSchema({- artifact: { schema: generationBlobRefSchema },- startSec: { schema: { kind: "number", minimum: 0 } },- endSec: { schema: { kind: "number", minimum: 0 } },- }),},- optional: true,- },- characterIds: { schema: { kind: "array", minItems: 1, maxItems: 3, items: idSchema }, optional: true },+ { name: "audioIds", value: { kind: "token", minLength: 1, maxLength: 255 }, minItems: 0, maxItems: 3 },+ { name: "characterIds", value: { kind: "token", minLength: 1, maxLength: 255 }, minItems: 0, maxItems: 3 },+ ],+ /** One shared reference budget; a video excerpt costs twice an image. */+ requires: [{+ kind: "weightedTotal",+ weights: { images: 1, excerpts: 2, characterIds: 1 },+ maximum: 7,+ }],});-function object(value: unknown, subject: string): Record<string, unknown> {- if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${subject} must be an object`);- return value as Record<string, unknown>;-}--export function verifyGeminiOmniRequest(value: unknown): asserts value is GeminiOmniRequest {- const request = object(value, "Gemini Omni request");- if (request.contract !== "svml.gemini-omni-request@1" || request.model !== "gemini-omni-video") {- throw new Error("Gemini Omni request identity is invalid");- }- if (![4, 6, 8, 10].includes(request.durationSec as number)- || (request.aspectRatio !== "16:9" && request.aspectRatio !== "9:16")- || (request.resolution !== "720p" && request.resolution !== "1080p" && request.resolution !== "4k")) {- throw new Error("Gemini Omni output parameters are invalid");- }- if (request.seed !== undefined- && (typeof request.seed !== "number" || !Number.isSafeInteger(request.seed)- || request.seed < 0 || request.seed > 2_147_483_647)) {- throw new Error("Gemini Omni seed is invalid");- }- const images = request.images === undefined ? [] : request.images;- const videos = request.videos === undefined ? [] : request.videos;- const characters = request.characterIds === undefined ? [] : request.characterIds;- const audios = request.audioIds === undefined ? [] : request.audioIds;- if (!Array.isArray(images) || !Array.isArray(videos) || !Array.isArray(characters) || !Array.isArray(audios)) {- throw new Error("Gemini Omni references are invalid");- }- if (audios.length > 1 || audios.some((id) => typeof id !== "string" || id.length === 0)) {- throw new Error("Gemini Omni accepts at most one opaque audio ID");- }- images.forEach((image) => assertGenerationBlobRef(image, "image/"));- videos.forEach((candidate) => {- const video = object(candidate, "Gemini Omni video reference");- assertGenerationBlobRef(video.artifact, "video/");- if (typeof video.startSec !== "number" || typeof video.endSec !== "number" || video.endSec <= video.startSec) {- throw new Error("Gemini Omni video range must have endSec > startSec");- }- });- const quota = images.length + videos.length * 2 + characters.length;- if (quota > 7) throw new Error(`Gemini Omni reference quota is ${quota}, over 7`);-}--export function sealGeminiOmniRequest(content: GeminiOmniRequestContent): GeminiOmniRequest {- const request = sealGenerationRequest(content);- verifyGeminiOmniRequest(request);- return request;+export function sealGeminiOmniRequest(+ ports: Readonly<Record<string, readonly GenerationPortValue[]>>,+): GenerationRequest {+ return sealGenerationPortRequest(geminiOmniVideoPorts, ports);}export const geminiOmniDefinition = defineExactModelModule({@@ -120,11 +56,8 @@ export const geminiOmniDefinition = defineExactModelModule({endpoints: [{key: "video",requestTypeName: "GeminiOmniVideoRequest",- capabilityName: "gemini-omni-video-generation",producerName: "request-gemini-omni-video",- result: "video",- requestSchema: geminiOmniRequestSchema,- verifyRequest: verifyGeminiOmniRequest,+ ports: geminiOmniVideoPorts,}],});diff --git a/packages/generation/src/index.ts b/packages/generation/src/index.tsindex e9af9c40..f6448a22 100644--- a/packages/generation/src/index.ts+++ b/packages/generation/src/index.ts@@ -16,6 +16,55 @@ export {generationTypes,generationValidatorDigests,} from "./manifest.js";+export {+ assertMappingCoversPorts,+ compileWireRequest,+ GENERATION_WIRE_MAPPING_V1,+ mappingSupportsRequest,+ selectWireModel,+} from "./mapping.js";+export type {+ GenerationArtifactUrlResolver,+ GenerationFieldMapping,+ GenerationWireMapping,+ GenerationWireRequest,+ GenerationWireRoute,+} from "./mapping.js";+export {+ assertGenerationPortTable,+ GENERATION_MEDIA_ROLES,+ GENERATION_PORTS_V1,+ generationPort,+ isMediaPort,+ sealGenerationPortTable,+} from "./ports.js";+export type {+ GenerationItemRequirement,+ GenerationMediaPort,+ GenerationMediaPortKind,+ GenerationMediaRole,+ GenerationMediaValue,+ GenerationPort,+ GenerationPortItemField,+ GenerationPortKind,+ GenerationPortRequirement,+ GenerationPortScalarKind,+ GenerationPortTable,+ GenerationPortValue,+ GenerationScalarPort,+} from "./ports.js";+export {+ GENERATION_REQUEST_V1,+ mediaValues,+ portsObjectSchema,+ portValues,+ presentPorts,+ requestSchemaFromPorts,+ sealGenerationPortRequest,+ verifyPortsAgainstTable,+ verifyRequestAgainstPorts,+} from "./request.js";+export type { GenerationPortSubset, GenerationRequest } from "./request.js";export {generatedImageSetSchema,generatedVideoSetSchema,diff --git a/packages/generation/src/mapping.ts b/packages/generation/src/mapping.tsnew file mode 100644index 00000000..7f5160d5--- /dev/null+++ b/packages/generation/src/mapping.ts@@ -0,0 +1,213 @@+import { canonicalize } from "@narratage/protocol";+import type { BlobRef, CanonicalValue, CapabilityRef } from "@narratage/protocol";++import { isMediaPort } from "./ports.js";+import type { GenerationMediaRole, GenerationMediaValue, GenerationPortTable } from "./ports.js";+import { presentPorts } from "./request.js";+import type { GenerationRequest } from "./request.js";++/**+ * How one service names the fields of one model's declared input ports.+ *+ * A mapping is data, not code, and it references its Capability by name. A+ * Provider package therefore never imports a model package: the model owns what+ * it eats, the service owns what it calls that on the wire.+ */+export const GENERATION_WIRE_MAPPING_V1 = "svml.generation-wire-mapping@1" as const;++export type GenerationArtifactUrlResolver = (artifact: BlobRef) => Promise<string>;++export type GenerationFieldMapping =+ /** One scalar written as-is. */+ | { readonly as: "value"; readonly field: string; readonly whenAbsent?: CanonicalValue }+ /** One scalar coerced to its string form, for services that type it loosely. */+ | { readonly as: "string"; readonly field: string; readonly whenAbsent?: CanonicalValue }+ /** Several scalars written as one array. */+ | { readonly as: "valueArray"; readonly field: string; readonly whenAbsent?: CanonicalValue }+ /** One media item written as a resolved URL. */+ | { readonly as: "url"; readonly field: string; readonly 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. */+export type GenerationWireRoute = {+ readonly model: string;+ readonly whenPresent?: readonly string[];+};++export type GenerationWireMapping = {+ readonly contract: "svml.generation-wire-mapping@1";+ /**+ * 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: "image" | "video";+ readonly routes: readonly GenerationWireRoute[];+ readonly fields: Readonly<Record<string, GenerationFieldMapping>>;+ readonly constants?: Readonly<Record<string, CanonicalValue>>;+};++export type GenerationWireRequest = {+ readonly model: string;+ readonly input: CanonicalValue;+};++function assert(condition: unknown, message: string): asserts condition {+ if (!condition) throw new Error(message);+}++export function selectWireModel(mapping: GenerationWireMapping, present: ReadonlySet<string>): string {+ for (const route of mapping.routes) {+ if (route.whenPresent === undefined || route.whenPresent.every((name) => present.has(name))) {+ return route.model;+ }+ }+ throw new Error(`${mapping.capability.name} has no route for ports ${[...present].sort().join(", ")}`);+}++async function urlsOf(+ values: readonly GenerationMediaValue[],+ resolve: GenerationArtifactUrlResolver,+): Promise<string[]> {+ return await Promise.all(values.map((item) => resolve(item.artifact)));+}++/**+ * Compile one port-shaped request into one service payload. The engine needs+ * only the mapping and the request, never the model package.+ */+export async function compileWireRequest(+ mapping: GenerationWireMapping,+ request: GenerationRequest,+ resolve: GenerationArtifactUrlResolver,+): Promise<GenerationWireRequest> {+ assert(mapping.contract === GENERATION_WIRE_MAPPING_V1, "Generation wire mapping contract is invalid");+ assert(request.model === mapping.capability.name,+ `${mapping.capability.name} mapping received a ${request.model} request`);+ const present = presentPorts(request);+ const input: Record<string, CanonicalValue> = { ...(mapping.constants ?? {}) };++ for (const [port, field] of Object.entries(mapping.fields)) {+ const supplied = request.ports[port];+ if (supplied === undefined) {+ if (field.whenAbsent !== undefined) input[field.field] = field.whenAbsent;+ continue;+ }+ if (field.as === "value") {+ input[field.field] = supplied[0] as CanonicalValue;+ } else if (field.as === "string") {+ input[field.field] = String(supplied[0]);+ } else if (field.as === "valueArray") {+ input[field.field] = supplied as readonly CanonicalValue[];+ } else if (field.as === "url") {+ input[field.field] = await resolve((supplied[0] as GenerationMediaValue).artifact);+ } else if (field.as === "urlArray") {+ input[field.field] = await urlsOf(supplied as readonly GenerationMediaValue[], resolve);+ } else {+ const media = supplied as readonly GenerationMediaValue[];+ input[field.field] = await Promise.all(media.map(async (item) => ({+ [field.urlKey]: await resolve(item.artifact),+ ...Object.fromEntries(Object.entries(field.fieldKeys)+ .filter(([source]) => item.fields?.[source] !== undefined)+ .map(([source, target]) => [target, item.fields![source] as CanonicalValue])),+ })));+ }+ }++ return { model: selectWireModel(mapping, present), input: canonicalize(input) };+}++/** Does this request only use ports this mapping can write? Needs no model package. */+export function mappingSupportsRequest(mapping: GenerationWireMapping, value: unknown): boolean {+ const request = value as GenerationRequest | undefined;+ if (request?.contract !== "svml.generation-request@1") return false;+ if (request.model !== mapping.capability.name) return false;+ if (request.ports === null || typeof request.ports !== "object") return false;+ return Object.keys(request.ports).every((port) => mapping.fields[port] !== undefined);+}++/**+ * 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.+ */+export function assertMappingCoversPorts(+ table: GenerationPortTable,+ mapping: GenerationWireMapping,+): void {+ assert(mapping.contract === GENERATION_WIRE_MAPPING_V1,+ `${table.model} mapping contract is invalid`);+ assert(mapping.capability.name === table.model,+ `mapping names Capability ${mapping.capability.name} but the port table declares ${table.model}`);+ assert(mapping.result === table.result,+ `${table.model} mapping result ${mapping.result} differs from the port table`);++ const declared = new Map(table.ports.map((port) => [port.name, port]));+ Object.keys(mapping.fields).forEach((name) => assert(declared.has(name),+ `${table.model} mapping names undeclared port ${name}`));++ for (const port of table.ports) {+ const field = mapping.fields[port.name];+ assert(field !== undefined, `${table.model} mapping does not cover port ${port.name}`);+ const subject = `${table.model} mapping for port ${port.name}`;+ if (isMediaPort(port)) {+ const media = port.value;+ const itemFields = media.itemFields ?? [];+ if (itemFields.length > 0) {+ assert(field.as === "itemObject", `${subject} must use itemObject because the port carries item fields`);+ for (const item of itemFields) {+ if (item.optional === true) continue;+ assert(field.fieldKeys[item.name] !== undefined,+ `${subject} does not map required item field ${item.name}`);+ }+ Object.keys(field.fieldKeys).forEach((name) => assert(+ itemFields.some((item) => item.name === name),+ `${subject} maps unknown item field ${name}`,+ ));+ continue;+ }+ assert(media.accepts.length === 1,+ `${subject} accepts ${media.accepts.join(", ")}; declare one port per media role so each maps to one wire field`);+ assert(field.as === "url" || field.as === "urlArray", `${subject} must resolve media to a URL`);+ if (field.as === "url") {+ assert(port.maxItems === 1, `${subject} uses url but the port accepts up to ${port.maxItems} items`);+ }+ continue;+ }+ if (port.maxItems > 1) {+ assert(field.as === "valueArray", `${subject} must use valueArray because the port accepts several values`);+ continue;+ }+ // A single-value port may still be written as a wire array when the service types it that way.+ assert(field.as === "value" || field.as === "string" || field.as === "valueArray",+ `${subject} must write a scalar or a single-element array`);+ }++ const emitted = Object.values(mapping.fields).map((field) => field.field);+ assert(new Set(emitted).size === emitted.length,+ `${table.model} mapping writes one wire field from two ports`);+ Object.keys(mapping.constants ?? {}).forEach((name) => assert(!emitted.includes(name),+ `${table.model} mapping constant ${name} collides with a mapped port`));++ assert(mapping.routes.length > 0, `${table.model} mapping declares no route`);+ mapping.routes.forEach((route, index) => {+ assert(route.model.trim().length > 0, `${table.model} route ${index} has an empty service model`);+ (route.whenPresent ?? []).forEach((name) => assert(declared.has(name),+ `${table.model} route ${index} names undeclared port ${name}`));+ const unconditional = route.whenPresent === undefined || route.whenPresent.length === 0;+ assert(unconditional === (index === mapping.routes.length - 1),+ `${table.model} must end with exactly one unconditional route`);+ });+}diff --git a/packages/generation/src/ports.ts b/packages/generation/src/ports.tsnew file mode 100644index 00000000..e5961ab6--- /dev/null+++ b/packages/generation/src/ports.ts@@ -0,0 +1,223 @@+import type { BlobRef } from "@narratage/protocol";++/**+ * 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 is a `svml.generation-ports@2` decision, not a field patch.+ */+export const GENERATION_PORTS_V1 = "svml.generation-ports@1" as const;++export type GenerationMediaRole = "image" | "video" | "audio";++export const GENERATION_MEDIA_ROLES: readonly GenerationMediaRole[] = ["image", "video", "audio"];++export 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. */+export 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. */+export type GenerationItemRequirement = {+ readonly kind: "strictlyIncreasing";+ readonly fields: readonly string[];+};++export type GenerationMediaPortKind = {+ readonly kind: "media";+ readonly accepts: readonly GenerationMediaRole[];+ readonly itemFields?: readonly GenerationPortItemField[];+ readonly itemRequires?: readonly GenerationItemRequirement[];+};++export type GenerationPortKind = GenerationPortScalarKind | GenerationMediaPortKind;++type GenerationPortBase = {+ readonly name: string;+ readonly minItems: number;+ readonly maxItems: number;+};++export type GenerationScalarPort = GenerationPortBase & { readonly value: GenerationPortScalarKind };+export 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.+ */+export type GenerationPort = GenerationScalarPort | GenerationMediaPort;++export 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;+ };++export type GenerationPortTable = {+ readonly contract: "svml.generation-ports@1";+ /** Exact model identity; this is also the Capability name. */+ readonly model: string;+ readonly result: "image" | "video";+ readonly ports: readonly GenerationPort[];+ readonly requires: readonly GenerationPortRequirement[];+};++export type GenerationMediaValue = {+ readonly role: GenerationMediaRole;+ readonly artifact: BlobRef;+ readonly fields?: Readonly<Record<string, string | number | boolean>>;+};++export type GenerationPortValue = string | number | boolean | GenerationMediaValue;++const PORT_NAME = /^[a-z][A-Za-z0-9]*$/u;++function assert(condition: unknown, message: string): asserts condition {+ if (!condition) throw new Error(message);+}++export function isMediaPort(port: GenerationPort): port is GenerationMediaPort {+ return port.value.kind === "media";+}++function assertScalarKind(value: GenerationPortScalarKind, subject: string): void {+ if (value.kind === "text") {+ assert(Number.isSafeInteger(value.maxChars) && value.maxChars > 0, `${subject} maxChars is invalid`);+ return;+ }+ if (value.kind === "token") {+ assert(Number.isSafeInteger(value.minLength) && value.minLength >= 1, `${subject} minLength is invalid`);+ assert(Number.isSafeInteger(value.maxLength) && value.maxLength >= value.minLength, `${subject} maxLength is invalid`);+ return;+ }+ if (value.kind === "enum") {+ assert(value.values.length > 0, `${subject} enum is empty`);+ assert(new Set(value.values).size === value.values.length, `${subject} enum repeats a value`);+ value.values.forEach((item) => assert(+ typeof item === "string" ? item.length > 0 : Number.isFinite(item),+ `${subject} enum contains an invalid value`,+ ));+ return;+ }+ if (value.kind === "number") {+ if (value.minimum !== undefined) assert(Number.isFinite(value.minimum), `${subject} minimum is invalid`);+ if (value.maximum !== undefined) assert(Number.isFinite(value.maximum), `${subject} maximum is invalid`);+ if (value.minimum !== undefined && value.maximum !== undefined) {+ assert(value.maximum >= value.minimum, `${subject} numeric bounds are inverted`);+ }+ return;+ }+ assert(value.kind === "boolean", `${subject} port kind is outside ${GENERATION_PORTS_V1}`);+}++export function assertGenerationPortTable(value: GenerationPortTable): void {+ assert(value.contract === GENERATION_PORTS_V1, "Generation port table contract is invalid");+ assert(typeof value.model === "string" && value.model.trim().length > 0, "Generation port table model is empty");+ assert(value.result === "image" || value.result === "video", `${value.model} port table result is invalid`);+ assert(value.ports.length > 0, `${value.model} declares no input port`);++ const names = new Set<string>();+ for (const port of value.ports) {+ const subject = `${value.model} port ${port.name}`;+ assert(PORT_NAME.test(port.name), `${subject} name is invalid`);+ assert(!names.has(port.name), `${subject} is declared twice`);+ names.add(port.name);+ assert(Number.isSafeInteger(port.minItems) && port.minItems >= 0, `${subject} minItems is invalid`);+ assert(Number.isSafeInteger(port.maxItems) && port.maxItems >= Math.max(1, port.minItems),+ `${subject} maxItems is invalid`);+ if (isMediaPort(port)) {+ const media = port.value;+ assert(media.accepts.length > 0, `${subject} accepts no media role`);+ assert(new Set(media.accepts).size === media.accepts.length, `${subject} repeats a media role`);+ media.accepts.forEach((role) => assert(GENERATION_MEDIA_ROLES.includes(role), `${subject} media role ${role} is invalid`));+ const fields = new Set<string>();+ for (const field of media.itemFields ?? []) {+ assert(PORT_NAME.test(field.name), `${subject} item field name is invalid`);+ assert(!fields.has(field.name), `${subject} item field ${field.name} is declared twice`);+ fields.add(field.name);+ assertScalarKind(field.value, `${subject} item field ${field.name}`);+ }+ for (const rule of media.itemRequires ?? []) {+ assert(rule.kind === "strictlyIncreasing", `${subject} declares an unsupported item requirement`);+ assert(rule.fields.length >= 2, `${subject} strictlyIncreasing needs at least two item fields`);+ rule.fields.forEach((name) => assert(fields.has(name),+ `${subject} strictlyIncreasing names unknown item field ${name}`));+ }+ } else {+ assertScalarKind(port.value, subject);+ }+ }++ for (const requirement of value.requires) {+ if (requirement.kind === "atMostOneOf") {+ assert(requirement.ports.length >= 2, `${value.model} atMostOneOf needs at least two ports`);+ requirement.ports.forEach((name) => assert(names.has(name),+ `${value.model} atMostOneOf names unknown port ${name}`));+ assert(new Set(requirement.ports).size === requirement.ports.length,+ `${value.model} atMostOneOf repeats a port`);+ continue;+ }+ if (requirement.kind === "requiresAnyOf") {+ assert(names.has(requirement.port), `${value.model} requiresAnyOf names unknown port ${requirement.port}`);+ assert(requirement.anyOf.length >= 1, `${value.model} requiresAnyOf lists no companion port`);+ requirement.anyOf.forEach((name) => {+ assert(names.has(name), `${value.model} requiresAnyOf names unknown port ${name}`);+ assert(name !== requirement.port, `${value.model} requiresAnyOf ${name} depends on itself`);+ });+ continue;+ }+ if (requirement.kind === "weightedTotal") {+ const entries = Object.entries(requirement.weights);+ assert(entries.length >= 1, `${value.model} weightedTotal lists no port`);+ entries.forEach(([name, weight]) => {+ assert(names.has(name), `${value.model} weightedTotal names unknown port ${name}`);+ assert(Number.isFinite(weight) && weight > 0, `${value.model} weightedTotal weight for ${name} is invalid`);+ });+ assert(Number.isFinite(requirement.maximum) && requirement.maximum > 0,+ `${value.model} weightedTotal maximum is invalid`);+ continue;+ }+ assert(requirement.kind === "requiresPresent", `${value.model} declares an unsupported requirement`);+ assert(names.has(requirement.port), `${value.model} requiresPresent names unknown port ${requirement.port}`);+ assert(requirement.needs.length > 0, `${value.model} requiresPresent lists no prerequisite`);+ requirement.needs.forEach((name) => {+ assert(names.has(name), `${value.model} requiresPresent names unknown port ${name}`);+ assert(name !== requirement.port, `${value.model} requiresPresent ${name} depends on itself`);+ });+ }+}++export function sealGenerationPortTable(value: GenerationPortTable): GenerationPortTable {+ assertGenerationPortTable(value);+ return value;+}++export function generationPort(table: GenerationPortTable, name: string): GenerationPort {+ const port = table.ports.find((item) => item.name === name);+ if (port === undefined) throw new Error(`${table.model} declares no port ${name}`);+ return port;+}diff --git a/packages/generation/src/request.ts b/packages/generation/src/request.tsnew file mode 100644index 00000000..26fc9a7c--- /dev/null+++ b/packages/generation/src/request.ts@@ -0,0 +1,290 @@+import type { ObjectFieldSchema, ValueSchema } from "@narratage/protocol";++import { assertGenerationBlobRef, sealGenerationRequest } from "./identity.js";+import { generationBlobRefSchema, generationObjectSchema } from "./schema.js";+import { assertGenerationPortTable, isMediaPort } from "./ports.js";+import type {+ GenerationMediaPort,+ GenerationMediaRole,+ GenerationMediaValue,+ GenerationPort,+ GenerationPortItemField,+ GenerationPortScalarKind,+ GenerationPortTable,+ GenerationPortValue,+} from "./ports.js";++/**+ * 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.+ */+export const GENERATION_REQUEST_V1 = "svml.generation-request@1" as const;++export type GenerationRequest = {+ readonly contract: "svml.generation-request@1";+ readonly model: string;+ /** An absent port is an omitted key. A present port always carries at least one value. */+ readonly ports: Readonly<Record<string, readonly GenerationPortValue[]>>;+};++function assert(condition: unknown, message: string): asserts condition {+ if (!condition) throw new Error(message);+}++function plainObject(value: unknown, subject: string): Record<string, unknown> {+ assert(value !== null && typeof value === "object" && !Array.isArray(value), `${subject} must be an object`);+ return value as Record<string, unknown>;+}++function mediaPrefix(role: GenerationMediaRole): "image/" | "video/" | "audio/" {+ return `${role}/` as "image/" | "video/" | "audio/";+}++function scalarSchema(value: GenerationPortScalarKind): ValueSchema {+ if (value.kind === "text") return { kind: "string", minLength: 1, maxLength: value.maxChars };+ if (value.kind === "token") return { kind: "string", minLength: value.minLength, maxLength: value.maxLength };+ if (value.kind === "boolean") return { kind: "boolean" };+ if (value.kind === "number") {+ return {+ kind: "number",+ ...(value.integer === undefined ? {} : { integer: value.integer }),+ ...(value.minimum === undefined ? {} : { minimum: value.minimum }),+ ...(value.maximum === undefined ? {} : { maximum: value.maximum }),+ };+ }+ const strings = value.values.every((item): item is string => typeof item === "string");+ if (strings) return { kind: "string", enum: [...value.values] };+ return { kind: "oneOf", variants: value.values.map((item) => ({ kind: "literal" as const, value: item })) };+}++function itemFieldsSchema(fields: readonly GenerationPortItemField[]): ValueSchema {+ return generationObjectSchema(Object.fromEntries(fields.map((field) => [field.name, {+ schema: scalarSchema(field.value),+ ...(field.optional === true ? { optional: true } : {}),+ } satisfies ObjectFieldSchema])));+}++function portItemSchema(port: GenerationPort): ValueSchema {+ if (!isMediaPort(port)) return scalarSchema(port.value);+ const media = port.value;+ return generationObjectSchema({+ role: { schema: { kind: "string", enum: [...media.accepts] } },+ artifact: { schema: generationBlobRefSchema },+ ...(media.itemFields === undefined || media.itemFields.length === 0+ ? {}+ : { fields: { schema: itemFieldsSchema(media.itemFields) } }),+ });+}++export 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[];+};++/** Derive the Schema of the port map alone, optionally leaving some ports for later. */+export function portsObjectSchema(+ table: GenerationPortTable,+ options: GenerationPortSubset = {},+): ValueSchema {+ assertGenerationPortTable(table);+ const omit = new Set(options.omit ?? []);+ omit.forEach((name) => assert(table.ports.some((port) => port.name === name),+ `${table.model} cannot omit undeclared port ${name}`));+ return generationObjectSchema(Object.fromEntries(table.ports+ .filter((port) => !omit.has(port.name))+ .map((port) => [port.name, {+ schema: {+ kind: "array",+ items: portItemSchema(port),+ minItems: Math.max(1, port.minItems),+ maxItems: port.maxItems,+ },+ ...(port.minItems === 0 ? { optional: true } : {}),+ } satisfies ObjectFieldSchema])));+}++/** Derive the structural Schema of one model's request from its port table. */+export function requestSchemaFromPorts(table: GenerationPortTable): ValueSchema {+ return generationObjectSchema({+ contract: { schema: { kind: "literal", value: GENERATION_REQUEST_V1 } },+ model: { schema: { kind: "literal", value: table.model } },+ ports: { schema: portsObjectSchema(table) },+ });+}++function verifyScalar(value: unknown, kind: GenerationPortScalarKind, subject: string): void {+ if (kind.kind === "text") {+ assert(typeof value === "string" && value.length > 0 && value.length <= kind.maxChars,+ `${subject} must be text of 1 to ${kind.maxChars} characters`);+ return;+ }+ if (kind.kind === "token") {+ assert(typeof value === "string" && value.length >= kind.minLength && value.length <= kind.maxLength,+ `${subject} must be a token of ${kind.minLength} to ${kind.maxLength} characters`);+ return;+ }+ if (kind.kind === "boolean") {+ assert(typeof value === "boolean", `${subject} must be a boolean`);+ return;+ }+ if (kind.kind === "number") {+ assert(typeof value === "number" && Number.isFinite(value), `${subject} must be a finite number`);+ if (kind.integer === true) assert(Number.isSafeInteger(value), `${subject} must be an integer`);+ if (kind.minimum !== undefined) assert(value >= kind.minimum, `${subject} must be at least ${kind.minimum}`);+ if (kind.maximum !== undefined) assert(value <= kind.maximum, `${subject} must be at most ${kind.maximum}`);+ return;+ }+ assert(+ (typeof value === "string" || typeof value === "number") && kind.values.includes(value),+ `${subject} must be one of ${kind.values.join(", ")}`,+ );+}++function verifyMediaValue(value: unknown, port: GenerationMediaPort, subject: string): void {+ const media = port.value;+ const item = plainObject(value, subject);+ const role = item.role;+ assert(typeof role === "string" && media.accepts.includes(role as GenerationMediaRole),+ `${subject} role must be one of ${media.accepts.join(", ")}`);+ assertGenerationBlobRef(item.artifact, mediaPrefix(role as GenerationMediaRole));+ const declared = media.itemFields ?? [];+ if (declared.length === 0) {+ assert(item.fields === undefined, `${subject} declares no item fields`);+ return;+ }+ const fields = plainObject(item.fields ?? {}, `${subject} fields`);+ const known = new Set(declared.map((field) => field.name));+ Object.keys(fields).forEach((name) => assert(known.has(name), `${subject} has unknown item field ${name}`));+ for (const field of declared) {+ const present = Object.prototype.hasOwnProperty.call(fields, field.name);+ if (!present) {+ assert(field.optional === true, `${subject} is missing item field ${field.name}`);+ continue;+ }+ verifyScalar(fields[field.name], field.value, `${subject} item field ${field.name}`);+ }+ for (const rule of media.itemRequires ?? []) {+ const values = rule.fields.map((name) => fields[name]).filter((item) => item !== undefined);+ if (values.length < rule.fields.length) continue;+ for (let index = 1; index < values.length; index += 1) {+ assert((values[index] as number) > (values[index - 1] as number),+ `${subject} requires ${rule.fields.join(" < ")}`);+ }+ }+}++/**+ * 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.+ */+export function verifyPortsAgainstTable(+ table: GenerationPortTable,+ value: unknown,+ options: GenerationPortSubset = {},+): void {+ assertGenerationPortTable(table);+ const omit = new Set(options.omit ?? []);+ const ports = plainObject(value, `${table.model} ports`);+ const declared = new Map(table.ports.map((port) => [port.name, port]));+ Object.keys(ports).forEach((name) => {+ assert(declared.has(name), `${table.model} names undeclared port ${name}`);+ assert(!omit.has(name), `${table.model} port ${name} is supplied later and must be absent here`);+ });++ const present = new Set<string>();+ for (const port of table.ports) {+ if (omit.has(port.name)) continue;+ const subject = `${table.model} port ${port.name}`;+ const supplied = ports[port.name];+ if (supplied === undefined) {+ assert(port.minItems === 0, `${subject} is required`);+ continue;+ }+ assert(Array.isArray(supplied), `${subject} must be an array`);+ assert(supplied.length >= Math.max(1, port.minItems),+ `${subject} needs at least ${Math.max(1, port.minItems)} value(s)`);+ assert(supplied.length <= port.maxItems, `${subject} accepts at most ${port.maxItems} value(s)`);+ present.add(port.name);+ supplied.forEach((item, index) => {+ const label = port.maxItems === 1 ? subject : `${subject}[${index}]`;+ if (isMediaPort(port)) verifyMediaValue(item, port, label);+ else verifyScalar(item, port.value, label);+ });+ }++ for (const requirement of table.requires) {+ if (requirement.kind === "atMostOneOf") {+ const used = requirement.ports.filter((name) => present.has(name));+ assert(used.length <= 1,+ `${table.model} accepts at most one of ${requirement.ports.join(", ")} but received ${used.join(", ")}`);+ continue;+ }+ if (requirement.kind === "requiresAnyOf") {+ if (!present.has(requirement.port)) continue;+ const satisfied = requirement.anyOf.some((name) => present.has(name) || omit.has(name));+ assert(satisfied,+ `${table.model} port ${requirement.port} needs at least one of ${requirement.anyOf.join(", ")}`);+ continue;+ }+ if (requirement.kind === "weightedTotal") {+ const total = Object.entries(requirement.weights).reduce((sum, [name, weight]) => {+ const supplied = ports[name];+ return sum + (Array.isArray(supplied) ? supplied.length : 0) * weight;+ }, 0);+ assert(total <= requirement.maximum,+ `${table.model} uses ${total} of its ${requirement.maximum} shared ${Object.keys(requirement.weights).sort().join("/")} budget`);+ continue;+ }+ if (!present.has(requirement.port)) continue;+ const missing = requirement.needs.filter((name) => !present.has(name) && !omit.has(name));+ assert(missing.length === 0,+ `${table.model} port ${requirement.port} also requires ${missing.join(", ")}`);+ }+}++export function verifyRequestAgainstPorts(+ table: GenerationPortTable,+ value: unknown,+): asserts value is GenerationRequest {+ assertGenerationPortTable(table);+ const request = plainObject(value, `${table.model} request`);+ assert(request.contract === GENERATION_REQUEST_V1, `${table.model} request contract is invalid`);+ assert(request.model === table.model, `${table.model} request model is invalid`);+ verifyPortsAgainstTable(table, request.ports);+}++/** Build one canonical request for a model from its declared ports. */+export function sealGenerationPortRequest(+ table: GenerationPortTable,+ ports: Readonly<Record<string, readonly GenerationPortValue[]>>,+): GenerationRequest {+ const content: GenerationRequest = {+ contract: GENERATION_REQUEST_V1,+ model: table.model,+ ports: Object.fromEntries(+ Object.entries(ports).filter(([, values]) => values !== undefined && values.length > 0),+ ),+ };+ const request = sealGenerationRequest(content);+ verifyRequestAgainstPorts(table, request);+ return request;+}++/** Which ports this request actually populates; drives Provider routing and coverage. */+export function presentPorts(request: GenerationRequest): ReadonlySet<string> {+ return new Set(Object.keys(request.ports));+}++export function portValues(request: GenerationRequest, name: string): readonly GenerationPortValue[] {+ return request.ports[name] ?? [];+}++export function mediaValues(request: GenerationRequest, name: string): readonly GenerationMediaValue[] {+ return portValues(request, name) as readonly GenerationMediaValue[];+}diff --git a/packages/generation/test/ports.test.ts b/packages/generation/test/ports.test.tsnew file mode 100644index 00000000..91833a32--- /dev/null+++ b/packages/generation/test/ports.test.ts@@ -0,0 +1,204 @@+import assert from "node:assert/strict";+import test from "node:test";++import { MemoryArtifactStore } from "@narratage/driver-node";+import {+ assertMappingCoversPorts,+ compileWireRequest,+ requestSchemaFromPorts,+ sealGenerationPortRequest,+ sealGenerationPortTable,+ selectWireModel,+ verifyRequestAgainstPorts,+} from "@narratage/generation";+import type { GenerationPortTable, GenerationWireMapping } from "@narratage/generation";++const table: GenerationPortTable = sealGenerationPortTable({+ contract: "svml.generation-ports@1",+ model: "demo-video",+ result: "video",+ ports: [+ { name: "prompt", value: { kind: "text", maxChars: 200 }, minItems: 1, maxItems: 1 },+ { name: "duration", value: { kind: "number", integer: true, minimum: 4, maximum: 15 }, minItems: 1, maxItems: 1 },+ { name: "resolution", value: { kind: "enum", values: ["480p", "720p"] }, minItems: 1, maxItems: 1 },+ { name: "referenceImage", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 9 },+ { name: "referenceAudio", value: { kind: "media", accepts: ["audio"] }, minItems: 0, maxItems: 3 },+ { name: "firstFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },+ { name: "lastFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },+ { name: "voiceId", value: { kind: "token", minLength: 1, maxLength: 64 }, minItems: 0, maxItems: 4 },+ {+ name: "excerpt",+ value: {+ kind: "media",+ accepts: ["video"],+ itemFields: [+ { name: "startSec", value: { kind: "number", minimum: 0 } },+ { name: "endSec", value: { kind: "number", minimum: 0 } },+ ],+ },+ minItems: 0,+ maxItems: 3,+ },+ ],+ requires: [+ { kind: "atMostOneOf", ports: ["referenceImage", "firstFrame"] },+ { kind: "requiresPresent", port: "lastFrame", needs: ["firstFrame"] },+ { kind: "requiresAnyOf", port: "referenceAudio", anyOf: ["referenceImage"] },+ { kind: "weightedTotal", weights: { referenceImage: 1, referenceAudio: 1 }, maximum: 10 },+ ],+});++const mapping: GenerationWireMapping = {+ contract: "svml.generation-wire-mapping@1",+ capability: { module: { name: "@narratage/demo", version: "0.0.0-dev" }, name: "demo-video" },+ result: "video",+ routes: [+ { model: "demo/image-to-video", whenPresent: ["firstFrame"] },+ { model: "demo/reference-to-video", whenPresent: ["referenceImage"] },+ { model: "demo/text-to-video" },+ ],+ fields: {+ prompt: { as: "value", field: "prompt" },+ duration: { as: "string", field: "duration" },+ resolution: { as: "value", field: "resolution" },+ referenceImage: { as: "urlArray", field: "reference_image_urls" },+ referenceAudio: { as: "urlArray", field: "reference_audio_urls" },+ firstFrame: { as: "url", field: "first_frame_url" },+ lastFrame: { as: "url", field: "last_frame_url" },+ voiceId: { as: "valueArray", field: "voice_ids" },+ excerpt: {+ as: "itemObject",+ field: "video_list",+ urlKey: "url",+ fieldKeys: { startSec: "start", endSec: "ends" },+ },+ },+ constants: { return_last_frame: false },+};++async function artifacts() {+ const store = new MemoryArtifactStore();+ return {+ image: await store.put(new Uint8Array([1]), "image/png"),+ video: await store.put(new Uint8Array([2]), "video/mp4"),+ audio: await store.put(new Uint8Array([3]), "audio/wav"),+ };+}++const resolve = async (artifact: { readonly digest: string }) => `https://cdn.test/${artifact.digest}`;++test("a port table derives the request Schema and rejects undeclared ports", () => {+ const schema = requestSchemaFromPorts(table);+ assert.equal(schema.kind, "object");+ const fields = (schema as { fields: Record<string, { schema: { kind: string } }> }).fields;+ assert.equal(fields.model!.schema.kind, "literal");+ const ports = fields.ports!.schema as { kind: string; fields: Record<string, { optional?: boolean }> };+ assert.equal(ports.kind, "object");+ assert.equal(ports.fields.prompt!.optional, undefined);+ assert.equal(ports.fields.referenceImage!.optional, true);+ assert.throws(+ () => verifyRequestAgainstPorts(table, {+ contract: "svml.generation-request@1",+ model: "demo-video",+ ports: { prompt: ["hi"], duration: [8], resolution: ["720p"], unknownPort: ["x"] },+ }),+ /undeclared port unknownPort/u,+ );+});++test("a media port enforces the media type its role demands", async () => {+ const { image, audio } = await artifacts();+ assert.throws(+ () => sealGenerationPortRequest(table, {+ prompt: ["hi"],+ duration: [8],+ resolution: ["720p"],+ firstFrame: [{ role: "image", artifact: audio }],+ }),+ /image\//u,+ );+ const ok = sealGenerationPortRequest(table, {+ prompt: ["hi"],+ duration: [8],+ resolution: ["720p"],+ firstFrame: [{ role: "image", artifact: image }],+ });+ assert.equal(ok.model, "demo-video");+});++test("port combination rules replace the old mode union", async () => {+ const { image } = await artifacts();+ const base = { prompt: ["hi"], duration: [8], resolution: ["720p"] } as const;+ assert.throws(+ () => sealGenerationPortRequest(table, {+ ...base,+ referenceImage: [{ role: "image", artifact: image }],+ firstFrame: [{ role: "image", artifact: image }],+ }),+ /at most one of referenceImage, firstFrame/u,+ );+ assert.throws(+ () => sealGenerationPortRequest(table, { ...base, lastFrame: [{ role: "image", artifact: image }] }),+ /lastFrame also requires firstFrame/u,+ );+ assert.throws(+ () => sealGenerationPortRequest(table, { ...base, resolution: ["1080p"] }),+ /must be one of 480p, 720p/u,+ );+});++test("one mapping compiles every port shape and routes by port presence", async () => {+ const { image, video, audio } = await artifacts();+ const request = sealGenerationPortRequest(table, {+ prompt: ["hello"],+ duration: [8],+ resolution: ["720p"],+ referenceImage: [{ role: "image", artifact: image }],+ referenceAudio: [{ role: "audio", artifact: audio }],+ voiceId: ["alpha", "beta"],+ excerpt: [{ role: "video", artifact: video, fields: { startSec: 1, endSec: 4 } }],+ });+ const wire = await compileWireRequest(mapping, request, resolve);+ assert.equal(wire.model, "demo/reference-to-video");+ assert.deepEqual(wire.input, {+ duration: "8",+ prompt: "hello",+ reference_audio_urls: [`https://cdn.test/${audio.digest}`],+ reference_image_urls: [`https://cdn.test/${image.digest}`],+ resolution: "720p",+ return_last_frame: false,+ video_list: [{ ends: 4, start: 1, url: `https://cdn.test/${video.digest}` }],+ voice_ids: ["alpha", "beta"],+ });++ const textOnly = sealGenerationPortRequest(table, { prompt: ["hi"], duration: [8], resolution: ["720p"] });+ assert.equal(selectWireModel(mapping, new Set(Object.keys(textOnly.ports))), "demo/text-to-video");+ const framed = sealGenerationPortRequest(table, {+ prompt: ["hi"],+ duration: [8],+ resolution: ["720p"],+ firstFrame: [{ role: "image", artifact: image }],+ });+ assert.equal((await compileWireRequest(mapping, framed, resolve)).model, "demo/image-to-video");+});++test("coverage rejects a mapping that forgets a port the model declares", () => {+ assertMappingCoversPorts(table, mapping);+ const { referenceAudio: _audio, ...withoutAudio } = mapping.fields;+ assert.throws(+ () => assertMappingCoversPorts(table, { ...mapping, fields: withoutAudio }),+ /does not cover port referenceAudio/u,+ );++ const { excerpt: _excerpt, ...missingPort } = mapping.fields;+ assert.throws(+ () => assertMappingCoversPorts(table, { ...mapping, fields: missingPort }),+ /does not cover port excerpt/u,+ );++ const wrongShape: GenerationWireMapping = {+ ...mapping,+ fields: { ...mapping.fields, voiceId: { as: "value", field: "voice_ids" } },+ };+ assert.throws(() => assertMappingCoversPorts(table, wrongShape), /must use valueArray/u);+});diff --git a/packages/gpt-image/src/index.ts b/packages/gpt-image/src/index.tsindex f249ad01..1cf6dc4f 100644--- a/packages/gpt-image/src/index.ts+++ b/packages/gpt-image/src/index.ts@@ -1,85 +1,45 @@-import {- assertGenerationBlobRef,- generationBlobRefSchema,- generationObjectSchema,- generationPromptSchema,- sealGenerationRequest,-} from "@narratage/generation";+import { sealGenerationPortRequest, sealGenerationPortTable } from "@narratage/generation";+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@narratage/generation";import { defineExactModelModule } from "@narratage/model-kit";-import type { BlobRef, ValueSchema } from "@narratage/protocol";export const gptImageModuleRef = { name: "@narratage/gpt-image", version: "0.0.0-dev" } as const;-export type GptImage2Mode = "text" | "image";-type Common = {- readonly contract: "svml.gpt-image-2-request@1";- readonly model: "gpt-image-2";- readonly prompt: string;- readonly aspectRatio: string;-};-export type GptImage2TextRequestContent = Common & { readonly mode: "text" };-export type GptImage2ImageRequestContent = Common & {- readonly mode: "image";- readonly images: readonly BlobRef[];-};-export type GptImage2RequestContent = GptImage2TextRequestContent | GptImage2ImageRequestContent;-export type GptImage2Request = GptImage2RequestContent;-const commonFields = {- contract: { schema: { kind: "literal", value: "svml.gpt-image-2-request@1" } },- model: { schema: { kind: "literal", value: "gpt-image-2" } },- prompt: { schema: generationPromptSchema },- aspectRatio: { schema: { kind: "string", minLength: 3, maxLength: 16 } },-} as const;-const schemas: Record<GptImage2Mode, ValueSchema> = {- text: generationObjectSchema({- ...commonFields,- mode: { schema: { kind: "literal", value: "text" } },- }),- image: generationObjectSchema({- ...commonFields,- mode: { schema: { kind: "literal", value: "image" } },- images: { schema: { kind: "array", minItems: 1, maxItems: 16, items: generationBlobRefSchema } },- }),-};--function object(value: unknown): Record<string, unknown> {- if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("GPT Image 2 request must be an object");- return value as Record<string, unknown>;-}--export function verifyGptImage2Request(value: unknown, expectedMode?: GptImage2Mode): asserts value is GptImage2Request {- const request = object(value);- if (request.contract !== "svml.gpt-image-2-request@1" || request.model !== "gpt-image-2") {- throw new Error("GPT Image 2 request identity is invalid");- }- if (expectedMode !== undefined && request.mode !== expectedMode) throw new Error(`Expected GPT Image 2 ${expectedMode}`);- if (request.mode === "image") {- if (!Array.isArray(request.images) || request.images.length === 0) throw new Error("GPT Image 2 input images are empty");- request.images.forEach((image) => assertGenerationBlobRef(image, "image/"));- } else if (request.mode !== "text") {- throw new Error("GPT Image 2 mode is invalid");- }-}+export const gptImage2Ports: GenerationPortTable = sealGenerationPortTable({+ contract: "svml.generation-ports@1",+ model: "gpt-image-2",+ result: "image",+ ports: [+ { name: "prompt", value: { kind: "text", maxChars: 20_000 }, minItems: 1, maxItems: 1 },+ {+ name: "aspectRatio",+ value: {+ kind: "enum",+ values: ["auto", "1:1", "3:2", "2:3", "4:3", "3:4", "5:4", "4:5",+ "16:9", "9:16", "2:1", "1:2", "3:1", "1:3", "21:9", "9:21"],+ },+ minItems: 1,+ maxItems: 1,+ },+ { name: "resolution", value: { kind: "enum", values: ["1K", "2K", "4K"] }, minItems: 1, maxItems: 1 },+ { name: "images", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 16 },+ ],+ requires: [],+});-export function sealGptImage2Request<T extends GptImage2RequestContent>(- content: T,-): T {- const request = sealGenerationRequest(content);- verifyGptImage2Request(request, content.mode);- return request;+export function sealGptImage2Request(+ ports: Readonly<Record<string, readonly GenerationPortValue[]>>,+): GenerationRequest {+ return sealGenerationPortRequest(gptImage2Ports, ports);}export const gptImageDefinition = defineExactModelModule({module: gptImageModuleRef,- endpoints: (["text", "image"] as const).map((mode) => ({- key: mode,- requestTypeName: mode === "text" ? "GptImage2TextRequest" : "GptImage2ImageRequest",- capabilityName: `gpt-image-2-${mode}-generation`,- producerName: `request-gpt-image-2-${mode}`,- result: "image" as const,- requestSchema: schemas[mode],- verifyRequest: (value: unknown) => verifyGptImage2Request(value, mode),- })),+ endpoints: [{+ key: "image",+ requestTypeName: "GptImage2Request",+ producerName: "request-gpt-image-2",+ ports: gptImage2Ports,+ }],});export const gptImageManifest = gptImageDefinition.manifest;diff --git a/packages/grok-imagine/src/index.ts b/packages/grok-imagine/src/index.tsindex 35e139b6..01f884a6 100644--- a/packages/grok-imagine/src/index.ts+++ b/packages/grok-imagine/src/index.ts@@ -1,124 +1,79 @@-import {- assertGenerationBlobRef,- generationBlobRefSchema,- generationObjectSchema,- generationPromptSchema,- sealGenerationRequest,-} from "@narratage/generation";+import { sealGenerationPortRequest, sealGenerationPortTable } from "@narratage/generation";+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@narratage/generation";import { defineExactModelModule } from "@narratage/model-kit";-import type { BlobRef, ValueSchema } from "@narratage/protocol";export const grokImagineModuleRef = { name: "@narratage/grok-imagine", version: "0.0.0-dev" } as const;-export type GrokImagineMode = "text" | "image" | "preview-1.5";+export const grokImagineModels = ["grok-imagine-video", "grok-imagine-video-1.5-preview"] as const;+export type GrokImagineModel = typeof grokImagineModels[number];-type Common = {- readonly contract: "svml.grok-imagine-video-request@1";- readonly prompt: string;- readonly aspectRatio: string;- readonly resolution: "480p" | "720p";- readonly durationSec: number;-};-export type GrokImagineTextRequestContent = Common & {- readonly model: "grok-imagine-video";- readonly mode: "text";-};-export type GrokImagineImageRequestContent = Common & {- readonly model: "grok-imagine-video";- readonly mode: "image";- readonly images: readonly BlobRef[];- /** Optional KIE continuation identity; omitted for ordinary image-to-video. */- readonly sourceTaskId?: string;-};-export type GrokImaginePreviewRequestContent = Common & {- readonly model: "grok-imagine-video-1.5-preview";- readonly mode: "preview-1.5";- readonly images?: readonly BlobRef[];-};-export type GrokImagineRequestContent =- | GrokImagineTextRequestContent- | GrokImagineImageRequestContent- | GrokImaginePreviewRequestContent;-export type GrokImagineRequest = GrokImagineRequestContent;--const aspectSchema = { kind: "string", minLength: 3, maxLength: 16 } as const satisfies ValueSchema;-const commonFields = {- contract: { schema: { kind: "literal", value: "svml.grok-imagine-video-request@1" } },- prompt: { schema: generationPromptSchema },- aspectRatio: { schema: aspectSchema },- resolution: { schema: { kind: "string", enum: ["480p", "720p"] } },- durationSec: { schema: { kind: "number", integer: true, minimum: 1, maximum: 15 } },-} as const;-const schemas: Record<GrokImagineMode, ValueSchema> = {- text: generationObjectSchema({- ...commonFields,- model: { schema: { kind: "literal", value: "grok-imagine-video" } },- mode: { schema: { kind: "literal", value: "text" } },- }),- image: generationObjectSchema({- ...commonFields,- model: { schema: { kind: "literal", value: "grok-imagine-video" } },- mode: { schema: { kind: "literal", value: "image" } },- images: { schema: { kind: "array", minItems: 1, maxItems: 4, items: generationBlobRefSchema } },- sourceTaskId: { schema: { kind: "string", minLength: 1, maxLength: 255 }, optional: true },- }),- "preview-1.5": generationObjectSchema({- ...commonFields,- model: { schema: { kind: "literal", value: "grok-imagine-video-1.5-preview" } },- mode: { schema: { kind: "literal", value: "preview-1.5" } },- images: {- schema: { kind: "array", minItems: 1, maxItems: 4, items: generationBlobRefSchema },- optional: true,+export const grokImagineVideoPorts: GenerationPortTable = sealGenerationPortTable({+ contract: "svml.generation-ports@1",+ model: "grok-imagine-video",+ result: "video",+ ports: [+ { name: "prompt", value: { kind: "text", maxChars: 5_000 }, minItems: 1, maxItems: 1 },+ {+ name: "aspectRatio",+ value: { kind: "enum", values: ["2:3", "3:2", "1:1", "16:9", "9:16"] },+ minItems: 1,+ maxItems: 1,},- }),-};+ { name: "resolution", value: { kind: "enum", values: ["480p", "720p", "1080p"] }, minItems: 1, maxItems: 1 },+ { name: "duration", value: { kind: "number", integer: true, minimum: 6, maximum: 30 }, minItems: 1, maxItems: 1 },+ { name: "images", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 4 },+ /** Continues an earlier generation; only meaningful beside its source images. */+ { name: "sourceTaskId", value: { kind: "token", minLength: 1, maxLength: 255 }, minItems: 0, maxItems: 1 },+ ],+ requires: [{ kind: "requiresPresent", port: "sourceTaskId", needs: ["images"] }],+});-function object(value: unknown): Record<string, unknown> {- if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Grok Imagine request must be an object");- return value as Record<string, unknown>;-}+export const grokImagine15PreviewPorts: GenerationPortTable = sealGenerationPortTable({+ contract: "svml.generation-ports@1",+ model: "grok-imagine-video-1.5-preview",+ result: "video",+ ports: [+ { name: "prompt", value: { kind: "text", maxChars: 5_000 }, minItems: 1, maxItems: 1 },+ {+ name: "aspectRatio",+ value: { kind: "enum", values: ["2:3", "3:2", "1:1", "16:9", "9:16"] },+ minItems: 1,+ maxItems: 1,+ },+ { name: "resolution", value: { kind: "enum", values: ["480p", "720p", "1080p"] }, minItems: 1, maxItems: 1 },+ { name: "duration", value: { kind: "number", integer: true, minimum: 6, maximum: 30 }, minItems: 1, maxItems: 1 },+ { name: "images", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 4 },+ ],+ requires: [],+});-export function verifyGrokImagineRequest(value: unknown, expectedMode?: GrokImagineMode): asserts value is GrokImagineRequest {- const request = object(value);- if (request.contract !== "svml.grok-imagine-video-request@1") throw new Error("Grok Imagine request contract is invalid");- if (expectedMode !== undefined && request.mode !== expectedMode) throw new Error(`Expected Grok Imagine ${expectedMode}`);- if (request.mode === "image") {- if (request.model !== "grok-imagine-video" || !Array.isArray(request.images) || request.images.length === 0) {- throw new Error("Grok Imagine image request is invalid");- }- request.images.forEach((image) => assertGenerationBlobRef(image, "image/"));- } else if (request.mode === "preview-1.5") {- if (request.model !== "grok-imagine-video-1.5-preview") throw new Error("Grok Imagine preview model is invalid");- if (request.images !== undefined) {- if (!Array.isArray(request.images)) throw new Error("Grok Imagine preview images are invalid");- request.images.forEach((image) => assertGenerationBlobRef(image, "image/"));- }- } else if (request.mode === "text") {- if (request.model !== "grok-imagine-video") throw new Error("Grok Imagine text model is invalid");- } else {- throw new Error("Grok Imagine mode is invalid");- }-}+export const grokImaginePorts: Readonly<Record<GrokImagineModel, GenerationPortTable>> = {+ "grok-imagine-video": grokImagineVideoPorts,+ "grok-imagine-video-1.5-preview": grokImagine15PreviewPorts,+};-export function sealGrokImagineRequest<T extends GrokImagineRequestContent>(- content: T,-): T {- const request = sealGenerationRequest(content);- verifyGrokImagineRequest(request, content.mode);- return request;+export function sealGrokImagineRequest(+ model: GrokImagineModel,+ ports: Readonly<Record<string, readonly GenerationPortValue[]>>,+): GenerationRequest {+ return sealGenerationPortRequest(grokImaginePorts[model], ports);}export const grokImagineDefinition = defineExactModelModule({module: grokImagineModuleRef,- endpoints: (["text", "image", "preview-1.5"] as const).map((mode) => ({- key: mode,- requestTypeName: mode === "text" ? "GrokImagineTextVideoRequest"- : mode === "image" ? "GrokImagineImageVideoRequest" : "GrokImagine15PreviewRequest",- capabilityName: `grok-imagine-${mode}-video-generation`,- producerName: `request-grok-imagine-${mode}`,- result: "video" as const,- requestSchema: schemas[mode],- verifyRequest: (value: unknown) => verifyGrokImagineRequest(value, mode),- })),+ endpoints: [+ {+ key: "video",+ requestTypeName: "GrokImagineVideoRequest",+ producerName: "request-grok-imagine-video",+ ports: grokImagineVideoPorts,+ },+ {+ key: "preview-1.5",+ requestTypeName: "GrokImagine15PreviewRequest",+ producerName: "request-grok-imagine-preview-1-5",+ ports: grokImagine15PreviewPorts,+ },+ ],});export const grokImagineManifest = grokImagineDefinition.manifest;diff --git a/packages/minimax-h3/src/index.ts b/packages/minimax-h3/src/index.tsindex 2ba4e09a..a4604dfc 100644--- a/packages/minimax-h3/src/index.ts+++ b/packages/minimax-h3/src/index.ts@@ -1,129 +1,69 @@-import {- assertGenerationBlobRef,- generationBlobRefSchema,- generationObjectSchema,- generationPromptSchema,- sealGenerationRequest,-} from "@narratage/generation";+import { sealGenerationPortRequest, sealGenerationPortTable } from "@narratage/generation";+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@narratage/generation";import { defineExactModelModule } from "@narratage/model-kit";-import type { BlobRef, ValueSchema } from "@narratage/protocol";export const minimaxH3ModuleRef = { name: "@narratage/minimax-h3", version: "0.0.0-dev" } as const;-export type MinimaxH3Mode = "text" | "frames" | "reference";-export type MinimaxH3Reference =- | { readonly kind: "image"; readonly artifact: BlobRef }- | { readonly kind: "video"; readonly artifact: BlobRef }- | { readonly kind: "audio"; readonly artifact: BlobRef };-type Common = {- readonly contract: "svml.minimax-h3-request@1";- readonly model: "minimax-h3";- readonly prompt: string;- readonly durationSec: number;-};--export type MinimaxH3TextRequestContent = Common & {- readonly mode: "text";- readonly aspectRatio: string;-};-export type MinimaxH3FramesRequestContent = Common & {- readonly mode: "frames";- readonly firstFrame: BlobRef;- readonly lastFrame?: BlobRef;-};-export type MinimaxH3ReferenceRequestContent = Common & {- readonly mode: "reference";- readonly references: readonly MinimaxH3Reference[];- readonly aspectRatio: string;-};-export type MinimaxH3RequestContent =- | MinimaxH3TextRequestContent- | MinimaxH3FramesRequestContent- | MinimaxH3ReferenceRequestContent;-export type MinimaxH3Request = MinimaxH3RequestContent;--const commonFields = {- contract: { schema: { kind: "literal", value: "svml.minimax-h3-request@1" } },- model: { schema: { kind: "literal", value: "minimax-h3" } },- prompt: { schema: generationPromptSchema },- durationSec: { schema: { kind: "number", integer: true, minimum: 1, maximum: 60 } },-} as const;-const aspect = { kind: "string", minLength: 3, maxLength: 16 } as const satisfies ValueSchema;-const referenceSchema: ValueSchema = {- kind: "oneOf",- variants: (["image", "video", "audio"] as const).map((kind) => generationObjectSchema({- kind: { schema: { kind: "literal", value: kind } },- artifact: { schema: generationBlobRefSchema },- })),-};--const schemas: Record<MinimaxH3Mode, ValueSchema> = {- text: generationObjectSchema({- ...commonFields,- mode: { schema: { kind: "literal", value: "text" } },- aspectRatio: { schema: aspect },- }),- frames: generationObjectSchema({- ...commonFields,- mode: { schema: { kind: "literal", value: "frames" } },- firstFrame: { schema: generationBlobRefSchema },- lastFrame: { schema: generationBlobRefSchema, optional: true },- }),- reference: generationObjectSchema({- ...commonFields,- mode: { schema: { kind: "literal", value: "reference" } },- references: { schema: { kind: "array", minItems: 1, maxItems: 12, items: referenceSchema } },- aspectRatio: { schema: aspect },- }),-};--function object(value: unknown, subject: string): Record<string, unknown> {- if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${subject} must be an object`);- return value as Record<string, unknown>;-}--export function verifyMinimaxH3Request(value: unknown, expectedMode?: MinimaxH3Mode): asserts value is MinimaxH3Request {- const request = object(value, "MiniMax H3 request");- if (request.contract !== "svml.minimax-h3-request@1" || request.model !== "minimax-h3") {- throw new Error("MiniMax H3 request identity is invalid");- }- if (expectedMode !== undefined && request.mode !== expectedMode) throw new Error(`Expected MiniMax H3 ${expectedMode}`);- if (request.mode === "frames") {- assertGenerationBlobRef(request.firstFrame, "image/");- if (request.lastFrame !== undefined) assertGenerationBlobRef(request.lastFrame, "image/");- } else if (request.mode === "reference") {- if (!Array.isArray(request.references) || request.references.length === 0) throw new Error("MiniMax H3 references are empty");- request.references.forEach((candidate) => {- const item = object(candidate, "MiniMax H3 reference");- if (item.kind !== "image" && item.kind !== "video" && item.kind !== "audio") {- throw new Error("MiniMax H3 reference kind is invalid");- }- assertGenerationBlobRef(item.artifact, `${item.kind}/` as "image/" | "video/" | "audio/");- });- } else if (request.mode !== "text") {- throw new Error("MiniMax H3 mode is invalid");- }-}+/**+ * What MiniMax H3 accepts is a property of the trained model, not of whichever+ * service resells it. A service that splits these ports across several of its+ * own endpoints expresses that in its wire mapping.+ *+ * `768P` and `2K` are the model's own two output tiers — H3-Base renders at+ * 768p and H3-Regenerate-2K re-renders from the original context — so the+ * spelling is MiniMax's, not any gateway's.+ */+export const minimaxH3Ports: GenerationPortTable = sealGenerationPortTable({+ contract: "svml.generation-ports@1",+ model: "minimax-h3",+ result: "video",+ ports: [+ { name: "prompt", value: { kind: "text", maxChars: 7_000 }, minItems: 1, maxItems: 1 },+ {+ name: "duration",+ value: { kind: "number", integer: true, minimum: 4, maximum: 15 },+ minItems: 1,+ maxItems: 1,+ },+ { name: "resolution", value: { kind: "enum", values: ["768P", "2K"] }, minItems: 0, maxItems: 1 },+ {+ name: "aspectRatio",+ value: { kind: "enum", values: ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16"] },+ minItems: 0,+ maxItems: 1,+ },+ { name: "referenceImage", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 9 },+ { name: "referenceVideo", value: { kind: "media", accepts: ["video"] }, minItems: 0, maxItems: 3 },+ { name: "referenceAudio", value: { kind: "media", accepts: ["audio"] }, minItems: 0, maxItems: 3 },+ { name: "firstFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },+ { name: "lastFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },+ ],+ requires: [+ { kind: "atMostOneOf", ports: ["referenceImage", "firstFrame"] },+ { kind: "atMostOneOf", ports: ["referenceVideo", "firstFrame"] },+ { kind: "atMostOneOf", ports: ["referenceAudio", "firstFrame"] },+ { kind: "requiresAnyOf", port: "referenceAudio", anyOf: ["referenceImage", "referenceVideo"] },+ // A first/last frame run inherits its framing from the uploaded image, so the+ // model takes no aspect ratio in that mode.+ { kind: "atMostOneOf", ports: ["aspectRatio", "firstFrame"] },+ { kind: "weightedTotal", weights: { referenceImage: 1, referenceVideo: 1, referenceAudio: 1 }, maximum: 12 },+ ],+});-export function sealMinimaxH3Request<T extends MinimaxH3RequestContent>(- content: T,-): T {- const request = sealGenerationRequest(content);- verifyMinimaxH3Request(request, content.mode);- return request;+export function sealMinimaxH3Request(+ ports: Readonly<Record<string, readonly GenerationPortValue[]>>,+): GenerationRequest {+ return sealGenerationPortRequest(minimaxH3Ports, ports);}export const minimaxH3Definition = defineExactModelModule({module: minimaxH3ModuleRef,- endpoints: (["text", "frames", "reference"] as const).map((mode) => ({- key: mode,- requestTypeName: `MinimaxH3${mode[0]!.toUpperCase()}${mode.slice(1)}Request`,- capabilityName: `minimax-h3-${mode}-generation`,- producerName: `request-minimax-h3-${mode}`,- result: "video" as const,- requestSchema: schemas[mode],- verifyRequest: (value: unknown) => verifyMinimaxH3Request(value, mode),- })),+ endpoints: [{+ key: "video",+ requestTypeName: "MinimaxH3Request",+ producerName: "request-minimax-h3",+ ports: minimaxH3Ports,+ }],});export const minimaxH3Manifest = minimaxH3Definition.manifest;diff --git a/packages/model-kit/src/index.ts b/packages/model-kit/src/index.tsindex 16498e7c..1d9bee2e 100644--- a/packages/model-kit/src/index.ts+++ b/packages/model-kit/src/index.ts@@ -8,7 +8,10 @@ import {generationManifestDigest,generationModuleRef,generationTypes,+ requestSchemaFromPorts,+ verifyRequestAgainstPorts,} from "@narratage/generation";+import type { GenerationPortTable } from "@narratage/generation";import {canonicalize,digestOf,@@ -21,18 +24,19 @@ import type {ModuleRef,ProducerRef,TypeRef,- ValueSchema,} from "@narratage/protocol";+/**+ * 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 capabilityName: string;readonly producerName: string;- readonly result: "image" | "video";- readonly requestSchema: ValueSchema;- /** Checks digest identity and model-specific constraints after structural validation. */- readonly verifyRequest: (value: unknown) => void;+ readonly ports: GenerationPortTable;};export type ExactModelEndpoint = {@@ -43,23 +47,25 @@ export type ExactModelEndpoint = {readonly returns: TypeRef;readonly implementationDigest: Digest;readonly validatorDigest: Digest;+ readonly ports: GenerationPortTable;readonly fragment: ReturnType<typeof sealGraphFragment>;};-export type ExactModelModule = {+export type ExactModelModule<Key extends string = string> = {readonly module: ModuleRef;readonly manifest: ModuleManifest;readonly manifestDigest: Digest;- readonly endpoints: Readonly<Record<string, ExactModelEndpoint>>;+ /** Keyed by the exact endpoint keys the module declared, so a stale key fails to compile. */+ readonly endpoints: Readonly<Record<Key, ExactModelEndpoint>>;readonly component: ComponentPackage & {readonly validators: readonly TypeValidatorFacet[];readonly producers: readonly ProducerFacet[];};};-export type DefineExactModelModuleOptions = {+export type DefineExactModelModuleOptions<Key extends string = string> = {readonly module: ModuleRef;- readonly endpoints: readonly ExactModelEndpointSpec[];+ readonly endpoints: readonly (Omit<ExactModelEndpointSpec, "key"> & { readonly key: Key })[];};function assert(condition: unknown, message: string): asserts condition {@@ -68,9 +74,9 @@ function assert(condition: unknown, message: string): asserts condition {function endpointRef(module: ModuleRef, spec: ExactModelEndpointSpec) {const requestType = { module, name: spec.requestTypeName };- const capability = { module, name: spec.capabilityName };+ const capability = { module, name: spec.ports.model };const producer = { module, name: spec.producerName };- const returns = spec.result === "image" ? generationTypes.imageSet : generationTypes.videoSet;+ const returns = spec.ports.result === "image" ? generationTypes.imageSet : generationTypes.videoSet;const implementationDigest = digestOf(`${module.name}/${spec.producerName}@1`);const validatorDigest = digestOf(`${module.name}/validate-${spec.requestTypeName}@1`);return { requestType, capability, producer, returns, implementationDigest, validatorDigest };@@ -88,12 +94,16 @@ function inlineRequest(* 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(options: DefineExactModelModuleOptions): ExactModelModule {+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 = {@@ -103,7 +113,7 @@ export function defineExactModelModule(options: DefineExactModelModuleOptions):dependencies: [{ module: generationModuleRef, digest: generationManifestDigest }],types: endpointData.map((item) => ({name: item.requestType.name,- schema: item.spec.requestSchema,+ schema: requestSchemaFromPorts(item.spec.ports),validator: {abi: "svml.type-validator@1",implementation: {@@ -135,7 +145,7 @@ export function defineExactModelModule(options: DefineExactModelModuleOptions):})),};- const endpoints = Object.fromEntries(endpointData.map((item) => {+ const endpoints = Object.fromEntries(endpointData.map((item): [Key, ExactModelEndpoint] => {const fragment = sealGraphFragment({name: `${options.module.name}/${item.spec.key}@1`,inputs: [{ name: "request", type: item.requestType }],@@ -161,6 +171,7 @@ export function defineExactModelModule(options: DefineExactModelModuleOptions):returns: item.returns,implementationDigest: item.implementationDigest,validatorDigest: item.validatorDigest,+ ports: item.spec.ports,fragment,} satisfies ExactModelEndpoint];}));@@ -169,14 +180,14 @@ export function defineExactModelModule(options: DefineExactModelModuleOptions):module: { ...options.module },manifest,manifestDigest: digestOf(manifest),- endpoints,+ endpoints: endpoints as Readonly<Record<Key, ExactModelEndpoint>>,component: {name: options.module.name,validators: endpointData.map((item) => ({type: item.requestType,implementationDigest: item.validatorDigest,handler({ value }) {- item.spec.verifyRequest(inlineRequest(value, item.spec.key));+ verifyRequestAgainstPorts(item.spec.ports, inlineRequest(value, item.spec.key));},})),producers: endpointData.map((item) => ({@@ -186,7 +197,7 @@ export function defineExactModelModule(options: DefineExactModelModuleOptions):const requestRecord = inputs.request;assert(requestRecord !== undefined, `${item.spec.key} request input is missing`);const request = inlineRequest(requestRecord.value, item.spec.key);- item.spec.verifyRequest(request);+ verifyRequestAgainstPorts(item.spec.ports, request);return { outputs: {}, needs: { generation: request } };},})),diff --git a/packages/nano-banana/src/index.ts b/packages/nano-banana/src/index.tsindex 65636e8e..3a484180 100644--- a/packages/nano-banana/src/index.ts+++ b/packages/nano-banana/src/index.ts@@ -1,78 +1,55 @@-import {- assertGenerationBlobRef,- generationBlobRefSchema,- generationObjectSchema,- generationPromptSchema,- sealGenerationRequest,-} from "@narratage/generation";+import { sealGenerationPortRequest, sealGenerationPortTable } from "@narratage/generation";+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@narratage/generation";import { defineExactModelModule } from "@narratage/model-kit";-import type { BlobRef, ValueSchema } from "@narratage/protocol";export const nanoBananaModuleRef = { name: "@narratage/nano-banana", version: "0.0.0-dev" } as const;export const nanoBananaModels = ["nano-banana-2", "nano-banana-pro"] as const;export type NanoBananaModel = typeof nanoBananaModels[number];-export type NanoBananaRequestContent<M extends NanoBananaModel = NanoBananaModel> = {- readonly contract: "svml.nano-banana-request@1";- readonly model: M;- readonly prompt: string;- readonly images?: readonly BlobRef[];- readonly aspectRatio: string;- readonly resolution: "1K" | "2K" | "4K";- readonly outputFormat: "png" | "jpg";-};-export type NanoBananaRequest<M extends NanoBananaModel = NanoBananaModel> = NanoBananaRequestContent<M>;-function requestSchema(model: NanoBananaModel): ValueSchema {- return generationObjectSchema({- contract: { schema: { kind: "literal", value: "svml.nano-banana-request@1" } },- model: { schema: { kind: "literal", value: model } },- prompt: { schema: generationPromptSchema },- images: {- schema: { kind: "array", minItems: 1, maxItems: 16, items: generationBlobRefSchema },- optional: true,- },- aspectRatio: { schema: { kind: "string", minLength: 3, maxLength: 16 } },- resolution: { schema: { kind: "string", enum: ["1K", "2K", "4K"] } },- outputFormat: { schema: { kind: "string", enum: ["png", "jpg"] } },+function nanoBananaPortTable(model: NanoBananaModel): GenerationPortTable {+ return sealGenerationPortTable({+ contract: "svml.generation-ports@1",+ model,+ result: "image",+ ports: [+ { name: "prompt", value: { kind: "text", maxChars: 20_000 }, minItems: 1, maxItems: 1 },+ { name: "images", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 14 },+ {+ name: "aspectRatio",+ value: {+ kind: "enum",+ values: ["auto", "1:1", "2:3", "3:2", "1:4", "4:1", "3:4", "4:3", "4:5",+ "5:4", "1:8", "8:1", "9:16", "16:9", "21:9"],+ },+ minItems: 1,+ maxItems: 1,+ },+ { name: "resolution", value: { kind: "enum", values: ["1K", "2K", "4K"] }, minItems: 1, maxItems: 1 },+ { name: "outputFormat", value: { kind: "enum", values: ["png", "jpg"] }, minItems: 1, maxItems: 1 },+ ],+ requires: [],});}-function object(value: unknown): Record<string, unknown> {- if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Nano Banana request must be an object");- return value as Record<string, unknown>;-}--export function verifyNanoBananaRequest(value: unknown, expectedModel?: NanoBananaModel): asserts value is NanoBananaRequest {- const request = object(value);- if (request.contract !== "svml.nano-banana-request@1"- || !nanoBananaModels.includes(request.model as NanoBananaModel)) {- throw new Error("Nano Banana request identity is invalid");- }- if (expectedModel !== undefined && request.model !== expectedModel) throw new Error(`Expected ${expectedModel}`);- if (request.images !== undefined) {- if (!Array.isArray(request.images) || request.images.length === 0) throw new Error("Nano Banana images are invalid");- request.images.forEach((image) => assertGenerationBlobRef(image, "image/"));- }-}+export const nanoBananaPorts: Readonly<Record<NanoBananaModel, GenerationPortTable>> = {+ "nano-banana-2": nanoBananaPortTable("nano-banana-2"),+ "nano-banana-pro": nanoBananaPortTable("nano-banana-pro"),+};-export function sealNanoBananaRequest<M extends NanoBananaModel>(- content: NanoBananaRequestContent<M>,-): NanoBananaRequest<M> {- const request = sealGenerationRequest(content);- verifyNanoBananaRequest(request, content.model);- return request;+export function sealNanoBananaRequest(+ model: NanoBananaModel,+ ports: Readonly<Record<string, readonly GenerationPortValue[]>>,+): GenerationRequest {+ return sealGenerationPortRequest(nanoBananaPorts[model], ports);}export const nanoBananaDefinition = defineExactModelModule({module: nanoBananaModuleRef,- endpoints: (["nano-banana-2", "nano-banana-pro"] as const).map((model) => ({+ endpoints: nanoBananaModels.map((model) => ({key: model === "nano-banana-2" ? "v2" : "pro",requestTypeName: model === "nano-banana-2" ? "NanoBanana2Request" : "NanoBananaProRequest",- capabilityName: `${model}-generation`,producerName: `request-${model}`,- result: "image" as const,- requestSchema: requestSchema(model),- verifyRequest: (value: unknown) => verifyNanoBananaRequest(value, model),+ ports: nanoBananaPorts[model],})),});diff --git a/packages/provider-kie/package.json b/packages/provider-kie/package.jsonindex 08ec30a8..0324b3bc 100644--- a/packages/provider-kie/package.json+++ b/packages/provider-kie/package.json@@ -11,18 +11,11 @@},"dependencies": {"@narratage/endpoint-kit": "workspace:*",- "@narratage/gemini-omni": "workspace:*","@narratage/generation": "workspace:*",- "@narratage/gpt-image": "workspace:*",- "@narratage/grok-imagine": "workspace:*",- "@narratage/minimax-h3": "workspace:*",- "@narratage/nano-banana": "workspace:*","@narratage/protocol": "workspace:*","@narratage/runtime": "workspace:*","@narratage/runtime-adapter": "workspace:*",- "@narratage/runtime-adapter-node": "workspace:*",- "@narratage/seedance": "workspace:*",- "@narratage/seedream": "workspace:*"+ "@narratage/runtime-adapter-node": "workspace:*"},"devDependencies": {"@narratage/artifact-store-fs": "workspace:*",@@ -30,10 +23,17 @@"@narratage/core": "workspace:*","@narratage/driver-node": "workspace:*","@narratage/elaborator": "workspace:*",+ "@narratage/gemini-omni": "workspace:*",+ "@narratage/gpt-image": "workspace:*",+ "@narratage/grok-imagine": "workspace:*","@narratage/local": "workspace:*","@narratage/media": "workspace:*",+ "@narratage/minimax-h3": "workspace:*","@narratage/model-kit": "workspace:*",+ "@narratage/nano-banana": "workspace:*","@narratage/narrative": "workspace:*",+ "@narratage/seedance": "workspace:*",+ "@narratage/seedream": "workspace:*","@narratage/validation": "workspace:*"}}diff --git a/packages/provider-kie/src/catalog.ts b/packages/provider-kie/src/catalog.tsdeleted file mode 100644index 0111dffa..00000000--- a/packages/provider-kie/src/catalog.ts+++ /dev/null@@ -1,313 +0,0 @@-import {- geminiOmniEndpoints,- verifyGeminiOmniRequest,-} from "@narratage/gemini-omni";-import type { GeminiOmniRequest } from "@narratage/gemini-omni";-import {- gptImageEndpoints,- verifyGptImage2Request,-} from "@narratage/gpt-image";-import type { GptImage2Request } from "@narratage/gpt-image";-import {- grokImagineEndpoints,- verifyGrokImagineRequest,-} from "@narratage/grok-imagine";-import type { GrokImagineRequest } from "@narratage/grok-imagine";-import {- minimaxH3Endpoints,- verifyMinimaxH3Request,-} from "@narratage/minimax-h3";-import type { MinimaxH3Request } from "@narratage/minimax-h3";-import {- nanoBananaEndpoints,- verifyNanoBananaRequest,-} from "@narratage/nano-banana";-import type { NanoBananaRequest } from "@narratage/nano-banana";-import { canonicalize } from "@narratage/protocol";-import type {- BlobRef,- CanonicalValue,- CapabilityRef,- TypeRef,-} from "@narratage/protocol";-import {- seedanceEndpoints,- verifySeedanceRequest,-} from "@narratage/seedance";-import type { SeedanceRequest } from "@narratage/seedance";-import {- seedreamEndpoints,- verifySeedreamRequest,-} from "@narratage/seedream";-import type { SeedreamRequest } from "@narratage/seedream";--export type KieArtifactUrlResolver = (artifact: BlobRef) => Promise<string>;--export type KieTask = {- readonly model: string;- readonly input: CanonicalValue;- readonly result: "image" | "video";-};--export type KieModelAdapter = {- readonly key: string;- readonly capability: CapabilityRef;- readonly returns: TypeRef;- readonly result: "image" | "video";- verify(value: unknown): void;- task(value: unknown, resolve: KieArtifactUrlResolver): Promise<KieTask>;-};--function capabilityKey(ref: CapabilityRef): string {- return `${ref.module.name}@${ref.module.version}#${ref.name}`;-}--async function urls(values: readonly BlobRef[] | undefined, resolve: KieArtifactUrlResolver): Promise<string[]> {- return values === undefined ? [] : await Promise.all(values.map(resolve));-}--function adapter(- key: string,- endpoint: { readonly capability: CapabilityRef; readonly returns: TypeRef },- result: "image" | "video",- verify: (value: unknown) => void,- task: (value: unknown, resolve: KieArtifactUrlResolver) => Promise<KieTask>,-): KieModelAdapter {- return { key, capability: endpoint.capability, returns: endpoint.returns, result, verify, task };-}--const seedanceAdapters = ([- ["standard", "bytedance/seedance-2", "seedance-2"],- ["fast", "bytedance/seedance-2-fast", "seedance-2-fast"],- ["mini", "bytedance/seedance-2-mini", "seedance-2-mini"],-] as const).map(([key, kieModel, authorModel]) => adapter(- `seedance.${key}`,- seedanceEndpoints[key]!,- "video",- (value) => verifySeedanceRequest(value, authorModel),- async (value, resolve) => {- verifySeedanceRequest(value, authorModel);- const request = value as SeedanceRequest;- const modeInput: Record<string, CanonicalValue> = {};- if (request.mode.kind === "frames") {- modeInput.first_frame_url = await resolve(request.mode.firstFrame);- if (request.mode.lastFrame !== undefined) modeInput.last_frame_url = await resolve(request.mode.lastFrame);- } else if (request.mode.kind === "reference") {- const groups = {- image: request.mode.items.filter((item) => item.kind === "image").map((item) => item.artifact),- video: request.mode.items.filter((item) => item.kind === "video").map((item) => item.artifact),- audio: request.mode.items.filter((item) => item.kind === "audio").map((item) => item.artifact),- };- if (groups.image.length > 0) modeInput.reference_image_urls = await urls(groups.image, resolve);- if (groups.video.length > 0) modeInput.reference_video_urls = await urls(groups.video, resolve);- if (groups.audio.length > 0) modeInput.reference_audio_urls = await urls(groups.audio, resolve);- }- return {- model: kieModel,- result: "video",- input: canonicalize({- prompt: request.prompt,- ...modeInput,- return_last_frame: false,- generate_audio: request.generateAudio,- resolution: request.resolution,- aspect_ratio: request.aspectRatio,- duration: request.durationSec,- web_search: request.webSearch,- }),- };- },-));--const minimaxAdapters = ([- ["text", "minimax-h3/text-to-video"],- ["frames", "minimax-h3/image-to-video"],- ["reference", "minimax-h3/reference-to-video"],-] as const).map(([mode, kieModel]) => adapter(- `minimax-h3.${mode}`,- minimaxH3Endpoints[mode]!,- "video",- (value) => verifyMinimaxH3Request(value, mode),- async (value, resolve) => {- verifyMinimaxH3Request(value, mode);- const request = value as MinimaxH3Request;- const input: Record<string, CanonicalValue> = {- prompt: request.prompt,- duration: request.durationSec,- };- if (request.mode === "text") input.aspect_ratio = request.aspectRatio;- if (request.mode === "frames") {- input.first_frame_url = await resolve(request.firstFrame);- if (request.lastFrame !== undefined) input.last_frame_url = await resolve(request.lastFrame);- }- if (request.mode === "reference") {- input.aspect_ratio = request.aspectRatio;- const images = request.references.filter((item) => item.kind === "image").map((item) => item.artifact);- const videos = request.references.filter((item) => item.kind === "video").map((item) => item.artifact);- const audios = request.references.filter((item) => item.kind === "audio").map((item) => item.artifact);- if (images.length > 0) input.reference_image_urls = await urls(images, resolve);- if (videos.length > 0) input.reference_video_urls = await urls(videos, resolve);- if (audios.length > 0) input.reference_audio_urls = await urls(audios, resolve);- }- return {- model: kieModel,- input: canonicalize(input),- result: "video",- };- },-));--const geminiAdapter = adapter(- "gemini-omni.video",- geminiOmniEndpoints.video!,- "video",- verifyGeminiOmniRequest,- async (value, resolve) => {- verifyGeminiOmniRequest(value);- const request = value as GeminiOmniRequest;- const input: Record<string, CanonicalValue> = {- prompt: request.prompt,- duration: String(request.durationSec),- aspect_ratio: request.aspectRatio,- resolution: request.resolution,- };- if (request.seed !== undefined) input.seed = request.seed;- if (request.images !== undefined) input.image_urls = await urls(request.images, resolve);- if (request.audioIds !== undefined) input.audio_ids = [...request.audioIds];- if (request.characterIds !== undefined) input.character_ids = [...request.characterIds];- if (request.videos !== undefined) {- input.video_list = await Promise.all(request.videos.map(async (video) => ({- url: await resolve(video.artifact),- start: video.startSec,- ends: video.endSec,- })));- }- return {- model: "gemini-omni-video",- input: canonicalize(input),- result: "video",- };- },-);--const grokAdapters = (["text", "image", "preview-1.5"] as const).map((mode) => adapter(- `grok-imagine.${mode}`,- grokImagineEndpoints[mode]!,- "video",- (value) => verifyGrokImagineRequest(value, mode),- async (value, resolve) => {- verifyGrokImagineRequest(value, mode);- const request = value as GrokImagineRequest;- const preview = request.mode === "preview-1.5";- const input: Record<string, CanonicalValue> = {- prompt: request.prompt,- aspect_ratio: request.aspectRatio,- resolution: request.resolution,- duration: preview ? request.durationSec : String(request.durationSec),- };- if (!preview) input.mode = "normal";- if (request.mode === "image") {- input.image_urls = await urls(request.images, resolve);- if (request.sourceTaskId !== undefined) input.task_id = request.sourceTaskId;- } else if (request.mode === "preview-1.5" && request.images !== undefined) {- input.image_urls = await urls(request.images, resolve);- }- return {- model: request.mode === "text" ? "grok-imagine/text-to-video"- : request.mode === "image" ? "grok-imagine/image-to-video" : "grok-imagine-video-1-5-preview",- input: canonicalize(input),- result: "video",- };- },-));--const gptImageAdapters = (["text", "image"] as const).map((mode) => adapter(- `gpt-image-2.${mode}`,- gptImageEndpoints[mode]!,- "image",- (value) => verifyGptImage2Request(value, mode),- async (value, resolve) => {- verifyGptImage2Request(value, mode);- const request = value as GptImage2Request;- const input: Record<string, CanonicalValue> = {- prompt: request.prompt,- aspect_ratio: request.aspectRatio,- };- if (request.mode === "image") input.input_urls = await urls(request.images, resolve);- return {- model: request.mode === "text" ? "gpt-image-2-text-to-image" : "gpt-image-2-image-to-image",- input: canonicalize(input),- result: "image",- };- },-));--const nanoAdapters = (["v2", "pro"] as const).map((key) => adapter(- `nano-banana.${key}`,- nanoBananaEndpoints[key]!,- "image",- (value) => verifyNanoBananaRequest(value, key === "v2" ? "nano-banana-2" : "nano-banana-pro"),- async (value, resolve) => {- const model = key === "v2" ? "nano-banana-2" : "nano-banana-pro";- verifyNanoBananaRequest(value, model);- const request = value as NanoBananaRequest;- return {- model,- result: "image",- input: canonicalize({- prompt: request.prompt,- image_input: await urls(request.images, resolve),- aspect_ratio: request.aspectRatio,- resolution: request.resolution,- output_format: request.outputFormat,- }),- };- },-));--const seedreamAdapters = (["text", "image"] as const).map((mode) => adapter(- `seedream.${mode}`,- seedreamEndpoints[mode]!,- "image",- (value) => verifySeedreamRequest(value, mode),- async (value, resolve) => {- verifySeedreamRequest(value, mode);- const request = value as SeedreamRequest;- const input: Record<string, CanonicalValue> = {- prompt: request.prompt,- aspect_ratio: request.aspectRatio,- quality: request.quality,- output_format: request.outputFormat,- nsfw_checker: request.nsfwCheck,- };- if (request.mode === "image") input.image_urls = await urls(request.images, resolve);- return {- model: request.mode === "text" ? "seedream/5-lite-text-to-image" : "seedream/5-lite-image-to-image",- input: canonicalize(input),- result: "image",- };- },-));--export const kieModelCatalog: readonly KieModelAdapter[] = [- ...seedanceAdapters,- ...minimaxAdapters,- geminiAdapter,- ...grokAdapters,- ...gptImageAdapters,- ...nanoAdapters,- ...seedreamAdapters,-];--const catalogByCapability = new Map(kieModelCatalog.map((item) => [capabilityKey(item.capability), item]));--export function kieAdapterForCapability(capability: CapabilityRef): KieModelAdapter | undefined {- return catalogByCapability.get(capabilityKey(capability));-}--export function verifyKieModelCatalog(): void {- if (catalogByCapability.size !== kieModelCatalog.length) throw new Error("KIE model catalog repeats a capability");- kieModelCatalog.forEach((item) => {- if (item.key.trim().length === 0) throw new Error("KIE model catalog contains an empty key");- });-}diff --git a/packages/provider-kie/src/index.ts b/packages/provider-kie/src/index.tsindex f90ce7c9..0dae990a 100644--- a/packages/provider-kie/src/index.ts+++ b/packages/provider-kie/src/index.ts@@ -1,13 +1,8 @@export {- kieAdapterForCapability,+ kieMappingForCapability,kieModelCatalog,verifyKieModelCatalog,-} from "./catalog.js";-export type {- KieArtifactUrlResolver,- KieModelAdapter,- KieTask,-} from "./catalog.js";+} from "./mapping.js";export {createKieProvider,kieProviderImplementationDigest,diff --git a/packages/provider-kie/src/mapping.ts b/packages/provider-kie/src/mapping.tsnew file mode 100644index 00000000..8e2610fe--- /dev/null+++ b/packages/provider-kie/src/mapping.ts@@ -0,0 +1,210 @@+import type { CapabilityRef, ModuleRef } from "@narratage/protocol";+import type { GenerationWireMapping } from "@narratage/generation";++/**+ * How KIE names each model's declared input ports.+ *+ * This file contains data only. It references Capabilities by module and model+ * name, so this Provider package imports no model package: a model owns what it+ * accepts, and KIE owns what it calls that on its wire. Splitting one model+ * across several KIE endpoints is a KIE fact and lives in `routes`.+ */++/** Model packages this KIE release is written against. A version bump is a mapping review. */+const MODEL_VERSION = "0.0.0-dev";++const SEEDANCE: ModuleRef = { name: "@narratage/seedance", version: MODEL_VERSION };+const MINIMAX: ModuleRef = { name: "@narratage/minimax-h3", version: MODEL_VERSION };+const GEMINI: ModuleRef = { name: "@narratage/gemini-omni", version: MODEL_VERSION };+const GROK: ModuleRef = { name: "@narratage/grok-imagine", version: MODEL_VERSION };+const GPT_IMAGE: ModuleRef = { name: "@narratage/gpt-image", version: MODEL_VERSION };+const NANO_BANANA: ModuleRef = { name: "@narratage/nano-banana", version: MODEL_VERSION };+const SEEDREAM: ModuleRef = { name: "@narratage/seedream", version: MODEL_VERSION };++/** KIE keeps each reference modality in its own array, as its schema documents. */+const referenceFields = {+ referenceImage: { as: "urlArray", field: "reference_image_urls" },+ referenceVideo: { as: "urlArray", field: "reference_video_urls" },+ referenceAudio: { as: "urlArray", field: "reference_audio_urls" },+} as const;++function seedanceMapping(model: string, kieModel: string): GenerationWireMapping {+ return {+ contract: "svml.generation-wire-mapping@1",+ capability: { module: SEEDANCE, name: model },+ result: "video",+ routes: [{ model: kieModel }],+ fields: {+ prompt: { as: "value", field: "prompt" },+ ...referenceFields,+ firstFrame: { as: "url", field: "first_frame_url" },+ lastFrame: { as: "url", field: "last_frame_url" },+ resolution: { as: "value", field: "resolution" },+ aspectRatio: { as: "value", field: "aspect_ratio" },+ duration: { as: "value", field: "duration" },+ generateAudio: { as: "value", field: "generate_audio" },+ webSearch: { as: "value", field: "web_search" },+ },+ };+}++const minimaxMapping: GenerationWireMapping = {+ contract: "svml.generation-wire-mapping@1",+ capability: { module: MINIMAX, name: "minimax-h3" },+ result: "video",+ routes: [+ { model: "minimax-h3/image-to-video", whenPresent: ["firstFrame"] },+ { model: "minimax-h3/reference-to-video", whenPresent: ["referenceImage"] },+ { model: "minimax-h3/reference-to-video", whenPresent: ["referenceVideo"] },+ { model: "minimax-h3/text-to-video" },+ ],+ fields: {+ prompt: { as: "value", field: "prompt" },+ duration: { as: "value", field: "duration" },+ resolution: { as: "value", field: "resolution" },+ aspectRatio: { as: "value", field: "aspect_ratio" },+ ...referenceFields,+ firstFrame: { as: "url", field: "first_frame_url" },+ lastFrame: { as: "url", field: "last_frame_url" },+ },+};++const geminiMapping: GenerationWireMapping = {+ contract: "svml.generation-wire-mapping@1",+ capability: { module: GEMINI, name: "gemini-omni-video" },+ result: "video",+ routes: [{ model: "gemini-omni-video" }],+ fields: {+ prompt: { as: "value", field: "prompt" },+ duration: { as: "string", field: "duration" },+ aspectRatio: { as: "value", field: "aspect_ratio" },+ resolution: { as: "value", field: "resolution" },+ seed: { as: "value", field: "seed" },+ images: { as: "urlArray", field: "image_urls" },+ audioIds: { as: "valueArray", field: "audio_ids" },+ characterIds: { as: "valueArray", field: "character_ids" },+ excerpts: {+ as: "itemObject",+ field: "video_list",+ urlKey: "url",+ fieldKeys: { startSec: "start", endSec: "ends" },+ },+ },+};++const grokVideoMapping: GenerationWireMapping = {+ contract: "svml.generation-wire-mapping@1",+ capability: { module: GROK, name: "grok-imagine-video" },+ result: "video",+ routes: [+ { model: "grok-imagine/image-to-video", whenPresent: ["images"] },+ { model: "grok-imagine/text-to-video" },+ ],+ fields: {+ prompt: { as: "value", field: "prompt" },+ aspectRatio: { as: "value", field: "aspect_ratio" },+ resolution: { as: "value", field: "resolution" },+ duration: { as: "string", field: "duration" },+ images: { as: "urlArray", field: "image_urls" },+ sourceTaskId: { as: "value", field: "task_id" },+ },+ constants: { mode: "normal" },+};++const grokPreviewMapping: GenerationWireMapping = {+ contract: "svml.generation-wire-mapping@1",+ capability: { module: GROK, name: "grok-imagine-video-1.5-preview" },+ result: "video",+ routes: [{ model: "grok-imagine-video-1-5-preview" }],+ fields: {+ prompt: { as: "value", field: "prompt" },+ aspectRatio: { as: "value", field: "aspect_ratio" },+ resolution: { as: "value", field: "resolution" },+ duration: { as: "value", field: "duration" },+ images: { as: "urlArray", field: "image_urls" },+ },+};++const gptImageMapping: GenerationWireMapping = {+ contract: "svml.generation-wire-mapping@1",+ capability: { module: GPT_IMAGE, name: "gpt-image-2" },+ result: "image",+ routes: [+ { model: "gpt-image-2-image-to-image", whenPresent: ["images"] },+ { model: "gpt-image-2-text-to-image" },+ ],+ fields: {+ prompt: { as: "value", field: "prompt" },+ aspectRatio: { as: "value", field: "aspect_ratio" },+ resolution: { as: "value", field: "resolution" },+ images: { as: "urlArray", field: "input_urls" },+ },+};++function nanoBananaMapping(model: string): GenerationWireMapping {+ return {+ contract: "svml.generation-wire-mapping@1",+ capability: { module: NANO_BANANA, name: model },+ result: "image",+ routes: [{ model }],+ fields: {+ prompt: { as: "value", field: "prompt" },+ /** KIE expects the key even with no input image. */+ images: { as: "urlArray", field: "image_input", whenAbsent: [] },+ aspectRatio: { as: "value", field: "aspect_ratio" },+ resolution: { as: "value", field: "resolution" },+ outputFormat: { as: "value", field: "output_format" },+ },+ };+}++const seedreamMapping: GenerationWireMapping = {+ contract: "svml.generation-wire-mapping@1",+ capability: { module: SEEDREAM, name: "seedream-5-lite" },+ result: "image",+ routes: [+ { model: "seedream/5-lite-image-to-image", whenPresent: ["images"] },+ { model: "seedream/5-lite-text-to-image" },+ ],+ fields: {+ prompt: { as: "value", field: "prompt" },+ aspectRatio: { as: "value", field: "aspect_ratio" },+ quality: { as: "value", field: "quality" },+ outputFormat: { as: "value", field: "output_format" },+ nsfwCheck: { as: "value", field: "nsfw_checker" },+ images: { as: "urlArray", field: "image_urls" },+ },+};++export const kieModelCatalog: readonly GenerationWireMapping[] = [+ seedanceMapping("seedance-2", "bytedance/seedance-2"),+ seedanceMapping("seedance-2-fast", "bytedance/seedance-2-fast"),+ seedanceMapping("seedance-2-mini", "bytedance/seedance-2-mini"),+ minimaxMapping,+ geminiMapping,+ grokVideoMapping,+ grokPreviewMapping,+ gptImageMapping,+ nanoBananaMapping("nano-banana-2"),+ nanoBananaMapping("nano-banana-pro"),+ seedreamMapping,+];++function capabilityKey(ref: CapabilityRef): string {+ return `${ref.module.name}@${ref.module.version}#${ref.name}`;+}++const catalogByCapability = new Map(kieModelCatalog.map((item) => [capabilityKey(item.capability), item]));++export function kieMappingForCapability(capability: CapabilityRef): GenerationWireMapping | undefined {+ return catalogByCapability.get(capabilityKey(capability));+}++export function verifyKieModelCatalog(): void {+ if (catalogByCapability.size !== kieModelCatalog.length) {+ throw new Error("KIE model catalog repeats a capability");+ }+ kieModelCatalog.forEach((item) => {+ if (item.capability.name.trim().length === 0) throw new Error("KIE model catalog contains an empty model");+ });+}diff --git a/packages/provider-kie/src/provider.ts b/packages/provider-kie/src/provider.tsindex 29575662..41ea2e4b 100644--- a/packages/provider-kie/src/provider.ts+++ b/packages/provider-kie/src/provider.ts@@ -5,9 +5,17 @@ import type {EndpointOutcome,} from "@narratage/endpoint-kit";import {+ compileWireRequest,+ generationTypes,+ mappingSupportsRequest,sealGeneratedImageSet,sealGeneratedVideoSet,} from "@narratage/generation";+import type {+ GenerationArtifactUrlResolver,+ GenerationRequest,+ GenerationWireRequest,+} from "@narratage/generation";import {canonicalize,digestOf,@@ -26,15 +34,10 @@ import { credentialRef } from "@narratage/runtime";import type { ArtifactStore, CredentialRef } from "@narratage/runtime";import {- kieAdapterForCapability,+ kieMappingForCapability,kieModelCatalog,verifyKieModelCatalog,-} from "./catalog.js";-import type {- KieArtifactUrlResolver,- KieModelAdapter,- KieTask,-} from "./catalog.js";+} from "./mapping.js";export const kieProviderModuleRef = { name: "@narratage/provider-kie", version: "0.0.0-dev" } as const;export const kieProviderImplementationDigest = digestOf("@narratage/provider-kie/market-endpoint@1");@@ -245,7 +248,7 @@ class KieClient {return url;}- async createTask(task: KieTask, apiKey: string): Promise<string> {+ async createTask(task: GenerationWireRequest, apiKey: string): Promise<string> {let response: Record<string, unknown>;try {response = await this.#json(`${this.#options.apiBaseUrl}/api/v1/jobs/createTask`, {@@ -374,11 +377,11 @@ function verifyCheckpoint(value: CanonicalValue | undefined, context: EndpointRe);}const checkpoint = object(value, "KIE checkpoint") as unknown as KieCheckpoint;- const adapter = kieAdapterForCapability(context.need.capability);+ const mapping = kieMappingForCapability(context.need.capability);if (checkpoint.contract !== "svml.kie-operation@1"|| typeof checkpoint.taskId !== "string"- || adapter === undefined- || checkpoint.catalogKey !== adapter.key+ || mapping === undefined+ || checkpoint.catalogKey !== mapping.capability.name|| checkpoint.requestDigest !== context.need.requestDigest|| !isDigest(checkpoint.contentRequestDigest)|| !Number.isSafeInteger(checkpoint.startedAt)@@ -419,27 +422,30 @@ function endpoint(options: {return {async start(context) {try {- const adapter = kieAdapterForCapability(context.need.capability);- if (adapter === undefined) throw new KieError("KIE_UNSUPPORTED_CAPABILITY", "KIE does not implement this exact capability");- adapter.verify(context.need.constraints);+ const mapping = kieMappingForCapability(context.need.capability);+ if (mapping === undefined) throw new KieError("KIE_UNSUPPORTED_CAPABILITY", "KIE does not implement this exact capability");const key = secret(context);const uploaded = new Map<Digest, Promise<string>>();- const resolve: KieArtifactUrlResolver = (artifact) => {+ const resolve: GenerationArtifactUrlResolver = (artifact) => {const existing = uploaded.get(artifact.digest);if (existing !== undefined) return existing;const promise = options.client.upload(artifact, context.artifacts, key);uploaded.set(artifact.digest, promise);return promise;};- const task = await adapter.task(context.need.constraints, resolve);+ const task = await compileWireRequest(+ mapping,+ context.need.constraints as unknown as GenerationRequest,+ resolve,+ );await options.gate.enter();const taskId = await options.client.createTask(task, key);const checkpoint: KieCheckpoint = {contract: "svml.kie-operation@1",taskId,- catalogKey: adapter.key,+ catalogKey: mapping.capability.name,model: task.model,- result: task.result,+ result: mapping.result,requestDigest: context.need.requestDigest,contentRequestDigest: contentRequestDigest(context.need.constraints),startedAt: options.now(),@@ -459,11 +465,10 @@ function endpoint(options: {return failure(error);}try {- const adapter = kieAdapterForCapability(context.need.capability);- if (adapter === undefined || adapter.key !== checkpoint.catalogKey) {+ const mapping = kieMappingForCapability(context.need.capability);+ if (mapping === undefined || mapping.capability.name !== checkpoint.catalogKey) {throw new KieError("KIE_CHECKPOINT_INVALID", "KIE checkpoint capability differs");}- adapter.verify(context.need.constraints);if (contentRequestDigest(context.need.constraints) !== checkpoint.contentRequestDigest) {throw new KieError("KIE_CHECKPOINT_INVALID", "KIE checkpoint request content differs");}@@ -604,18 +609,12 @@ export function createKieProvider(config: CreateKieProviderOptions = {}) {defaultConcurrency: config.defaultConcurrency ?? 2,capabilities: kieModelCatalog.map((item) => ({capability: item.capability,- returns: item.returns,+ returns: item.result === "image" ? generationTypes.imageSet : generationTypes.videoSet,lifecycle: "recoverable" as const,endpoint: providerEndpoint,retry: { maxAttempts: 3 },- supports: (need) => {- try {- item.verify(need.constraints);- return true;- } catch {- return false;- }- },+ /** Model semantics were already admitted by Core; KIE only checks it can write every port. */+ supports: (need) => mappingSupportsRequest(item, need.constraints),})),});}diff --git a/packages/provider-kie/test/live-smoke.ts b/packages/provider-kie/test/live-smoke.tsindex d9937bb1..7a8e8631 100644--- a/packages/provider-kie/test/live-smoke.ts+++ b/packages/provider-kie/test/live-smoke.ts@@ -194,15 +194,12 @@ async function smokeCases(root: string): Promise<readonly SmokeCase[]> {{key: "gpt-image-2",media: "image",- endpoint: endpoint(gptImageEndpoints.text, "GPT Image 2 text"),+ endpoint: endpoint(gptImageEndpoints.image, "GPT Image 2"),manifest: gptImageManifest,component: gptImageComponent,request: sealGptImage2Request({- contract: "svml.gpt-image-2-request@1",- model: "gpt-image-2",- mode: "text",- prompt: productPrompt,- aspectRatio: "1:1",+ prompt: [productPrompt],+ aspectRatio: ["1:1"],}) as unknown as CanonicalValue,},{@@ -211,30 +208,25 @@ async function smokeCases(root: string): Promise<readonly SmokeCase[]> {endpoint: endpoint(nanoBananaEndpoints.v2, "Nano Banana 2"),manifest: nanoBananaManifest,component: nanoBananaComponent,- request: sealNanoBananaRequest({- contract: "svml.nano-banana-request@1",- model: "nano-banana-2",- prompt: productPrompt,- aspectRatio: "1:1",- resolution: "1K",- outputFormat: "png",+ request: sealNanoBananaRequest("nano-banana-2", {+ prompt: [productPrompt],+ aspectRatio: ["1:1"],+ resolution: ["1K"],+ outputFormat: ["png"],}) as unknown as CanonicalValue,},{key: "seedream-5-lite",media: "image",- endpoint: endpoint(seedreamEndpoints.text, "Seedream 5 Lite text"),+ endpoint: endpoint(seedreamEndpoints.image, "Seedream 5 Lite"),manifest: seedreamManifest,component: seedreamComponent,request: sealSeedreamRequest({- contract: "svml.seedream-5-lite-request@1",- model: "seedream-5-lite",- mode: "text",- prompt: productPrompt,- aspectRatio: "1:1",- quality: "basic",- outputFormat: "png",- nsfwCheck: true,+ prompt: [productPrompt],+ aspectRatio: ["1:1"],+ quality: ["basic"],+ outputFormat: ["png"],+ nsfwCheck: [true],}) as unknown as CanonicalValue,},{@@ -243,31 +235,25 @@ async function smokeCases(root: string): Promise<readonly SmokeCase[]> {endpoint: endpoint(seedanceEndpoints.mini, "Seedance 2 Mini"),manifest: seedanceManifest,component: seedanceComponent,- request: sealSeedanceRequest({- contract: "svml.seedance-request@1",- model: "seedance-2-mini",- mode: { kind: "text" },- prompt: motionPrompt,- resolution: "480p",- aspectRatio: "1:1",- durationSec: 4,- generateAudio: false,- webSearch: false,+ request: sealSeedanceRequest("seedance-2-mini", {+ prompt: [motionPrompt],+ resolution: ["480p"],+ aspectRatio: ["1:1"],+ duration: [4],+ generateAudio: [false],+ webSearch: [false],}) as unknown as CanonicalValue,},{key: "minimax-h3",media: "video",- endpoint: endpoint(minimaxH3Endpoints.text, "MiniMax H3 text"),+ endpoint: endpoint(minimaxH3Endpoints.video, "MiniMax H3"),manifest: minimaxH3Manifest,component: minimaxH3Component,request: sealMinimaxH3Request({- contract: "svml.minimax-h3-request@1",- model: "minimax-h3",- mode: "text",- prompt: motionPrompt,- durationSec: 6,- aspectRatio: "16:9",+ prompt: [motionPrompt],+ duration: [6],+ aspectRatio: ["16:9"],}) as unknown as CanonicalValue,},{@@ -277,28 +263,23 @@ async function smokeCases(root: string): Promise<readonly SmokeCase[]> {manifest: geminiOmniManifest,component: geminiOmniComponent,request: sealGeminiOmniRequest({- contract: "svml.gemini-omni-request@1",- model: "gemini-omni-video",- prompt: motionPrompt,- durationSec: 4,- aspectRatio: "16:9",- resolution: "720p",+ prompt: [motionPrompt],+ duration: [4],+ aspectRatio: ["16:9"],+ resolution: ["720p"],}) as unknown as CanonicalValue,},{key: "grok-imagine",media: "video",- endpoint: endpoint(grokImagineEndpoints.text, "Grok Imagine text"),+ endpoint: endpoint(grokImagineEndpoints.video, "Grok Imagine"),manifest: grokImagineManifest,component: grokImagineComponent,- request: sealGrokImagineRequest({- contract: "svml.grok-imagine-video-request@1",- model: "grok-imagine-video",- mode: "text",- prompt: motionPrompt,- aspectRatio: "2:3",- resolution: "480p",- durationSec: 6,+ request: sealGrokImagineRequest("grok-imagine-video", {+ prompt: [motionPrompt],+ aspectRatio: ["2:3"],+ resolution: ["480p"],+ duration: [6],}) as unknown as CanonicalValue,},];@@ -310,16 +291,13 @@ async function smokeCases(root: string): Promise<readonly SmokeCase[]> {cases.push({key: "gpt-image-2-edit",media: "image",- endpoint: endpoint(gptImageEndpoints.image, "GPT Image 2 image"),+ endpoint: endpoint(gptImageEndpoints.image, "GPT Image 2 edit"),manifest: gptImageManifest,component: gptImageComponent,request: sealGptImage2Request({- contract: "svml.gpt-image-2-request@1",- model: "gpt-image-2",- mode: "image",- prompt: "Keep the glass sphere unchanged and replace the blue background with a matte warm orange studio background, no text.",- aspectRatio: "1:1",- images: [reference],+ prompt: ["Keep the glass sphere unchanged and replace the blue background with a matte warm orange studio background, no text."],+ aspectRatio: ["1:1"],+ images: [{ role: "image", artifact: reference }],}) as unknown as CanonicalValue,});}diff --git a/packages/provider-kie/test/models.test.ts b/packages/provider-kie/test/models.test.tsindex 50498e36..4469aa1f 100644--- a/packages/provider-kie/test/models.test.ts+++ b/packages/provider-kie/test/models.test.ts@@ -11,22 +11,101 @@ import {sealGeminiOmniRequest,} from "@narratage/gemini-omni";import { MemoryArtifactStore } from "@narratage/driver-node";-import { generationManifest } from "@narratage/generation";-import { gptImageDefinition, gptImageManifest, sealGptImage2Request } from "@narratage/gpt-image";-import { grokImagineDefinition, grokImagineManifest, sealGrokImagineRequest } from "@narratage/grok-imagine";-import { minimaxH3Definition, minimaxH3Manifest, sealMinimaxH3Request } from "@narratage/minimax-h3";-import { nanoBananaDefinition, nanoBananaManifest, sealNanoBananaRequest } from "@narratage/nano-banana";+import {+ assertMappingCoversPorts,+ compileWireRequest,+ generationManifest,+} from "@narratage/generation";+import type { GenerationPortTable } from "@narratage/generation";+import {+ gptImageDefinition,+ gptImageManifest,+ sealGptImage2Request,+} from "@narratage/gpt-image";+import {+ grokImagineDefinition,+ grokImagineManifest,+ sealGrokImagineRequest,+} from "@narratage/grok-imagine";+import {+ minimaxH3Definition,+ minimaxH3Manifest,+ sealMinimaxH3Request,+} from "@narratage/minimax-h3";+import {+ nanoBananaDefinition,+ nanoBananaManifest,+ sealNanoBananaRequest,+} from "@narratage/nano-banana";import { kieModelCatalog } from "@narratage/provider-kie";-import { seedanceDefinition, seedanceManifest, sealSeedanceRequest } from "@narratage/seedance";-import { seedreamDefinition, seedreamManifest, sealSeedreamRequest } from "@narratage/seedream";-import type { LinkedProgram } from "@narratage/protocol";+import { seedanceDefinition, seedanceManifest, seedancePorts, sealSeedanceRequest } from "@narratage/seedance";+import {+ seedreamDefinition,+ seedreamManifest,+ sealSeedreamRequest,+} from "@narratage/seedream";+import type { CapabilityRef, LinkedProgram } from "@narratage/protocol";++/**+ * Every exact model this repository ships, paired with the Capability it publishes.+ * The Capability carries the module version, so a mapping written for an older model+ * version fails here rather than at submission time.+ */+const modelCapabilities: readonly { readonly ports: GenerationPortTable; readonly capability: CapabilityRef }[] = [+ seedanceDefinition, minimaxH3Definition, geminiOmniDefinition, grokImagineDefinition,+ gptImageDefinition, nanoBananaDefinition, seedreamDefinition,+].flatMap((definition) => Object.values(definition.endpoints)+ .map((endpoint) => ({ ports: endpoint.ports, capability: endpoint.capability })));++function capabilityKey(ref: CapabilityRef): string {+ return `${ref.module.name}@${ref.module.version}#${ref.name}`;+}++const upload = async (artifact: { readonly digest: string }) => `https://upload.test/${artifact.digest}`;test("the selected KIE release is seven exact model families and no Grok image capability", () => {- assert.equal(kieModelCatalog.length, 16);- assert.equal(kieModelCatalog.some((item) => item.key.startsWith("grok-imagine.") && item.result === "image"), false);+ assert.equal(kieModelCatalog.length, 11);+ assert.equal(+ kieModelCatalog.some((item) => item.capability.name.startsWith("grok-") && item.result === "image"),+ false,+ );assert.deepEqual(- [...new Set(kieModelCatalog.map((item) => item.key.split(".", 1)[0]))].sort(),- ["gemini-omni", "gpt-image-2", "grok-imagine", "minimax-h3", "nano-banana", "seedance", "seedream"],+ [...new Set(kieModelCatalog.map((item) => item.capability.module.name))].sort(),+ [+ "@narratage/gemini-omni",+ "@narratage/gpt-image",+ "@narratage/grok-imagine",+ "@narratage/minimax-h3",+ "@narratage/nano-banana",+ "@narratage/seedance",+ "@narratage/seedream",+ ],+ );+});++/**+ * The check the old hand-written translators could not perform. Forgetting a+ * reference role or an item field used to surface only after paid generation+ * returned the wrong result; it now fails here.+ */+test("the KIE mapping covers every port every exact model declares", () => {+ assert.equal(modelCapabilities.length, kieModelCatalog.length);+ const mappings = new Map(kieModelCatalog.map((item) => [capabilityKey(item.capability), item]));+ for (const { ports, capability } of modelCapabilities) {+ // Matched on the full Capability, version included: a stale mapping cannot pass by name alone.+ const mapping = mappings.get(capabilityKey(capability));+ assert.ok(mapping, `KIE declares no mapping for ${capabilityKey(capability)}`);+ assertMappingCoversPorts(ports, mapping);+ }+});++test("dropping one reference modality from a mapping fails coverage before any spend", () => {+ const seedance = kieModelCatalog.find((item) => item.capability.name === "seedance-2-mini");+ assert.ok(seedance);+ const { referenceAudio: _dropped, ...withoutAudio } = seedance.fields;+ assert.throws(+ () => assertMappingCoversPorts(seedancePorts["seedance-2-mini"], { ...seedance, fields: withoutAudio }),+ /does not cover port referenceAudio/u,);});@@ -67,33 +146,33 @@ test("Gemini Omni enforces the weighted seven-unit reference quota", async () =>const image = await artifacts.put(new Uint8Array([1]), "image/png");const video = await artifacts.put(new Uint8Array([2]), "video/mp4");assert.throws(() => sealGeminiOmniRequest({- contract: "svml.gemini-omni-request@1",- model: "gemini-omni-video",- prompt: "Use every reference.",- durationSec: 4,- aspectRatio: "16:9",- resolution: "720p",- images: [image, image, image],- videos: [{ artifact: video, startSec: 0, endSec: 1 }],+ prompt: ["Use every reference."],+ duration: [4],+ aspectRatio: ["16:9"],+ resolution: ["720p"],+ images: [+ { role: "image", artifact: image },+ { role: "image", artifact: image },+ { role: "image", artifact: image },+ ],+ excerpts: [{ role: "video", artifact: video, fields: { startSec: 0, endSec: 1 } }],characterIds: ["a", "b", "c"],- }), /quota is 8/u);+ }), /uses 8 of its 7 shared/u);});test("Gemini Omni binds its documented output controls into the KIE request", async () => {const request = sealGeminiOmniRequest({- contract: "svml.gemini-omni-request@1",- model: "gemini-omni-video",- prompt: "A glass sphere rolls across a blue floor.",- durationSec: 4,- aspectRatio: "16:9",- resolution: "720p",- seed: 42,+ prompt: ["A glass sphere rolls across a blue floor."],+ duration: [4],+ aspectRatio: ["16:9"],+ resolution: ["720p"],+ seed: [42],});- const adapter = kieModelCatalog.find((item) => item.key === "gemini-omni.video");- assert.ok(adapter);- const task = await adapter.task(request, async () => "https://upload.test/reference");+ const mapping = kieModelCatalog.find((item) => item.capability.name === "gemini-omni-video");+ assert.ok(mapping);+ const task = await compileWireRequest(mapping, request, upload);assert.deepEqual(task.input, {- prompt: request.prompt,+ prompt: "A glass sphere rolls across a blue floor.",duration: "4",aspect_ratio: "16:9",resolution: "720p",@@ -102,137 +181,143 @@ test("Gemini Omni binds its documented output controls into the KIE request", as});test("Seedream safety policy is explicit author content and contributes to request identity", () => {- const unchecked = sealSeedreamRequest({- contract: "svml.seedream-5-lite-request@1",- model: "seedream-5-lite",- mode: "text",- prompt: "A fashion editorial.",- aspectRatio: "3:4",- quality: "basic",- outputFormat: "png",- nsfwCheck: false,- });- const checked = sealSeedreamRequest({- contract: "svml.seedream-5-lite-request@1",- model: "seedream-5-lite",- mode: "text",- prompt: "A fashion editorial.",- aspectRatio: "3:4",- quality: "basic",- outputFormat: "png",- nsfwCheck: true,- });- assert.equal(unchecked.nsfwCheck, false);+ const base = {+ prompt: ["A fashion editorial."],+ aspectRatio: ["3:4"],+ quality: ["basic"],+ outputFormat: ["png"],+ };+ const unchecked = sealSeedreamRequest({ ...base, nsfwCheck: [false] });+ const checked = sealSeedreamRequest({ ...base, nsfwCheck: [true] });+ assert.deepEqual(unchecked.ports.nsfwCheck, [false]);assert.notEqual(digestOf(unchecked), digestOf(checked));});-test("all sixteen exact capabilities translate to their documented KIE model slug", async () => {+test("all eleven exact capabilities route to their documented KIE model slug", async () => {const store = new MemoryArtifactStore();const image = await store.put(new Uint8Array([1]), "image/png");const video = await store.put(new Uint8Array([2]), "video/mp4");const audio = await store.put(new Uint8Array([3]), "audio/wav");- const seedance = (model: "seedance-2" | "seedance-2-fast" | "seedance-2-mini") => sealSeedanceRequest({- contract: "svml.seedance-request@1",- model,- prompt: "A studio shot.",- mode: { kind: "text" },- resolution: model === "seedance-2" ? "1080p" : "720p",- aspectRatio: "16:9",- durationSec: 5,- generateAudio: false,- webSearch: false,+ const seedance = (model: "seedance-2" | "seedance-2-fast" | "seedance-2-mini") => sealSeedanceRequest(model, {+ prompt: ["A studio shot."],+ resolution: [model === "seedance-2" ? "1080p" : "720p"],+ aspectRatio: ["16:9"],+ duration: [5],+ generateAudio: [false],+ webSearch: [false],});- const commonH3 = {- contract: "svml.minimax-h3-request@1" as const,- model: "minimax-h3" as const,- prompt: "A studio shot.",- durationSec: 6,- };const commonGrok = {- contract: "svml.grok-imagine-video-request@1" as const,- prompt: "A studio shot.",- aspectRatio: "16:9",- resolution: "480p" as const,- durationSec: 6,- };- const commonGpt = {- contract: "svml.gpt-image-2-request@1" as const,- model: "gpt-image-2" as const,- prompt: "A studio portrait.",- aspectRatio: "auto",- };+ prompt: ["A studio shot."],+ aspectRatio: ["16:9"],+ resolution: ["480p"],+ duration: [6],+ } as const;const commonSeedream = {- contract: "svml.seedream-5-lite-request@1" as const,- model: "seedream-5-lite" as const,- prompt: "A studio portrait.",- aspectRatio: "1:1",- quality: "basic" as const,- outputFormat: "png" as const,- nsfwCheck: true,+ prompt: ["A studio portrait."],+ aspectRatio: ["1:1"],+ quality: ["basic"],+ outputFormat: ["png"],+ nsfwCheck: [true],};const cases = [- ["seedance.standard", seedance("seedance-2"), "bytedance/seedance-2"],- ["seedance.fast", seedance("seedance-2-fast"), "bytedance/seedance-2-fast"],- ["seedance.mini", seedance("seedance-2-mini"), "bytedance/seedance-2-mini"],- ["minimax-h3.text", sealMinimaxH3Request({ ...commonH3, mode: "text", aspectRatio: "16:9" }), "minimax-h3/text-to-video"],- ["minimax-h3.frames", sealMinimaxH3Request({ ...commonH3, mode: "frames", firstFrame: image }), "minimax-h3/image-to-video"],- ["minimax-h3.reference", sealMinimaxH3Request({- ...commonH3,- mode: "reference",- aspectRatio: "adaptive",- references: [- { kind: "image", artifact: image },- { kind: "video", artifact: video },- { kind: "audio", artifact: audio },- ],+ ["seedance-2", seedance("seedance-2"), "bytedance/seedance-2"],+ ["seedance-2-fast", seedance("seedance-2-fast"), "bytedance/seedance-2-fast"],+ ["seedance-2-mini", seedance("seedance-2-mini"), "bytedance/seedance-2-mini"],+ ["minimax-h3", sealMinimaxH3Request({+ prompt: ["A studio shot."],+ duration: [6],+ aspectRatio: ["16:9"],+ }), "minimax-h3/text-to-video"],+ ["minimax-h3", sealMinimaxH3Request({+ prompt: ["A studio shot."],+ duration: [6],+ firstFrame: [{ role: "image", artifact: image }],+ }), "minimax-h3/image-to-video"],+ ["minimax-h3", sealMinimaxH3Request({+ prompt: ["A studio shot."],+ duration: [6],+ referenceImage: [{ role: "image", artifact: image }],+ referenceVideo: [{ role: "video", artifact: video }],+ referenceAudio: [{ role: "audio", artifact: audio }],}), "minimax-h3/reference-to-video"],- ["gemini-omni.video", sealGeminiOmniRequest({- contract: "svml.gemini-omni-request@1",- model: "gemini-omni-video",- prompt: "A studio shot.",- durationSec: 4,- aspectRatio: "16:9",- resolution: "720p",- images: [image],+ ["gemini-omni-video", sealGeminiOmniRequest({+ prompt: ["A studio shot."],+ duration: [4],+ aspectRatio: ["16:9"],+ resolution: ["720p"],+ images: [{ role: "image", artifact: image }],}), "gemini-omni-video"],- ["grok-imagine.text", sealGrokImagineRequest({ ...commonGrok, model: "grok-imagine-video", mode: "text" }), "grok-imagine/text-to-video"],- ["grok-imagine.image", sealGrokImagineRequest({+ ["grok-imagine-video", sealGrokImagineRequest("grok-imagine-video", commonGrok), "grok-imagine/text-to-video"],+ ["grok-imagine-video", sealGrokImagineRequest("grok-imagine-video", {...commonGrok,- model: "grok-imagine-video",- mode: "image",- images: [image],+ images: [{ role: "image", artifact: image }],}), "grok-imagine/image-to-video"],- ["grok-imagine.preview-1.5", sealGrokImagineRequest({- ...commonGrok,- model: "grok-imagine-video-1.5-preview",- mode: "preview-1.5",- }), "grok-imagine-video-1-5-preview"],- ["gpt-image-2.text", sealGptImage2Request({ ...commonGpt, mode: "text" }), "gpt-image-2-text-to-image"],- ["gpt-image-2.image", sealGptImage2Request({ ...commonGpt, mode: "image", images: [image] }), "gpt-image-2-image-to-image"],- ["nano-banana.v2", sealNanoBananaRequest({- contract: "svml.nano-banana-request@1",- model: "nano-banana-2",- prompt: "A studio portrait.",- aspectRatio: "auto",- resolution: "2K",- outputFormat: "jpg",+ ["grok-imagine-video-1.5-preview",+ sealGrokImagineRequest("grok-imagine-video-1.5-preview", commonGrok),+ "grok-imagine-video-1-5-preview"],+ ["gpt-image-2", sealGptImage2Request({+ prompt: ["A studio portrait."],+ aspectRatio: ["auto"],+ resolution: ["1K"],+ }), "gpt-image-2-text-to-image"],+ ["gpt-image-2", sealGptImage2Request({+ prompt: ["A studio portrait."],+ aspectRatio: ["auto"],+ resolution: ["1K"],+ images: [{ role: "image", artifact: image }],+ }), "gpt-image-2-image-to-image"],+ ["nano-banana-2", sealNanoBananaRequest("nano-banana-2", {+ prompt: ["A studio portrait."],+ aspectRatio: ["auto"],+ resolution: ["2K"],+ outputFormat: ["jpg"],}), "nano-banana-2"],- ["nano-banana.pro", sealNanoBananaRequest({- contract: "svml.nano-banana-request@1",- model: "nano-banana-pro",- prompt: "A studio portrait.",- images: [image],- aspectRatio: "1:1",- resolution: "1K",- outputFormat: "png",+ ["nano-banana-pro", sealNanoBananaRequest("nano-banana-pro", {+ prompt: ["A studio portrait."],+ images: [{ role: "image", artifact: image }],+ aspectRatio: ["1:1"],+ resolution: ["1K"],+ outputFormat: ["png"],}), "nano-banana-pro"],- ["seedream.text", sealSeedreamRequest({ ...commonSeedream, mode: "text" }), "seedream/5-lite-text-to-image"],- ["seedream.image", sealSeedreamRequest({ ...commonSeedream, mode: "image", images: [image] }), "seedream/5-lite-image-to-image"],+ ["seedream-5-lite", sealSeedreamRequest(commonSeedream), "seedream/5-lite-text-to-image"],+ ["seedream-5-lite", sealSeedreamRequest({+ ...commonSeedream,+ images: [{ role: "image", artifact: image }],+ }), "seedream/5-lite-image-to-image"],] as const;- for (const [key, request, expectedModel] of cases) {- const item = kieModelCatalog.find((candidate) => candidate.key === key);- assert.ok(item, key);- const task = await item.task(request, async (artifact) => `https://upload.test/${artifact.digest}`);- assert.equal(task.model, expectedModel, key);+ for (const [model, request, expectedModel] of cases) {+ const mapping = kieModelCatalog.find((candidate) => candidate.capability.name === model);+ assert.ok(mapping, model);+ const task = await compileWireRequest(mapping, request, upload);+ assert.equal(task.model, expectedModel, `${model} -> ${expectedModel}`);}});++test("one model reaching a service that splits it keeps the reference roles intact", async () => {+ const store = new MemoryArtifactStore();+ const image = await store.put(new Uint8Array([1]), "image/png");+ const audio = await store.put(new Uint8Array([3]), "audio/wav");+ const request = sealSeedanceRequest("seedance-2-mini", {+ prompt: ["A presenter speaks."],+ referenceImage: [{ role: "image", artifact: image }],+ referenceAudio: [{ role: "audio", artifact: audio }],+ resolution: ["720p"],+ aspectRatio: ["9:16"],+ duration: [5],+ generateAudio: [true],+ webSearch: [false],+ });+ const mapping = kieModelCatalog.find((item) => item.capability.name === "seedance-2-mini");+ assert.ok(mapping);+ const task = await compileWireRequest(mapping, request, upload);+ assert.deepEqual(task.input, {+ prompt: "A presenter speaks.",+ reference_image_urls: [`https://upload.test/${image.digest}`],+ reference_audio_urls: [`https://upload.test/${audio.digest}`],+ resolution: "720p",+ aspect_ratio: "9:16",+ duration: 5,+ generate_audio: true,+ web_search: false,+ });+});diff --git a/packages/provider-kie/test/provider.test.ts b/packages/provider-kie/test/provider.test.tsindex 022012ea..8f2f300f 100644--- a/packages/provider-kie/test/provider.test.ts+++ b/packages/provider-kie/test/provider.test.ts@@ -67,16 +67,14 @@ function operation(request: Need) {test("KIE uploads content-addressed references, resumes one task, and persists generated bytes", async () => {const artifacts = new MemoryArtifactStore();const firstFrame = await artifacts.put(new Uint8Array([1, 2, 3]), "image/png");- const requestValue = sealSeedanceRequest({- contract: "svml.seedance-request@1",- model: "seedance-2-mini",- prompt: "A presenter turns toward camera.",- mode: { kind: "frames", firstFrame },- resolution: "720p",- aspectRatio: "16:9",- durationSec: 6,- generateAudio: false,- webSearch: false,+ const requestValue = sealSeedanceRequest("seedance-2-mini", {+ prompt: ["A presenter turns toward camera."],+ firstFrame: [{ role: "image", artifact: firstFrame }],+ resolution: ["720p"],+ aspectRatio: ["16:9"],+ duration: [6],+ generateAudio: [false],+ webSearch: [false],});const request = need(requestValue as unknown as CanonicalValue);const calls: string[] = [];@@ -98,7 +96,6 @@ test("KIE uploads content-addressed references, resumes one task, and persists gassert.equal(body.model, "bytedance/seedance-2-mini");const modelInput = body.input as Record<string, unknown>;assert.equal(modelInput.first_frame_url, "https://tempfile.redpandaai.co/reference.png");- assert.equal(modelInput.return_last_frame, false);return Response.json({ code: 200, msg: "success", data: { taskId: "task_seedance_test" } });}if (url.includes("/api/v1/jobs/recordInfo")) {@@ -154,16 +151,13 @@ test("KIE uploads content-addressed references, resumes one task, and persists g});test("KIE never retries an ambiguous paid submission", async () => {- const requestValue = sealSeedanceRequest({- contract: "svml.seedance-request@1",- model: "seedance-2-mini",- prompt: "A clean studio shot.",- mode: { kind: "text" },- resolution: "720p",- aspectRatio: "16:9",- durationSec: 5,- generateAudio: false,- webSearch: false,+ const requestValue = sealSeedanceRequest("seedance-2-mini", {+ prompt: ["A clean studio shot."],+ resolution: ["720p"],+ aspectRatio: ["16:9"],+ duration: [5],+ generateAudio: [false],+ webSearch: [false],});const request = need(requestValue as unknown as CanonicalValue);let calls = 0;@@ -186,16 +180,13 @@ test("KIE never retries an ambiguous paid submission", async () => {});test("KIE preserves an HTTP-200 business rejection without calling it an ambiguous submission", async () => {- const requestValue = sealSeedanceRequest({- contract: "svml.seedance-request@1",- model: "seedance-2-mini",- prompt: "A clean studio shot.",- mode: { kind: "text" },- resolution: "720p",- aspectRatio: "16:9",- durationSec: 5,- generateAudio: false,- webSearch: false,+ const requestValue = sealSeedanceRequest("seedance-2-mini", {+ prompt: ["A clean studio shot."],+ resolution: ["720p"],+ aspectRatio: ["16:9"],+ duration: [5],+ generateAudio: [false],+ webSearch: [false],});const request = need(requestValue as unknown as CanonicalValue);let calls = 0;@@ -219,16 +210,13 @@ test("KIE preserves an HTTP-200 business rejection without calling it an ambiguo});test("KIE refuses to resubmit when a recovered Operation has no task checkpoint", async () => {- const requestValue = sealSeedanceRequest({- contract: "svml.seedance-request@1",- model: "seedance-2-mini",- prompt: "A clean studio shot.",- mode: { kind: "text" },- resolution: "720p",- aspectRatio: "16:9",- durationSec: 5,- generateAudio: false,- webSearch: false,+ const requestValue = sealSeedanceRequest("seedance-2-mini", {+ prompt: ["A clean studio shot."],+ resolution: ["720p"],+ aspectRatio: ["16:9"],+ duration: [5],+ generateAudio: [false],+ webSearch: [false],});const request = need(requestValue as unknown as CanonicalValue);let calls = 0;diff --git a/packages/seedance-speaker/src/kit.ts b/packages/seedance-speaker/src/kit.tsindex 92bb067c..38f65672 100644--- a/packages/seedance-speaker/src/kit.ts+++ b/packages/seedance-speaker/src/kit.ts@@ -11,6 +11,8 @@ import {} from "@narratage/seedance";import type { SeedanceSpeechProgram } from "@narratage/seedance";+import type { BlobRef } from "@narratage/protocol";+import type { SpeakerTakeIntent } from "./types.js";export const speakerMethodDefaults = {@@ -102,6 +104,18 @@ export function bindSpeakerPromptKit(intent: SpeakerTakeIntent): PromptKitInvocareturn invocation;}+/** The model keeps one port per reference modality; the Speaker groups its takes accordingly. */+function referencePortsOf(+ references: SpeakerTakeIntent["references"],+): Record<string, readonly { readonly role: "image" | "video" | "audio"; readonly artifact: BlobRef }[]> {+ const ports: Record<string, { readonly role: "image" | "video" | "audio"; readonly artifact: BlobRef }[]> = {};+ const names = { image: "referenceImage", video: "referenceVideo", audio: "referenceAudio" } as const;+ for (const item of references) {+ (ports[names[item.kind]] ??= []).push({ role: item.kind, artifact: item.artifact });+ }+ return ports;+}+export function renderSpeakerSpeechProgram(program: PromptProgram,intent: SpeakerTakeIntent,@@ -111,14 +125,13 @@ export function renderSpeakerSpeechProgram(return sealSeedanceSpeechProgram({contract: "svml.seedance-speech-spine@1",model: intent.model,- prompt: program.blocks.map((item) => item.text).join(program.separator),- mode: {- kind: "reference",- items: intent.references.map((item) => ({ kind: item.kind, artifact: item.artifact })),+ ports: {+ prompt: [program.blocks.map((item) => item.text).join(program.separator)],+ ...referencePortsOf(intent.references),+ resolution: [intent.resolution],+ aspectRatio: [intent.aspectRatio],+ generateAudio: [true],+ webSearch: [intent.webSearch],},- resolution: intent.resolution,- aspectRatio: intent.aspectRatio,- generateAudio: true,- webSearch: intent.webSearch,});}diff --git a/packages/seedance-speaker/test/kit.test.ts b/packages/seedance-speaker/test/kit.test.tsindex 3a834f41..bdd57e2c 100644--- a/packages/seedance-speaker/test/kit.test.ts+++ b/packages/seedance-speaker/test/kit.test.ts@@ -92,12 +92,18 @@ test("rendering the generic Prompt Program preserves exact Seedance method and rconst prompt = compilePromptKit(officialUgcV1KitSpec, bindSpeakerPromptKit(take));const program = renderSpeakerSpeechProgram(prompt, take);assert.equal(program.model, "seedance-2-mini");- assert.equal(program.resolution, "720p");- assert.equal(program.aspectRatio, "9:16");- assert.equal(program.mode.kind, "reference");- if (program.mode.kind !== "reference") assert.fail("expected reference mode");- assert.deepEqual(program.mode.items.map((item) => item.kind), ["image", "audio"]);- assert.equal(program.prompt, prompt.blocks.map((item) => item.text).join("\n\n"));+ assert.deepEqual(program.ports.resolution, ["720p"]);+ assert.deepEqual(program.ports.aspectRatio, ["9:16"]);+ assert.deepEqual(+ (program.ports.referenceImage ?? []).map((item) => (item as { readonly role: string }).role),+ ["image"],+ );+ assert.deepEqual(+ (program.ports.referenceAudio ?? []).map((item) => (item as { readonly role: string }).role),+ ["audio"],+ );+ assert.deepEqual(program.ports.prompt, [prompt.blocks.map((item) => item.text).join("\n\n")]);+ assert.equal(program.ports.duration, undefined, "duration arrives from speech estimation");});test("Speaker rejects invalid media while Prompt Kit rejects unknown parameters", () => {diff --git a/packages/seedance/src/index.ts b/packages/seedance/src/index.tsindex 018e0d10..f32f78e8 100644--- a/packages/seedance/src/index.ts+++ b/packages/seedance/src/index.ts@@ -1,60 +1,102 @@import { artifactDependency } from "@narratage/artifact";import {- assertGenerationBlobRef,- generationBlobRefSchema,generationObjectSchema,generationPromptSchema,- sealGenerationRequest,+ portsObjectSchema,+ sealGenerationPortRequest,+ sealGenerationPortTable,+ verifyPortsAgainstTable,+} from "@narratage/generation";+import type {+ GenerationPortTable,+ GenerationPortValue,+ GenerationRequest,} from "@narratage/generation";import { defineExactModelModule } from "@narratage/model-kit";import { narrativeDependency } from "@narratage/narrative";import { assertSpeechDurationIdentity, speechDependency, speechTypes } from "@narratage/speech";import type { SpeechDuration } from "@narratage/speech";import { canonicalize, digestOf } from "@narratage/protocol";-import type { BlobRef, Digest, ProducerRef, TypeRef, ValueSchema } from "@narratage/protocol";+import type { Digest, ProducerRef, TypeRef, ValueSchema } from "@narratage/protocol";export const seedanceModuleRef = { name: "@narratage/seedance", version: "0.0.0-dev" } as const;export const seedanceModels = ["seedance-2", "seedance-2-fast", "seedance-2-mini"] as const;export type SeedanceModel = typeof seedanceModels[number];-export type SeedanceReference =- | { readonly kind: "image"; readonly artifact: BlobRef }- | { readonly kind: "video"; readonly artifact: BlobRef }- | { readonly kind: "audio"; readonly artifact: BlobRef };+const ASPECT_RATIOS = ["1:1", "4:3", "3:4", "16:9", "9:16", "21:9", "adaptive"] as const;-export type SeedanceMode =- | { readonly kind: "text" }- | { readonly kind: "frames"; readonly firstFrame: BlobRef; readonly lastFrame?: BlobRef }- | { readonly kind: "reference"; readonly items: readonly SeedanceReference[] };+/**+ * What Seedance 2 accepts is fixed when the model is trained; no service+ * reselling it can widen or narrow this. Every limit below is stated identically+ * by ByteDance's own launch material, KIE and fal — only the wire field names+ * differ between services, and those live in each Provider's wire mapping.+ *+ * Reference modalities are separate ports because the model gives each its own+ * capacity: 9 images, 3 videos, 3 audio clips, and no more than 12 files in+ * total. Only the resolution ceiling differs between the variants.+ */+function seedancePortTable(model: SeedanceModel): GenerationPortTable {+ return sealGenerationPortTable({+ contract: "svml.generation-ports@1",+ model,+ result: "video",+ ports: [+ { name: "prompt", value: { kind: "text", maxChars: 20_000 }, minItems: 1, maxItems: 1 },+ { name: "referenceImage", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 9 },+ { name: "referenceVideo", value: { kind: "media", accepts: ["video"] }, minItems: 0, maxItems: 3 },+ { name: "referenceAudio", value: { kind: "media", accepts: ["audio"] }, minItems: 0, maxItems: 3 },+ { name: "firstFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },+ { name: "lastFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },+ {+ name: "resolution",+ value: {+ kind: "enum",+ values: model === "seedance-2" ? ["480p", "720p", "1080p", "4k"] : ["480p", "720p"],+ },+ minItems: 1,+ maxItems: 1,+ },+ { name: "aspectRatio", value: { kind: "enum", values: [...ASPECT_RATIOS] }, minItems: 1, maxItems: 1 },+ { name: "duration", value: { kind: "number", integer: true, minimum: 4, maximum: 15 }, minItems: 1, maxItems: 1 },+ { name: "generateAudio", value: { kind: "boolean" }, minItems: 1, maxItems: 1 },+ { name: "webSearch", value: { kind: "boolean" }, minItems: 1, maxItems: 1 },+ ],+ requires: [+ // First-frame, first-and-last-frame and multimodal reference are three+ // scenarios the model cannot combine.+ { kind: "atMostOneOf", ports: ["referenceImage", "firstFrame"] },+ { kind: "atMostOneOf", ports: ["referenceVideo", "firstFrame"] },+ { kind: "atMostOneOf", ports: ["referenceAudio", "firstFrame"] },+ { kind: "requiresPresent", port: "lastFrame", needs: ["firstFrame"] },+ // Reference audio cannot travel alone; it needs at least one visual reference.+ { kind: "requiresAnyOf", port: "referenceAudio", anyOf: ["referenceImage", "referenceVideo"] },+ { kind: "weightedTotal", weights: { referenceImage: 1, referenceVideo: 1, referenceAudio: 1 }, maximum: 12 },+ ],+ });+}-export type SeedanceRequestContent<M extends SeedanceModel = SeedanceModel> = {- readonly contract: "svml.seedance-request@1";- readonly model: M;- readonly prompt: string;- readonly mode: SeedanceMode;- readonly resolution: "480p" | "720p" | "1080p";- readonly aspectRatio: "1:1" | "4:3" | "3:4" | "16:9" | "9:16" | "21:9" | "adaptive";- readonly durationSec: number;- readonly generateAudio: boolean;- readonly webSearch: boolean;+export const seedancePorts: Readonly<Record<SeedanceModel, GenerationPortTable>> = {+ "seedance-2": seedancePortTable("seedance-2"),+ "seedance-2-fast": seedancePortTable("seedance-2-fast"),+ "seedance-2-mini": seedancePortTable("seedance-2-mini"),};-export type SeedanceRequest<M extends SeedanceModel = SeedanceModel> = SeedanceRequestContent<M>;+export type SeedancePortMap = Readonly<Record<string, readonly GenerationPortValue[]>>;++export function sealSeedanceRequest(model: SeedanceModel, ports: SeedancePortMap): GenerationRequest {+ return sealGenerationPortRequest(seedancePorts[model], ports);+}export type SeedancePrompt = {readonly contract: "svml.seedance-prompt@1";readonly text: string;};+/** One authored generation minus the duration only speech estimation can supply. */export type SeedanceSpeechProgram = {readonly contract: "svml.seedance-speech-spine@1";readonly model: SeedanceModel;- readonly prompt: string;- readonly mode: SeedanceMode;- readonly resolution: "480p" | "720p" | "1080p";- readonly aspectRatio: "1:1" | "4:3" | "3:4" | "16:9" | "9:16" | "21:9" | "adaptive";- readonly generateAudio: true;- readonly webSearch: boolean;+ readonly ports: SeedancePortMap;};export const seedanceTypes = {@@ -75,17 +117,22 @@ export const seedanceSpeechCompileImplementationDigests = Object.fromEntries(export const seedanceSurfaceImplementationDigests = {prompt: digestOf("@narratage/seedance/prompt-surface@1"),- speech: digestOf("@narratage/seedance/speech-surface@3"),- video: digestOf("@narratage/seedance/video-surface@1"),+ speech: digestOf("@narratage/seedance/speech-surface@4"),+ video: digestOf("@narratage/seedance/video-surface@2"),} as const;+function assertObject(value: unknown): asserts value is Record<string, unknown> {+ if (value === null || typeof value !== "object" || Array.isArray(value)) {+ throw new Error("Seedance value must be an object");+ }+}+export function sealSeedancePrompt(text: string): SeedancePrompt {const normalized = text.trim();if (normalized.length === 0 || normalized.length > 20_000) {throw new Error("Seedance Prompt must contain 1 to 20,000 characters");}- const content = { contract: "svml.seedance-prompt@1" as const, text: normalized };- return content;+ return { contract: "svml.seedance-prompt@1" as const, text: normalized };}export function verifySeedancePrompt(value: unknown): asserts value is SeedancePrompt {@@ -95,173 +142,50 @@ export function verifySeedancePrompt(value: unknown): asserts value is SeedanceP}}-export function sealSeedanceSpeechProgram(value: SeedanceSpeechProgram): SeedanceSpeechProgram {- const result = structuredClone(value);- verifySeedanceSpeechProgram(result);- return result;-}-export function verifySeedanceSpeechProgram(value: unknown): asserts value is SeedanceSpeechProgram {assertObject(value);- if (- value.contract !== "svml.seedance-speech-spine@1"- || !seedanceModels.includes(value.model as SeedanceModel)- || typeof value.prompt !== "string"- || value.prompt.trim().length === 0- || value.generateAudio !== true- || typeof value.webSearch !== "boolean"- || !["480p", "720p", "1080p"].includes(value.resolution as string)- || !["1:1", "4:3", "3:4", "16:9", "9:16", "21:9", "adaptive"].includes(value.aspectRatio as string)- ) {- throw new Error("Seedance SpeechProgram is invalid");+ if (value.contract !== "svml.seedance-speech-spine@1"+ || !seedanceModels.includes(value.model as SeedanceModel)) {+ throw new Error("Seedance SpeechProgram identity is invalid");}- const program = value as unknown as SeedanceSpeechProgram;- sealSeedanceRequest({- contract: "svml.seedance-request@1",- model: program.model,- prompt: program.prompt,- mode: program.mode,- resolution: program.resolution,- aspectRatio: program.aspectRatio,- durationSec: 4,- generateAudio: true,- webSearch: program.webSearch,- });+ const table = seedancePorts[value.model as SeedanceModel];+ verifyPortsAgainstTable(table, value.ports, { omit: ["duration"] });+ const generateAudio = (value.ports as SeedancePortMap).generateAudio;+ if (generateAudio?.[0] !== true) throw new Error("Seedance SpeechProgram must generate audio");+}++export function sealSeedanceSpeechProgram(value: SeedanceSpeechProgram): SeedanceSpeechProgram {+ const result = canonicalize(value) as unknown as SeedanceSpeechProgram;+ verifySeedanceSpeechProgram(result);+ return result;}export function compileSeedanceSpeechRequest(program: SeedanceSpeechProgram,duration: SpeechDuration,-): SeedanceRequest {+): GenerationRequest {verifySeedanceSpeechProgram(program);assertSpeechDurationIdentity(duration);- if (!Number.isSafeInteger(duration.durationSec) || duration.durationSec < 4 || duration.durationSec > 15) {- throw new Error("Seedance Speech duration must be an integer between 4 and 15 seconds");- }- return sealSeedanceRequest({- contract: "svml.seedance-request@1",- model: program.model,- prompt: program.prompt,- mode: program.mode,- resolution: program.resolution,- aspectRatio: program.aspectRatio,- durationSec: duration.durationSec,- generateAudio: true,- webSearch: program.webSearch,- });+ return sealSeedanceRequest(program.model, { ...program.ports, duration: [duration.durationSec] });}-const referenceSchema: ValueSchema = {- kind: "oneOf",- variants: (["image", "video", "audio"] as const).map((kind) => generationObjectSchema({- kind: { schema: { kind: "literal", value: kind } },- artifact: { schema: generationBlobRefSchema },- })),-};--const modeSchema: ValueSchema = {- kind: "oneOf",- variants: [- generationObjectSchema({ kind: { schema: { kind: "literal", value: "text" } } }),- generationObjectSchema({- kind: { schema: { kind: "literal", value: "frames" } },- firstFrame: { schema: generationBlobRefSchema },- lastFrame: { schema: generationBlobRefSchema, optional: true },- }),- generationObjectSchema({- kind: { schema: { kind: "literal", value: "reference" } },- items: { schema: { kind: "array", minItems: 1, maxItems: 12, items: referenceSchema } },- }),- ],-};--const aspectRatioSchema = {- kind: "string",- enum: ["1:1", "4:3", "3:4", "16:9", "9:16", "21:9", "adaptive"],-} as const satisfies ValueSchema;--const speechSpineSchema: ValueSchema = generationObjectSchema({+const speechSpineSchema = (model: SeedanceModel): ValueSchema => generationObjectSchema({contract: { schema: { kind: "literal", value: "svml.seedance-speech-spine@1" } },- model: { schema: { kind: "string", enum: [...seedanceModels] } },- prompt: { schema: generationPromptSchema },- mode: { schema: modeSchema },- resolution: { schema: { kind: "string", enum: ["480p", "720p", "1080p"] } },- aspectRatio: { schema: aspectRatioSchema },- generateAudio: { schema: { kind: "literal", value: true } },- webSearch: { schema: { kind: "boolean" } },+ model: { schema: { kind: "literal", value: model } },+ ports: { schema: portsObjectSchema(seedancePorts[model], { omit: ["duration"] }) },});-function requestSchema(model: SeedanceModel): ValueSchema {- return generationObjectSchema({- contract: { schema: { kind: "literal", value: "svml.seedance-request@1" } },- model: { schema: { kind: "literal", value: model } },- prompt: { schema: generationPromptSchema },- mode: { schema: modeSchema },- resolution: {- schema: {- kind: "string",- enum: model === "seedance-2" ? ["480p", "720p", "1080p"] : ["480p", "720p"],- },- },- aspectRatio: { schema: aspectRatioSchema },- durationSec: { schema: { kind: "number", integer: true, minimum: 4, maximum: 15 } },- generateAudio: { schema: { kind: "boolean" } },- webSearch: { schema: { kind: "boolean" } },- });-}--function assertObject(value: unknown): asserts value is Record<string, unknown> {- if (value === null || typeof value !== "object" || Array.isArray(value)) {- throw new Error("Seedance request must be an object");- }-}--export function verifySeedanceRequest(value: unknown, expectedModel?: SeedanceModel): asserts value is SeedanceRequest {- assertObject(value);- if (value.contract !== "svml.seedance-request@1") throw new Error("Seedance request contract is invalid");- if (!seedanceModels.includes(value.model as SeedanceModel)) throw new Error("Seedance model is invalid");- if (expectedModel !== undefined && value.model !== expectedModel) throw new Error(`Expected ${expectedModel}`);- const mode = value.mode;- assertObject(mode);- if (mode.kind === "frames") {- assertGenerationBlobRef(mode.firstFrame, "image/");- if (mode.lastFrame !== undefined) assertGenerationBlobRef(mode.lastFrame, "image/");- } else if (mode.kind === "reference") {- if (!Array.isArray(mode.items) || mode.items.length === 0) throw new Error("Seedance references are empty");- for (const item of mode.items) {- assertObject(item);- if (item.kind !== "image" && item.kind !== "video" && item.kind !== "audio") {- throw new Error("Seedance reference kind is invalid");- }- assertGenerationBlobRef(item.artifact, `${item.kind}/` as "image/" | "video/" | "audio/");- }- } else if (mode.kind !== "text") {- throw new Error("Seedance mode is invalid");- }-}--export function sealSeedanceRequest<M extends SeedanceModel>(- content: SeedanceRequestContent<M>,-): SeedanceRequest<M> {- const request = sealGenerationRequest(content);- verifySeedanceRequest(request, content.model);- return request;-}-const seedanceBaseDefinition = defineExactModelModule({module: seedanceModuleRef,- endpoints: [+ endpoints: ([["standard", "seedance-2"],["fast", "seedance-2-fast"],["mini", "seedance-2-mini"],- ].map(([key, model]) => ({- key: key!,- requestTypeName: `${model!.split("-").map((part) => part[0]!.toUpperCase() + part.slice(1)).join("")}Request`,- capabilityName: `${model}-generation`,+ ] as const).map(([key, model]) => ({+ key,+ requestTypeName: `${model.split("-").map((part) => part[0]!.toUpperCase() + part.slice(1)).join("")}Request`,producerName: `request-${model}`,- result: "video" as const,- requestSchema: requestSchema(model as SeedanceModel),- verifyRequest: (value: unknown) => verifySeedanceRequest(value, model as SeedanceModel),+ ports: seedancePorts[model],})),});@@ -282,7 +206,10 @@ export const seedanceManifest = {],types: [...seedanceBaseDefinition.manifest.types,- { name: seedanceTypes.speechSpine.name, schema: speechSpineSchema },+ {+ name: seedanceTypes.speechSpine.name,+ schema: { kind: "oneOf", variants: seedanceModels.map(speechSpineSchema) } satisfies ValueSchema,+ },{name: seedanceTypes.prompt.name,schema: generationObjectSchema({diff --git a/packages/seedance/src/surface.ts b/packages/seedance/src/surface.tsindex 6e393e8d..93a2bf42 100644--- a/packages/seedance/src/surface.ts+++ b/packages/seedance/src/surface.ts@@ -15,22 +15,31 @@ import {createSeedanceGenerationFragment,createSeedanceSpeechGenerationFragment,} from "./fragment.js";+import { generationPort } from "@narratage/generation";+import type { GenerationMediaRole, GenerationPortTable } from "@narratage/generation";+import {sealSeedancePrompt,sealSeedanceRequest,sealSeedanceSpeechProgram,seedanceEndpoints,+ seedancePorts,seedanceSpeechCompileProducers,seedanceTypes,verifySeedancePrompt,} from "./index.js";import type {SeedanceModel,+ SeedancePortMap,SeedancePrompt,- SeedanceReference,} from "./index.js";-type ReferenceInput = SeedanceReference & { readonly role?: string };+/** `role` is the media kind the port accepts; `label` is the author's own note about it. */+type ReferenceInput = {+ readonly role: GenerationMediaRole;+ readonly artifact: BlobRef;+ readonly label?: string;+};function localName(value: string): string {return value.includes(":") ? value.slice(value.lastIndexOf(":") + 1) : value;@@ -154,43 +163,57 @@ function booleanAttribute(element: StructuredElement, name: string, fallback: bothrow new Error(`${element.name}.${name} must be true or false`);}+/** The model's own port table is the only source of truth for these bounds. */+function enumeratedPort(table: GenerationPortTable, name: string): readonly (string | number)[] {+ const port = generationPort(table, name);+ if (port.value.kind !== "enum") throw new Error(`${table.model} port ${name} is not enumerated`);+ return port.value.values;+}+function generationSettings(element: StructuredElement,model: SeedanceModel,suppliedDurationSec?: number,-): {- readonly durationSec: number;- readonly resolution: "480p" | "720p" | "1080p";- readonly aspectRatio: "1:1" | "4:3" | "3:4" | "16:9" | "9:16" | "21:9" | "adaptive";- readonly webSearch: boolean;-} {+): SeedancePortMap {+ const table = seedancePorts[model];+ const duration = generationPort(table, "duration");+ if (duration.value.kind !== "number") throw new Error("Seedance duration port is not numeric");const durationSec = suppliedDurationSec ?? integerAttribute(element, "duration");- if (durationSec < 4 || durationSec > 15) {- throw new Error(`${element.name}.duration must be between 4 and 15 seconds`);+ const { minimum = 0, maximum = Number.MAX_SAFE_INTEGER } = duration.value;+ if (durationSec < minimum || durationSec > maximum) {+ throw new Error(`${element.name}.duration must be between ${minimum} and ${maximum} seconds`);}+ const resolutions = enumeratedPort(table, "resolution");const resolution = optionalStringAttribute(element, "resolution") ?? "720p";- if (resolution !== "480p" && resolution !== "720p" && resolution !== "1080p") {- throw new Error(`${element.name}.resolution must be 480p, 720p or 1080p`);- }- if (resolution === "1080p" && model !== "seedance-2") {- throw new Error(`${element.name}.resolution 1080p is available only for the standard model`);+ if (!resolutions.includes(resolution)) {+ throw new Error(`${element.name}.resolution must be ${resolutions.join(", ")} for ${model}`);}+ const aspectRatios = enumeratedPort(table, "aspectRatio");const aspectRatio = optionalStringAttribute(element, "aspect-ratio") ?? "9:16";- if (!["1:1", "4:3", "3:4", "16:9", "9:16", "21:9", "adaptive"].includes(aspectRatio)) {+ if (!aspectRatios.includes(aspectRatio)) {throw new Error(`${element.name}.aspect-ratio is not supported by Seedance`);}return {- durationSec,- resolution,- aspectRatio: aspectRatio as "1:1" | "4:3" | "3:4" | "16:9" | "9:16" | "21:9" | "adaptive",- webSearch: booleanAttribute(element, "web-search", false),+ duration: [durationSec],+ resolution: [resolution],+ aspectRatio: [aspectRatio],+ webSearch: [booleanAttribute(element, "web-search", false)],};}+const REFERENCE_PORTS = {+ image: "referenceImage",+ video: "referenceVideo",+ audio: "referenceAudio",+} as const satisfies Record<GenerationMediaRole, string>;+function references(element: StructuredElement,+ model: SeedanceModel,resolveReference: (path: string) => SurfaceResolvedReference | undefined,): ReferenceInput[] {+ const table = seedancePorts[model];+ const accepted = Object.keys(REFERENCE_PORTS) as readonly GenerationMediaRole[];const result: ReferenceInput[] = [];for (const child of element.children) {if (child.kind === "text") {@@ -198,29 +221,45 @@ function references(continue;}if (localName(child.name) !== "Reference") throw new Error(`${element.name} accepts only Reference children`);- attributes(child, [], ["image", "video", "audio", "role"]);- const kinds = (["image", "video", "audio"] as const).filter((kind) => child.attributes[kind] !== undefined);- if (kinds.length !== 1) throw new Error(`${child.name} requires exactly one of image, video or audio`);- const kind = kinds[0]!;- const source = resolved(child, kind, resolveReference);- const artifact = blob(source, `${child.name}.${kind}`);- if (!artifact.mediaType.startsWith(`${kind}/`)) {- throw new Error(`${child.name}.${kind} must reference ${kind} media`);+ attributes(child, [], [...accepted, "role"]);+ const kinds = accepted.filter((kind) => child.attributes[kind] !== undefined);+ if (kinds.length !== 1) throw new Error(`${child.name} requires exactly one of ${accepted.join(", ")}`);+ const role = kinds[0]!;+ const source = resolved(child, role, resolveReference);+ const artifact = blob(source, `${child.name}.${role}`);+ if (!artifact.mediaType.startsWith(`${role}/`)) {+ throw new Error(`${child.name}.${role} must reference ${role} media`);+ }+ const label = optionalStringAttribute(child, "role");+ result.push({ role, artifact, ...(label === undefined ? {} : { label }) });+ }+ // Every bound below is read from the model's own port table, never repeated here.+ for (const role of accepted) {+ const port = generationPort(table, REFERENCE_PORTS[role]);+ const used = result.filter((item) => item.role === role).length;+ if (used > port.maxItems) {+ throw new Error(`${element.name} accepts at most ${port.maxItems} ${role} references`);}- const role = optionalStringAttribute(child, "role");- result.push({ kind, artifact, ...(role === undefined ? {} : { role }) });}- if (result.length > 12) throw new Error(`${element.name} accepts at most 12 references`);return result;}function referencePrompt(values: readonly ReferenceInput[]): string {- const roles = values.flatMap((item, index) => item.role === undefined+ const roles = values.flatMap((item, index) => item.label === undefined? []- : [`Reference ${item.kind} ${index + 1} is the ${item.role}.`]);+ : [`Reference ${item.role} ${index + 1} is the ${item.label}.`]);return roles.length === 0 ? "" : `\n\nReference roles:\n${roles.join("\n")}`;}+/** Authored references split into the model's per-modality ports; labels never reach the wire. */+function referencePorts(values: readonly ReferenceInput[]): SeedancePortMap {+ return Object.fromEntries((Object.keys(REFERENCE_PORTS) as readonly GenerationMediaRole[])+ .map((role) => [REFERENCE_PORTS[role], values+ .filter((item) => item.role === role)+ .map(({ artifact }) => ({ role, artifact }))])+ .filter(([, items]) => (items as readonly unknown[]).length > 0));+}+function dialogueExcerpt(reference: SurfaceResolvedReference, subject: string): { readonly dialogue: string } {if (!sameType(reference.type, narrativeTypes.dialogueExcerpt)) {throw new Error(`${subject} must reference a NarrativeDialogueExcerpt such as script.segment.opening.dialogue`);@@ -304,16 +343,12 @@ export const decodeSeedanceVideoSurface: StructuredSurfaceHandler = ({ element,]);const selected = modelSelection(element);const declaredPrompt = prompt(resolved(element, "prompt", resolveReference), `${element.name}.prompt`);- const refs = references(element, resolveReference);- const request = sealSeedanceRequest({- contract: "svml.seedance-request@1",- model: selected.model,- prompt: declaredPrompt.text + referencePrompt(refs),- mode: refs.length === 0- ? { kind: "text" }- : { kind: "reference", items: refs.map(({ role: _role, ...item }) => item) },+ const refs = references(element, selected.model, resolveReference);+ const request = sealSeedanceRequest(selected.model, {+ prompt: [declaredPrompt.text + referencePrompt(refs)],+ ...referencePorts(refs),...generationSettings(element, selected.model),- generateAudio: booleanAttribute(element, "generate-audio", false),+ generateAudio: [booleanAttribute(element, "generate-audio", false)],});return generationOutput(element, request, `${stringAttribute(element, "id")}.video`);};@@ -325,23 +360,20 @@ export const decodeSeedanceSpeechSurface: StructuredSurfaceHandler = ({ element,const selected = modelSelection(element);const declaredPrompt = prompt(resolved(element, "prompt", resolveReference), `${element.name}.prompt`);const spoken = dialogueExcerpt(resolved(element, "dialogue", resolveReference), `${element.name}.dialogue`);- const refs = references(element, resolveReference);+ const refs = references(element, selected.model, resolveReference);const duration = speechDurationReference(element, resolveReference);const promptText = `${declaredPrompt.text}${referencePrompt(refs)}\n\nSpoken dialogue — say exactly:\n${spoken.dialogue}`;- const mode = refs.length === 0- ? { kind: "text" as const }- : { kind: "reference" as const, items: refs.map(({ role: _role, ...item }) => item) };if (duration !== undefined) {- const settings = generationSettings(element, selected.model, 4);+ const { duration: _later, ...settings } = generationSettings(element, selected.model, 4);const program = sealSeedanceSpeechProgram({contract: "svml.seedance-speech-spine@1",model: selected.model,- prompt: promptText,- mode,- resolution: settings.resolution,- aspectRatio: settings.aspectRatio,- generateAudio: true,- webSearch: settings.webSearch,+ ports: {+ prompt: [promptText],+ ...referencePorts(refs),+ ...settings,+ generateAudio: [true],+ },});const id = stringAttribute(element, "id");const programId = `${id}.program`;@@ -369,13 +401,11 @@ export const decodeSeedanceSpeechSurface: StructuredSurfaceHandler = ({ element,fragments: [fragment],};}- const request = sealSeedanceRequest({- contract: "svml.seedance-request@1",- model: selected.model as SeedanceModel,- prompt: promptText,- mode,+ const request = sealSeedanceRequest(selected.model, {+ prompt: [promptText],+ ...referencePorts(refs),...generationSettings(element, selected.model),- generateAudio: true,+ generateAudio: [true],});return generationOutput(element, request, stringAttribute(element, "id"));};diff --git a/packages/seedream/src/index.ts b/packages/seedream/src/index.tsindex fbb624eb..d6668eb0 100644--- a/packages/seedream/src/index.ts+++ b/packages/seedream/src/index.ts@@ -1,92 +1,45 @@-import {- assertGenerationBlobRef,- generationBlobRefSchema,- generationObjectSchema,- generationPromptSchema,- sealGenerationRequest,-} from "@narratage/generation";+import { sealGenerationPortRequest, sealGenerationPortTable } from "@narratage/generation";+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@narratage/generation";import { defineExactModelModule } from "@narratage/model-kit";-import type { BlobRef, ValueSchema } from "@narratage/protocol";export const seedreamModuleRef = { name: "@narratage/seedream", version: "0.0.0-dev" } as const;-export type SeedreamMode = "text" | "image";-type Common = {- readonly contract: "svml.seedream-5-lite-request@1";- readonly model: "seedream-5-lite";- readonly prompt: string;- readonly aspectRatio: string;- readonly quality: "basic";- readonly outputFormat: "png" | "jpg";- /** Explicit author choice; the Provider never silently changes this policy. */- readonly nsfwCheck: boolean;-};-export type SeedreamTextRequestContent = Common & { readonly mode: "text" };-export type SeedreamImageRequestContent = Common & {- readonly mode: "image";- readonly images: readonly BlobRef[];-};-export type SeedreamRequestContent = SeedreamTextRequestContent | SeedreamImageRequestContent;-export type SeedreamRequest = SeedreamRequestContent;-const commonFields = {- contract: { schema: { kind: "literal", value: "svml.seedream-5-lite-request@1" } },- model: { schema: { kind: "literal", value: "seedream-5-lite" } },- prompt: { schema: generationPromptSchema },- aspectRatio: { schema: { kind: "string", minLength: 3, maxLength: 16 } },- quality: { schema: { kind: "literal", value: "basic" } },- outputFormat: { schema: { kind: "string", enum: ["png", "jpg"] } },- nsfwCheck: { schema: { kind: "boolean" } },-} as const;-const schemas: Record<SeedreamMode, ValueSchema> = {- text: generationObjectSchema({- ...commonFields,- mode: { schema: { kind: "literal", value: "text" } },- }),- image: generationObjectSchema({- ...commonFields,- mode: { schema: { kind: "literal", value: "image" } },- images: { schema: { kind: "array", minItems: 1, maxItems: 16, items: generationBlobRefSchema } },- }),-};--function object(value: unknown): Record<string, unknown> {- if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Seedream request must be an object");- return value as Record<string, unknown>;-}--export function verifySeedreamRequest(value: unknown, expectedMode?: SeedreamMode): asserts value is SeedreamRequest {- const request = object(value);- if (request.contract !== "svml.seedream-5-lite-request@1" || request.model !== "seedream-5-lite") {- throw new Error("Seedream request identity is invalid");- }- if (expectedMode !== undefined && request.mode !== expectedMode) throw new Error(`Expected Seedream ${expectedMode}`);- if (request.mode === "image") {- if (!Array.isArray(request.images) || request.images.length === 0) throw new Error("Seedream input images are empty");- request.images.forEach((image) => assertGenerationBlobRef(image, "image/"));- } else if (request.mode !== "text") {- throw new Error("Seedream mode is invalid");- }-}+export const seedream5LitePorts: GenerationPortTable = sealGenerationPortTable({+ contract: "svml.generation-ports@1",+ model: "seedream-5-lite",+ result: "image",+ ports: [+ { name: "prompt", value: { kind: "text", maxChars: 3_000 }, minItems: 1, maxItems: 1 },+ {+ name: "aspectRatio",+ value: { kind: "enum", values: ["1:1", "4:3", "3:4", "16:9", "9:16", "2:3", "3:2", "21:9"] },+ minItems: 1,+ maxItems: 1,+ },+ /** Basic renders 2K, high 3K and ultra 4K. */+ { name: "quality", value: { kind: "enum", values: ["basic", "high", "ultra"] }, minItems: 1, maxItems: 1 },+ { name: "outputFormat", value: { kind: "enum", values: ["png", "jpeg"] }, minItems: 1, maxItems: 1 },+ /** Explicit author choice; the Provider never silently changes this policy. */+ { name: "nsfwCheck", value: { kind: "boolean" }, minItems: 1, maxItems: 1 },+ { name: "images", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 16 },+ ],+ requires: [],+});-export function sealSeedreamRequest<T extends SeedreamRequestContent>(- content: T,-): T {- const request = sealGenerationRequest(content);- verifySeedreamRequest(request, content.mode);- return request;+export function sealSeedreamRequest(+ ports: Readonly<Record<string, readonly GenerationPortValue[]>>,+): GenerationRequest {+ return sealGenerationPortRequest(seedream5LitePorts, ports);}export const seedreamDefinition = defineExactModelModule({module: seedreamModuleRef,- endpoints: (["text", "image"] as const).map((mode) => ({- key: mode,- requestTypeName: mode === "text" ? "Seedream5LiteTextRequest" : "Seedream5LiteImageRequest",- capabilityName: `seedream-5-lite-${mode}-generation`,- producerName: `request-seedream-5-lite-${mode}`,- result: "image" as const,- requestSchema: schemas[mode],- verifyRequest: (value: unknown) => verifySeedreamRequest(value, mode),- })),+ endpoints: [{+ key: "image",+ requestTypeName: "Seedream5LiteRequest",+ producerName: "request-seedream-5-lite",+ ports: seedream5LitePorts,+ }],});export const seedreamManifest = seedreamDefinition.manifest;diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 027eeddd..c417f3a4 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -984,24 +984,9 @@ importers:'@narratage/endpoint-kit':specifier: workspace:*version: link:../endpoint-kit- '@narratage/gemini-omni':- specifier: workspace:*- version: link:../gemini-omni'@narratage/generation':specifier: workspace:*version: link:../generation- '@narratage/gpt-image':- specifier: workspace:*- version: link:../gpt-image- '@narratage/grok-imagine':- specifier: workspace:*- version: link:../grok-imagine- '@narratage/minimax-h3':- specifier: workspace:*- version: link:../minimax-h3- '@narratage/nano-banana':- specifier: workspace:*- version: link:../nano-banana'@narratage/protocol':specifier: workspace:*version: link:../protocol@@ -1014,12 +999,6 @@ importers:'@narratage/runtime-adapter-node':specifier: workspace:*version: link:../runtime-adapter-node- '@narratage/seedance':- specifier: workspace:*- version: link:../seedance- '@narratage/seedream':- specifier: workspace:*- version: link:../seedreamdevDependencies:'@narratage/artifact-store-fs':specifier: workspace:*@@ -1036,18 +1015,39 @@ importers:'@narratage/elaborator':specifier: workspace:*version: link:../elaborator+ '@narratage/gemini-omni':+ specifier: workspace:*+ version: link:../gemini-omni+ '@narratage/gpt-image':+ specifier: workspace:*+ version: link:../gpt-image+ '@narratage/grok-imagine':+ specifier: workspace:*+ version: link:../grok-imagine'@narratage/local':specifier: workspace:*version: link:../local'@narratage/media':specifier: workspace:*version: link:../media+ '@narratage/minimax-h3':+ specifier: workspace:*+ version: link:../minimax-h3'@narratage/model-kit':specifier: workspace:*version: link:../model-kit+ '@narratage/nano-banana':+ specifier: workspace:*+ version: link:../nano-banana'@narratage/narrative':specifier: workspace:*version: link:../narrative+ '@narratage/seedance':+ specifier: workspace:*+ version: link:../seedance+ '@narratage/seedream':+ specifier: workspace:*+ version: link:../seedream'@narratage/validation':specifier: workspace:*version: link:../validationdiff --git a/tools/package-boundaries.test.mjs b/tools/package-boundaries.test.mjsindex e4aca014..d2cc0610 100644--- a/tools/package-boundaries.test.mjs+++ b/tools/package-boundaries.test.mjs@@ -102,6 +102,31 @@ test("the declared domain-neutral distribution closes without syntax, AIGC or viassert.deepEqual(graph.get("@narratage/core"), ["@narratage/protocol"]);});+test("a Provider reaches no exact-model package, so models and services stay N+M", async () => {+ const packages = await workspacePackages();+ const graph = productionGraph(packages);+ const models = [+ "@narratage/gemini-omni",+ "@narratage/gpt-image",+ "@narratage/grok-imagine",+ "@narratage/minimax-h3",+ "@narratage/nano-banana",+ "@narratage/seedance",+ "@narratage/seedream",+ ];+ for (const name of [...packages.keys()].filter((item) => item.startsWith("@narratage/provider-"))) {+ const reached = transitive(graph, name);+ assert.deepEqual(+ models.filter((model) => reached.has(model)),+ [],+ `${name} depends on an exact-model package; a Provider must map declared ports instead`,+ );+ }+ // The shared port and wire-mapping vocabulary is the only legitimate meeting point.+ assert.ok(transitive(graph, "@narratage/provider-kie").has("@narratage/generation"));+ assert.ok(transitive(graph, "@narratage/seedance").has("@narratage/generation"));+});+test("Text compilation is one explicit leaf assembly, not a Package Loader or Local Runtime dependency", async () => {const graph = productionGraph(await workspacePackages());assert.ok(transitive(graph, "@narratage/compiler-text-node").has("@narratage/text"));@@ -172,7 +197,7 @@ test("every workspace package is exercised by some test, directly or through a tfor (const file of await readdir(testRoot)) {if (!file.endsWith(".ts")) continue;const source = await readFile(new URL(file, testRoot), "utf8");- for (const match of source.matchAll(/"(@narratage\/[a-z-]+)"/gu)) {+ for (const match of source.matchAll(/"(@narratage\/[a-z0-9-]+)"/gu)) {testedImports.add(match[1]);for (const dependency of transitive(graph, match[1])) testedImports.add(dependency);}