@nodaro/shared 2.20.0 → 2.21.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "2.20.0",
+  "version": "2.21.1",
   "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
   "type": "module",
   "license": "Apache-2.0",

package/src/__tests__/safety-retry-policy.test.ts

@@ -0,0 +1,62 @@
+import { T2I_TO_I2I_VARIANT } from "../model-constants.js"
+import { describe, it, expect } from "vitest"
+import { safetyRetryPolicy } from "../safety-retry-policy.js"
+import { MODEL_CATALOG, getModel } from "../model-catalog.js"
+
+describe("safetyRetryPolicy", () => {
+  it("gives gpt-image-2 a second attempt and names its fallback", () => {
+    expect(safetyRetryPolicy("gpt-image-2")).toEqual({
+      maxAttempts: 2,
+      fallback: "nano-banana-pro",
+    })
+  })
+
+  it("gives a model without the flag a single attempt and no fallback", () => {
+    // nano-banana-pro does not declare `safetyFilter` itself.
+    expect(safetyRetryPolicy("nano-banana-pro")).toEqual({ maxAttempts: 1 })
+  })
+
+  it("gives an unknown model id a single attempt and no fallback", () => {
+    expect(safetyRetryPolicy("totally-not-a-real-model-id")).toEqual({ maxAttempts: 1 })
+  })
+
+  it("every declared fallback resolves to a catalog entry that can actually cover the flagged model", () => {
+    const flagged = Object.values(MODEL_CATALOG).filter((m) => m.safetyFilter?.fallback)
+    // Sanity: this guard is only meaningful if at least one entry exercises it.
+    expect(flagged.length).toBeGreaterThan(0)
+
+    for (const entry of flagged) {
+      const fallbackId = entry.safetyFilter!.fallback!
+      const fallbackEntry = getModel(fallbackId)
+
+      expect(fallbackEntry, `${entry.id} declares fallback "${fallbackId}" which is not a catalog entry`).toBeDefined()
+      expect(fallbackEntry!.kind, `${entry.id}'s fallback "${fallbackId}" does not produce an image`).toBe("image")
+
+      for (const mode of entry.modes) {
+        expect(
+          fallbackEntry!.modes,
+          `${entry.id}'s fallback "${fallbackId}" is missing mode "${mode}" that ${entry.id} supports`,
+        ).toContain(mode)
+      }
+
+      expect(
+        fallbackEntry!.features ?? [],
+        `${entry.id}'s fallback "${fallbackId}" does not accept a reference image`,
+      ).toContain("reference-image")
+    }
+  })
+})
+
+describe("i2i variants inherit their base model's safety policy", () => {
+  it("resolves the referenced-request id (gpt-image-2-i2i) to the same policy as gpt-image-2", () => {
+    expect(safetyRetryPolicy("gpt-image-2-i2i")).toEqual({ maxAttempts: 2, fallback: "nano-banana-pro" })
+  })
+
+  it("every T2I_TO_I2I_VARIANT pair declares the same safetyFilter on both sides", () => {
+    for (const [t2i, i2i] of Object.entries(T2I_TO_I2I_VARIANT)) {
+      const base = MODEL_CATALOG[t2i]?.safetyFilter ?? null
+      const twin = MODEL_CATALOG[i2i]?.safetyFilter ?? null
+      expect({ pair: `${t2i} -> ${i2i}`, twin }).toEqual({ pair: `${t2i} -> ${i2i}`, twin: base })
+    }
+  })
+})

package/src/__tests__/topaz-upscale.test.ts

@@ -0,0 +1,132 @@
+import { describe, it, expect } from "vitest"
+import { resolveTopazUpscale, buildCreditModelIdentifier } from "../index.js"
+
+describe("resolveTopazUpscale", () => {
+  it("defaults to the provider's own default factor when nothing is set", () => {
+    const r = resolveTopazUpscale({})
+    expect(r.upscaleFactor).toBe("2")
+    expect(r.creditTier).toBeUndefined()
+    expect(r.adjustments).toEqual([])
+  })
+
+  it("takes an explicit factor as the lever and prices it", () => {
+    expect(resolveTopazUpscale({ upscaleFactor: "1" })).toMatchObject({ upscaleFactor: "1", creditTier: undefined })
+    expect(resolveTopazUpscale({ upscaleFactor: "2" })).toMatchObject({ upscaleFactor: "2", creditTier: undefined })
+    expect(resolveTopazUpscale({ upscaleFactor: "4" })).toMatchObject({ upscaleFactor: "4", creditTier: "4K" })
+  })
+
+  it("an explicit factor wins over a legacy targetResolution (the factor is what we send)", () => {
+    const r = resolveTopazUpscale({ upscaleFactor: "2", targetResolution: "4K" })
+    expect(r.upscaleFactor).toBe("2")
+    expect(r.creditTier).toBeUndefined()
+  })
+
+  it("maps a legacy targetResolution forward when no factor is set", () => {
+    expect(resolveTopazUpscale({ targetResolution: "2K" })).toMatchObject({ upscaleFactor: "2", creditTier: undefined })
+    expect(resolveTopazUpscale({ targetResolution: "4K" })).toMatchObject({ upscaleFactor: "4", creditTier: "4K" })
+  })
+
+  it("caps a legacy 8K request at the 4x the provider actually offers, and says so", () => {
+    const r = resolveTopazUpscale({ targetResolution: "8K" })
+    expect(r.upscaleFactor).toBe("4")
+    expect(r.creditTier).toBe("4K")
+    expect(r.adjustments).toHaveLength(1)
+    expect(r.adjustments[0]).toMatchObject({ field: "targetResolution", from: "8K", to: "4" })
+  })
+
+  it("coerces an out-of-enum factor and records the adjustment", () => {
+    const r = resolveTopazUpscale({ upscaleFactor: "8" })
+    expect(r.upscaleFactor).toBe("2")
+    expect(r.adjustments[0]).toMatchObject({ field: "upscaleFactor", from: "8", to: "2" })
+  })
+
+  it("every resolution it can return prices through the existing composites", () => {
+    for (const input of [
+      {}, { upscaleFactor: "1" }, { upscaleFactor: "2" }, { upscaleFactor: "4" },
+      { targetResolution: "2K" }, { targetResolution: "4K" }, { targetResolution: "8K" },
+    ]) {
+      const { creditTier } = resolveTopazUpscale(input)
+      const id = buildCreditModelIdentifier("topaz-image-upscale", undefined, undefined, undefined, creditTier)
+      expect(["topaz-image-upscale", "topaz-image-upscale:4K"]).toContain(id)
+    }
+  })
+
+  // --- Fix round 1 (2026-09-02 review): factor resolved before adjustments
+  // are built, `to` always pinned to the resolved factor, `from` always the
+  // raw untransformed input, and a valid factor's override of a stored
+  // targetResolution is disclosed rather than silently dropped. ---
+
+  it("an invalid factor still lets a legacy tier win, and reports the REAL resolved factor", () => {
+    const r = resolveTopazUpscale({ upscaleFactor: "8", targetResolution: "4K" })
+    expect(r.upscaleFactor).toBe("4")
+    expect(r.creditTier).toBe("4K")
+    const factorAdj = r.adjustments.find((a) => a.field === "upscaleFactor")
+    expect(factorAdj).toMatchObject({ field: "upscaleFactor", from: "8", to: "4" })
+  })
+
+  it("a valid factor overriding a disagreeing legacy tier discloses the override", () => {
+    const r = resolveTopazUpscale({ upscaleFactor: "2", targetResolution: "8K" })
+    expect(r.upscaleFactor).toBe("2")
+    const tierAdj = r.adjustments.find((a) => a.field === "targetResolution")
+    expect(tierAdj).toBeDefined()
+    expect(tierAdj).toMatchObject({ field: "targetResolution", from: "8K", to: undefined })
+  })
+
+  it("a valid factor that agrees with the legacy tier's factor discloses nothing", () => {
+    const r = resolveTopazUpscale({ upscaleFactor: "4", targetResolution: "4K" })
+    expect(r.upscaleFactor).toBe("4")
+    expect(r.adjustments).toEqual([])
+  })
+
+  it("an unknown legacy tier alone falls back to the default and reports the raw token", () => {
+    const r = resolveTopazUpscale({ targetResolution: "1080p" })
+    expect(r.upscaleFactor).toBe("2")
+    expect(r.creditTier).toBeUndefined()
+    expect(r.adjustments).toHaveLength(1)
+    expect(r.adjustments[0]).toMatchObject({ field: "targetResolution", from: "1080p", to: "2" })
+  })
+
+  const FACTOR_INPUTS: Array<string | undefined> = [undefined, "2", "4", "8", "foo", " 4 ", "4k"]
+  const TIER_INPUTS: Array<string | null | undefined> = [undefined, "2K", "4K", "8K", "4k", "1080p", null]
+
+  describe("factor x targetResolution table", () => {
+    for (const upscaleFactor of FACTOR_INPUTS) {
+      for (const targetResolution of TIER_INPUTS) {
+        const label = `upscaleFactor=${JSON.stringify(upscaleFactor)} targetResolution=${JSON.stringify(targetResolution)}`
+        it(`${label} — adjustments never disclose a factor other than the resolved one`, () => {
+          const result = resolveTopazUpscale({ upscaleFactor, targetResolution })
+
+          // Every field:"upscaleFactor" adjustment must announce the factor
+          // that was ACTUALLY resolved — never an intermediate guess.
+          expect(
+            result.adjustments.every((a) => a.field !== "upscaleFactor" || a.to === result.upscaleFactor),
+          ).toBe(true)
+
+          // `from` is always the raw, untransformed input — never trimmed or
+          // case-normalized — for both adjustment kinds.
+          for (const adj of result.adjustments) {
+            if (adj.field === "upscaleFactor") {
+              expect(adj.from).toBe(upscaleFactor)
+            } else {
+              expect(adj.from).toBe(targetResolution)
+            }
+          }
+
+          // The resolved factor and credit tier are always internally consistent.
+          expect(result.creditTier).toBe(result.upscaleFactor === "4" ? "4K" : undefined)
+
+          // Every resolution this function can produce must still price
+          // through an existing composite identifier.
+          const id = buildCreditModelIdentifier(
+            "topaz-image-upscale",
+            undefined,
+            undefined,
+            undefined,
+            result.creditTier,
+          )
+          expect(["topaz-image-upscale", "topaz-image-upscale:4K"]).toContain(id)
+        })
+      }
+    }
+  })
+})

package/src/__tests__/unresolved-ref-tokens.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from "vitest"
+import { unresolvedRefTokens, classifyRefToken, REF_TOKEN_NAMESPACE_PREFIXES } from "../node-refs.js"
+
+const S = (...v: string[]) => new Set(v)
+
+describe("classifyRefToken", () => {
+  it("skips every reference namespace, not just image:", () => {
+    for (const p of REF_TOKEN_NAMESPACE_PREFIXES) {
+      expect(classifyRefToken(`${p}1`, S())).toBe("skip")
+    }
+    // Regression: {video:1} and {audio:1} classified as "missing" before this.
+    expect(classifyRefToken("video:1", S())).toBe("skip")
+    expect(classifyRefToken("audio:1", S())).toBe("skip")
+    expect(classifyRefToken("slot:hero", S())).toBe("skip")
+    // D-13c: {ref:<id>} is a live grammar (resolveRefIdTokens) — it must skip
+    // too, or the dispatch guard refuses every id-addressed reference prompt.
+    expect(classifyRefToken("ref:hero", S())).toBe("skip")
+  })
+
+  it("matches the namespace case-insensitively (the resolvers' regexes are /i)", () => {
+    // D-13d: REFERENCE_TOKEN_RE is /gi and REF_ID_TOKEN_RE spells [rR][eE][fF],
+    // so {Image:1} / {Ref:x} resolve at the provider layer and must not classify
+    // as a missing node ref.
+    expect(classifyRefToken("Image:1", S())).toBe("skip")
+    expect(classifyRefToken("REF:hero", S())).toBe("skip")
+  })
+
+  it("keeps reserved template vars reserved and resolves case-insensitively", () => {
+    expect(classifyRefToken("userPrompt", S())).toBe("reserved")
+    expect(classifyRefToken("MyNode", S("mynode"))).toBe("wired")
+    expect(classifyRefToken("MyNode", S())).toBe("missing")
+  })
+
+  it("classifies unknown when the caller has no ref data at all", () => {
+    expect(classifyRefToken("MyNode", null)).toBe("unknown")
+  })
+})
+
+describe("unresolvedRefTokens", () => {
+  it("reports a token whose label matches no node at all", () => {
+    expect(unresolvedRefTokens("a {gravity flip} shot", { resolvable: S(), known: S() }))
+      .toEqual(["gravity flip"])
+  })
+
+  it("passes a token whose label names a node that exists but produced nothing", () => {
+    expect(unresolvedRefTokens("say {notes}", { resolvable: S(), known: S("notes") })).toEqual([])
+  })
+
+  it("passes a token that resolved", () => {
+    expect(unresolvedRefTokens("say {notes}", { resolvable: S("notes"), known: S("notes") })).toEqual([])
+  })
+
+  it("passes a token with an explicit || fallback (resolveNodeRefs substitutes it)", () => {
+    expect(unresolvedRefTokens("a {mood || calm} scene", { resolvable: S(), known: S() })).toEqual([])
+  })
+
+  it("never fires on the reference/recast grammars or reserved vars", () => {
+    expect(unresolvedRefTokens("{image:1:face} {video:1} {slot:x} {ref:hero} {userPrompt}", { resolvable: S(), known: S() }))
+      .toEqual([])
+  })
+
+  it("de-duplicates and preserves the author's casing for the message", () => {
+    expect(unresolvedRefTokens("{Describe Image} then {describe image}", { resolvable: S(), known: S() }))
+      .toEqual(["Describe Image"])
+  })
+})

package/src/__tests__/video-analysis.test.ts

@@ -9,6 +9,7 @@ import {
   VIDEO_ANALYSIS_SPEED_EFFECTS, VIDEO_ANALYSIS_SHOT_ANGLES, VIDEO_ANALYSIS_FACELESS_ANGLES,
   VIDEO_ANALYSIS_VISUAL_EFFECTS, VIDEO_ANALYSIS_TRANSITIONS,
   VIDEO_ANALYSIS_MAX_VARIATIONS, VIDEO_ANALYSIS_VARIATION_SLUGS, VIDEO_ANALYSIS_DEFAULT_VARIATION,
+  VIDEO_ANALYSIS_AUDIO_MODES,
   type EntitySlot, type AudioLayer,
 } from "../video-analysis.js"
 
@@ -218,6 +219,60 @@ describe("speech attribution (speakerSlot)", () => {
   })
 })
 
+describe("the audio grammar (mode vocabulary + who is speaking)", () => {
+  it("distinguishes AMBIENCE from SFX — room tone is not a door slam", () => {
+    // They are different layers of a real mix and they are recreated by
+    // different means: ambience is a continuous bed, an sfx is a discrete hit.
+    // Collapsing them onto `sfx` made a scene's continuous bed indistinguishable
+    // from its one-off noises, so a recreation had to guess which it was told.
+    expect([...VIDEO_ANALYSIS_AUDIO_MODES]).toEqual(["speech", "music", "sfx", "ambience"])
+    const parsed = windowAnalysisSchema.parse({
+      slots: [slot],
+      scenes: [{ ...baseScene, audio: [{ mode: "ambience", content: "distant traffic, room tone" }] }],
+    })
+    expect(parsed.scenes[0]!.audio[0]!.mode).toBe("ambience")
+  })
+
+  it("names the speaker BOTH ways — by slot id and by cast name", () => {
+    // `speakerSlot` addresses a slot in THIS analysis; `speaker` is the plain
+    // name a document that has no slots (a studio production's cast) keys by.
+    // One layer may legitimately carry both.
+    const parsed = windowAnalysisSchema.parse({
+      slots: [slot],
+      scenes: [{ ...baseScene, audio: [{ mode: "speech", content: "As a kid…", speakerSlot: "hero", speaker: "Jack Mercer" }] }],
+    })
+    expect(parsed.scenes[0]!.audio[0]).toMatchObject({ speakerSlot: "hero", speaker: "Jack Mercer" })
+  })
+
+  it("dropUnknownSpeakers strips slot attribution from an AMBIENCE layer too — nobody is speaking", () => {
+    // The new mode must land on the non-speech side of the sanitizer, not slip
+    // through it as an unrecognised value. This one's RED was a `tsc` error on
+    // the literal, not a runtime failure — the sanitizer never validated the
+    // mode; the sibling parse case above carries the runtime pin.
+    const r = dropUnknownSpeakers([{ mode: "ambience", content: "room tone", speakerSlot: "hero" }], new Set(["hero"]))
+    expect(r.audio[0]).not.toHaveProperty("speakerSlot")
+    expect(r.dropped).toEqual(["hero"])
+  })
+
+  it("the name-keyed speaker survives the SLOT sanitizer — it names no slot to check", () => {
+    // `dropUnknownSpeakers` is the slot channel's sweep: it can only judge an
+    // id against the surviving slot list, and a cast NAME has no id space to be
+    // unknown in. Pinned so a later reader does not "fix" the asymmetry into a
+    // sweep that silently eats the field studio imports this type for.
+    const audio: AudioLayer[] = [{ mode: "speech", content: "hi", speaker: "Jack Mercer" }]
+    const r = dropUnknownSpeakers(audio, new Set())
+    expect(r.audio).toBe(audio)
+    expect(r.audio[0]!.speaker).toBe("Jack Mercer")
+    expect(r.dropped).toEqual([])
+  })
+
+  it("both attributions are OPTIONAL — an older producer emits neither", () => {
+    const parsed = windowAnalysisSchema.parse({ slots: [slot], scenes: [baseScene] })
+    expect(parsed.scenes[0]!.audio[0]).not.toHaveProperty("speakerSlot")
+    expect(parsed.scenes[0]!.audio[0]).not.toHaveProperty("speaker")
+  })
+})
+
 describe("cinematography fields (angle / speed / onScreenText / look)", () => {
   it("carries angle and speed as closed enums through a window round-trip", () => {
     const parsed = windowAnalysisSchema.parse({
@@ -348,6 +403,34 @@ describe("cinematography fields (angle / speed / onScreenText / look)", () => {
     expect(r.look?.format).toBe("anamorphic digital")
     expect(r.meta).not.toHaveProperty("look")
   })
+
+  it("look carries the Style picker's own ID beside the prose — the PICK must not be stripped", () => {
+    // The analyzer emits the id it PICKED from the Style catalog alongside the
+    // prose it corresponds to: { styleId: "pixar-3d", style: "3D stylized
+    // animation", influence: "Pixar style" }. A z.object drops what it does not
+    // declare, so an undeclared `styleId` silently loses the pick on every
+    // consumer that reads an analysis back THROUGH this schema — and a pick is
+    // worth strictly more than the prose, because it addresses the catalog.
+    const look = { styleId: "pixar-3d", style: "3D stylized animation", influence: "Pixar style" }
+    // The window layer, where the pick enters…
+    expect(windowAnalysisSchema.parse({ look, slots: [], scenes: [] }).look).toMatchObject(look)
+    // …and the merged result, where every consumer reads it.
+    const r = videoAnalysisResultSchema.parse({
+      meta: { durationSec: 10, width: 1920, height: 1080, aspectRatio: "16:9" },
+      look,
+      slots: [],
+      scenes: [{ ...baseScene, sceneNumber: 1, visualResolved: "x", slotRefs: [] }],
+    })
+    expect(r.look).toMatchObject(look)
+  })
+
+  it("mergeClipLook folds the pick like any other field — first window to read it wins", () => {
+    // The fold is generic (Object.entries), so this only breaks if someone
+    // narrows it to a hand-written field list — the hop that has eaten a field
+    // before.
+    expect(mergeClipLook([{ style: "3D stylized animation" }, { styleId: "pixar-3d" }]))
+      .toEqual({ style: "3D stylized animation", styleId: "pixar-3d" })
+  })
 })
 
 describe("mergeClipLook", () => {

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

@@ -78,16 +78,37 @@ describe("getVideoAudioCapability", () => {
     }
   })
 
+  it("returns ambient (always on) for both Gemini Omni SKUs", () => {
+    // Google's own docs: "By default the model will try to generate an
+    // appropriate audio track for a video." Not `none` — the catalog has said
+    // "native audio" since the SKUs landed, and this map was the one place that
+    // disagreed, so every reader of it described the models as silent.
+    //
+    // Not `native_speech` either: the SAME page scopes dialogue to a path we do
+    // not drive — "Multi-turn voice extension: Generating spoken dialogue or
+    // speech is supported when extending previously generated videos via
+    // multi-turn (`previous_interaction_id`)" — and KIE's createTask schema
+    // exposes no such field. Same bar Wan 3.0 was held to.
+    for (const m of ["gemini-omni-video", "gemini-omni-flash"]) {
+      const cap = getVideoAudioCapability(m)
+      expect(cap.mode, m).toBe("ambient")
+      // No on/off parameter anywhere in the KIE input schema ⇒ alwaysOn, no field.
+      expect(cap.alwaysOn, m).toBe(true)
+      expect(cap.field, m).toBeUndefined()
+      expect(cap.affectsCost, m).toBeUndefined()
+    }
+  })
+
+  it("the two Omni SKUs never disagree — they are one model at two speeds", () => {
+    expect(VIDEO_AUDIO_CAPABILITY["gemini-omni-flash"]).toEqual(VIDEO_AUDIO_CAPABILITY["gemini-omni-video"])
+  })
+
   it("defaults to none for silent / unknown / undefined models", () => {
     for (const m of [
       "minimax",
       "hailuo-2.3",
       "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",
@@ -105,6 +126,8 @@ describe("videoModelSupportsAudio", () => {
     expect(videoModelSupportsAudio("kling-3-omni")).toBe(true)
     expect(videoModelSupportsAudio("seedance-2")).toBe(true)
     expect(videoModelSupportsAudio("seedance")).toBe(true)
+    expect(videoModelSupportsAudio("gemini-omni-video")).toBe(true)
+    expect(videoModelSupportsAudio("gemini-omni-flash")).toBe(true)
     expect(videoModelSupportsAudio("minimax")).toBe(false)
     expect(videoModelSupportsAudio(undefined)).toBe(false)
   })
@@ -124,6 +147,10 @@ describe("videoModelCanSpeakDialogue", () => {
     expect(videoModelCanSpeakDialogue("kling-3-omni")).toBe(true)
     // ambient-only models are NOT dialogue-capable — their audio is SFX/ambient
     expect(videoModelCanSpeakDialogue("seedance")).toBe(false)
+    // Gemini Omni generates an audio track on every render, but its documented
+    // dialogue path is multi-turn extension, which our transport cannot reach.
+    expect(videoModelCanSpeakDialogue("gemini-omni-video")).toBe(false)
+    expect(videoModelCanSpeakDialogue("gemini-omni-flash")).toBe(false)
     expect(videoModelCanSpeakDialogue("minimax")).toBe(false)
     expect(videoModelCanSpeakDialogue(undefined)).toBe(false)
   })
@@ -260,6 +287,13 @@ describe("applyVideoAudioToggle — neutral audio intent → per-model KIE field
     expect(input).toEqual({})
   })
 
+  it("is a no-op for always-on Gemini Omni — the KIE schema has no audio lever", () => {
+    const input: Record<string, unknown> = {}
+    applyVideoAudioToggle(input, "gemini-omni-video", { sound: false })
+    applyVideoAudioToggle(input, "gemini-omni-flash", { generateAudio: true })
+    expect(input).toEqual({})
+  })
+
   it("is a no-op for silent / unknown models (not in the capability table)", () => {
     const input: Record<string, unknown> = {}
     applyVideoAudioToggle(input, "minimax", { sound: true })

package/src/__tests__/video-catalog-totality.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "vitest"
+import {
+  MODEL_CATALOG,
+  resolutionOptionsByKind,
+  aspectRatioOptionsByKind,
+  durationsByMode,
+} from "../model-catalog.js"
+import { VIDEO_GEN_PROVIDERS } from "../model-constants.js"
+
+/**
+ * Every video model a user can pick must have a catalog entry. The catalog is
+ * what `normalizeModelInput` / `normalizeVideoRequestParams` snap against, what
+ * `VIDEO_PROVIDERS_REQUIRING_IMAGE` derives from, and what the frontend option
+ * menus are built from — a model outside it silently opts out of all three and
+ * gets its option lists hand-spliced into the frontend instead. That is exactly
+ * how ltx-2.3-fast reached Replicate with a 720p resolution and a 422 came back
+ * (app-reports triage 2026-09-01, P3).
+ */
+describe("MODEL_CATALOG covers every generatable video provider", () => {
+  it("has an entry for every VIDEO_GEN_PROVIDERS member", () => {
+    const missing = VIDEO_GEN_PROVIDERS.filter((p) => !MODEL_CATALOG[p])
+    expect(
+      missing,
+      `Add a MODEL_CATALOG entry (modes / aspectRatios / resolutions / durations / pricing) for: ${missing.join(", ")}`,
+    ).toEqual([])
+  })
+
+  // Deliberately a KEY-PRESENCE check, not `kind === "video"`. `grok`'s entry
+  // lives in IMAGE_MODELS with `kind: "image"` (it is a t2v provider whose
+  // catalog row is the image sibling), so tightening this assertion would fail
+  // on `grok` for a reason unrelated to LTX. Fix that entry first if you ever
+  // want the stronger form.
+
+  it("every video entry's pricing identifiers are unique and non-empty", () => {
+    for (const p of VIDEO_GEN_PROVIDERS) {
+      const entry = MODEL_CATALOG[p]
+      if (!entry) continue
+      const ids = entry.pricing.map((v) => v.identifier)
+      expect(ids.length, `${p} has no pricing rows`).toBeGreaterThan(0)
+      expect(new Set(ids).size, `${p} has duplicate pricing identifiers`).toBe(ids.length)
+    }
+  })
+})
+
+/**
+ * Deleting the LTX hand-splices in frontend/model-options.ts (Task 7 step 5)
+ * hands resolution/aspect/duration option rendering to these catalog-derived
+ * helpers. Pin their LTX output to exactly what the deleted splices used to
+ * hard-code, so the refactor is provably UI-neutral — including the "2k"
+ * label regression (R24) the brief called out: MODEL_VALUE_LABELS had no
+ * "2k" entry, so the derived option rendered lowercase "2k" where the spliced
+ * literal rendered "2K" until that label was added.
+ */
+describe("LTX catalog-derived options match the deleted frontend splices exactly", () => {
+  const RESOLUTION_OPTIONS = [
+    { value: "1080p", label: "1080p" },
+    { value: "2k", label: "2K" },
+    { value: "4k", label: "4K" },
+  ]
+  const ASPECT_OPTIONS = [
+    { value: "16:9", label: "16:9 (Landscape)" },
+    { value: "9:16", label: "9:16 (Portrait)" },
+  ]
+
+  it("resolutionOptionsByKind('video') renders both LTX ids identically to the deleted VIDEO_RESOLUTION_OPTIONS splice", () => {
+    const options = resolutionOptionsByKind("video")
+    expect(options["ltx-2.3-pro"]).toEqual(RESOLUTION_OPTIONS)
+    expect(options["ltx-2.3-fast"]).toEqual(RESOLUTION_OPTIONS)
+  })
+
+  it("aspectRatioOptionsByKind('video') renders both LTX ids identically to the deleted _VIDEO_ASPECT_BY_PROVIDER splice", () => {
+    const options = aspectRatioOptionsByKind("video")
+    expect(options["ltx-2.3-pro"]).toEqual(ASPECT_OPTIONS)
+    expect(options["ltx-2.3-fast"]).toEqual(ASPECT_OPTIONS)
+  })
+
+  it("durationsByMode merges to the same duration lists the deleted out[\"ltx-2.3-*\"] splice hard-coded", () => {
+    const i2v = durationsByMode("i2v")
+    const t2v = durationsByMode("t2v")
+    const merge = (id: string) =>
+      Array.from(new Set([...(i2v[id] ?? []), ...(t2v[id] ?? [])])).sort((a, b) => a - b)
+    expect(merge("ltx-2.3-pro")).toEqual([6, 8, 10])
+    expect(merge("ltx-2.3-fast")).toEqual([6, 8, 10, 12, 14, 16, 18, 20])
+  })
+})

package/src/__tests__/video-collapse-parity.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from "vitest"
+import { MODEL_CATALOG, normalizeVideoRequestParams } from "../index.js"
+import {
+  normalizeMinimaxH3Resolution,
+  normalizeWan3Resolution,
+  VIDEO_GEN_PROVIDERS,
+} from "../model-constants.js"
+
+/**
+ * Most video providers RENDER whatever band they are handed, so an off-list
+ * request is best snapped to the nearest supported one. A few instead COLLAPSE
+ * anything unrecognised to a fixed default, and for those the nearest band is
+ * wrong in the most expensive direction: MiniMax H3 renders 2K for every value
+ * that isn't "768p", so snapping a stale Seedance "720p" to the pixel-nearest
+ * 768P would bill the CHEAP tier against a 2K render — and `commit_credits`
+ * (migration 176) only refunds a surplus, never collects a shortfall.
+ *
+ * `ModelCatalogEntry.unlistedResolutionRendersAs` is how a model declares that
+ * behaviour. These tests pin every declaration to what the provider's OWN
+ * normalizer returns, so a change to one without the other fails the build
+ * rather than silently repricing live runs.
+ */
+describe("unlistedResolutionRendersAs matches the provider's own collapse rule", () => {
+  // Real off-list VALUES only. A blank/absent resolution is a different case —
+  // it never reaches the snap (there is nothing to snap), and the identifier
+  // already prices it through the provider's own collapse rule, so price and
+  // render agree on it without this field.
+  const OFF_LIST = ["720p", "480p", "1080p", "4k", "nonsense"]
+
+  it("minimax-h3 declares what normalizeMinimaxH3Resolution collapses to", () => {
+    const declared = MODEL_CATALOG["minimax-h3"]!.unlistedResolutionRendersAs
+    expect(declared).toBeDefined()
+    for (const off of OFF_LIST) {
+      if ((MODEL_CATALOG["minimax-h3"]!.resolutions as readonly string[]).includes(off)) continue
+      expect(normalizeMinimaxH3Resolution(off), `H3 renders ${off} as`).toBe(declared)
+      expect(normalizeVideoRequestParams("minimax-h3", { resolution: off }).resolution).toBe(declared)
+    }
+  })
+
+  it("the wan-3 family declares what normalizeWan3Resolution collapses to", () => {
+    for (const id of ["wan-3", "wan-3-prime"]) {
+      const declared = MODEL_CATALOG[id]!.unlistedResolutionRendersAs
+      expect(declared, id).toBeDefined()
+      for (const off of ["4k", "2k", "nonsense"]) {
+        // The catalog spells bands lowercase; the KIE wire form is uppercase.
+        expect(normalizeWan3Resolution(off).toLowerCase(), `${id} renders ${off} as`).toBe(declared)
+        expect(normalizeVideoRequestParams(id, { resolution: off }).resolution).toBe(declared)
+      }
+    }
+  })
+
+  it("a declared collapse target is always one of the model's own bands", () => {
+    for (const provider of VIDEO_GEN_PROVIDERS) {
+      const entry = MODEL_CATALOG[provider]
+      const declared = entry?.unlistedResolutionRendersAs
+      if (declared === undefined) continue
+      expect(entry!.resolutions, `${provider} declares a collapse target but no resolutions`).toBeDefined()
+      expect(entry!.resolutions, `${provider}: "${declared}" is not one of its bands`).toContain(declared)
+    }
+  })
+
+  it("does not change a listed value — the collapse rule only governs OFF-list requests", () => {
+    expect(normalizeVideoRequestParams("minimax-h3", { resolution: "768P" }).resolution).toBe("768P")
+    expect(normalizeVideoRequestParams("minimax-h3", { resolution: "2K" }).resolution).toBe("2K")
+    expect(normalizeVideoRequestParams("wan-3", { resolution: "480p" }).resolution).toBe("480p")
+    expect(normalizeVideoRequestParams("wan-3", { resolution: "1080p" }).resolution).toBe("1080p")
+  })
+
+  it("every other video model still snaps to the NEAREST band", () => {
+    // The collapse rule is an opt-in exception, not the default: a 4k request on
+    // a 1080p-max model must still render 1080p, never the cheapest tier (R7).
+    expect(MODEL_CATALOG["seedance-2-5"]!.unlistedResolutionRendersAs).toBeUndefined()
+    expect(normalizeVideoRequestParams("seedance-2-5", { resolution: "4k" }).resolution).toBe("1080p")
+    expect(normalizeVideoRequestParams("seedance-2-5", { resolution: "360p" }).resolution).toBe("480p")
+  })
+})