@nodaro/shared 2.20.0 → 2.21.1

package/src/model-catalog.ts

@@ -133,6 +133,24 @@ export interface ModelCatalogEntry {
   features?: readonly string[]
   aspectRatios?: readonly string[]
   resolutions?: readonly string[]
+  /**
+   * What this model actually RENDERS for a resolution outside `resolutions`.
+   *
+   * Most providers honour whatever band they are sent, so an off-list value is
+   * best snapped to the NEAREST supported one — a 4k request on a 1080p-max
+   * model renders 1080p. A few instead COLLAPSE anything unrecognised to a
+   * fixed default (MiniMax H3 → 2K, Wan 3.0 → 720p), and for those the nearest
+   * band is the wrong answer in the most expensive direction: snapping a stale
+   * "720p" to H3's cheap 768P would send a value the provider ignores, so we
+   * would bill the 768P tier against a 2K render, and `commit_credits` never
+   * collects the shortfall.
+   *
+   * Declare it in the catalog's own spelling. `normalizeVideoRequestParams`
+   * uses it in place of the nearest-band snap; `video-collapse-parity.test.ts`
+   * pins each declaration to what the provider normalizer actually returns, so
+   * the two cannot drift.
+   */
+  unlistedResolutionRendersAs?: string
   qualities?: readonly string[]
   durations?: readonly number[]
   pricing: readonly PriceVariant[]
@@ -155,6 +173,12 @@ export interface ModelCatalogEntry {
    * Frontend pickers ignore this flag.
    */
   mcpHidden?: boolean
+  /**
+   * The provider's safety filter is known to be non-deterministic on this
+   * model — the platform retries a blocked request once; `fallback` names
+   * the catalog model to offer when it blocks again.
+   */
+  safetyFilter?: { stochastic: true; fallback?: string }
 }
 
 /**
@@ -177,7 +201,7 @@ export const MODEL_RECOMMENDATIONS: readonly ModelRecommendation[] = [
   { intent: "cheapest realistic image", modelIds: ["z-image", "qwen", "imagen4-fast"], note: "Z-Image is the cheapest. Qwen / Imagen4 Fast for slightly higher quality." },
   { intent: "highest fidelity image", modelIds: ["nano-banana-pro", "imagen4-ultra", "flux-flex"], note: "Pick by family preference; all three are premium tiers." },
   { intent: "image edit / restyle", modelIds: ["flux-kontext", "ideogram-remix", "seedream-5-pro-i2i"], note: "Flux Kontext preserves identity; Ideogram Remix is character-aware; Seedream 5 Pro for instruction-based edits (5 Lite is the budget option)." },
-  { intent: "highest-resolution image (4K / 8K)", modelIds: ["topaz-image-upscale", "nano-banana-pro", "gpt-image-2"], note: "Generate at native then Topaz upscale for 8K." },
+  { intent: "highest-resolution image", modelIds: ["topaz-image-upscale", "nano-banana-pro", "gpt-image-2"], note: "Generate at the model's top tier, then Topaz upscale 4x (Topaz's only lever is the 1x/2x/4x factor)." },
   { intent: "background removal / cutout", modelIds: ["recraft-remove-bg"], note: "Cheap, no prompt needed." },
   // video
   { intent: "best cinematic video", modelIds: ["veo3", "kling-3.0", "seedance-2"], note: "VEO 3.1 Quality for premium narrative; Kling 3.0 for music-synced motion; Seedance 2 for reference-driven consistency." },
@@ -545,6 +569,7 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
       { identifier: "gpt-image-2:2K", credits: 30, note: "2K" },
       { identifier: "gpt-image-2:4K", credits: 60, note: "4K" },
     ],
+    safetyFilter: { stochastic: true, fallback: "nano-banana-pro" },
   },
   "gpt-image-2-i2i": {
     id: "gpt-image-2-i2i",
@@ -554,6 +579,7 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
     label: "GPT Image 2 (I2I)",
     series: "GPT Image",
     description: "Image-to-image with GPT Image 2.",
+    safetyFilter: { stochastic: true, fallback: "nano-banana-pro" },
     useCases: ["edit", "high-res"],
     features: ["reference-image"],
     aspectRatios: GPT_IMAGE_2_RATIOS,
@@ -975,14 +1001,15 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
     family: "Topaz",
     label: "Topaz Image Upscale",
     series: "Topaz",
-    description: "High-quality image upscale up to 8K. Best for production-ready output.",
+    description: "High-quality image upscale at 1x (enhance only), 2x or 4x. Best for production-ready output.",
     useCases: ["upscale", "high-res", "premium"],
     features: ["reference-image"],
-    resolutions: ["2K", "4K", "8K"],
+    // No `resolutions`: the provider's only quality lever is `upscale_factor`
+    // (1/2/4) — see resolveTopazUpscale. The 2K/4K/8K menu this used to
+    // advertise had no provider parameter behind it.
     pricing: [
-      { identifier: "topaz-image-upscale", credits: 25, note: "2K default" },
-      { identifier: "topaz-image-upscale:4K", credits: 50, note: "4K" },
-      { identifier: "topaz-image-upscale:8K", credits: 100, note: "8K" },
+      { identifier: "topaz-image-upscale", credits: 25, note: "1x / 2x" },
+      { identifier: "topaz-image-upscale:4K", credits: 50, note: "4x (legacy identifier)" },
     ],
   },
 }
@@ -1017,6 +1044,7 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
   // docs.kie.ai/market/minimax-h3/{text,image,reference}-to-video.
   "minimax-h3": {
     id: "minimax-h3",
+    unlistedResolutionRendersAs: "2K",
     kind: "video",
     modes: ["i2v", "t2v"] as const,
     family: "MiniMax",
@@ -1505,6 +1533,7 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
   // declared explicitly in PRICING_DEFAULT_RESOLUTION, never by array position.
   "wan-3": {
     id: "wan-3",
+    unlistedResolutionRendersAs: "720p",
     kind: "video",
     modes: ["i2v", "t2v"] as const,
     family: "Alibaba",
@@ -1529,6 +1558,7 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
   },
   "wan-3-prime": {
     id: "wan-3-prime",
+    unlistedResolutionRendersAs: "720p",
     kind: "video",
     modes: ["i2v", "t2v"] as const,
     family: "Alibaba",
@@ -1697,6 +1727,76 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
       { identifier: "wan-2.7-t2v", credits: 188, note: "5s 720p default" },
     ],
   },
+  // Lightricks LTX 2.3 (Replicate, not KIE). Both variants run one endpoint per
+  // variant and switch behaviour with a `task` discriminator, so t2v and i2v are
+  // the SAME id — no VIDEO_MODE_ALIASES row. `extend` / `retake` are separate
+  // priced ops on the same model (ids below) but are NOT listed in `modes`:
+  // they are driven by the Extend Video / Video Retake nodes' own pickers, and
+  // adding the mode here would duplicate LTX in those menus.
+  // Bands are lowercase to match LTX_DURATION_TIERS' keys in credit-identifiers.ts
+  // and QUALITY_MAP in node-default-mappings.ts.
+  "ltx-2.3-pro": {
+    id: "ltx-2.3-pro",
+    kind: "video",
+    modes: ["i2v", "t2v"] as const,
+    family: "Lightricks",
+    label: "LTX 2.3 Pro",
+    series: "LTX",
+    description: "Lightricks LTX 2.3 Pro — text/image/audio→video up to 4K, 6/8/10s, end-frame interpolation.",
+    useCases: ["premium", "high-res", "narrative"],
+    features: ["end-frame"],
+    aspectRatios: ["16:9", "9:16"] as const,
+    resolutions: ["1080p", "2k", "4k"] as const,
+    durations: [6, 8, 10],
+    pricing: [
+      { identifier: "ltx-2.3-pro", credits: 240, note: "default 1080p 6s" },
+      { identifier: "ltx-2.3-pro:1080p:6s", credits: 240 },
+      { identifier: "ltx-2.3-pro:1080p:8s", credits: 320 },
+      { identifier: "ltx-2.3-pro:1080p:10s", credits: 400 },
+      { identifier: "ltx-2.3-pro:2k:6s", credits: 480 },
+      { identifier: "ltx-2.3-pro:2k:8s", credits: 640 },
+      { identifier: "ltx-2.3-pro:2k:10s", credits: 800 },
+      { identifier: "ltx-2.3-pro:4k:6s", credits: 960 },
+      { identifier: "ltx-2.3-pro:4k:8s", credits: 1280 },
+      { identifier: "ltx-2.3-pro:4k:10s", credits: 1600 },
+      { identifier: "ltx-2.3-pro-extend:per-second", credits: 40, note: "extend, per second of new footage" },
+      { identifier: "ltx-2.3-pro-retake:per-second", credits: 40, note: "retake, per second re-rendered" },
+    ],
+  },
+  "ltx-2.3-fast": {
+    id: "ltx-2.3-fast",
+    kind: "video",
+    modes: ["i2v", "t2v"] as const,
+    family: "Lightricks",
+    label: "LTX 2.3 Fast",
+    series: "LTX",
+    description: "Lightricks LTX 2.3 Fast — text/image→video up to 20s at 1080p (6/8/10s at 2K and 4K). No audio input, no extend.",
+    useCases: ["long-form", "fast", "narrative"],
+    features: ["end-frame"],
+    aspectRatios: ["16:9", "9:16"] as const,
+    resolutions: ["1080p", "2k", "4k"] as const,
+    // Flat union across bands — 12–20s exist only at 1080p (LTX_DURATION_TIERS
+    // in credit-identifiers.ts is the per-band authority and snaps a 2k/4k
+    // request back onto 6/8/10s, so the reservation is always a real tier).
+    durations: [6, 8, 10, 12, 14, 16, 18, 20],
+    pricing: [
+      { identifier: "ltx-2.3-fast", credits: 180, note: "default 1080p 6s" },
+      { identifier: "ltx-2.3-fast:1080p:6s", credits: 180 },
+      { identifier: "ltx-2.3-fast:1080p:8s", credits: 240 },
+      { identifier: "ltx-2.3-fast:1080p:10s", credits: 300 },
+      { identifier: "ltx-2.3-fast:1080p:12s", credits: 360 },
+      { identifier: "ltx-2.3-fast:1080p:14s", credits: 420 },
+      { identifier: "ltx-2.3-fast:1080p:16s", credits: 480 },
+      { identifier: "ltx-2.3-fast:1080p:18s", credits: 540 },
+      { identifier: "ltx-2.3-fast:1080p:20s", credits: 600 },
+      { identifier: "ltx-2.3-fast:2k:6s", credits: 360 },
+      { identifier: "ltx-2.3-fast:2k:8s", credits: 480 },
+      { identifier: "ltx-2.3-fast:2k:10s", credits: 600 },
+      { identifier: "ltx-2.3-fast:4k:6s", credits: 720 },
+      { identifier: "ltx-2.3-fast:4k:8s", credits: 960 },
+      { identifier: "ltx-2.3-fast:4k:10s", credits: 1200 },
+    ],
+  },
   // ── HappyHorse (1.1 — ids kept version-less; repointed in place when KIE
   // delisted 1.0, same param surface, so saved workflows keep working) ──
   "happyhorse": {
@@ -2714,6 +2814,187 @@ export function normalizeModelInput(
   return out
 }
 
+/** Aspect tokens that mean "match the input" or "let the provider decide". They
+ *  are NOT concrete ratios, so snapping them onto one is always wrong — the
+ *  provider adapter (applySeedance2Params, applyMinimaxH3Params) resolves them
+ *  once it knows the run's mode. */
+const PASSTHROUGH_ASPECT_TOKENS = new Set(["auto", "adaptive"])
+
+/** Approximate vertical pixel count per band token, for nearest-band matching.
+ *  Anything of the form `<N>p` is parsed directly; these are the named bands
+ *  the catalogs use that do not follow that form. */
+const RESOLUTION_BAND_PIXELS: Record<string, number> = {
+  "2k": 1440,
+  "4k": 2160,
+  "8k": 4320,
+}
+
+function bandPixels(token: string): number | undefined {
+  const t = token.trim().toLowerCase()
+  if (RESOLUTION_BAND_PIXELS[t] !== undefined) return RESOLUTION_BAND_PIXELS[t]
+  const m = /^(\d+)p$/.exec(t)
+  return m ? Number(m[1]) : undefined
+}
+
+/** Nearest member of `allowed` to `token` by vertical pixels. An UNPARSEABLE
+ *  request falls back to the highest declared band — never the cheapest, which
+ *  is what a catalog-order fallback would give (R7). Highest is computed from
+ *  the pixel counts, not from the array position: most video catalogs list
+ *  ascending but not all do (minimax-h3 is `["2K", "768P"]`), and an ordering
+ *  convention is not something a money path should depend on. */
+function nearestResolutionBand(token: string, allowed: readonly string[]): string {
+  let highest = allowed[allowed.length - 1]!
+  let highestPx = -Infinity
+  for (const a of allowed) {
+    const px = bandPixels(a)
+    if (px !== undefined && px > highestPx) { highestPx = px; highest = a }
+  }
+  const want = bandPixels(token)
+  if (want === undefined) return highest
+  let best = highest
+  let bestDist = Infinity
+  for (const a of allowed) {
+    const px = bandPixels(a)
+    if (px === undefined) continue
+    const d = Math.abs(px - want)
+    if (d < bestDist) { bestDist = d; best = a }
+  }
+  return best
+}
+
+/** Nearest aspect ratio in log space. Mirrors
+ *  `backend/src/providers/video/aspect-ratio.ts` exactly — that helper cannot
+ *  be imported here (wrong package), and the totality test in
+ *  `backend/src/lib/mcp/__tests__/video-normalizer-totality.test.ts` pins the
+ *  two implementations to the same answer for every catalogued model. */
+function nearestAspectRatio(token: string, allowed: readonly string[]): string | undefined {
+  const [w, h] = token.split(":").map(Number)
+  if (!w || !h) return undefined
+  const target = Math.log(w / h)
+  let best: string | undefined
+  let bestDist = Infinity
+  for (const c of allowed) {
+    const [cw, ch] = c.split(":").map(Number)
+    if (!cw || !ch) continue
+    const d = Math.abs(Math.log(cw / ch) - target)
+    if (d < bestDist) { bestDist = d; best = c }
+  }
+  return best
+}
+
+/**
+ * Read a catalog lever off an UNVALIDATED input as a trimmed string.
+ *
+ * `normalizeVideoRequestParams` runs in both routes' creditGuard preHandler —
+ * which fires BEFORE the route's Zod parse — and in all four `buildPayload`
+ * branches, whose `data` is persisted workflow JSON that an agent/import/
+ * FieldMapping can write any JSON type into. A bare `.trim()` therefore throws
+ * `TypeError` on `{"resolution": 1080}`: a 500 where the route used to return a
+ * clean Zod 400, and in the DAG a thrown lever takes the WHOLE run down after
+ * sibling nodes have already reserved and generated. So coerce rather than
+ * assume — same posture as `sameOptionValue`, which has always used `String(v)`.
+ *
+ * `null`/`undefined`/blank mean "absent" (there is nothing to snap) and read as
+ * `undefined`, so the priced fill downstream supplies the band the identifier
+ * assumes — price and wire still agree. Everything else is stringified: a
+ * numeric `1080` becomes `"1080"` and snaps like its string form.
+ */
+function readOptionToken(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined
+  const s = (typeof value === "string" ? value : String(value)).trim()
+  return s === "" ? undefined : s
+}
+
+export interface NormalizedVideoRequest {
+  aspectRatio?: string
+  resolution?: string
+  adjustments: ModelInputAdjustment[]
+}
+
+/**
+ * The video lane's LIMITED normalizer: `aspectRatio` + `resolution` only, and
+ * only when the catalog actually declares the option list.
+ *
+ * Three deliberate differences from `normalizeModelInput`:
+ *   1. It never DROPS a lever. `normalizeModelInput` removes a value whose list
+ *      the catalog doesn't declare; on the video lane `resolution` is a pricing
+ *      input, so dropping it would lower the reserved tier and `commit_credits`
+ *      never collects an upward delta — a params fix would become a money bug.
+ *   2. "Auto" / "adaptive" pass through (see PASSTHROUGH_ASPECT_TOKENS).
+ *   3. It snaps to the NEAREST option, not to `allowed[0]`. `normalizeModelInput`
+ *      would turn a portrait 9:21 into landscape 16:9 and a 4k request into the
+ *      cheapest 480p; nearest matches what the provider adapters and the MCP
+ *      normalizer already do, so all three give ONE answer. Its snap policy is
+ *      deliberately left alone — it is shared with the image lane and the
+ *      copilot, and PR 4 defers changing it.
+ *
+ * `duration` is deliberately NOT normalized here: the LTX bands make duration
+ * legality resolution-dependent, which a flat catalog list can't express, and
+ * `buildVideoCreditModelIdentifier` already snaps duration onto a seeded tier.
+ * Carrying THAT tier to the wire is `pricedVideoSelection`'s job
+ * (`credit-identifiers.ts`), which runs after this one, once resolution is known.
+ *
+ * An OMITTED lever stays omitted here — filling it is a pricing decision, not a
+ * catalog one, and likewise belongs to `pricedVideoSelection`.
+ *
+ * Case is canonicalised to the catalog's own spelling — the credit identifiers
+ * key their tables case-SENSITIVELY (LTX_DURATION_TIERS), so this is the single
+ * place a "4K" becomes "4k", and it runs before every identifier site.
+ *
+ * Pure — so the credit-identifier preHandler, `computeCredits`, the reservation
+ * site and the payload build can all call it and cannot disagree (spec §4).
+ */
+export function normalizeVideoRequestParams(
+  modelId: string,
+  input: { aspectRatio?: string; resolution?: string },
+): NormalizedVideoRequest {
+  const m = MODEL_CATALOG[modelId]
+  // Seeded from the COERCED tokens, never the raw input: this function's own
+  // return type promises `string | undefined`, and its callers feed it straight
+  // to the credit identifier and the provider wire. Handing back the caller's
+  // `1080` or `[]` verbatim would break that promise at exactly the sites that
+  // must agree on one value.
+  const aspect = readOptionToken(input.aspectRatio)
+  const res = readOptionToken(input.resolution)
+  const out: NormalizedVideoRequest = { aspectRatio: aspect, resolution: res, adjustments: [] }
+  if (!m) return out
+
+  if (m.aspectRatios?.length && aspect && !PASSTHROUGH_ASPECT_TOKENS.has(aspect.toLowerCase())) {
+    const allowed = m.aspectRatios
+    const exact = allowed.find((a) => a === aspect) ?? allowed.find((a) => a.toLowerCase() === aspect.toLowerCase())
+    if (exact !== undefined) {
+      out.aspectRatio = exact
+    } else {
+      const next = nearestAspectRatio(aspect, allowed.filter((a) => !PASSTHROUGH_ASPECT_TOKENS.has(a.toLowerCase()))) ?? allowed[0]!
+      out.adjustments.push({
+        field: "aspectRatio", from: aspect, to: next,
+        reason: `${m.label} does not support aspect ratio "${aspect}" — using "${next}" instead. Supported: ${allowed.join(", ")}.`,
+      })
+      out.aspectRatio = next
+    }
+  }
+
+  if (m.resolutions?.length && res) {
+    const allowed = m.resolutions
+    const exact = allowed.find((a) => a === res) ?? allowed.find((a) => a.toLowerCase() === res.toLowerCase())
+    if (exact !== undefined) {
+      out.resolution = exact
+    } else {
+      // A provider that COLLAPSES an unrecognised band renders its declared
+      // default no matter what we send, so that default — not the nearest band
+      // — is the value the wire and the price must both carry.
+      const next = m.unlistedResolutionRendersAs ?? nearestResolutionBand(res, allowed)
+      out.adjustments.push({
+        field: "resolution", from: res, to: next,
+        reason: `${m.label} does not support resolution "${res}" — using "${next}" instead. Supported: ${allowed.join(", ")}.`,
+      })
+      out.resolution = next
+    }
+  }
+
+  return out
+}
+
 // =============================================================================
 // Frontend picker helpers — return `{value, label}[]` shapes that the
 // existing config-panel components expect, derived from the catalog so we
@@ -2742,6 +3023,7 @@ const MODEL_VALUE_LABELS: Record<string, string> = {
   "2K": "2K (High)",
   "4K": "4K (Ultra)",
   "4k": "4K",
+  "2k": "2K",
   "8K": "8K (Ultra)",
   // qualities
   "medium": "Medium (Balanced)",

package/src/model-constants.ts

@@ -1900,6 +1900,89 @@ export const VIDEO_REF_LIMITS_BY_PROVIDER: Record<
   // verified provider path + the catalog `reference-image` feature.
 }
 
+/** Per-reference-video duration bounds, in seconds. */
+export interface RefVideoDurationLimit {
+  minSec: number
+  maxSec: number
+  /** Cap on the SUM of all reference-video durations, when the provider has one. */
+  maxTotalSec?: number
+}
+
+/**
+ * Reference-video duration limits, provider-declared.
+ *
+ * `VIDEO_REF_LIMITS_BY_PROVIDER` above caps the reference COUNT; these cap the
+ * duration of each clip. Both routes already ffprobe every reference video to
+ * price the run (ee/billing/seedance2-ref-video-credits.ts and
+ * minimax-h3-credits.ts), so the numbers are in hand before the job exists —
+ * and until 2026-09-02 they were discarded, which is why "Each reference video
+ * must be between 2 and 30 seconds" and "video duration 52838 ms, expected
+ * [2000, 15000] ms" were reaching users as post-payment provider rejects
+ * (app-reports §11.3).
+ *
+ * Data-driven, exactly like SEEDANCE_2_R2V_MAX_AUDIO_SEC_BY_PROVIDER above:
+ * only providers with a VERIFIED documented limit are listed, so an unknown
+ * provider is never false-rejected.
+ *
+ * Sources: docs.kie.ai/market/bytedance/seedance-2-5 ("Single video duration:
+ * [2, 30] seconds"; "Total duration of reference videos must not exceed 30
+ * seconds") and docs.kie.ai/market/minimax-h3/reference-to-video (reference
+ * videos are "2 to 15 seconds" each and "the total duration of all reference
+ * videos cannot exceed 15 seconds", up to 3 videos) — both fetched 2026-09-02.
+ */
+export const VIDEO_REF_VIDEO_DURATION_LIMITS: Record<string, RefVideoDurationLimit | undefined> = {
+  "seedance-2-5": { minSec: 2, maxSec: 30, maxTotalSec: 30 },
+  // MiniMax Hailuo 3 — the provider states the per-clip bound in its own reject
+  // text: "content[1].video_url: invalid param: video duration 52838 ms,
+  // expected [2000, 15000] ms" (app-reports P4, 2 rows, the same clip retried).
+  // The KIE reference-to-video doc adds the COMBINED cap — the same shape the
+  // audio side already declares in SEEDANCE_2_R2V_MAX_AUDIO_SEC_BY_PROVIDER
+  // above, whose h3 row cites the same page.
+  "minimax-h3": { minSec: 2, maxSec: 15, maxTotalSec: 15 },
+}
+
+/**
+ * Validate probed reference-video durations against the provider's limits.
+ *
+ * Non-finite / non-positive entries are IGNORED, never rejected: the probe
+ * helpers treat an unreadable clip as a worst-case duration for pricing, and
+ * turning a failed ffprobe into a user-facing 400 would block legitimate runs
+ * on a transient probe failure. Callers therefore pass the RAW per-URL probe
+ * outcomes (a rejected ffprobe arrives here as NaN) — an ignored entry also
+ * contributes nothing to the `maxTotalSec` sum, so a probe blip can never push
+ * an otherwise-legal set over the total cap either.
+ */
+export function checkRefVideoDurations(
+  provider: string,
+  durationsSec: readonly number[],
+): { ok: true } | { ok: false; message: string } {
+  const limit = VIDEO_REF_VIDEO_DURATION_LIMITS[provider]
+  if (!limit) return { ok: true }
+
+  const usable = durationsSec.filter((d) => Number.isFinite(d) && d > 0)
+  if (usable.length === 0) return { ok: true }
+
+  const offender = usable.find((d) => d < limit.minSec || d > limit.maxSec)
+  if (offender !== undefined) {
+    return {
+      ok: false,
+      message: `Each reference video must be between ${limit.minSec} and ${limit.maxSec} seconds — one is ${offender.toFixed(1)}s. Trim it (a Trim Video node upstream works) and run again.`,
+    }
+  }
+
+  if (limit.maxTotalSec !== undefined) {
+    const total = usable.reduce((a, b) => a + b, 0)
+    if (total > limit.maxTotalSec) {
+      return {
+        ok: false,
+        message: `Reference videos must not exceed ${limit.maxTotalSec} seconds in total — these add up to ${total.toFixed(1)}s. Remove one or trim them and run again.`,
+      }
+    }
+  }
+
+  return { ok: true }
+}
+
 /**
  * Video models where credit cost depends on resolution AND whether a video
  * reference is connected. Identifier suffix: `:{resolution}[-ref]`.
@@ -2087,8 +2170,8 @@ export interface VideoAudioCapability {
 /**
  * Per-model audio capability. Only models that produce SOME audio are listed;
  * anything absent defaults to `{ mode: "none" }` via `getVideoAudioCapability`,
- * so silent models (minimax, hailuo, wan, grok-i2v, gemini-omni-video, runway,
- * pika, …) need no entry. New audio-capable models MUST be added here — the
+ * so silent models (minimax, hailuo, wan-i2v, grok-i2v, runway, pika, …) need
+ * no entry. New audio-capable models MUST be added here — the
  * `video-audio-capability` guard test cross-checks this map against the model
  * configs' `extraParams.sound` / `generate_audio` + VEO/Seedance-2 sets so a
  * forgotten entry fails CI rather than silently disabling audio.
@@ -2137,10 +2220,39 @@ export const VIDEO_AUDIO_CAPABILITY: Record<string, VideoAudioCapability> = {
   // and skip the lip-sync pass. `defaultOn` mirrors the KIE default so an
   // intent-less request is described honestly; audio is priced into the uniform
   // per-second rate, so NOT cost-affecting (no `:audio` composite).
-  // gemini-omni-flash is deliberately ABSENT — gemini-omni-video is absent too
-  // (mode "none"), and the siblings must not disagree.
   "wan-3": { mode: "ambient", field: "audio", defaultOn: true },
   "wan-3-prime": { mode: "ambient", field: "audio", defaultOn: true },
+  // Gemini Omni (both SKUs — the pro `gemini-omni-video` and the faster
+  // `gemini-omni-flash`; one model at two speeds, so their rows are identical
+  // and a test pins that). Settled 2026-09-03 from Google's own documentation
+  // at https://ai.google.dev/gemini-api/docs/omni, having been unlisted — and
+  // therefore reported as SILENT — while the catalog described both as "native
+  // audio".
+  //
+  // "ambient", and alwaysOn with no toggle field, on three sentences from that
+  // page:
+  //   - "By default the model will try to generate an appropriate audio track
+  //     for a video." Audio on every render, and the KIE input schema
+  //     (prompt / image_urls / first+last_frame_url / audio_ids / video_list /
+  //     character_ids / duration / aspect_ratio / seed / resolution — see
+  //     docs.kie.ai/market/gemini-omni-video and
+  //     docs.kie.ai/market/google/gemini-omni-flash-1-1) carries no on/off
+  //     lever, so there is nothing for applyVideoAudioToggle to write.
+  //   - NOT native_speech: "Multi-turn voice extension: Generating spoken
+  //     dialogue or speech is supported when extending previously generated
+  //     videos via multi-turn (`previous_interaction_id`)" — a field KIE's
+  //     createTask schema does not expose, so the dialogue path is unreachable
+  //     on our transport. Held to the Wan 3.0 bar: no documented dialogue
+  //     guarantee on the path we actually drive ⇒ ambient, and upgrade only on
+  //     a live probe (the kling-3.0 standard). Classifying it native_speech
+  //     would reroute the Story→Video dialogue pipeline past the lip-sync pass.
+  //   - NOT audio_driven either: "Uploading audio references is unsupported in
+  //     the current version of the API", and "any audio in a video reference is
+  //     ignored" — there is no reference-audio transport to be driven by, and
+  //     runGeminiOmni never sends `audio_ids`.
+  // Audio is priced into the per-tier rate, so NOT cost-affecting.
+  "gemini-omni-video": { mode: "ambient", alwaysOn: true },
+  "gemini-omni-flash": { mode: "ambient", alwaysOn: true },
 }
 
 const VIDEO_AUDIO_NONE: VideoAudioCapability = { mode: "none" }

package/src/node-refs.ts

@@ -50,6 +50,10 @@ export function canonicalVarName(label: string): string {
  * SUPPRESS auto-injection of a connected node the author already placed
  * explicitly via `{label}` (so it isn't injected twice). `matchAll` over the
  * global pattern does not mutate its lastIndex, so sharing the constant is safe.
+ *
+ * Deliberately NOT `REF_TOKEN_NAMESPACE_PREFIXES`: widening this changes
+ * run-time auto-injection on BOTH engines (follow-up ticket), not just the
+ * editor.
  */
 export function extractReferencedLabels(
   ...texts: ReadonlyArray<string | undefined | null>
@@ -251,3 +255,81 @@ export function resolveNodeRefs(
   }
   return result
 }
+
+/**
+ * Token namespaces that are NOT node-label references. `{image:1:face}` is the
+ * unified-reference grammar, `{slot:x}` is recast's, `{video:N}`/`{audio:N}`
+ * are reference handles, and `{ref:<id>}` is the id-addressed reference form —
+ * all five are substituted by their own resolvers (`resolveReferenceTokens`,
+ * `resolveRefIdTokens`, the recast slot pass), not by resolveNodeRefs. Before
+ * this list existed, only `image:` was excluded, so `{video:1}` classified as a
+ * MISSING node ref.
+ *
+ * Compared against the LOWERCASED token name: `REFERENCE_TOKEN_RE` is `/gi` and
+ * `REF_ID_TOKEN_RE` spells `[rR][eE][fF]`, so `{Image:1}` / `{Ref:x}` really do
+ * resolve downstream and must never read as a missing node ref.
+ */
+export const REF_TOKEN_NAMESPACE_PREFIXES: readonly string[] = [
+  "image:", "video:", "audio:", "slot:", "ref:",
+]
+
+export type RefTokenKind = "wired" | "reserved" | "missing" | "skip" | "unknown"
+
+/**
+ * Classify a parsed `{...}` token name against the resolvable label set.
+ * `resolvable === null` means the caller has no ref data at all — such tokens
+ * classify `unknown` and must render like wired, so "no data" never
+ * masquerades as "nothing wired".
+ *
+ * Single source of truth for the editor decoration, the missing-refs chip
+ * (frontend/src/lib/prompt-ref-scan.ts delegates here) and the execution
+ * engine's dispatch guard.
+ */
+export function classifyRefToken(
+  name: string,
+  resolvable: ReadonlySet<string> | null,
+): RefTokenKind {
+  const lower = name.toLowerCase()
+  if (name === "" || REF_TOKEN_NAMESPACE_PREFIXES.some((p) => lower.startsWith(p))) return "skip"
+  if (RESERVED_TEMPLATE_VARS.has(name)) return "reserved"
+  if (resolvable === null) return "unknown"
+  return resolvable.has(canonicalVarName(name)) ? "wired" : "missing"
+}
+
+/**
+ * The `{Label}` tokens in `text` that `resolveNodeRefs` would leave LITERAL and
+ * that no upstream node can explain — i.e. exactly what would reach a provider
+ * as the characters `{Label}`. Evidence for why this matters: `{Describe Image}`
+ * ×2 (gpt-image-2) and `{gravity flip}` / `{rewind}` (seedance-2-5) in the
+ * 2026-09-01 app-reports export.
+ *
+ * `resolvable` — labels with a value in the ref map (canonical/lowercase).
+ * `known`      — canonical labels of the nodes the caller considers to EXIST
+ *                (no state requirement; the backend passes every node in the
+ *                run's graph).
+ *
+ * A token whose label is in `known` but not `resolvable` PASSES: the node
+ * exists and simply produced nothing, which is the caller's to substitute (the
+ * backend resolves it to empty text), not this function's to refuse. A token
+ * with an explicit `|| fallback` passes too — the fallback is substituted.
+ * Returns original-cased names, de-duplicated by canonical form, for the
+ * user-facing message.
+ */
+export function unresolvedRefTokens(
+  text: string,
+  opts: { resolvable: ReadonlySet<string>; known: ReadonlySet<string> },
+): string[] {
+  if (typeof text !== "string" || text.length === 0) return []
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const m of text.matchAll(NODE_REF_PATTERN)) {
+    const { name, fallback } = parseNodeRef(m[1] ?? "")
+    if (fallback !== null) continue
+    if (classifyRefToken(name, opts.resolvable) !== "missing") continue
+    const canon = canonicalVarName(name)
+    if (opts.known.has(canon) || seen.has(canon)) continue
+    seen.add(canon)
+    out.push(name)
+  }
+  return out
+}

package/src/node-runtime-keys.ts

@@ -16,6 +16,18 @@ export const EXECUTION_DATA_KEYS: ReadonlySet<string> = new Set([
   "currentJobId",
   "currentJobProgress",
   "errorMessage",
+  // Structured detail alongside errorMessage for a safety-filter block
+  // (see `JobErrorHint` in the app's frontend/src/types/nodes.ts). Same
+  // lifecycle as errorMessage: a RESULT the user expects to survive reload,
+  // never user-edited config.
+  "errorHint",
+  // A job policy registered by the deployment held this node's result for a
+  // human reviewer (`jobs.status = "pending_review"`). Pure run state, like
+  // executionStatus: the node is still "running" and the flag disappears the
+  // moment the review resolves — so it is ALSO in TRANSIENT_RUNTIME_KEYS
+  // below. Without the transient half, a flip into review marks a passive tab
+  // dirty and a preset captures "awaiting review".
+  "jobAwaitingReview",
   "isStreaming",
   "generatedImageUrl",
   "generatedVideoUrl",
@@ -80,6 +92,7 @@ export const TRANSIENT_RUNTIME_KEYS: ReadonlySet<string> = new Set([
   "executionStatus",
   "currentJobId",
   "currentJobProgress",
+  "jobAwaitingReview",
   "isStreaming",
   "subWorkflowProgress",
   "__listTotal",