@nodaro/shared 2.19.0 → 2.21.0

package/src/__tests__/video-request-normalize.test.ts

@@ -0,0 +1,239 @@
+import { describe, it, expect } from "vitest"
+import {
+  normalizeVideoRequestParams,
+  pricedVideoSelection,
+  buildVideoCreditModelIdentifier,
+  MODEL_CATALOG,
+  VIDEO_GEN_PROVIDERS,
+} from "../index.js"
+
+describe("normalizeVideoRequestParams", () => {
+  // R6: NEAREST, not allowed[0]. A portrait request must not become landscape.
+  it("snaps an off-list ratio to the NEAREST member of the model's list", () => {
+    const r = normalizeVideoRequestParams("seedance-2-5", { aspectRatio: "9:21" })
+    expect(r.aspectRatio).toBe("9:16")
+    expect(r.adjustments).toHaveLength(1)
+  })
+  it("snaps 4:5 and 5:4 the same way the provider adapter does", () => {
+    expect(normalizeVideoRequestParams("seedance-2-5", { aspectRatio: "4:5" }).aspectRatio).toBe("3:4")
+    expect(normalizeVideoRequestParams("seedance-2-5", { aspectRatio: "5:4" }).aspectRatio).toBe("4:3")
+  })
+
+  it("passes 'Auto' and 'adaptive' through untouched (the provider decides)", () => {
+    expect(normalizeVideoRequestParams("seedance-2-5", { aspectRatio: "Auto" }).aspectRatio).toBe("Auto")
+    expect(normalizeVideoRequestParams("seedance-2-5", { aspectRatio: "adaptive" }).aspectRatio).toBe("adaptive")
+  })
+
+  // R7: nearest band, not the cheapest. A 4k request on a 1080p-max model is
+  // 1080p, never 480p.
+  it("snaps an off-list resolution to the NEAREST declared band", () => {
+    expect(normalizeVideoRequestParams("seedance-2-5", { resolution: "4k" }).resolution).toBe("1080p")
+    expect(normalizeVideoRequestParams("seedance-2-5", { resolution: "2k" }).resolution).toBe("1080p")
+    expect(normalizeVideoRequestParams("seedance-2-5", { resolution: "360p" }).resolution).toBe("480p")
+  })
+
+  // §11.3 log-pull: two t2v rows failed createTask with "resolution is not
+  // within the range of allowed options". KIE exposes only 480p/720p/1080p for
+  // seedance-2-5 (providers/kie/models.ts:664-680, live probes 2026-08-08 and
+  // 08-17) while the route types `resolution` as a bare string. Asserts the
+  // exact snapped value, not membership — R7: the nearest band is 1080p, and a
+  // `toContain` pin would have hidden a silent downgrade to 480p.
+  it("snaps the off-list seedance-2-5 resolutions the t2v route admits, to the NEAREST band", () => {
+    for (const bad of ["2k", "4k", "1440p"]) {
+      expect(normalizeVideoRequestParams("seedance-2-5", { resolution: bad }).resolution).toBe("1080p")
+    }
+  })
+
+  // R3: the one place a case variant is canonicalised, upstream of every
+  // credit identifier (which key their tables case-sensitively).
+  it("canonicalises a case variant to the catalog's own spelling", () => {
+    expect(normalizeVideoRequestParams("ltx-2.3-fast", { resolution: "4K" }).resolution).toBe("4k")
+    expect(normalizeVideoRequestParams("ltx-2.3-fast", { resolution: "1080P" }).resolution).toBe("1080p")
+  })
+
+  it("snaps a resolution onto the model's own list", () => {
+    expect(normalizeVideoRequestParams("ltx-2.3-fast", { resolution: "720p" }).resolution).toBe("1080p")
+  })
+
+  it("NEVER drops a resolution for a model that declares none — dropping would lower the reserved tier", () => {
+    const r = normalizeVideoRequestParams("kling-turbo", { resolution: "1080p" })
+    expect(r.resolution).toBe("1080p")
+    expect(r.adjustments).toEqual([])
+  })
+
+  it("leaves an unknown model completely alone", () => {
+    const r = normalizeVideoRequestParams("not-a-model", { aspectRatio: "9:21", resolution: "720p" })
+    expect(r).toMatchObject({ aspectRatio: "9:21", resolution: "720p", adjustments: [] })
+  })
+
+  it("is idempotent", () => {
+    const once = normalizeVideoRequestParams("seedance-2-5", { aspectRatio: "9:21", resolution: "1080p" })
+    const twice = normalizeVideoRequestParams("seedance-2-5", once)
+    expect(twice.aspectRatio).toBe(once.aspectRatio)
+    expect(twice.resolution).toBe(once.resolution)
+    expect(twice.adjustments).toEqual([])
+  })
+
+  // The normalizer runs in the creditGuard preHandler (BEFORE the route's Zod
+  // parse) and in every buildPayload branch (whose `data` is unvalidated
+  // persisted workflow JSON, and whose aspectRatio can be FieldMapping-injected
+  // at run time). A non-string lever must therefore coerce, never throw: a throw
+  // is a 500 where the route used to return a clean Zod 400, and in the DAG it
+  // takes the whole run down after sibling nodes have already reserved.
+  it("coerces a NUMERIC lever exactly like its string form, instead of throwing", () => {
+    expect(normalizeVideoRequestParams("seedance-2-5", { resolution: 1080 as never }).resolution)
+      .toBe(normalizeVideoRequestParams("seedance-2-5", { resolution: "1080" }).resolution)
+    expect(normalizeVideoRequestParams("seedance-2-5", { aspectRatio: 16 as never }).aspectRatio)
+      .toBe(normalizeVideoRequestParams("seedance-2-5", { aspectRatio: "16" }).aspectRatio)
+    // "1080" is not "1080p", so it snaps to the nearest band rather than matching.
+    expect(normalizeVideoRequestParams("seedance-2-5", { resolution: 1080 as never }).resolution).toBe("1080p")
+  })
+
+  it("snaps a non-string lever FAIL-SAFE rather than throwing", () => {
+    for (const junk of [{}, [1, 2], true, () => {}]) {
+      const r = () => normalizeVideoRequestParams("seedance-2-5", { resolution: junk as never, aspectRatio: junk as never })
+      expect(r, `resolution/aspectRatio = ${String(junk)}`).not.toThrow()
+      const out = r()
+      // Unparseable ⇒ the highest declared band (never the cheapest, R7) and a
+      // concrete ratio — always a value the model actually accepts.
+      expect(MODEL_CATALOG["seedance-2-5"]!.resolutions).toContain(out.resolution)
+      expect(MODEL_CATALOG["seedance-2-5"]!.aspectRatios).toContain(out.aspectRatio)
+    }
+  })
+
+  it("reads null / blank as ABSENT, and never hands the raw value back", () => {
+    // The return type promises `string | undefined` and its callers feed it
+    // straight to the credit identifier and the provider wire, so a `null` or
+    // `""` must come back as `undefined` (the priced fill then supplies the band
+    // the identifier assumes) rather than as the caller's own value.
+    for (const blank of [null, "", "   "]) {
+      const r = normalizeVideoRequestParams("seedance-2-5", { resolution: blank as never, aspectRatio: blank as never })
+      expect(r.resolution, `resolution = ${JSON.stringify(blank)}`).toBeUndefined()
+      expect(r.aspectRatio, `aspectRatio = ${JSON.stringify(blank)}`).toBeUndefined()
+      expect(r.adjustments).toEqual([])
+    }
+  })
+
+  it("never returns a non-string lever, even for an unknown model", () => {
+    const r = normalizeVideoRequestParams("not-a-model", { resolution: 1080 as never, aspectRatio: 16 as never })
+    expect(r.resolution).toBe("1080")
+    expect(r.aspectRatio).toBe("16")
+  })
+
+  it("leaves an omitted lever omitted — the pricing fill is a separate, deliberate step", () => {
+    const r = normalizeVideoRequestParams("ltx-2.3-pro", {})
+    expect(r.resolution).toBeUndefined()
+    expect(r.aspectRatio).toBeUndefined()
+    expect(r.adjustments).toEqual([])
+  })
+})
+
+describe("pricedVideoSelection", () => {
+  // (A) The identifier prices an ABSENT resolution as a concrete band. Where
+  // that band is the platform's DECLARED provider default, it must also be the
+  // value we send — reserving 1080p and sending no key at all let Replicate
+  // pick its own undocumented default.
+  it("fills the declared default band for LTX", () => {
+    expect(pricedVideoSelection({ provider: "ltx-2.3-pro" }).resolution).toBe("1080p")
+    expect(pricedVideoSelection({ provider: "ltx-2.3-fast" }).resolution).toBe("1080p")
+  })
+
+  it("fills the declared default band for the providers that declare one", () => {
+    expect(pricedVideoSelection({ provider: "seedance-2-5" }).resolution).toBe("720p")
+    expect(pricedVideoSelection({ provider: "wan-3" }).resolution).toBe("720p")
+    expect(pricedVideoSelection({ provider: "wan-3-prime" }).resolution).toBe("720p")
+  })
+
+  it("fills NOTHING for a provider with no declared default — its identifier fallback is a hedge, not a verified provider default", () => {
+    // seedance-2 / -fast / -mini pin resolution 720p KIE-side but have no
+    // PRICING_DEFAULT_RESOLUTION row, so the identifier prices 480p. Filling
+    // 480p on the wire would DOWNGRADE the render to match a known-wrong price.
+    expect(pricedVideoSelection({ provider: "seedance-2" }).resolution).toBeUndefined()
+    expect(pricedVideoSelection({ provider: "seedance-2-mini" }).resolution).toBeUndefined()
+    expect(pricedVideoSelection({ provider: "kling-turbo" }).resolution).toBeUndefined()
+    expect(pricedVideoSelection({ provider: "veo3" }).resolution).toBeUndefined()
+  })
+
+  it("never overrides an explicit resolution", () => {
+    expect(pricedVideoSelection({ provider: "ltx-2.3-pro", resolution: "4k" }).resolution).toBe("4k")
+    expect(pricedVideoSelection({ provider: "seedance-2-5", resolution: "480p" }).resolution).toBe("480p")
+  })
+
+  // (B) LTX duration: the identifier snaps onto a SEEDED per-band tier, so the
+  // wire must carry that tier. 7s prices as 6s — send 6s.
+  it("carries the seeded LTX duration tier the identifier priced", () => {
+    expect(pricedVideoSelection({ provider: "ltx-2.3-pro", duration: 7 }).duration).toBe(6)
+    expect(pricedVideoSelection({ provider: "ltx-2.3-pro", resolution: "4k", duration: 20 }).duration).toBe(10)
+    expect(pricedVideoSelection({ provider: "ltx-2.3-fast", duration: 20 }).duration).toBe(20)
+    // 20s exists only at 1080p — a 2k request snaps back onto that band's ladder.
+    expect(pricedVideoSelection({ provider: "ltx-2.3-fast", resolution: "2k", duration: 20 }).duration).toBe(10)
+  })
+
+  it("reports the LTX duration snap as an adjustment, but never the omitted-value fill", () => {
+    expect(pricedVideoSelection({ provider: "ltx-2.3-pro", duration: 7 }).adjustments).toHaveLength(1)
+    expect(pricedVideoSelection({ provider: "ltx-2.3-pro", duration: 6 }).adjustments).toEqual([])
+    expect(pricedVideoSelection({ provider: "ltx-2.3-pro" }).adjustments).toEqual([])
+  })
+
+  it("leaves duration alone for every non-LTX provider (legality is not a flat catalog list)", () => {
+    expect(pricedVideoSelection({ provider: "seedance-2-5", duration: 7 }).duration).toBeUndefined()
+    expect(pricedVideoSelection({ provider: "kling-3.0", duration: 7 }).duration).toBeUndefined()
+  })
+})
+
+/**
+ * The invariant that makes the FILL safe: carrying the priced selection to the
+ * wire can never move the reserved tier. (The catalog snap that runs before it
+ * legitimately can — an off-list "4K" on a 1080p-max model is priced at the
+ * band we will actually render, which is the whole point. This pins the second
+ * step only: given the snapped value, filling what the identifier assumed is a
+ * disclosure of the price already being charged, never a repricing.)
+ */
+describe("pricedVideoSelection cannot move the credit identifier", () => {
+  const RESOLUTIONS = [undefined, "480p", "720p", "1080p", "2k", "4k", "4K", "720P"]
+  const DURATIONS = [undefined, 4, 5, 6, 7, 8, 10, 12, 20, 30]
+
+  it("covers every catalogued video provider", () => {
+    expect(VIDEO_GEN_PROVIDERS.length).toBeGreaterThan(20)
+  })
+
+  for (const nodeType of ["text-to-video", "image-to-video"] as const) {
+    it(`${nodeType}: id(priced) === id(raw) for every provider × resolution × duration`, () => {
+      const drift: string[] = []
+      for (const provider of VIDEO_GEN_PROVIDERS) {
+        for (const rawRes of RESOLUTIONS) {
+          for (const rawDur of DURATIONS) {
+            for (const hasVideoRef of [false, true]) {
+              const norm = normalizeVideoRequestParams(provider, { resolution: rawRes })
+              const priced = pricedVideoSelection({ provider, resolution: norm.resolution, duration: rawDur })
+              const rawId = buildVideoCreditModelIdentifier(provider, rawDur, undefined, nodeType, undefined, norm.resolution, hasVideoRef)
+              const pricedId = buildVideoCreditModelIdentifier(
+                provider,
+                priced.duration ?? rawDur,
+                undefined,
+                nodeType,
+                undefined,
+                norm.resolution ?? priced.resolution,
+                hasVideoRef,
+              )
+              if (rawId !== pricedId) {
+                drift.push(`${provider} res=${rawRes} dur=${rawDur} ref=${hasVideoRef}: ${rawId} → ${pricedId}`)
+              }
+            }
+          }
+        }
+      }
+      expect(drift, `the normalize+fill pair moved the reserved tier:\n${drift.join("\n")}`).toEqual([])
+    })
+  }
+
+  it("only fills a resolution the model's own catalog declares", () => {
+    for (const provider of VIDEO_GEN_PROVIDERS) {
+      const filled = pricedVideoSelection({ provider }).resolution
+      if (filled === undefined) continue
+      const declared = MODEL_CATALOG[provider]?.resolutions as readonly string[] | undefined
+      expect(declared, `${provider} fills "${filled}" but declares no resolutions`).toBeDefined()
+      expect(declared, `${provider} fills "${filled}", which is not in its catalog list`).toContain(filled)
+    }
+  })
+})

package/src/credit-identifiers.ts

@@ -28,7 +28,7 @@ import {
   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.
@@ -80,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`,
@@ -107,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
@@ -161,6 +235,32 @@ const LTX_DURATION_TIERS: Record<string, Record<string, number[]>> = {
   "ltx-2.3-fast": { "1080p": [6, 8, 10, 12, 14, 16, 18, 20], "2k": [6, 8, 10], "4k": [6, 8, 10] },
 }
 
+/**
+ * The (band, duration) tier the LTX pricing ladder charges for a request, or
+ * `undefined` for a non-LTX provider. Extracted so
+ * `buildVideoCreditModelIdentifier` and `pricedVideoSelection` read the ladder
+ * ONCE — the routes must send the tier they reserved, and a second copy of this
+ * math is exactly how the two drift apart.
+ *
+ * An unknown/absent band falls back to 1080p (LTX's own default, and the band
+ * `snapLtxInput` snaps to at the Replicate call), and an off-tier duration
+ * snaps to the NEAREST seeded one so the emitted composite always prices.
+ */
+function ltxPricedTier(
+  provider: string,
+  resolution?: string,
+  duration?: number | string,
+): { band: string; duration: number } | undefined {
+  const bands = LTX_DURATION_TIERS[provider]
+  if (!bands) return undefined
+  const band = bands[String(resolution)] ? String(resolution) : "1080p"
+  const allowed = bands[band]!
+  const raw = typeof duration === "string" ? parseInt(duration, 10) : (duration ?? allowed[0]!)
+  const want = Number.isNaN(raw) ? allowed[0]! : raw
+  const dur = allowed.reduce((b, a) => (Math.abs(a - want) < Math.abs(b - want) ? a : b))
+  return { band, duration: dur }
+}
+
 export function buildVideoCreditModelIdentifier(
   provider: string,
   duration?: number | string,
@@ -218,14 +318,9 @@ export function buildVideoCreditModelIdentifier(
   // (actual < reserved) and NEVER collects an upward delta, so an under-reserved
   // LTX run (the bare-id default = cheapest 1080p:6s tier) stays under-charged
   // even with meteredCost:true. Snap to a seeded tier so the id always prices.
-  if (effectiveProvider === "ltx-2.3-pro" || effectiveProvider === "ltx-2.3-fast") {
-    const bands = LTX_DURATION_TIERS[effectiveProvider]
-    const band = bands[String(resolution)] ? String(resolution) : "1080p"
-    const allowed = bands[band]
-    const raw = typeof duration === "string" ? parseInt(duration, 10) : (duration ?? allowed[0])
-    const want = Number.isNaN(raw) ? allowed[0] : raw
-    const dur = allowed.reduce((b, a) => (Math.abs(a - want) < Math.abs(b - want) ? a : b))
-    return `${effectiveProvider}:${band}:${dur}s`
+  const ltxTier = ltxPricedTier(effectiveProvider, resolution, duration)
+  if (ltxTier) {
+    return `${effectiveProvider}:${ltxTier.band}:${ltxTier.duration}s`
   }
 
   if (!DURATION_PRICED_PROVIDERS.has(effectiveProvider)) {
@@ -331,6 +426,92 @@ export function buildVideoCreditModelIdentifier(
   return identifier
 }
 
+/** What the video credit identifier PRICES for a request, for the levers whose
+ *  priced value must also be the value we SEND. */
+export interface PricedVideoSelection {
+  /** The resolution band the reservation is priced at when the request omitted
+   *  one — and only where the platform DECLARES that band as the provider's own
+   *  default. `undefined` means "leave `resolution` exactly as the request had
+   *  it": either the caller supplied one, or the provider's real default is not
+   *  known to be the band the identifier assumes. */
+  resolution?: string
+  /** The seeded duration tier the reservation is priced at (LTX only — the one
+   *  family whose duration ladder is per-band and case-sensitively seeded).
+   *  `undefined` for every other provider: their duration passes through. */
+  duration?: number
+  /** Non-empty only for a lever the caller ASKED for and did not get (an LTX
+   *  7s snapped to the 6s tier). Filling an omitted lever is a disclosure of
+   *  the price already being charged, not a correction, so it reports nothing. */
+  adjustments: ModelInputAdjustment[]
+}
+
+/**
+ * The other half of the video money path: `normalizeVideoRequestParams` snaps a
+ * value the CATALOG governs; this returns the value the PRICE ladder governs.
+ *
+ * Two defects it closes, both of the same shape — the identifier prices one
+ * thing and the wire carries another, and `commit_credits` (migration 176) only
+ * ever refunds a surplus, so the reservation is the final charge:
+ *
+ *  1. **Absent resolution.** `buildVideoCreditModelIdentifier` prices an omitted
+ *     `resolution` as a concrete band (LTX → 1080p; a
+ *     {@link PRICING_DEFAULT_RESOLUTION} member → its declared default). Leaving
+ *     the key unset then lets the provider pick — documented for the KIE members
+ *     (their `extraParams` pin the same band) but UNDOCUMENTED for LTX on
+ *     Replicate. Sending the band we priced makes the two agree by construction.
+ *
+ *     The fill is deliberately limited to providers with a DECLARED default.
+ *     `buildVideoCreditModelIdentifier` also has un-declared fallbacks — the
+ *     cheapest tier for a resolution-priced provider with no
+ *     `PRICING_DEFAULT_RESOLUTION` row — and those are a HEDGE, not a verified
+ *     provider default: seedance-2 / -fast / -mini pin `resolution: "720p"`
+ *     KIE-side while the identifier prices 480p, so filling 480p would downgrade
+ *     the render to match a price we already know is wrong. That mismatch is a
+ *     pre-existing identifier bug and is fixed by seeding the row, not here.
+ *
+ *  2. **LTX duration.** The LTX ladder is seeded per (band × seconds), so the
+ *     identifier snaps 7s onto the 6s tier. Sending 7s bills six and renders
+ *     seven. Most other providers' durations pass through untouched: their
+ *     legality is a flat catalog list the caller already sees, and their tiers
+ *     are ranges (`durationSec <= maxSeconds`), not seeded points. Gemini Omni
+ *     is the one other seeded ladder — `GEMINI_OMNI_DURATIONS` ([4, 6, 8, 10])
+ *     is nearest-snapped by `buildVideoCreditModelIdentifier`, the same shape
+ *     as LTX — but this function does not carry it yet: a 7s request prices
+ *     `:6` while 7s is still what gets sent. Pre-existing, out of scope here,
+ *     and ticketed as a follow-up (`geminiOmniPricedTier`, mirroring
+ *     `ltxPricedTier`).
+ *
+ * Pure, and IDEMPOTENT against the identifier: feeding its output back in
+ * cannot move the reserved tier. `video-request-normalize.test.ts` proves that
+ * over every provider × resolution × duration.
+ */
+export function pricedVideoSelection(opts: {
+  provider: string
+  resolution?: string
+  duration?: number | string
+}): PricedVideoSelection {
+  const adjustments: ModelInputAdjustment[] = []
+  const ltx = ltxPricedTier(opts.provider, opts.resolution, opts.duration)
+
+  // The band the request will be priced AND rendered at. An explicit value
+  // always wins — this only ever fills an omission.
+  const resolution = opts.resolution
+    ?? (ltx ? ltx.band : PRICING_DEFAULT_RESOLUTION[opts.provider])
+
+  if (!ltx) return { resolution, adjustments }
+
+  const requested = typeof opts.duration === "string" ? parseInt(opts.duration, 10) : opts.duration
+  if (requested !== undefined && !Number.isNaN(requested) && requested !== ltx.duration) {
+    adjustments.push({
+      field: "duration",
+      from: requested,
+      to: ltx.duration,
+      reason: `LTX renders ${ltx.band} in ${ltx.duration}s steps — using ${ltx.duration}s instead of ${requested}s.`,
+    })
+  }
+  return { resolution, duration: ltx.duration, adjustments }
+}
+
 /**
  * Compute composite model identifier for motion control with duration-tiered pricing.
  * Examples: "kling-3.0-motion:10s", "kling-3.0-motion:1080p:15s", "motion-transfer:5s"
@@ -365,3 +546,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/index.ts

@@ -18,6 +18,7 @@ export { usdToCredits, creditsToUsd, CREDIT_ROUNDING_RESOLUTION } from "./credit
 export {
   CREDIT_BASE_USD,
   IMAGE_PROMPT_MAX,
+  IMAGE_ASPECT_RATIO_VALUES,
   MAX_IMAGE_PROMPT_CHARS_BY_PROVIDER,
   getMaxImagePromptChars,
   PROMPT_HARD_CEILING,
@@ -35,6 +36,7 @@ export {
   getMaxSunoStyleChars,
   VIDEO_PROMPT_MAX,
   SUNO_TEXT_MAX,
+  SUNO_HARD_CEILING,
   NATIVE_NEGATIVE_PROMPT_MODELS,
   NATIVE_NEGATIVE_VIDEO_PROVIDERS,
   applyVideoNegativePrompt,
@@ -106,6 +108,8 @@ export {
   NATIVE_ADAPTIVE_ASPECT,
   FRAME_MODE_ADAPTIVE_ONLY_ASPECT,
   VIDEO_REF_LIMITS_BY_PROVIDER,
+  VIDEO_REF_VIDEO_DURATION_LIMITS,
+  checkRefVideoDurations,
   VIDEO_PROVIDERS_REQUIRING_IMAGE,
   videoProviderRequiresImage,
   VIDEO_MODE_ALIASES,
@@ -173,6 +177,7 @@ export { FEATURED_ENTITIES, getFeaturedEntities } from "./featured-entities.js"
 export type { FeaturedEntity } from "./featured-entities.js"
 
 export type {
+  ImageAspectRatio,
   ImageGenProvider,
   ImageMaskMode,
   ImageI2IProvider,
@@ -209,6 +214,7 @@ export type {
   VideoAudioCapability,
   GvpAnchorChoice,
   GvpAnchorWireMode,
+  RefVideoDurationLimit,
 } from "./model-constants.js"
 
 
@@ -234,13 +240,28 @@ export type {
 export {
   buildCreditModelIdentifier,
   resolveImageGenCreditIdentifier,
+  resolveNormalizedImageGen,
   buildVideoCreditModelIdentifier,
+  pricedVideoSelection,
   buildMotionCreditModelIdentifier,
+  sunoCreditType,
+  SUNO_VERSION_PRICED_OPERATIONS,
+  SUNO_SELECT_OPERATIONS,
 } from "./credit-identifiers.js"
+export type { NormalizedImageGen, PricedVideoSelection } from "./credit-identifiers.js"
 
 export * from "./credit-estimators/index.js"
 export { extractVideoDurationFromNode } from "./video-duration.js"
 
+export {
+  resolveTopazUpscale,
+  TOPAZ_UPSCALE_FACTORS,
+  TOPAZ_DEFAULT_UPSCALE_FACTOR,
+  type TopazUpscaleFactor,
+  type TopazUpscaleAdjustment,
+  type TopazUpscaleResolution,
+} from "./topaz-upscale.js"
+
 
 
 
@@ -617,8 +638,8 @@ export type { LottieOverlayCatalogEntry } from "./lottie-overlay-catalog.js"
 
 export { resolveFieldMappings, resolveLocationFields } from "./resolve-field-mappings.js"
 
-export { resolveNodeRefs, parseNodeRef, canonicalVarName, NODE_REF_PATTERN, RESERVED_TEMPLATE_VARS, extractReferencedLabels, combineSameLabelRefs, refHandleCategory, REF_HANDLE_CATEGORY, REFERENCE_HANDLE_MAP, referenceModalityForHandle, FRAME_TARGET_HANDLES, countRefModalityEdges } from "./node-refs.js"
-export type { RefCandidate, ReferenceModality, RefModalityEdge } from "./node-refs.js"
+export { resolveNodeRefs, parseNodeRef, canonicalVarName, NODE_REF_PATTERN, RESERVED_TEMPLATE_VARS, extractReferencedLabels, combineSameLabelRefs, refHandleCategory, REF_HANDLE_CATEGORY, REFERENCE_HANDLE_MAP, referenceModalityForHandle, FRAME_TARGET_HANDLES, countRefModalityEdges, REF_TOKEN_NAMESPACE_PREFIXES, classifyRefToken, unresolvedRefTokens } from "./node-refs.js"
+export type { RefCandidate, ReferenceModality, RefModalityEdge, RefTokenKind } from "./node-refs.js"
 
 
 export { resolveSourceThroughConnectedList } from "./list-source-resolver.js"
@@ -719,9 +740,11 @@ export {
   modelIdsByKindMode,
   buildModelMenu,
   normalizeModelInput,
+  normalizeVideoRequestParams,
   defaultResolutionFor,
 } from "./model-catalog.js"
 export type {
+  NormalizedVideoRequest,
   ModelCatalogEntry,
   ModelKind,
   ModelMode,
@@ -735,6 +758,11 @@ export type {
   NormalizedModelInput,
 } from "./model-catalog.js"
 
+// Per-model safety-filter retry/fallback policy (derives from
+// `ModelCatalogEntry.safetyFilter` above).
+export { safetyRetryPolicy } from "./safety-retry-policy.js"
+export type { SafetyRetryPolicy } from "./safety-retry-policy.js"
+
 export {
   STATIC_CAPTION_STYLES,
   KINETIC_CAPTION_STYLES,