@nodaro/shared 2.2.1 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "2.2.1",
+  "version": "2.5.0",
   "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__/effective-tier.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from "vitest"
+import {
+  resolveStoredTier,
+  resolveEffectiveTier,
+  isPaygRetentionActive,
+  PAYG_RETENTION_DAYS,
+} from "../effective-tier.js"
+
+const DAY_MS = 24 * 60 * 60 * 1000
+const NOW = new Date("2026-08-12T12:00:00Z")
+const daysAgo = (n: number) => new Date(NOW.getTime() - n * DAY_MS)
+
+describe("resolveStoredTier", () => {
+  it("prefers tier, falls back to subscription_tier, then free", () => {
+    expect(resolveStoredTier({ tier: "pro", subscription_tier: "basic" })).toBe("pro")
+    expect(resolveStoredTier({ tier: null, subscription_tier: "basic" })).toBe("basic")
+    expect(resolveStoredTier({ tier: null, subscription_tier: null })).toBe("free")
+  })
+})
+
+describe("resolveEffectiveTier — the payg derivation matrix (design §9)", () => {
+  it("never-paid free user stays free", () => {
+    expect(
+      resolveEffectiveTier({ tier: "free", subscription_tier: null, lifetime_topup_credits: 0 })
+    ).toBe("free")
+  })
+
+  it("free user with NET lifetime > 0 derives payg — even at zero current balance", () => {
+    expect(
+      resolveEffectiveTier({ tier: "free", subscription_tier: null, lifetime_topup_credits: 3300 })
+    ).toBe("payg")
+  })
+
+  it("refunded-to-zero user drops back to free (NET lifetime)", () => {
+    expect(
+      resolveEffectiveTier({ tier: "free", subscription_tier: null, lifetime_topup_credits: 0 })
+    ).toBe("free")
+  })
+
+  it("#489 pre-subscribe carryover fixture: topup balance without purchase stays free", () => {
+    // Cancel-path carryover moves a pre-subscribe balance into topup_credits
+    // with NO purchase — lifetime stays 0, so the user must NOT derive payg.
+    expect(
+      resolveEffectiveTier({ tier: "free", subscription_tier: null, lifetime_topup_credits: 0 })
+    ).toBe("free")
+  })
+
+  it("every stored paid tier passes through untouched, regardless of lifetime", () => {
+    for (const t of ["basic", "standard", "pro", "business"]) {
+      expect(
+        resolveEffectiveTier({ tier: t, subscription_tier: null, lifetime_topup_credits: 9999 })
+      ).toBe(t)
+    }
+  })
+
+  it("subscription_tier-only legacy rows resolve through the stored fallback", () => {
+    expect(
+      resolveEffectiveTier({ tier: null, subscription_tier: "standard", lifetime_topup_credits: 500 })
+    ).toBe("standard")
+  })
+
+  it("null-tier never-paid rows resolve free; with lifetime they derive payg", () => {
+    expect(
+      resolveEffectiveTier({ tier: null, subscription_tier: null, lifetime_topup_credits: 0 })
+    ).toBe("free")
+    expect(
+      resolveEffectiveTier({ tier: null, subscription_tier: null, lifetime_topup_credits: 100 })
+    ).toBe("payg")
+  })
+})
+
+describe("isPaygRetentionActive — 90-day activity window boundaries", () => {
+  it("exports the 90-day constant", () => {
+    expect(PAYG_RETENTION_DAYS).toBe(90)
+  })
+
+  it("purchase activity: 89d active, 90d active (inclusive), 91d inactive", () => {
+    const base = { lifetimeTopupCredits: 100, lastSpendAt: null }
+    expect(isPaygRetentionActive({ ...base, lastTopupAt: daysAgo(89) }, NOW)).toBe(true)
+    expect(isPaygRetentionActive({ ...base, lastTopupAt: daysAgo(90) }, NOW)).toBe(true)
+    expect(isPaygRetentionActive({ ...base, lastTopupAt: daysAgo(91) }, NOW)).toBe(false)
+  })
+
+  it("spend activity counts on its own (usage_logs MAX, not balance polls)", () => {
+    const base = { lifetimeTopupCredits: 100, lastTopupAt: daysAgo(200) }
+    expect(isPaygRetentionActive({ ...base, lastSpendAt: daysAgo(10) }, NOW)).toBe(true)
+    expect(isPaygRetentionActive({ ...base, lastSpendAt: daysAgo(91) }, NOW)).toBe(false)
+  })
+
+  it("either source alone is sufficient; the most recent wins", () => {
+    expect(
+      isPaygRetentionActive(
+        { lifetimeTopupCredits: 100, lastTopupAt: daysAgo(120), lastSpendAt: daysAgo(5) },
+        NOW
+      )
+    ).toBe(true)
+  })
+
+  it("string timestamps (supabase rows) are accepted", () => {
+    expect(
+      isPaygRetentionActive(
+        { lifetimeTopupCredits: 100, lastTopupAt: daysAgo(5).toISOString(), lastSpendAt: null },
+        NOW
+      )
+    ).toBe(true)
+  })
+
+  it("all-null activity is inactive; never-paid users are never retention-active", () => {
+    expect(
+      isPaygRetentionActive({ lifetimeTopupCredits: 100, lastTopupAt: null, lastSpendAt: null }, NOW)
+    ).toBe(false)
+    expect(
+      isPaygRetentionActive({ lifetimeTopupCredits: 0, lastTopupAt: daysAgo(1), lastSpendAt: null }, NOW)
+    ).toBe(false)
+  })
+})

package/src/__tests__/normalize-model-input.test.ts

@@ -0,0 +1,153 @@
+import { describe, it, expect } from "vitest"
+import {
+  MODEL_CATALOG,
+  normalizeModelInput,
+  validateModelInput,
+  defaultResolutionFor,
+} from "../model-catalog.js"
+
+/**
+ * `normalizeModelInput` is the correcting twin of `validateModelInput`, used at
+ * persistence and execution boundaries where rejecting a fixable value would
+ * abort a run (and take every already-billed sibling node with it).
+ *
+ * The load-bearing invariant is the round-trip: whatever the normalizer emits
+ * MUST satisfy the validator. If those two ever disagree, a "normalized" node
+ * still 400s upstream and the whole exercise is theatre.
+ */
+
+describe("normalizeModelInput", () => {
+  it("leaves an already-valid combination untouched", () => {
+    const out = normalizeModelInput("gpt-image-2", { aspectRatio: "16:9", resolution: "2K" })
+    expect(out.aspectRatio).toBe("16:9")
+    expect(out.resolution).toBe("2K")
+    expect(out.adjustments).toEqual([])
+  })
+
+  it("snaps the aspect ratio that aborted the 2026-08-09 run", () => {
+    // gpt-image (GPT Image 1.5) accepts 1:1 / 3:2 / 2:3 only — KIE rejects 16:9.
+    const out = normalizeModelInput("gpt-image", { aspectRatio: "16:9" })
+    expect(out.aspectRatio).not.toBe("16:9")
+    expect(MODEL_CATALOG["gpt-image"].aspectRatios).toContain(out.aspectRatio!)
+    expect(out.adjustments).toHaveLength(1)
+    expect(out.adjustments[0].field).toBe("aspectRatio")
+    expect(out.adjustments[0].from).toBe("16:9")
+    // The reason is user-facing — it must name the alternatives.
+    expect(out.adjustments[0].reason).toContain("3:2")
+  })
+
+  it("drops a lever the model does not have at all", () => {
+    // Same node also carried resolution "2K"; GPT Image 1.5 has no resolution.
+    const out = normalizeModelInput("gpt-image", { resolution: "2K" })
+    expect(out.resolution).toBeUndefined()
+    expect(out.adjustments[0]).toMatchObject({ field: "resolution", from: "2K", to: undefined })
+  })
+
+  it("canonicalizes an equivalent spelling instead of re-pricing the node", () => {
+    // Flux 2 resolution reaches the payload builder as a bare megapixel count
+    // ("1"); the catalog lists the display form ("1 MP"). Treating that as
+    // invalid would snap it to the 2 MP default — a silent price increase on a
+    // node the user configured correctly.
+    const out = normalizeModelInput("flux-2-pro", { resolution: "1" })
+    expect(out.resolution).toBe("1 MP")
+    expect(out.adjustments).toEqual([])
+    // Case drift is the same class of non-change.
+    expect(normalizeModelInput("nano-banana-pro", { resolution: "4k" }).resolution).toBe("4K")
+    expect(normalizeModelInput("nano-banana-pro", { resolution: "4k" }).adjustments).toEqual([])
+  })
+
+  it("does NOT treat a different unit as equivalent", () => {
+    // "1" must not quietly satisfy a 1K/2K/4K model — those are different scales.
+    const out = normalizeModelInput("nano-banana-pro", { resolution: "1" })
+    expect(out.resolution).not.toBe("1")
+    expect(MODEL_CATALOG["nano-banana-pro"].resolutions).toContain(out.resolution!)
+    expect(out.adjustments).toHaveLength(1)
+  })
+
+  it("prefers the Flux 2 default over the cheapest option when snapping", () => {
+    // options[0] is "0.5 MP" — snapping there would silently downgrade quality.
+    const out = normalizeModelInput("flux-2-pro", { resolution: "2K" })
+    expect(out.resolution).toBe(defaultResolutionFor("flux-2-pro"))
+    expect(out.resolution).toBe("2 MP")
+  })
+
+  it("applies the gpt-image-2 cross-field rules after snapping", () => {
+    expect(normalizeModelInput("gpt-image-2", { aspectRatio: "auto", resolution: "4K" }).resolution).toBe("1K")
+    expect(normalizeModelInput("gpt-image-2", { aspectRatio: "1:1", resolution: "4K" }).resolution).toBe("2K")
+  })
+
+  it("passes unknown model ids through untouched (the Zod enum owns those)", () => {
+    const out = normalizeModelInput("totally-fake-model", { aspectRatio: "21:9" })
+    expect(out.aspectRatio).toBe("21:9")
+    expect(out.adjustments).toEqual([])
+  })
+
+  it("is idempotent — normalizing twice changes nothing the second time", () => {
+    const once = normalizeModelInput("gpt-image", { aspectRatio: "16:9", resolution: "2K" })
+    const twice = normalizeModelInput("gpt-image", {
+      aspectRatio: once.aspectRatio,
+      resolution: once.resolution,
+    })
+    expect(twice.adjustments).toEqual([])
+    expect(twice.aspectRatio).toBe(once.aspectRatio)
+  })
+
+  // -------------------------------------------------------------------------
+  // The invariant. Runs over the WHOLE catalog so a model added later is
+  // covered by default rather than by anyone remembering to extend a list.
+  // -------------------------------------------------------------------------
+  it("INVARIANT: normalized output always satisfies validateModelInput", () => {
+    // Deliberately hostile inputs — a value from some OTHER model's allow-list
+    // is exactly what a provider switch or a non-UI author leaves behind.
+    const hostile = [
+      { aspectRatio: "16:9" },
+      { aspectRatio: "auto" },
+      { aspectRatio: "1:1", resolution: "4K" },
+      { aspectRatio: "21:9", resolution: "2K", quality: "high" },
+      { resolution: "0.5 MP" },
+      { quality: "basic" },
+      { duration: 7 },
+      { aspectRatio: "9:21", resolution: "8K", quality: "TURBO", duration: 999 },
+    ]
+
+    const failures: string[] = []
+    for (const modelId of Object.keys(MODEL_CATALOG)) {
+      for (const input of hostile) {
+        const out = normalizeModelInput(modelId, input)
+        const issue = validateModelInput(modelId, {
+          aspectRatio: out.aspectRatio,
+          resolution: out.resolution,
+          quality: out.quality,
+          duration: out.duration,
+        })
+        if (issue) {
+          failures.push(
+            `${modelId} ← ${JSON.stringify(input)} → ${JSON.stringify({
+              aspectRatio: out.aspectRatio,
+              resolution: out.resolution,
+              quality: out.quality,
+              duration: out.duration,
+            })}: ${issue.message}`,
+          )
+        }
+      }
+    }
+
+    expect(failures, `normalizeModelInput emitted values validateModelInput rejects:\n${failures.join("\n")}`).toEqual([])
+  })
+
+  it("INVARIANT: every adjustment names a real change", () => {
+    for (const modelId of Object.keys(MODEL_CATALOG)) {
+      const out = normalizeModelInput(modelId, {
+        aspectRatio: "21:9",
+        resolution: "8K",
+        quality: "high",
+        duration: 999,
+      })
+      for (const adj of out.adjustments) {
+        expect(adj.from, `${modelId}/${adj.field} reported a no-op adjustment`).not.toEqual(adj.to)
+        expect(adj.reason.length).toBeGreaterThan(0)
+      }
+    }
+  })
+})

package/src/__tests__/normalize-node-params.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from "vitest"
+import { normalizeNodeModelParams, MODEL_PARAM_NODE_TYPES } from "../normalize-node-params.js"
+
+/**
+ * Write-boundary guard for agent/import-authored graphs. The config panel's
+ * provider-aware dropdown and its stale-value snap are React effects — they
+ * only run for a node whose panel or hover strip is mounted, so a node written
+ * straight into workflow JSON never meets either.
+ */
+
+const node = (id: string, type: string, data: Record<string, unknown>) => ({
+  id,
+  type,
+  position: { x: 0, y: 0 },
+  data,
+})
+
+describe("normalizeNodeModelParams", () => {
+  it("heals the exact node that aborted the 2026-08-09 run", () => {
+    const { nodes, adjustments } = normalizeNodeModelParams([
+      node("node_8", "generate-image", { provider: "gpt-image", aspectRatio: "16:9", resolution: "2K" }),
+    ])
+    const d = nodes[0].data as Record<string, unknown>
+    expect(d.aspectRatio).not.toBe("16:9")
+    expect(d.resolution).toBeUndefined() // GPT Image 1.5 has no resolution lever
+    expect(adjustments.map((a) => a.field).sort()).toEqual(["aspectRatio", "resolution"])
+    expect(adjustments[0].nodeId).toBe("node_8")
+    expect(adjustments[0].provider).toBe("gpt-image")
+  })
+
+  it("leaves the sibling nodes that were already valid completely alone", () => {
+    // Same workflow, the five nodes that generated fine — must be untouched,
+    // and returned BY REFERENCE so a delta/CAS save sees no spurious change.
+    const input = [
+      node("a", "generate-image", { provider: "gpt-image-2", aspectRatio: "16:9", resolution: "2K" }),
+      node("b", "generate-image", { provider: "grok", aspectRatio: "16:9" }),
+    ]
+    const { nodes, adjustments } = normalizeNodeModelParams(input)
+    expect(adjustments).toEqual([])
+    expect(nodes[0]).toBe(input[0])
+    expect(nodes[1]).toBe(input[1])
+  })
+
+  it("never mutates the caller's node objects", () => {
+    const input = [node("n1", "generate-image", { provider: "gpt-image", aspectRatio: "16:9" })]
+    const before = JSON.parse(JSON.stringify(input))
+    normalizeNodeModelParams(input)
+    expect(input).toEqual(before)
+  })
+
+  it("ignores node types that carry no catalog-governed params", () => {
+    const input = [
+      node("t1", "text-prompt", { provider: "gpt-image", aspectRatio: "16:9" }),
+      node("v1", "image-to-video", { provider: "veo3", aspectRatio: "21:9" }),
+    ]
+    const { nodes, adjustments } = normalizeNodeModelParams(input)
+    expect(adjustments).toEqual([])
+    expect(nodes).toEqual(input)
+    expect(MODEL_PARAM_NODE_TYPES.has("image-to-video")).toBe(false)
+  })
+
+  it("skips multi-provider nodes rather than guessing an intersection", () => {
+    const input = [
+      node("m1", "generate-image", {
+        providers: ["gpt-image", "gpt-image-2"],
+        provider: "gpt-image",
+        aspectRatio: "16:9",
+      }),
+    ]
+    const { nodes, adjustments } = normalizeNodeModelParams(input)
+    expect(adjustments).toEqual([])
+    expect(nodes[0]).toBe(input[0])
+  })
+
+  it("survives malformed nodes without throwing", () => {
+    const input = [
+      { id: "x", type: "generate-image" },
+      { id: "y", type: "generate-image", data: null },
+      { id: "z", type: "generate-image", data: { provider: 42 } },
+      { type: "generate-image", data: { provider: "gpt-image", aspectRatio: "16:9" } },
+    ] as Array<{ id?: unknown; type?: unknown; data?: unknown }>
+    expect(() => normalizeNodeModelParams(input)).not.toThrow()
+    const { adjustments } = normalizeNodeModelParams(input)
+    // The last entry has no id but IS healable — it reports under a placeholder.
+    expect(adjustments.every((a) => typeof a.nodeId === "string")).toBe(true)
+  })
+
+  it("is idempotent — a second pass reports nothing", () => {
+    const first = normalizeNodeModelParams([
+      node("n1", "generate-image", { provider: "gpt-image", aspectRatio: "16:9", resolution: "2K" }),
+    ])
+    const second = normalizeNodeModelParams(first.nodes)
+    expect(second.adjustments).toEqual([])
+  })
+})

package/src/effective-tier.ts

@@ -0,0 +1,72 @@
+/**
+ * Effective-tier resolution — the payg derivation.
+ *
+ * "payg" is a DERIVED tier, never stored: a user whose stored tier resolves
+ * to "free" but who has NET lifetime top-up credits (granted − refunded,
+ * clamped ≥ 0 by every SQL writer) is treated as "payg" by entitlement
+ * checks. Stored tier stays untouched, so subscription webhooks never learn
+ * about payg and a cancel→free transition re-derives it automatically.
+ *
+ * Lives in @nodaro/shared because the pipeline tier maps already do, and
+ * both backend (credit gates, workers) and read surfaces need one source.
+ *
+ * The profile fields are REQUIRED (non-optional) on purpose: a call site
+ * whose SELECT forgot to fetch `lifetime_topup_credits` becomes a compile
+ * error instead of a silent `?? 0` that quietly deactivates payg — that is
+ * the failure mode this shape exists to prevent.
+ */
+
+/** Stored-tier resolution — mirrors SQL COALESCE(tier, subscription_tier, 'free'). */
+export function resolveStoredTier(p: {
+  tier: string | null
+  subscription_tier: string | null
+}): string {
+  return p.tier ?? p.subscription_tier ?? "free"
+}
+
+/**
+ * Effective tier: stored "free" with NET lifetime top-ups > 0 derives "payg".
+ * Every other stored tier passes through untouched.
+ */
+export function resolveEffectiveTier(p: {
+  tier: string | null
+  subscription_tier: string | null
+  lifetime_topup_credits: number
+}): string {
+  const stored = resolveStoredTier(p)
+  if (stored === "free" && p.lifetime_topup_credits > 0) return "payg"
+  return stored
+}
+
+/** Media-retention activity window for payg users (design 2026-07-05 §4.6). */
+export const PAYG_RETENTION_DAYS = 90
+
+/**
+ * Is this payg user inside their retention-activity window?
+ *
+ * Activity = credit SPEND (callers supply MAX(usage_logs.created_at) — never
+ * `last_daily_reset`, which read-only balance polls bump) OR a top-up
+ * PURCHASE (`last_topup_at`). Within PAYG_RETENTION_DAYS of either → the
+ * nightly reaper leaves their media alone; past it, the standard free-tier
+ * reaper rules apply. A user with no lifetime purchases is never
+ * retention-active (they are not payg).
+ */
+export function isPaygRetentionActive(
+  p: {
+    lifetimeTopupCredits: number
+    lastTopupAt: string | Date | null
+    lastSpendAt: string | Date | null
+  },
+  now: Date
+): boolean {
+  if (p.lifetimeTopupCredits <= 0) return false
+  const cutoff = now.getTime() - PAYG_RETENTION_DAYS * 24 * 60 * 60 * 1000
+  const at = (v: string | Date | null): number | null => {
+    if (v === null) return null
+    const t = v instanceof Date ? v.getTime() : new Date(v).getTime()
+    return Number.isFinite(t) ? t : null
+  }
+  const topup = at(p.lastTopupAt)
+  const spend = at(p.lastSpendAt)
+  return (topup !== null && topup >= cutoff) || (spend !== null && spend >= cutoff)
+}

package/src/index.ts

@@ -540,6 +540,13 @@ export type {
   SharedListing,
 } from "./community.js"
 
+export {
+  resolveStoredTier,
+  resolveEffectiveTier,
+  isPaygRetentionActive,
+  PAYG_RETENTION_DAYS,
+} from "./effective-tier.js"
+
 export {
   NODE_DEFAULT_TYPES,
   validateProviderForNodeType,
@@ -693,6 +700,8 @@ export {
   creditRangesAll,
   modelIdsByKindMode,
   buildModelMenu,
+  normalizeModelInput,
+  defaultResolutionFor,
 } from "./model-catalog.js"
 export type {
   ModelCatalogEntry,
@@ -704,6 +713,8 @@ export type {
   ValidationField,
   LabeledOption,
   ModelMenuOption,
+  ModelInputAdjustment,
+  NormalizedModelInput,
 } from "./model-catalog.js"
 
 export {
@@ -876,6 +887,13 @@ export type { VoiceChangerModel } from "./voice-changer-models.js"
 
 // --- Node presets ---
 export { EXECUTION_DATA_KEYS, TRANSIENT_RUNTIME_KEYS, stripTransientRuntimeData } from "./node-runtime-keys.js"
+
+export {
+  MODEL_PARAM_NODE_TYPES,
+  normalizeNodeModelParams,
+  describeNodeAdjustments,
+} from "./normalize-node-params.js"
+export type { NodeParamAdjustment, NormalizedNodes } from "./normalize-node-params.js"
 export { extractPresetData, PRESET_EXCLUDED_KEYS, PRESET_APPLY_CLEAR_KEYS, presetDataMatches } from "./node-preset-extract.js"
 
 // --- Factory prompt-snippets (reusable inline prompt fragments) ---

package/src/model-catalog.ts

@@ -28,6 +28,8 @@
  *   `docs/choosing-models.md` guide. CI (`gen:skills:check`) fails on drift.
  */
 
+import { isFlux2Model } from "./flux2-pricing.js"
+
 export type ModelKind = "image" | "video" | "audio"
 
 export type ModelMode =
@@ -2385,6 +2387,165 @@ export function validateModelInput(
   return null
 }
 
+/**
+ * The resolution a Flux 2 model should land on when its stored value is absent
+ * or invalid. Flux 2 exposes ascending megapixel options ("0.5 MP"…"4 MP"), so
+ * snapping to `options[0]` would silently downgrade every node to the cheapest
+ * tier; each variant has a sensible mid default instead. Returns undefined for
+ * every non-Flux-2 model (they snap to `options[0]` normally).
+ */
+export function defaultResolutionFor(modelId: string): string | undefined {
+  if (!isFlux2Model(modelId)) return undefined
+  return modelId === "flux-2-klein" ? "1 MP" : "2 MP"
+}
+
+/**
+ * True when two option values denote the same setting written differently.
+ * Handles case/whitespace ("4k" vs "4K") and the megapixel form Flux 2 stores
+ * as a bare count ("1") against the catalog's display form ("1 MP").
+ */
+function sameOptionValue(a: string | number, b: string | number): boolean {
+  if (a === b) return true
+  const norm = (v: string | number) =>
+    String(v).trim().toLowerCase().replace(/\s*mp$/, "").replace(/\s+/g, "")
+  const na = norm(a)
+  const nb = norm(b)
+  if (na === nb) return true
+  // Numeric equivalence so "1" matches "1.0" and " 1 MP".
+  const fa = Number(na)
+  const fb = Number(nb)
+  return Number.isFinite(fa) && Number.isFinite(fb) && fa === fb
+}
+
+/** One correction `normalizeModelInput` made, for disclosure to the user. */
+export interface ModelInputAdjustment {
+  field: "aspectRatio" | "resolution" | "quality" | "duration"
+  /** The value that was asked for. */
+  from: string | number
+  /** What it became — `undefined` means the lever was dropped entirely. */
+  to: string | number | undefined
+  reason: string
+}
+
+export interface NormalizedModelInput {
+  aspectRatio?: string
+  resolution?: string
+  quality?: string
+  duration?: number
+  /** Empty when the input was already valid. */
+  adjustments: ModelInputAdjustment[]
+}
+
+/**
+ * Coerce a model's parameters into a combination the model actually accepts.
+ *
+ * The correcting twin of `validateModelInput`. Validation is right when a
+ * human/agent is composing a single call and can retry (MCP verbs do this).
+ * It is the WRONG answer at a persistence or execution boundary: rejecting
+ * there turns a fixable typo into a failed run — and a failed run takes every
+ * already-generated, already-billed sibling node down with it. Incident
+ * 2026-08-09: one node carrying `gpt-image` + `16:9` (a pair the config panel
+ * cannot produce, written straight into workflow JSON by a non-UI author)
+ * aborted a run whose five other nodes had already produced images.
+ *
+ * Rules, mirroring the config panels' provider-change snap:
+ *  - Model has no such lever → drop the value (sending it 400s upstream).
+ *  - Value outside the model's allow-list → snap to the model's default
+ *    (`defaultResolutionFor`) or the first valid option.
+ *  - Then apply cross-field constraints that only hold for certain models.
+ *
+ * Unknown model ids pass through untouched — the route's Zod model enum is the
+ * right gate for those, exactly as in `validateModelInput`.
+ *
+ * Every correction is reported in `adjustments` so callers can disclose what
+ * changed rather than silently handing back something else.
+ */
+export function normalizeModelInput(
+  modelId: string,
+  input: {
+    aspectRatio?: string
+    resolution?: string
+    quality?: string
+    duration?: number
+  },
+): NormalizedModelInput {
+  const m = MODEL_CATALOG[modelId]
+  const adjustments: ModelInputAdjustment[] = []
+  if (!m) return { ...input, adjustments }
+
+  const out: NormalizedModelInput = { ...input, adjustments }
+
+  const snap = <T extends string | number>(
+    field: ModelInputAdjustment["field"],
+    value: T | undefined,
+    allowed: readonly T[] | undefined,
+    preferred?: T,
+  ): T | undefined => {
+    if (value === undefined) return undefined
+    if (!allowed || allowed.length === 0) {
+      adjustments.push({
+        field,
+        from: value,
+        to: undefined,
+        reason: `${m.label} has no ${field} setting — the value was dropped.`,
+      })
+      return undefined
+    }
+    if (allowed.includes(value)) return value
+    // Same value, different spelling — canonicalize instead of "correcting".
+    // Stored data is not uniform with the catalog's display form: Flux 2 bills
+    // off a bare megapixel count ("1") while the catalog lists "1 MP", and "4k"
+    // appears alongside "4K". Treating those as invalid would snap a perfectly
+    // good value to a DIFFERENT tier — i.e. silently re-price the node — which
+    // is worse than the bug this function exists to fix.
+    const canonical = allowed.find((a) => sameOptionValue(a, value))
+    if (canonical !== undefined) return canonical
+    const next = preferred !== undefined && allowed.includes(preferred) ? preferred : allowed[0]
+    adjustments.push({
+      field,
+      from: value,
+      to: next,
+      reason: `${m.label} does not support ${field} "${value}" — using "${next}" instead. Supported: ${allowed.join(", ")}.`,
+    })
+    return next
+  }
+
+  out.aspectRatio = snap("aspectRatio", input.aspectRatio, m.aspectRatios)
+  out.resolution = snap(
+    "resolution",
+    input.resolution,
+    m.resolutions,
+    defaultResolutionFor(modelId),
+  )
+  out.quality = snap("quality", input.quality, m.qualities)
+  out.duration = snap("duration", input.duration, m.durations)
+
+  // Cross-field constraints — a pair that is individually valid but jointly
+  // rejected upstream. GPT Image 2 (per docs.kie.ai): `auto` requires 1K, and
+  // 1:1 cannot go to 4K. Applied last so it sees the already-snapped values.
+  if (modelId === "gpt-image-2" || modelId === "gpt-image-2-i2i") {
+    if (out.aspectRatio === "auto" && out.resolution !== undefined && out.resolution !== "1K") {
+      adjustments.push({
+        field: "resolution",
+        from: out.resolution,
+        to: "1K",
+        reason: `${m.label} only renders 1K at the "auto" aspect ratio.`,
+      })
+      out.resolution = "1K"
+    } else if (out.aspectRatio === "1:1" && out.resolution === "4K") {
+      adjustments.push({
+        field: "resolution",
+        from: "4K",
+        to: "2K",
+        reason: `${m.label} cannot render 4K at a 1:1 aspect ratio.`,
+      })
+      out.resolution = "2K"
+    }
+  }
+
+  return out
+}
+
 // =============================================================================
 // Frontend picker helpers — return `{value, label}[]` shapes that the
 // existing config-panel components expect, derived from the catalog so we