@nodaro/shared 2.20.0 → 2.21.1

package/src/__tests__/video-ref-video-duration-limits.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from "vitest"
+import { checkRefVideoDurations, VIDEO_REF_VIDEO_DURATION_LIMITS, VIDEO_REF_LIMITS_BY_PROVIDER } from "../index.js"
+
+describe("checkRefVideoDurations", () => {
+  it("accepts seedance-2-5 clips inside [2, 30]s", () => {
+    expect(checkRefVideoDurations("seedance-2-5", [2, 15, 12.5])).toEqual({ ok: true })
+  })
+  it("rejects a clip under the floor and names the offender", () => {
+    const r = checkRefVideoDurations("seedance-2-5", [1.4])
+    expect(r.ok).toBe(false)
+    expect(r.ok === false && r.message).toContain("between 2 and 30 seconds")
+  })
+  it("rejects a clip over the ceiling", () => {
+    expect(checkRefVideoDurations("seedance-2-5", [31]).ok).toBe(false)
+  })
+  it("rejects a legal set whose TOTAL exceeds the cap", () => {
+    const r = checkRefVideoDurations("seedance-2-5", [20, 20])
+    expect(r.ok).toBe(false)
+    expect(r.ok === false && r.message).toContain("30 seconds in total")
+  })
+  it("passes any provider with no declared limit through", () => {
+    expect(checkRefVideoDurations("veo3", [99])).toEqual({ ok: true })
+  })
+  it("ignores unusable probe values rather than inventing a rejection", () => {
+    expect(checkRefVideoDurations("seedance-2-5", [Number.NaN, 0, -1])).toEqual({ ok: true })
+  })
+  it("ignores a failed probe mixed in with usable ones (NaN never inflates the total)", () => {
+    // The route stashes RAW per-URL probe outcomes, so a rejected ffprobe reaches
+    // this checker as NaN. It must neither reject on its own nor push an
+    // otherwise-legal set over the total cap.
+    expect(checkRefVideoDurations("seedance-2-5", [20, Number.NaN, 9])).toEqual({ ok: true })
+  })
+  it("only declares limits for providers that actually accept reference videos", () => {
+    for (const id of Object.keys(VIDEO_REF_VIDEO_DURATION_LIMITS)) {
+      expect((VIDEO_REF_LIMITS_BY_PROVIDER[id]?.videos ?? 0), `${id} declares a duration limit but takes no reference videos`).toBeGreaterThan(0)
+    }
+  })
+})
+
+describe("minimax-h3 reference-video bounds", () => {
+  // §11.3 / P4: "video duration 52838 ms, expected [2000, 15000] ms" ×2 — the
+  // provider's own reject text is the per-clip source; the combined cap comes
+  // from docs.kie.ai/market/minimax-h3/reference-to-video.
+  it("declares the 2-15s per-clip bound the provider enforces", () => {
+    expect(VIDEO_REF_VIDEO_DURATION_LIMITS["minimax-h3"]).toMatchObject({ minSec: 2, maxSec: 15 })
+  })
+  it("declares the 15s COMBINED cap the KIE doc states", () => {
+    expect(VIDEO_REF_VIDEO_DURATION_LIMITS["minimax-h3"]).toMatchObject({ maxTotalSec: 15 })
+  })
+  it("rejects the exact clip from the two P4 rows", () => {
+    const r = checkRefVideoDurations("minimax-h3", [52.838])
+    expect(r.ok).toBe(false)
+    expect(r.ok === false && r.message).toContain("between 2 and 15 seconds")
+  })
+  it("accepts a clip inside the bound", () => {
+    expect(checkRefVideoDurations("minimax-h3", [14.9])).toEqual({ ok: true })
+  })
+  it("accepts three clips that together stay inside the combined cap", () => {
+    expect(checkRefVideoDurations("minimax-h3", [5, 5, 5])).toEqual({ ok: true })
+  })
+  it("rejects three per-clip-legal videos whose TOTAL exceeds 15s", () => {
+    const r = checkRefVideoDurations("minimax-h3", [6, 6, 6])
+    expect(r.ok).toBe(false)
+    expect(r.ok === false && r.message).toContain("15 seconds in total")
+  })
+  it("ignores a failed probe rather than rejecting the run", () => {
+    expect(checkRefVideoDurations("minimax-h3", [Number.NaN, 10])).toEqual({ ok: true })
+  })
+})

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

@@ -235,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,
@@ -292,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)) {
@@ -405,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"

package/src/index.ts

@@ -108,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,
@@ -212,6 +214,7 @@ export type {
   VideoAudioCapability,
   GvpAnchorChoice,
   GvpAnchorWireMode,
+  RefVideoDurationLimit,
 } from "./model-constants.js"
 
 
@@ -239,16 +242,26 @@ export {
   resolveImageGenCreditIdentifier,
   resolveNormalizedImageGen,
   buildVideoCreditModelIdentifier,
+  pricedVideoSelection,
   buildMotionCreditModelIdentifier,
   sunoCreditType,
   SUNO_VERSION_PRICED_OPERATIONS,
   SUNO_SELECT_OPERATIONS,
 } from "./credit-identifiers.js"
-export type { NormalizedImageGen } 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"
+
 
 
 
@@ -625,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"
@@ -727,9 +740,11 @@ export {
   modelIdsByKindMode,
   buildModelMenu,
   normalizeModelInput,
+  normalizeVideoRequestParams,
   defaultResolutionFor,
 } from "./model-catalog.js"
 export type {
+  NormalizedVideoRequest,
   ModelCatalogEntry,
   ModelKind,
   ModelMode,
@@ -743,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,