@nodaro/shared 3.8.0 → 3.10.0

package/src/i18n/types.ts

@@ -120,6 +120,7 @@ export const I18N_CATALOGS = [
   "camera-format",
   "camera-motions",
   "character-fx",
+  "character-motion",
   "color-look",
   "composition-effects",
   "era",

package/src/index.ts

@@ -89,6 +89,12 @@ export {
   AI_WRITER_PROVIDERS,
   QA_CHECK_PROVIDERS,
   SUNO_MODELS,
+  SUNO_ACTIVE_MODELS,
+  SUNO_LEGACY_MODELS,
+  DEFAULT_SUNO_MODEL,
+  SUNO_DURATION_MODELS,
+  isLegacySunoModel,
+  sunoModelHonoursDuration,
   SUNO_ADD_TRACK_MODELS,
   VOICE_DESIGN_MODELS,
   DEFAULT_VOICE_DESIGN_MODEL,
@@ -161,6 +167,7 @@ export {
   DEFAULT_VIDEO_DURATION_SEC,
   applyDefaultVideoSelection,
   PRICING_DEFAULT_DURATION_SEC,
+  pricedOutputDurationSec,
   PRICING_DEFAULT_RESOLUTION,
 } from "./model-constants.js"
 
@@ -247,6 +254,7 @@ export {
   pricedVideoSelection,
   buildMotionCreditModelIdentifier,
   sunoCreditType,
+  SUNO_VERSION_CREDIT_KEYS,
   SUNO_VERSION_PRICED_OPERATIONS,
   SUNO_SELECT_OPERATIONS,
 } from "./credit-identifiers.js"
@@ -540,6 +548,8 @@ export type { LocationCatalogRef } from "./location-preset-catalog-map.js"
 export {
   PARAMETER_NODE_TYPES,
   HINT_EXEMPT_PARAMETER_TYPES,
+  VIDEO_ONLY_PARAMETER_NODE_TYPES,
+  EXECUTION_GRAPH_COMPOSED_PARAMETER_TYPES,
   getParameterValue,
   setRegisteredPersonPackFields,
 } from "./parameter-node-value.js"
@@ -724,6 +734,8 @@ export {
   MODEL_RECOMMENDATIONS,
   listModels,
   groupByFamily,
+  groupByKindAndFamily,
+  MODEL_KINDS,
   getModel,
   validateModelInput,
   // Frontend picker derivers
@@ -970,6 +982,16 @@ export type { VoiceChangerModel } from "./voice-changer-models.js"
 // --- Node presets ---
 export { EXECUTION_DATA_KEYS, TRANSIENT_RUNTIME_KEYS, stripTransientRuntimeData } from "./node-runtime-keys.js"
 
+// --- Execution node state (wire contract) ---
+export {
+  OUTPUT_BEARING_NODE_STATUSES,
+  nodeStateMayCarryOutput,
+} from "./node-execution-state.js"
+export type {
+  NodeExecutionStatus,
+  NodeExecutionStateWire,
+} from "./node-execution-state.js"
+
 export {
   MODEL_PARAM_NODE_TYPES,
   normalizeNodeModelParams,
@@ -996,6 +1018,9 @@ export * from "./reference-sheet/index.js"
 // --- Reference Board (templates + provider constant) ---
 export * from "./reference-board-templates.js"
 
+// --- Marketplace template categories (the eight use cases) ---
+export * from "./template-categories.js"
+
 // --- Model tree (derive node targets + product-line grouping for the Models tab) ---
 export * from "./model-tree.js"
 
@@ -1064,6 +1089,9 @@ export * from "./scene3d-v2.js"
 export * from "./scene3d-v2-plan.js"
 export * from "./scene3d-v2-resources.js"
 export * from "./scene3d-camera-track.js"
+// --- What an authoring run says about its own answer: assumptions, summary,
+//     repair count. Additive and optional on every Scene3D authoring lane. ---
+export * from "./scene3d-delivery-notes.js"
 // --- 3D Render Pro: one durable operation, scene + video in one result ---
 export * from "./pro-3d-render.js"
 // --- Scene3D render pricing: which frame-size tier a render settles at.

package/src/model-catalog.ts

@@ -52,7 +52,6 @@ export type ModelMode =
   | "music"
   | "sfx"
   | "stt"
-  | "voice-clone"
   | "voice-design"
   | "voice-changer"
   | "isolation"
@@ -207,7 +206,7 @@ export const MODEL_RECOMMENDATIONS: readonly ModelRecommendation[] = [
   { intent: "best cinematic video", modelIds: ["veo3", "kling-3.0", "seedance-2"], note: "VEO 3.1 Quality for premium narrative; Kling 3.0 for music-synced motion; Seedance 2 for reference-driven consistency." },
   { intent: "cheap batch video clips", modelIds: ["veo3.1", "wan-turbo", "bytedance-lite"], note: "VEO 3.1 Fast is the best price/quality balance with native audio." },
   { intent: "video with start + end frame", modelIds: ["veo3", "veo3.1", "kling-turbo", "minimax", "hailuo-standard", "seedance-2"], note: "All listed support an end frame; VEO uses imageUrls[start, end]." },
-  { intent: "music / song generation", modelIds: ["suno-v5", "suno"], note: "Suno v5 has better vocal quality at the same price." },
+  { intent: "music / song generation", modelIds: ["suno-v6", "suno-v6_wild", "suno-v6_mini", "suno-v5_5"], note: "V6 is the default flagship; V6 Wild for bolder, less predictable results; V6 Mini when speed matters; v5.5 / v5 / v4 keep their own character. Same price." },
   { intent: "voice over / narration", modelIds: ["elevenlabs-v3", "elevenlabs-turbo"], note: "v3 supports [audio tags] for emotion; Turbo is cheaper for plain narration." },
   { intent: "lip-sync a portrait to audio", modelIds: ["kling-avatar-pro", "kling-avatar", "infinitalk"], note: "Pro for best mouth shape; InfiniTalk for resolution control." },
   { intent: "transcription / captions", modelIds: ["elevenlabs-stt"], note: "Word-level timestamps available." },
@@ -755,23 +754,8 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
       { identifier: "ideogram-remix:QUALITY", credits: 60, note: "best quality" },
     ],
   },
-  "ideogram-reframe": {
-    id: "ideogram-reframe",
-    kind: "image",
-    modes: ["edit"] as const,
-    family: "Ideogram",
-    label: "Ideogram Reframe",
-    series: "Ideogram",
-    description: "Outpaint / reframe to a new aspect ratio while preserving subject.",
-    useCases: ["outpaint", "reframe"],
-    features: ["reference-image"],
-    aspectRatios: IDEOGRAM_RATIOS,
-    pricing: [
-      { identifier: "ideogram-reframe", credits: 18, note: "BALANCED default" },
-      { identifier: "ideogram-reframe:TURBO", credits: 18, note: "fastest" },
-      { identifier: "ideogram-reframe:QUALITY", credits: 18, note: "best quality" },
-    ],
-  },
+  // `ideogram-reframe` was retired 2026-09-15 — KIE's `ideogram/v3-reframe`
+  // fails every task upstream (#1331); see IDEOGRAM_PROVIDERS in model-constants.
 
   // ── Google Imagen ──
   "imagen4": {
@@ -1238,9 +1222,17 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
     family: "Google",
     label: "VEO 3.1 Quality",
     series: "VEO",
-    description: "Google VEO 3.1 Quality — premium cinematic video. 4/6/8s clips, optional end frame, native audio. Flat per-generation pricing across durations.",
+    description: "Google VEO 3.1 Quality — premium cinematic video. 4/6/8s clips, optional end frame, native audio. No reference-to-video mode (Fast/Lite only). Flat per-generation pricing across durations.",
     useCases: ["cinematic", "premium", "narrative"],
-    features: ["end-frame", "audio", "reference-image"],
+    // NO "reference-image": KIE serves REFERENCE_2_VIDEO on the Fast and Lite
+    // SKUs only. Its own words, on a production job (2026-09-04, app-reports
+    // lane G): "Reference to video only supports the Veo Fast model and Veo
+    // Lite model." Until 2026-09-15 this entry claimed the feature, so the
+    // editor offered the reference handles, the adapter sent
+    // generationType: "REFERENCE_2_VIDEO", and the call came back 422 every
+    // time — after credits were reserved. `veo3.1` (KIE `veo3_fast`) and
+    // `veo3_lite` DO serve it and keep the flag.
+    features: ["end-frame", "audio"],
     durations: [4, 6, 8],
     aspectRatios: VIDEO_RATIOS_HV,
     // 720p (default) + 1080p inline. 4K generates the base at 1080p then chains
@@ -2204,7 +2196,7 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
     id: "omnihuman-1-5",
     kind: "video",
     modes: ["lip-sync"] as const,
-    family: "ByteDance",
+    family: "Bytedance",
     label: "OmniHuman 1.5",
     series: "OmniHuman",
     description: "Premium prompt-directed talking avatar from a still image + audio. 720p / 1080p, up to 60s. People, pets, anime.",
@@ -2468,17 +2460,8 @@ const AUDIO_MODELS: Record<string, ModelCatalogEntry> = {
   },
 
   // ── ElevenLabs voice utilities ──
-  "voice-clone": {
-    id: "voice-clone",
-    kind: "audio",
-    modes: ["voice-clone"] as const,
-    family: "ElevenLabs",
-    label: "Voice Clone (Instant)",
-    series: "ElevenLabs",
-    description: "Clone a voice from a short reference clip. Instant clone via direct ElevenLabs API.",
-    useCases: ["voice-clone", "personalization"],
-    pricing: [{ identifier: "voice-clone", credits: 50 }],
-  },
+  // (voice cloning was retired platform-wide on 2026-09-15 — no catalog entry,
+  //  no price, no MCP tool; existing clones still resolve as TTS voice ids.)
   "elevenlabs-voice-design": {
     id: "elevenlabs-voice-design",
     kind: "audio",
@@ -2534,6 +2517,17 @@ const AUDIO_MODELS: Record<string, ModelCatalogEntry> = {
     useCases: ["dubbing", "multilingual"],
     pricing: [{ identifier: "elevenlabs-dubbing", credits: 40, note: "per minute of the dubbed span (min 1)" }],
   },
+  "elevenlabs-dubbing-v2": {
+    id: "elevenlabs-dubbing-v2",
+    kind: "audio",
+    modes: ["dubbing"] as const,
+    family: "ElevenLabs",
+    label: "ElevenLabs Dubbing v2",
+    series: "ElevenLabs",
+    description: "Translate + dub audio or a whole video into a new language — video in, dubbed video out. Async.",
+    useCases: ["dubbing", "multilingual"],
+    pricing: [{ identifier: "elevenlabs-dubbing-v2", credits: 1100, note: "per minute of the dubbed span (min 1)" }],
+  },
   "elevenlabs-forced-alignment": {
     id: "elevenlabs-forced-alignment",
     kind: "audio",
@@ -2580,7 +2574,7 @@ const AUDIO_MODELS: Record<string, ModelCatalogEntry> = {
     label: "Suno v5",
     series: "Suno",
     dataValue: "V5",
-    description: "Newer Suno v5 — better vocal quality, more genres. Same price as v4.",
+    description: "Suno v5 — better vocal quality than v4, more genres. Same price.",
     useCases: ["music", "song", "vocals", "premium"],
     pricing: [{ identifier: "suno-v5", credits: 30, note: "per generation" }],
   },
@@ -2592,11 +2586,47 @@ const AUDIO_MODELS: Record<string, ModelCatalogEntry> = {
     label: "Suno v5.5",
     series: "Suno",
     dataValue: "V5_5",
-    description: "Suno v5.5 — latest model with improved audio quality and expressiveness.",
+    description: "Suno v5.5 — improved audio quality and expressiveness over v5.",
     useCases: ["music", "song", "vocals", "premium"],
     pricing: [{ identifier: "suno-v5_5", credits: 30, note: "per generation" }],
+  },
+  "suno-v6": {
+    id: "suno-v6",
+    kind: "audio",
+    modes: ["music"] as const,
+    family: "Suno",
+    label: "Suno V6",
+    series: "Suno",
+    dataValue: "V6",
+    description: "Suno V6 — greater musical expression with more natural vocals and richer details. The flagship and the default.",
+    useCases: ["music", "song", "vocals", "premium"],
+    pricing: [{ identifier: "suno-v6", credits: 30, note: "per generation" }],
     featured: true,
   },
+  "suno-v6_wild": {
+    id: "suno-v6_wild",
+    kind: "audio",
+    modes: ["music"] as const,
+    family: "Suno",
+    label: "Suno V6 Wild",
+    series: "Suno",
+    dataValue: "V6_WILD",
+    description: "Suno V6 Wild — pushes creative boundaries for bolder, more distinctive musical expression; more varied, less predictable results.",
+    useCases: ["music", "song", "vocals", "experimental"],
+    pricing: [{ identifier: "suno-v6_wild", credits: 30, note: "per generation" }],
+  },
+  "suno-v6_mini": {
+    id: "suno-v6_mini",
+    kind: "audio",
+    modes: ["music"] as const,
+    family: "Suno",
+    label: "Suno V6 Mini",
+    series: "Suno",
+    dataValue: "V6_MINI",
+    description: "Suno V6 Mini — lightweight and fast, balancing quality and speed for effortless creation.",
+    useCases: ["music", "song", "vocals", "fast"],
+    pricing: [{ identifier: "suno-v6_mini", credits: 30, note: "per generation" }],
+  },
 }
 
 // =============================================================================
@@ -2642,6 +2672,29 @@ export function groupByFamily(
   return Array.from(groups.entries()).map(([family, models]) => ({ family, models }))
 }
 
+export const MODEL_KINDS = ["image", "video", "audio"] as const satisfies readonly ModelKind[]
+
+/**
+ * The Image / Video / Audio envelope every model-discovery surface renders
+ * (`GET /v1/models`, MCP `list_models`): each model is filed under ITS OWN
+ * kind, then by vendor family within that kind — so a vendor that ships more
+ * than one kind (Google: Imagen + VEO, ByteDance: Seedream + Seedance, …)
+ * appears once per kind it actually ships.
+ *
+ * This is the ONE grouping both surfaces call. Grouping by family first and
+ * letting the family's first model pick the section filed every VEO, Seedance,
+ * Wan and ByteDance video model under "image" whenever the call carried no
+ * `kind` filter (#1332) — an explicit `kind` pre-filtered the list and hid it.
+ * Empty sections are omitted; section order is fixed image → video → audio.
+ */
+export function groupByKindAndFamily(
+  entries: ModelCatalogEntry[],
+): Array<{ kind: ModelKind; families: Array<{ family: string; models: ModelCatalogEntry[] }> }> {
+  return MODEL_KINDS
+    .map((kind) => ({ kind, families: groupByFamily(entries.filter((m) => m.kind === kind)) }))
+    .filter((section) => section.families.length > 0)
+}
+
 export function getModel(id: string): ModelCatalogEntry | undefined {
   return MODEL_CATALOG[id]
 }

package/src/model-constants.ts

@@ -91,14 +91,20 @@ export const MAX_IMAGE_PROMPT_CHARS_BY_PROVIDER: Record<string, number> = {
   "seedream-5-lite-i2i": 3000, // docs.kie.ai/market/seedream-5-lite-image-to-image (NB: t2i sibling is 1000)
   "qwen": 3000,                // docs.kie.ai/market/qwen/text-to-image
   "qwen-edit": 2000,           // docs.kie.ai/market/qwen/image-edit
+  // Z-Image is the SHORTEST of the family — "maxLength: 1000" in its schema
+  // (docs.kie.ai/market/z-image/z-image, re-fetched 2026-09-15). It was listed
+  // below as "verified == 5000", which is how three production runs on
+  // 2026-09-07 sent a workflow-assembled prompt straight into KIE's
+  // `{"code":500,"msg":"The text length cannot exceed the maximum limit"}`.
+  "z-image": 1000,             // docs.kie.ai/market/z-image/z-image
   // verified == 5000 default (no entry needed): imagen4(-fast/-ultra), nano-banana,
   //   nano-banana-edit, flux, flux-flex, gpt-image-2, ideogram-v3/-edit/-remix,
-  //   z-image, grok, qwen-i2i, seedream-5-pro, seedream-5-pro-i2i
+  //   grok, qwen-i2i, seedream-5-pro, seedream-5-pro-i2i
   //   (docs.kie.ai/market/seedream/5-pro-text-to-image + 5-pro-image-to-image).
   // grok-i2i: doc states 390000 (78× its t2i sibling) — treated as a KIE schema
   //   typo and left at the 5000 default per the sanity-cap decision.
   // UNVERIFIED (no limit stated in schema) → 5000 default: flux-kontext(-max)
-  //   gpt-image, gpt-image-i2i, flux-i2i, flux-pro-i2i, ideogram-reframe.
+  //   gpt-image, gpt-image-i2i, flux-i2i, flux-pro-i2i.
 }
 
 /** Max assembled image-prompt length (chars) for a provider: its verified
@@ -119,10 +125,10 @@ export const VIDEO_PROMPT_MAX = 8000
 
 /**
  * Suno prompt / lyrics / content ceiling — the LARGEST any Suno version accepts
- * in custom mode (V4.5 / V4.5PLUS / V4.5ALL / V5 / V5.5 = 5000). NOT the route
+ * in custom mode (V6 family and V4.5+ / V5 / V5.5 = 5000). NOT the route
  * Zod bound — the routes bind at {@link SUNO_HARD_CEILING} and clamp to the
  * per-version cap via {@link getMaxSunoPromptChars} (3000 non-custom for every
- * version; in custom mode 3000 for V4/V3.5, 5000 for V4.5+/V5) before the job
+ * version; in custom mode 3000 for V4/V3.5, 5000 for V4.5+/V5/V6) before the job
  * is built. This constant is shared with the editor `maxLength` / counter
  * (warn-don't-block at the per-version cap). `style` and `title` have their
  * own caps ({@link getMaxSunoStyleChars} / {@link SUNO_TITLE_MAX}).
@@ -310,9 +316,11 @@ export function getMaxTtsChars(provider: string | undefined): number {
  * SUNO_TEXT_MAX} is 5000 today — the largest per-version prompt cap; the
  * route Zod bound is {@link SUNO_HARD_CEILING}.)
  *   - prompt / lyrics: 3000 in non-custom mode (all versions); in custom mode
- *     3000 for V4/V3.5 and 5000 for V4.5 / V4.5PLUS / V4.5ALL / V5 / V5.5.
- *   - style: 200 for V4/V3.5, 1000 for V4.5+.
- *   - title: 80 (all versions).
+ *     3000 for V4/V3.5 and 5000 for V4.5 / V4.5PLUS / V4.5ALL / V5 / V5.5 and
+ *     the whole V6 family (V6 / V6_WILD / V6_MINI).
+ *   - style: 200 for V4/V3.5, 1000 for V4.5+ and V6.
+ *   - title: 80 (all versions; the extend docs quote 100 for V6 — we keep the
+ *     stricter generate cap so one value is right everywhere).
  */
 export const SUNO_TITLE_MAX = 80
 
@@ -506,7 +514,6 @@ export const MODELS_WITH_REFERENCE_IMAGE_SUPPORT = new Set([
   "flux-kontext-max",
   "ideogram-edit",
   "ideogram-remix",
-  "ideogram-reframe",
   "qwen-i2i",
   "qwen-edit",
   "seedream-edit",
@@ -586,7 +593,6 @@ export const REF_IMAGE_MAX_LIMITS: Record<string, number> = {
   "flux-kontext-max": 1,
   "ideogram-edit": 1,
   "ideogram-remix": 1,
-  "ideogram-reframe": 1,
   "qwen-i2i": 1,
   "qwen-edit": 1,
   "grok-i2i": 1,
@@ -660,7 +666,6 @@ export const VARIABLE_PRICING_MODELS: Record<string, "quality" | "resolution" |
   "topaz-image-upscale": "resolution",
   "ideogram-edit": "rendering-speed",
   "ideogram-remix": "rendering-speed",
-  "ideogram-reframe": "rendering-speed",
   "ideogram-v3": "rendering-speed",
   "wan-2.7": "resolution",
   "wan-2.7-pro": "resolution",
@@ -687,7 +692,12 @@ export const RESOLUTION_2K_4K_TIERED_PROVIDERS = new Set([
 ])
 
 // Ideogram family models with TURBO/QUALITY pricing variants
-export const IDEOGRAM_PROVIDERS = new Set(["ideogram-edit", "ideogram-remix", "ideogram-reframe", "ideogram-v3"])
+// `ideogram-reframe` (KIE `ideogram/v3-reframe`) was retired 2026-09-15: KIE no
+// longer documents the model and every task — the minimal documented payload
+// included — fails upstream with "[500] internal error" (#1331). Its price rows
+// are removed by migration 424; re-add everywhere per the Provider Enum Sync
+// table if KIE brings it back.
+export const IDEOGRAM_PROVIDERS = new Set(["ideogram-edit", "ideogram-remix", "ideogram-v3"])
 
 // =====================================================================
 // Provider arrays (single source of truth for route Zod validation)
@@ -742,7 +752,6 @@ export const IMAGE_I2I_PROVIDERS = [
   "grok-2-i2i",
   "ideogram-edit",
   "ideogram-remix",
-  "ideogram-reframe",
   "qwen-i2i",
   "qwen-edit",
   "seedream-edit",
@@ -1229,19 +1238,72 @@ export const QA_CHECK_PROVIDERS = [
 ] as const
 export type QaCheckProvider = typeof QA_CHECK_PROVIDERS[number]
 
-/** Suno model versions */
-export const SUNO_MODELS = [
-  "V4",
-  "V4_5",
+/**
+ * The current Suno generation (docs.kie.ai/suno-api/generate-music, 2026-09:
+ * the V6 family), listed first in every picker; V6 is the default.
+ *
+ *   - V6      — flagship: greater musical expression, more natural vocals, richer details.
+ *   - V6_WILD — bolder, more distinctive, less predictable output for exploration.
+ *   - V6_MINI — lightweight and fast; quality/speed balance.
+ *
+ * This is also the set that honours `duration` ({@link SUNO_DURATION_MODELS}).
+ */
+export const SUNO_ACTIVE_MODELS = ["V6", "V6_WILD", "V6_MINI"] as const
+export type SunoActiveModel = typeof SUNO_ACTIVE_MODELS[number]
+
+/**
+ * The earlier Suno generations. Still offered in every picker as ordinary
+ * choices (users report each has its own character), still accepted by every
+ * route, and confirmed generating on 2026-09-11. KIE's docs tag them
+ * "Discontinued"; if KIE ever stops serving one, coerce it to
+ * {@link DEFAULT_SUNO_MODEL} at the provider send seam — never remove it from
+ * {@link SUNO_MODELS}, which would 400 every saved music workflow.
+ */
+export const SUNO_LEGACY_MODELS = [
+  "V5_5",
+  "V5",
   "V4_5PLUS",
   "V4_5ALL",
-  "V5",
-  "V5_5",
+  "V4_5",
+  "V4",
 ] as const
+export type SunoLegacyModel = typeof SUNO_LEGACY_MODELS[number]
+
+/**
+ * Every Suno model version — the picker order, the route / MCP Zod enum and
+ * the `data.model` type on Suno nodes. Current generation first (V6 = default),
+ * then the earlier generations newest-first.
+ */
+export const SUNO_MODELS = [...SUNO_ACTIVE_MODELS, ...SUNO_LEGACY_MODELS] as const
 export type SunoModel = typeof SUNO_MODELS[number]
 
-/** Suno models that support add-instrumental / add-vocals operations */
-export const SUNO_ADD_TRACK_MODELS = ["V4_5PLUS", "V5", "V5_5"] as const
+/** The Suno version used when a caller omits `model` — KIE's own default. */
+export const DEFAULT_SUNO_MODEL = "V6" satisfies SunoActiveModel
+
+export function isLegacySunoModel(model: string | undefined): model is SunoLegacyModel {
+  return (SUNO_LEGACY_MODELS as readonly string[]).includes(model ?? "")
+}
+
+/**
+ * Suno versions that HONOUR `duration` (custom mode only). Per the generate /
+ * extend docs the field "will only take effect when the model is V6, V6_MINI,
+ * or V6_WILD" — V5_5 was struck from that sentence when V6 shipped. The
+ * provider client's send-gate (`sunoGenerate` in suno-client.ts) is the single
+ * chokepoint that consults this set; the editor uses it only to decide whether
+ * to SHOW the duration field.
+ */
+export const SUNO_DURATION_MODELS: ReadonlySet<string> = new Set<SunoModel>(SUNO_ACTIVE_MODELS)
+
+export function sunoModelHonoursDuration(model: string | undefined): boolean {
+  return SUNO_DURATION_MODELS.has(model ?? "")
+}
+
+/**
+ * Suno models accepted by add-instrumental / add-vocals (docs enum: the V6
+ * family plus V4_5PLUS / V5 / V5_5). Same current-then-earlier order as
+ * {@link SUNO_MODELS}.
+ */
+export const SUNO_ADD_TRACK_MODELS = [...SUNO_ACTIVE_MODELS, "V4_5PLUS", "V5", "V5_5"] as const
 export type SunoAddTrackModel = typeof SUNO_ADD_TRACK_MODELS[number]
 
 /** Voice design models */
@@ -1310,7 +1372,7 @@ export const I2I_STRENGTH_SUPPORT: Record<string, { min: number; max: number; st
 
 /** Models that accept a seed parameter for reproducible generation */
 export const SEED_SUPPORT = new Set([
-  "ideogram-remix", "ideogram-reframe", "ideogram-v3",
+  "ideogram-remix", "ideogram-v3",
   "qwen", "qwen-i2i", "qwen-edit",
   "flux", "flux-flex", "flux-i2i", "flux-pro-i2i", "flux-kontext", "flux-kontext-max",
   "flux-2-klein", "kontext-multi",
@@ -1318,7 +1380,7 @@ export const SEED_SUPPORT = new Set([
 
 /** Ideogram models that support rendering_speed selection (TURBO/BALANCED/QUALITY) */
 export const RENDERING_SPEED_SUPPORT = new Set([
-  "ideogram-remix", "ideogram-reframe", "ideogram-v3",
+  "ideogram-remix", "ideogram-v3",
 ])
 
 /** Models that accept guidance_scale for controlling prompt adherence */
@@ -1924,8 +1986,13 @@ export const VIDEO_REF_LIMITS_BY_PROVIDER: Record<
   "kling-3-omni": { images: 7 },     // catalog/docs: "end frame + up to 7 reference images"
   "grok-i2v": { images: 7 },         // backend kie/models.ts maxRefImages: 7
   "happyhorse-ref2v": { images: 9 }, // backend kie/models.ts maxRefImages: 9
-  // VEO 3.x — REFERENCE_2_VIDEO path caps refs at 3 (kie/video.ts slice(0, 3)).
-  "veo3": { images: 3 },
+  // VEO 3.x — REFERENCE_2_VIDEO path caps refs at 3 (kie/video.ts slices to
+  // this number). `veo3` (VEO 3.1 QUALITY) is deliberately ABSENT: KIE serves
+  // reference-to-video on the Fast and Lite SKUs only and rejects it on
+  // Quality with "Reference to video only supports the Veo Fast model and Veo
+  // Lite model." (production, 2026-09-04). Absent ⇒ 0 ⇒ the handle dims, the
+  // `connectedReferences` assembly strips image tokens, and kie/video.ts never
+  // flips a Quality call to REFERENCE_2_VIDEO.
   "veo3.1": { images: 3 },
   "veo3_lite": { images: 3 },
   // NOTE: wan-i2v / hailuo-2.3[-pro] / bytedance-pro[-fast] / grok-imagine-video-1.5
@@ -2458,6 +2525,33 @@ export const VIDEO_VARIABLE_PRICING: Record<string, "duration" | "duration+audio
  */
 export const PRICING_DEFAULT_DURATION_SEC: Record<string, number> = {
   "minimax-h3": 6,
+  // KIE renders 8s when `duration` is omitted (kie/models.ts extraParams), and
+  // Seedance 2.5 prices one tier per second across 4–30s, so the 5s fallback
+  // billed a 5s tier against an 8s render — and under-reserved every
+  // reference-video run's output seconds by three (#1397).
+  "seedance-2-5": 8,
+  // Same shape: KIE renders 8s by default and the ladder is priced per second,
+  // so the 5s fallback billed a 5s tier against an 8s render (caught by the
+  // render-default ↔ priced-tier invariant in
+  // backend/src/providers/__tests__/pricing-default-duration-sync.test.ts).
+  "grok-imagine-video-1.5": 8,
+}
+
+/**
+ * The output seconds a request is PRICED at: the requested duration when the
+ * caller gave one, else the provider's own default render length
+ * ({@link PRICING_DEFAULT_DURATION_SEC}), else the historical 5s fallback.
+ *
+ * The ONE source for `buildVideoCreditModelIdentifier`'s tier AND for every
+ * dynamic reservation that scales by output seconds (the Seedance 2 and
+ * MiniMax Hailuo 3 reference-video overrides on both the route and the DAG
+ * lane) — a literal `?? 5` in any of those places re-opens the gap this map
+ * closes.
+ */
+export function pricedOutputDurationSec(provider: string, requested: number | string | undefined): number {
+  const fallback = PRICING_DEFAULT_DURATION_SEC[provider] ?? 5
+  const parsed = typeof requested === "string" ? parseInt(requested, 10) : requested
+  return parsed === undefined || Number.isNaN(parsed) ? fallback : parsed
 }
 
 /**

package/src/node-execution-state.ts

@@ -0,0 +1,95 @@
+/**
+ * The wire contract for one node's entry in an execution's `nodeStates` map —
+ * the shape the orchestrator persists on `workflow_executions.node_states`,
+ * emits on the SSE execution stream, and every client reads back.
+ *
+ * Why this lives here rather than in the backend
+ * ----------------------------------------------
+ * The shape had THREE independent declarations — the orchestrator's rich
+ * `NodeExecutionState` (workflow-engine/types.ts), the SDK's loose one
+ * (`packages/client/src/resources/executions.ts`) and the editor's local copy
+ * (`workflow-editor/run-handlers.ts`) — and nothing tied them together. The
+ * field that made that expensive is `output`: it used to be an unstated
+ * convention that only a COMPLETED node carries one, so every consumer read it
+ * exclusively under `status === "completed"` and a failed node's retained
+ * result had nowhere to travel.
+ *
+ * This module states the rule once. The backend keeps its richer `NodeOutput`
+ * typing (its `NodeExecutionState` must stay ASSIGNABLE to the wire shape — a
+ * type-level test pins that); the SDK and the editor extend/import it.
+ */
+
+/**
+ * The status a node reports inside an execution.
+ *
+ * `cancelled` is deliberately absent: a cancelled child job is mapped onto
+ * `skipped` by the reconcile lane (see `lib/reconcile/node-states.ts`), and a
+ * HELD job keeps `status: "running"` with the `awaitingReview` sidecar rather
+ * than adding a member here.
+ */
+export type NodeExecutionStatus =
+  | "pending"
+  | "running"
+  | "completed"
+  | "failed"
+  | "skipped"
+
+/**
+ * The statuses whose node state MAY carry `output`.
+ *
+ * `completed` is the obvious one. `failed` is here because a run can refuse
+ * its result and still RETAIN what it produced — the 3D-scene authoring lanes
+ * publish a real, renderable revision and then fail the job on the visual
+ * reviewer's verdict (`SCENE_QUALITY_FAILED`), so the scene and the refusal are
+ * both true at once. That output was billed; dropping it because the status is
+ * not `"completed"` is what this set exists to stop.
+ *
+ * `pending` / `running` / `skipped` never carry one: nothing has settled, or
+ * the node was gated out.
+ */
+export const OUTPUT_BEARING_NODE_STATUSES: ReadonlySet<NodeExecutionStatus> =
+  new Set<NodeExecutionStatus>(["completed", "failed"])
+
+/** Whether a node in this status may carry `output`. */
+export function nodeStateMayCarryOutput(status: string | undefined): boolean {
+  return (
+    status !== undefined &&
+    OUTPUT_BEARING_NODE_STATUSES.has(status as NodeExecutionStatus)
+  )
+}
+
+/**
+ * One node's execution state, as it travels on the wire.
+ *
+ * Additive by construction — an older client ignores fields it does not know,
+ * which is why `output` on a failed node is safe to start sending.
+ *
+ * `TOutput` lets a declaration that knows its own richer output shape (the
+ * orchestrator's `NodeOutput`, the editor's) stay ASSIGNABLE to this contract
+ * instead of restating it; the default is what an external client sees.
+ */
+export interface NodeExecutionStateWire<TOutput = Record<string, unknown>> {
+  status: NodeExecutionStatus | (string & {})
+  nodeType?: string
+  jobId?: string | null
+  /** Every job id of a fan-out node (one per list / loop iteration). */
+  jobIds?: string[]
+  creditsUsed?: number
+  error?: string | null
+  /** Stable code for a refusal a client may branch on — never on the text. */
+  errorCode?: string
+  /**
+   * What the node produced.
+   *
+   * Present for a `completed` node, and for a `failed` node whose run RETAINED
+   * a structured result (see {@link OUTPUT_BEARING_NODE_STATUSES}). A consumer
+   * that reads it must therefore gate on the FIELD, not on the status, and
+   * must not treat its presence as success.
+   */
+  output?: TOutput
+  startedAt?: string | null
+  completedAt?: string | null
+  /** The node's job is parked in `pending_review`; `status` stays "running". */
+  awaitingReview?: boolean
+  progress?: number
+}