@nodaro/shared 2.18.0 → 2.20.0

package/src/__tests__/video-audio-capability.test.ts

@@ -63,6 +63,21 @@ describe("getVideoAudioCapability", () => {
     expect(cap.field).toBe("generateAudio")
   })
 
+  it("returns ambient with the `audio` field for the Wan 3.0 family", () => {
+    // Wan 3.0's lever is literally `input.audio` — neither `sound` nor
+    // `generate_audio`. Classified "ambient", NOT audio_driven: the KIE schema
+    // documents no dialogue guarantee, and reference audio is a generic
+    // conditioning array rather than a verified lip-sync transport.
+    for (const m of ["wan-3", "wan-3-prime"]) {
+      const cap = getVideoAudioCapability(m)
+      expect(cap.mode, m).toBe("ambient")
+      expect(cap.field, m).toBe("audio")
+      expect(cap.defaultOn, m).toBe(true)
+      // Audio is priced into the uniform per-second rate — no `:audio` composite.
+      expect(cap.affectsCost, m).toBeUndefined()
+    }
+  })
+
   it("defaults to none for silent / unknown / undefined models", () => {
     for (const m of [
       "minimax",
@@ -70,6 +85,9 @@ describe("getVideoAudioCapability", () => {
       "wan-i2v",
       "grok-i2v",
       "gemini-omni-video",
+      // Gemini Omni Flash mirrors its sibling: deliberately unlisted, so both
+      // Omni SKUs report the same audio capability.
+      "gemini-omni-flash",
       "runway",
       "pika",
       "totally-unknown-model",
@@ -192,6 +210,31 @@ describe("applyVideoAudioToggle — neutral audio intent → per-model KIE field
     expect(v1.generate_audio).toBe(true)
   })
 
+  it("maps the neutral toggle onto Wan 3.0's `audio` field", () => {
+    // The dispatcher used to be a two-way if/else whose `else` wrote
+    // `input.sound` — a field the Wan 3.0 contract does not have, so the
+    // toggle would have been silently dropped.
+    const on: Record<string, unknown> = {}
+    applyVideoAudioToggle(on, "wan-3", { sound: true })
+    expect(on.audio).toBe(true)
+    expect(on.sound).toBeUndefined()
+    expect(on.generate_audio).toBeUndefined()
+
+    const off: Record<string, unknown> = {}
+    applyVideoAudioToggle(off, "wan-3-prime", { sound: false })
+    expect(off.audio).toBe(false)
+
+    // Not cost-affecting, so the legacy alias is honoured too.
+    const alias: Record<string, unknown> = {}
+    applyVideoAudioToggle(alias, "wan-3", { generateAudio: true })
+    expect(alias.audio).toBe(true)
+
+    // No intent → the model's own default (KIE `audio: true`) is left alone.
+    const neutral: Record<string, unknown> = {}
+    applyVideoAudioToggle(neutral, "wan-3", {})
+    expect(neutral).toEqual({})
+  })
+
   it("accepts `generateAudio` as a legacy alias on FREE models (Seedance)", () => {
     const input: Record<string, unknown> = {}
     applyVideoAudioToggle(input, "seedance", { generateAudio: true })

package/src/__tests__/video-mode-for-inputs.test.ts

@@ -43,7 +43,7 @@ describe("resolveVideoModeForInputs", () => {
     // (generate-video.md mode table). kling-3-omni is i2v-only and keeps its
     // documented orchestrator behavior (image_required on the t2v path) —
     // whether refs alone should satisfy it is a separate question from #861.
-    for (const id of ["seedance-2", "gemini-omni-video", "veo3.1", "kling-3-omni"]) {
+    for (const id of ["seedance-2", "gemini-omni-video", "gemini-omni-flash", "veo3.1", "kling-3-omni", "wan-3", "wan-3-prime"]) {
       expect(resolveVideoModeForInputs(id, { hasStartFrame: false, hasImageRefs: true })).toBe(T2V)
     }
   })

package/src/__tests__/wan-3-catalog.test.ts

@@ -0,0 +1,243 @@
+import { describe, it, expect } from "vitest"
+import { MODEL_CATALOG } from "../model-catalog.js"
+import {
+  IMAGE_TO_VIDEO_PROVIDERS,
+  TEXT_TO_VIDEO_PROVIDERS,
+  VIDEO_REF_LIMITS_BY_PROVIDER,
+  VIDEO_PROVIDERS_REQUIRING_IMAGE,
+  getVideoAudioCapability,
+  defaultVideoAspectRatio,
+  getMaxVideoPromptChars,
+  WAN_3_PROVIDERS,
+  isWan3Provider,
+  WAN_3_DEFAULT_RESOLUTION,
+  normalizeWan3Resolution,
+  isSeedance2Provider,
+  isMinimaxH3Provider,
+  SEEDANCE_2_PROVIDERS,
+  DURATION_PRICED_PROVIDERS,
+  VIDEO_DURATION_TIERS,
+  RESOLUTION_DURATION_PRICING,
+  PRICING_DEFAULT_RESOLUTION,
+  NATIVE_ADAPTIVE_ASPECT,
+  SEEDANCE_2_R2V_MAX_AUDIO_SEC_BY_PROVIDER,
+  GVP_SUPPORTED_PROVIDERS,
+  GVP_EXTEND_PROVIDERS,
+} from "../model-constants.js"
+import { buildVideoCreditModelIdentifier } from "../credit-identifiers.js"
+
+const WAN_3_IDS = ["wan-3", "wan-3-prime"] as const
+const DURATIONS_2_TO_30 = Array.from({ length: 29 }, (_, i) => i + 2)
+
+describe("wan-3 / wan-3-prime catalog", () => {
+  for (const id of WAN_3_IDS) {
+    describe(id, () => {
+      const entry = MODEL_CATALOG[id]
+
+      it("exists with both video modes under ONE id (no t2v twin, no alias)", () => {
+        expect(entry).toBeDefined()
+        expect(entry.kind).toBe("video")
+        expect([...entry.modes].sort()).toEqual(["i2v", "t2v"])
+        expect(entry.series).toBe("Wan")
+        expect(entry.family).toBe("Alibaba")
+      })
+
+      it("lists resolutions ASCENDING — the default is declared, not smuggled in at index 0", () => {
+        // Every video entry in the catalog is ascending, and three unrelated
+        // consumers read index 0 (the frontend fail-safe snap, payload-builder's
+        // resolution fill, the GVP display order). The 720p billing/render
+        // default lives in PRICING_DEFAULT_RESOLUTION instead.
+        expect(entry.resolutions).toEqual(["480p", "720p", "1080p"])
+        expect(PRICING_DEFAULT_RESOLUTION[id]).toBe("720p")
+      })
+
+      it("offers every integer second 2-30 (`-1` model-chosen duration is NOT exposed)", () => {
+        expect(entry.durations).toEqual(DURATIONS_2_TO_30)
+        expect(entry.durations).not.toContain(-1)
+      })
+
+      it("uses the Wan 3.0 six-ratio set: adaptive first, NO 21:9", () => {
+        expect(entry.aspectRatios).toEqual(["adaptive", "16:9", "4:3", "1:1", "3:4", "9:16"])
+        // Reusing VIDEO_RATIOS_SEEDANCE_2 would have offered 21:9, which the
+        // Wan 3.0 enum rejects at request time.
+        expect(entry.aspectRatios).not.toContain("21:9")
+      })
+
+      it("declares end-frame + audio + reference-image, and deliberately NOT video-reference", () => {
+        expect(entry.features).toEqual(expect.arrayContaining(["end-frame", "audio", "reference-image"]))
+        // `video-reference` would derive wan into GVP_EXTEND_PROVIDERS, but the
+        // r2v forwarding path is unwired and KIE caps input-video + output at
+        // 30s — a bound the segment splitter cannot express.
+        expect(entry.features).not.toContain("video-reference")
+      })
+    })
+  }
+})
+
+describe("wan-3 provider wiring", () => {
+  for (const id of WAN_3_IDS) {
+    it(`${id} is registered for BOTH t2v and i2v and is NOT image-required`, () => {
+      expect(IMAGE_TO_VIDEO_PROVIDERS).toContain(id)
+      expect(TEXT_TO_VIDEO_PROVIDERS).toContain(id)
+      expect(VIDEO_PROVIDERS_REQUIRING_IMAGE.has(id)).toBe(false)
+    })
+
+    it(`${id} carries the 10/5/5 multimodal reference caps`, () => {
+      expect(VIDEO_REF_LIMITS_BY_PROVIDER[id]).toEqual({ images: 10, videos: 5, audio: 5 })
+      expect(SEEDANCE_2_R2V_MAX_AUDIO_SEC_BY_PROVIDER[id]).toBe(15)
+    })
+
+    it(`${id} audio capability: ambient behind the model's own \`audio\` boolean, default on`, () => {
+      const cap = getVideoAudioCapability(id)
+      expect(cap.mode).toBe("ambient")
+      expect(cap.field).toBe("audio")
+      expect(cap.defaultOn).toBe(true)
+      expect(cap.affectsCost).toBeUndefined()
+    })
+
+    it(`${id} defaults to the adaptive aspect (the KIE default, first in its enum)`, () => {
+      expect(defaultVideoAspectRatio(id)).toBe("adaptive")
+      expect(NATIVE_ADAPTIVE_ASPECT[id]).toBe("adaptive")
+    })
+
+    it(`${id} prompt cap is the documented 20000 chars`, () => {
+      expect(getMaxVideoPromptChars(id)).toBe(20000)
+    })
+
+    it(`${id} prices per second: one duration tier per allowed second 2-30`, () => {
+      expect(DURATION_PRICED_PROVIDERS.has(id)).toBe(true)
+      const tiers = VIDEO_DURATION_TIERS[id]
+      expect(tiers.map((t) => t.maxSeconds)).toEqual(DURATIONS_2_TO_30)
+      expect(RESOLUTION_DURATION_PRICING[id]).toEqual(["480p", "720p", "1080p"])
+    })
+  }
+})
+
+describe("wan-3 family predicate — exact membership, never prefix-matched", () => {
+  it("matches exactly the two Wan 3.0 SKUs", () => {
+    expect([...WAN_3_PROVIDERS].sort()).toEqual(["wan-3", "wan-3-prime"])
+    expect(isWan3Provider("wan-3")).toBe(true)
+    expect(isWan3Provider("wan-3-prime")).toBe(true)
+  })
+
+  it("does NOT match any Wan 2.x id (the prefix trap)", () => {
+    for (const other of ["wan", "wan-i2v", "wan-turbo", "wan-flash", "wan-videoedit", "wan-2.7-i2v", "wan-2.7-t2v"]) {
+      expect(isWan3Provider(other), other).toBe(false)
+    }
+    expect(isWan3Provider(undefined)).toBe(false)
+    expect(isWan3Provider("")).toBe(false)
+  })
+
+  it("stays OUT of the Seedance 2 and MiniMax H3 family sets", () => {
+    for (const id of WAN_3_IDS) {
+      expect(isSeedance2Provider(id), id).toBe(false)
+      expect(SEEDANCE_2_PROVIDERS.has(id), id).toBe(false)
+      expect(isMinimaxH3Provider(id), id).toBe(false)
+    }
+  })
+
+  it("IS a blessed GVP SKU (derived) but NOT extend-eligible", () => {
+    for (const id of WAN_3_IDS) {
+      expect([...GVP_SUPPORTED_PROVIDERS], id).toContain(id)
+      expect([...GVP_EXTEND_PROVIDERS], id).not.toContain(id)
+    }
+  })
+})
+
+describe("normalizeWan3Resolution — the ONE producer of the uppercase wire form", () => {
+  it("uppercases a supported tier, case-insensitively", () => {
+    expect(normalizeWan3Resolution("480p")).toBe("480P")
+    expect(normalizeWan3Resolution("480P")).toBe("480P")
+    expect(normalizeWan3Resolution("720p")).toBe("720P")
+    expect(normalizeWan3Resolution("1080P")).toBe("1080P")
+    expect(normalizeWan3Resolution(" 1080p ")).toBe("1080P")
+  })
+
+  it("collapses undefined / garbage / an off-menu tier to the 720P platform default", () => {
+    expect(WAN_3_DEFAULT_RESOLUTION).toBe("720P")
+    // 720P, not KIE's own 1080P default: the bare credit identifier prices the
+    // 720p tier, so billing can never undercut the render.
+    expect(normalizeWan3Resolution(undefined)).toBe("720P")
+    expect(normalizeWan3Resolution("")).toBe("720P")
+    expect(normalizeWan3Resolution("4k")).toBe("720P")
+    expect(normalizeWan3Resolution("2K")).toBe("720P")
+  })
+})
+
+describe("wan-3 credit identifiers — totality over the whole (duration × resolution) space", () => {
+  const build = (provider: string, duration?: number, resolution?: string) =>
+    buildVideoCreditModelIdentifier(provider, duration, undefined, "image-to-video", undefined, resolution, undefined)
+
+  for (const id of WAN_3_IDS) {
+    it(`${id} emits exactly one composite per (duration, resolution) pair — 87 distinct ids`, () => {
+      const emitted = new Set<string>()
+      for (const d of DURATIONS_2_TO_30) {
+        for (const res of ["480p", "720p", "1080p"]) {
+          const identifier = build(id, d, res)
+          expect(identifier, `${id} ${d}s ${res}`).toBe(`${id}:${d}s:${res}`)
+          emitted.add(identifier)
+        }
+      }
+      expect(emitted.size).toBe(87)
+    })
+
+    it(`${id} prices an OMITTED resolution at the declared 720p default, not the cheapest tier`, () => {
+      // The tier list is ascending, so a bare resTiers[0] fallback would have
+      // reserved 480p against a 720p render — and commit_credits (refund-only)
+      // can never collect the shortfall.
+      expect(build(id, 5)).toBe(`${id}:5s:720p`)
+      expect(build(id, 8)).toBe(`${id}:8s:720p`)
+    })
+
+    it(`${id} collapses an UNSUPPORTED resolution to the same 720p default`, () => {
+      for (const bogus of ["4k", "2k", "360p", "768P", "not-a-resolution"]) {
+        expect(build(id, 5, bogus), bogus).toBe(`${id}:5s:720p`)
+      }
+    })
+
+    it(`${id} bills the tier it RENDERS for every spelling of the resolution`, () => {
+      // The render path is `normalizeWan3Resolution` (case-insensitive, trims),
+      // so the billing path must collapse through the SAME normalizer. KIE's own
+      // OpenAPI enum is UPPERCASE ("1080P"), which is the natural value for an
+      // integrator reading the provider docs and reaches both consumers raw:
+      // the route Zod is `z.string().optional()` and neither the credit builder
+      // nor the queue payload canonicalises it. A case-sensitive `includes`
+      // rendered 1080P while billing the 720p row — a 2x shortfall that
+      // commit_credits (refund-only) can never collect.
+      for (const spelling of ["1080P", "480P", "720P", " 720p ", "1080p", "480p", "720p", "4K", "garbage"]) {
+        const rendered = normalizeWan3Resolution(spelling).toLowerCase()
+        expect(build(id, 5, spelling), `${id} 5s "${spelling}"`).toBe(`${id}:5s:${rendered}`)
+        expect(build(id, 30, spelling), `${id} 30s "${spelling}"`).toBe(`${id}:30s:${rendered}`)
+      }
+    })
+
+    it(`${id} snaps an off-menu duration into a seeded tier rather than the bare id`, () => {
+      // Below the floor → the first tier; above the ceiling → the last one.
+      expect(build(id, 1, "720p")).toBe(`${id}:2s:720p`)
+      expect(build(id, 45, "720p")).toBe(`${id}:30s:720p`)
+      // An omitted duration renders the KIE default of 5s.
+      expect(build(id, undefined, "720p")).toBe(`${id}:5s:720p`)
+    })
+
+    it(`${id} never emits the bare id from the generate path`, () => {
+      for (const d of [undefined, ...DURATIONS_2_TO_30]) {
+        for (const res of [undefined, "480p", "720p", "1080p", "4k"]) {
+          expect(build(id, d, res)).not.toBe(id)
+        }
+      }
+    })
+  }
+
+  it("every catalog pricing row for the family is an id the builder can actually emit", () => {
+    for (const id of WAN_3_IDS) {
+      for (const row of MODEL_CATALOG[id].pricing ?? []) {
+        // The bare row is the reservation-time default; every other row is a
+        // duration×resolution composite the builder must be able to produce.
+        if (row.identifier === id) continue
+        const m = /^(.+):(\d+)s:(\d+p)$/.exec(row.identifier)
+        expect(m, row.identifier).not.toBeNull()
+        expect(build(m![1]!, Number(m![2]), m![3])).toBe(row.identifier)
+      }
+    }
+  })
+})

package/src/credit-identifiers.ts

@@ -21,11 +21,14 @@ import {
   T2I_TO_I2I_VARIANT,
   isVeoProvider,
   isMinimaxH3Provider,
+  isGeminiOmniProvider,
+  isWan3Provider,
   normalizeMinimaxH3Resolution,
+  normalizeWan3Resolution,
   getVideoAudioCapability,
 } from "./model-constants.js"
 import { isFlux2Model } from "./flux2-pricing.js"
-import { MODEL_CATALOG } from "./model-catalog.js"
+import { MODEL_CATALOG, normalizeModelInput, type ModelInputAdjustment } from "./model-catalog.js"
 
 /**
  * Compute composite model identifier for variable credit pricing.
@@ -77,6 +80,90 @@ export function buildCreditModelIdentifier(
   return provider
 }
 
+/**
+ * An image request's catalog-snapped parameters PLUS the credit identifier
+ * priced off them.
+ *
+ * `adjustments` is the disclosure channel: every lever this changed, why, and
+ * to what. Routes return it in the 200 body so a caller learns their value was
+ * corrected instead of silently getting something else.
+ */
+export interface NormalizedImageGen {
+  /** Credit identifier, priced off the SNAPPED `resolution` / `quality`. */
+  identifier: string
+  /** The catalog model id the params were snapped against (post T2I→I2I swap). */
+  modelId: string
+  aspectRatio?: string
+  resolution?: string
+  quality?: string
+  /** Empty when the caller's values were already valid for `modelId`. */
+  adjustments: ModelInputAdjustment[]
+}
+
+/**
+ * Snap an image request's catalog-governed levers to a combination the model
+ * actually accepts, and price the credit identifier off the SNAPPED values.
+ *
+ * WHY THE SNAP LIVES HERE and not at the call site. Both image routes compute
+ * their credit identifier TWICE — once in the `creditGuard` preHandler (the
+ * CHECK) and once at the handler's `reserveCreditsForJob` (the DEBIT) — and a
+ * dedicated test asserts the two stay byte-identical (see
+ * `backend/src/routes/__tests__/generate-image.test.ts`, "CHECK === DEBIT").
+ * `resolution` and `quality` are pricing dimensions, so a snap applied at only
+ * one of those sites breaks that invariant, and `commit_credits` never collects
+ * an upward delta — the reserve IS the charge. Putting the snap inside the
+ * primitive makes CHECK, DEBIT and the workflow orchestrator agree by
+ * construction rather than by everyone remembering to call a normalizer.
+ *
+ * Inputs are typed `unknown` on purpose: the preHandler runs BEFORE Zod, so a
+ * caller can put a number or an object in `resolution`. Non-strings become
+ * `undefined` rather than reaching `normalizeModelInput` as a lie.
+ *
+ * Unknown model ids pass through untouched (same contract as
+ * `normalizeModelInput`) — the route's provider enum is the gate for those.
+ */
+export function resolveNormalizedImageGen(opts: {
+  provider: string | undefined
+  aspectRatio?: unknown
+  quality?: unknown
+  resolution?: unknown
+  renderingSpeed?: unknown
+  refCount: number
+  swapToI2i?: boolean
+}): NormalizedImageGen {
+  const str = (v: unknown): string | undefined =>
+    typeof v === "string" && v.length > 0 ? v : undefined
+
+  const provider = str(opts.provider) ?? "nano-banana"
+  // Same swap `resolveEffectiveProvider` applies in the route: refs attached to
+  // a bare T2I provider route the run to its i2i sibling, which has its OWN
+  // catalog entry and its own lever lists.
+  const modelId =
+    opts.swapToI2i && opts.refCount > 0 ? (T2I_TO_I2I_VARIANT[provider] ?? provider) : provider
+
+  const n = normalizeModelInput(modelId, {
+    aspectRatio: str(opts.aspectRatio),
+    resolution: str(opts.resolution),
+    quality: str(opts.quality),
+  })
+
+  return {
+    identifier: buildCreditModelIdentifier(
+      modelId,
+      n.quality,
+      n.resolution,
+      str(opts.renderingSpeed),
+      undefined,
+      opts.refCount,
+    ),
+    modelId,
+    aspectRatio: n.aspectRatio,
+    resolution: n.resolution,
+    quality: n.quality,
+    adjustments: n.adjustments,
+  }
+}
+
 /**
  * Reference-aware image-generation credit identifier — the SINGLE source of
  * truth shared by the single-node routes (`/v1/generate-image`,
@@ -104,17 +191,7 @@ export function resolveImageGenCreditIdentifier(opts: {
   refCount: number
   swapToI2i?: boolean
 }): string {
-  const provider = opts.provider || "nano-banana"
-  const effectiveProvider =
-    opts.swapToI2i && opts.refCount > 0 ? (T2I_TO_I2I_VARIANT[provider] ?? provider) : provider
-  return buildCreditModelIdentifier(
-    effectiveProvider,
-    opts.quality,
-    opts.resolution,
-    opts.renderingSpeed,
-    undefined,
-    opts.refCount,
-  )
+  return resolveNormalizedImageGen(opts).identifier
 }
 
 // T2V-specific credit overrides: some providers have different costs for T2V
@@ -137,9 +214,11 @@ const T2V_CREDIT_OVERRIDES: Record<string, string> = {
  * @param resolution - Output resolution (used by Seedance 2 for 480p/720p pricing)
  * @param hasVideoRef - Whether a reference video is connected (Seedance 2 uses a lower per-second rate when true)
  */
-/** Gemini Omni Video duration tiers (seconds). Mirrors `MODEL_CATALOG["gemini-omni-video"].durations`
- *  and `KIE_VIDEO_MODELS["gemini-omni-video"].allowedDurations`. Hoisted to module scope so the
- *  nearest-tier snap below doesn't reallocate on every (hot-path) call. */
+/** Gemini Omni duration tiers (seconds). Mirrors the `durations` of BOTH
+ *  `MODEL_CATALOG["gemini-omni-video"]` and `MODEL_CATALOG["gemini-omni-flash"]`
+ *  (and their `KIE_VIDEO_MODELS[*].allowedDurations`) — the family shares one
+ *  ladder. Hoisted to module scope so the nearest-tier snap below doesn't
+ *  reallocate on every (hot-path) call. */
 const GEMINI_OMNI_DURATIONS = [4, 6, 8, 10]
 
 /**
@@ -191,17 +270,21 @@ export function buildVideoCreditModelIdentifier(
     return effectiveProvider
   }
 
-  // Gemini Omni Video: priced by (resolution-band × duration), with a flat
-  // per-generation rate when a source video is supplied (V2V). Lowercase "4k".
-  if (effectiveProvider === "gemini-omni-video") {
+  // Gemini Omni family (gemini-omni-video + gemini-omni-flash): priced by
+  // (resolution-band × duration), with a flat per-generation rate when a source
+  // video is supplied (V2V). Lowercase "4k". The prefix is TEMPLATED from the
+  // provider id, so a further Omni SKU needs no edit here — it only has to join
+  // GEMINI_OMNI_PROVIDERS and seed its rows. These models are deliberately NOT
+  // in DURATION_PRICED_PROVIDERS; this branch early-returns before that gate.
+  if (isGeminiOmniProvider(effectiveProvider)) {
     if (hasVideoRef) {
-      return resolution === "4k" ? "gemini-omni-video:4k:vref" : "gemini-omni-video:vref"
+      return resolution === "4k" ? `${effectiveProvider}:4k:vref` : `${effectiveProvider}:vref`
     }
     // Snap to nearest allowed tier (NOT a min/max clamp) so off-tier durations
     // map to a SEEDED composite; default 8 when unset.
     const raw = parseInt(String(duration ?? 8), 10)
     const d = Number.isNaN(raw) ? 8 : GEMINI_OMNI_DURATIONS.reduce((b, a) => (Math.abs(a - raw) < Math.abs(b - raw) ? a : b))
-    return resolution === "4k" ? `gemini-omni-video:4k:${d}` : `gemini-omni-video:${d}`
+    return resolution === "4k" ? `${effectiveProvider}:4k:${d}` : `${effectiveProvider}:${d}`
   }
 
   // LTX 2.3: priced by (resolution-band × duration-seconds). The RESERVE must be
@@ -281,7 +364,31 @@ export function buildVideoCreditModelIdentifier(
   // guard fuzzes the whole resolution space.
   const resTiers = RESOLUTION_DURATION_PRICING[effectiveProvider]
   if (resTiers) {
-    const res = resolution && resTiers.includes(resolution) ? resolution : resTiers[0]!
+    // The "default tier" is the provider's DECLARED default when it has one
+    // (PRICING_DEFAULT_RESOLUTION — wan-3 renders 720p, not the cheapest tier),
+    // otherwise the first listed tier. Declaring it explicitly means a cosmetic
+    // reorder of the tier list can never reprice a live model, and an OMITTED
+    // *or* unsupported resolution both land on what actually renders instead of
+    // on the cheapest row (commit_credits refunds a surplus but can never
+    // collect a shortfall). Behaviour-neutral for every member without a
+    // declared default.
+    const declaredDefault = PRICING_DEFAULT_RESOLUTION[effectiveProvider]
+    const fallback = declaredDefault && resTiers.includes(declaredDefault) ? declaredDefault : resTiers[0]!
+    // Wan 3.0 renders through `normalizeWan3Resolution`, which is CASE-INSENSITIVE
+    // ("1080P" — KIE's own OpenAPI enum spelling, and the natural value for an
+    // integrator reading the provider docs — renders 1080P). The tier list here is
+    // lowercase and `Array.includes` is case-sensitive, so without this the render
+    // path and the billing path disagree: "1080P" rendered the top tier and billed
+    // the 720p row, a shortfall `commit_credits` (refund-only) can never collect.
+    // Collapsing through the SAME normalizer the runner uses makes render == billed
+    // by construction for every spelling, including garbage (→ the declared 720p).
+    // Scoped to the wan family on purpose: the other RESOLUTION_DURATION_PRICING
+    // members pass `resolution` to their wire verbatim, so case-folding their
+    // billing without probing their wire would reprice live models.
+    const requested = isWan3Provider(effectiveProvider)
+      ? normalizeWan3Resolution(resolution).toLowerCase()
+      : resolution
+    const res = requested && resTiers.includes(requested) ? requested : fallback
     identifier += `:${res}`
   }
 
@@ -332,3 +439,66 @@ export function buildMotionCreditModelIdentifier(
   const resSuffix = resolution === "1080p" ? ":1080p" : ""
   return `${base}${resSuffix}:${tier.suffix}`
 }
+
+/**
+ * The Suno operations whose credit key depends on the model VERSION.
+ *
+ * `/v1/suno/generate`, `/cover` and `/extend` resolve their creditGuard
+ * identifier through `sunoCreditType(model, <operation>)` (routes/suno.ts
+ * :247-249, :335-337, :407-409). EVERY other Suno route charges a flat
+ * per-operation key and ignores the version the node carries — mashup (:648),
+ * add-instrumental (:852), add-vocals (:907), upload-extend (:1016),
+ * replace-section (:710), style-boost (:771), convert-wav (:962),
+ * lyrics (:482), music-video (:594), voice (:1218).
+ *
+ * Anything that QUOTES a Suno price — a dropdown row, a node badge, the
+ * workflow-credit estimator — must follow the same split, or it displays a
+ * credit key the route never charges.
+ */
+export const SUNO_VERSION_PRICED_OPERATIONS = [
+  "suno-generate",
+  "suno-cover",
+  "suno-extend",
+] as const
+
+/**
+ * The seven Suno operations that appear behind a select/dropdown UI (model
+ * pickers, node badges, the credit estimator) — the three version-priced
+ * operations above, plus the four flat-key operations exercised by
+ * `sunoCreditType`'s own test suite. A readonly tuple so later tasks (the
+ * model dropdowns, node badges) can iterate or count it without redeclaring
+ * the list and drifting from this one.
+ */
+export const SUNO_SELECT_OPERATIONS = [
+  "suno-generate",
+  "suno-cover",
+  "suno-extend",
+  "suno-mashup",
+  "suno-add-instrumental",
+  "suno-add-vocals",
+  "suno-upload-extend",
+] as const
+
+/**
+ * OUR Nodaro credit key for a Suno operation, given the model version and the
+ * operation (which is also the node type and the BullMQ job name).
+ *
+ * This is the single source of truth for the Suno pricing contract, shared by
+ * the reservation path (routes/suno.ts creditGuard), the egress seam
+ * (workers/handlers/suno.ts `modelKey`, which must match what was reserved),
+ * both workflow-credit estimators (ee/billing/credits.ts and the frontend
+ * config-panels/helpers.ts), the seven Suno model dropdowns and the three Suno
+ * node badges. It is a billing key — NEVER a KIE provider id — which is what
+ * satisfies the B3 egress invariant.
+ *
+ * V5_5 → "suno-v5_5", V5 → "suno-v5", any other version → the operation key.
+ * A non-version-priced operation is returned unchanged.
+ */
+export function sunoCreditType(model: string | undefined, operation: string): string {
+  if (!(SUNO_VERSION_PRICED_OPERATIONS as readonly string[]).includes(operation)) {
+    return operation
+  }
+  if (model === "V5_5") return "suno-v5_5"
+  if (model === "V5") return "suno-v5"
+  return operation
+}

package/src/i18n/held-prop.ar.ts

@@ -69,6 +69,8 @@ const map: LocaleCatalogMap = {
   "compass": { label: "بوصلة", description: "بوصلة بحرية محمولة، استكشاف" },
   "bow-and-arrow": { label: "قوس وسهم", description: "قوس مشدود بسهم متأهب" },
   "shield": { label: "درع", description: "درع محمول، عصور وسطى / خيال" },
+  // --- picker-gaps 2026-09-01 ---
+  "work-gloves": { label: "قفازات عمل", description: "قفازات عمل جلدية بالية ممسوكة باليد" },
 }
 
 export default map

package/src/i18n/held-prop.de.ts

@@ -60,6 +60,9 @@ const map: LocaleCatalogMap = {
   "compass": { label: "Kompass", description: "Handgehaltener nautischer Kompass, Erkundung" },
   "bow-and-arrow": { label: "Pfeil und Bogen", description: "Gespannter Bogen mit eingelegtem Pfeil" },
   "shield": { label: "Schild", description: "Handgehaltenes Schild, mittelalterlich / Fantasy" },
+
+  // --- picker-gaps 2026-09-01 ---
+  "work-gloves": { label: "Arbeitshandschuhe", description: "Abgetragene lederne Arbeitshandschuhe in der Hand gehalten" },
 }
 
 export default map

package/src/i18n/held-prop.es.ts

@@ -78,6 +78,9 @@ const map: LocaleCatalogMap = {
   "compass": { label: "Brújula", description: "Brújula náutica de mano, exploración" },
   "bow-and-arrow": { label: "Arco y Flecha", description: "Arco de tiro tensado con flecha encajada" },
   "shield": { label: "Escudo", description: "Escudo de mano, medieval / fantasía" },
+
+  // --- picker-gaps 2026-09-01 ---
+  "work-gloves": { label: "Guantes de Trabajo", description: "Guantes de cuero de trabajo desgastados sostenidos en la mano" },
 }
 
 export default map

package/src/i18n/held-prop.fr.ts

@@ -69,6 +69,8 @@ const map: LocaleCatalogMap = {
   "compass": { label: "Boussole", description: "Boussole nautique à main, exploration" },
   "bow-and-arrow": { label: "Arc et flèche", description: "Arc de tir à l'arc tendu avec flèche encochée" },
   "shield": { label: "Bouclier", description: "Bouclier porté à la main, médiéval / fantasy" },
+  // --- picker-gaps 2026-09-01 ---
+  "work-gloves": { label: "Gants de travail", description: "Gants de travail en cuir usés tenus à la main" },
 }
 
 export default map

package/src/i18n/held-prop.he.ts

@@ -68,6 +68,9 @@ const map: LocaleCatalogMap = {
   "compass": { label: "מצפן", description: "מצפן ימי מוחזק ביד, חקירה" },
   "bow-and-arrow": { label: "קשת וחץ", description: "קשת קשתות דרוכה עם חץ על המיתר" },
   "shield": { label: "מגן", description: "מגן מוחזק ביד, ימי הביניים / פנטזיה" },
+
+  // --- picker-gaps 2026-09-01 ---
+  "work-gloves": { label: "כפפות עבודה", description: "כפפות עבודה שחוקות מעור, מוחזקות ביד" },
 }
 
 export default map

package/src/i18n/held-prop.hi.ts

@@ -77,6 +77,8 @@ const map: LocaleCatalogMap = {
   "compass": { label: "कम्पास", description: "हाथ का nautical कम्पास, अन्वेषण" },
   "bow-and-arrow": { label: "धनुष-बाण", description: "तीर लगाया हुआ खींचा हुआ archery धनुष" },
   "shield": { label: "ढाल", description: "हाथ की ढाल, मध्यकालीन / fantasy" },
+  // --- picker-gaps 2026-09-01 ---
+  "work-gloves": { label: "काम के दस्ताने", description: "हाथ में पकड़े हुए घिसे चमड़े के काम के दस्ताने" },
 }
 
 export default map

package/src/i18n/held-prop.ja.ts

@@ -79,6 +79,9 @@ const map: LocaleCatalogMap = {
   "compass": { label: "コンパス", description: "手持ちの航海用コンパス、探検" },
   "bow-and-arrow": { label: "弓矢", description: "矢をつがえて引き絞った弓" },
   "shield": { label: "盾", description: "手持ちの盾、中世／ファンタジー" },
+
+  // --- picker-gaps 2026-09-01 ---
+  "work-gloves": { label: "作業用手袋", description: "手に持った使い込まれた革の作業用手袋" },
 }
 
 export default map