@nodaro/shared 2.19.0 → 2.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "2.19.0",
+  "version": "2.21.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__/credit-identifiers.test.ts

@@ -1,5 +1,7 @@
 import {
   buildCreditModelIdentifier,
+  resolveImageGenCreditIdentifier,
+  resolveNormalizedImageGen,
   buildVideoCreditModelIdentifier,
   buildMotionCreditModelIdentifier,
 } from "../credit-identifiers.js"
@@ -870,3 +872,134 @@ describe("gemini-omni-flash", () => {
     }
   })
 })
+
+// ---------------------------------------------------------------------------
+// resolveNormalizedImageGen
+// ---------------------------------------------------------------------------
+describe("resolveNormalizedImageGen", () => {
+  it("snaps an off-list aspect ratio and reports it", () => {
+    const out = resolveNormalizedImageGen({
+      provider: "gpt-image-2",
+      aspectRatio: "3:2",
+      resolution: "4K",
+      refCount: 0,
+      swapToI2i: true,
+    })
+    // 3:2 is not in GPT_IMAGE_2_RATIOS -> allowed[0] ("auto"), which then
+    // cascades resolution to 1K via the model's cross-field rule.
+    expect(out.aspectRatio).toBe("auto")
+    expect(out.resolution).toBe("1K")
+    expect(out.identifier).toBe("gpt-image-2")
+    expect(out.adjustments.map((a) => a.field)).toEqual(["aspectRatio", "resolution"])
+  })
+
+  it("prices the SNAPPED resolution — gpt-image-2 auto + 2K reserves the 1K tier", () => {
+    const out = resolveNormalizedImageGen({
+      provider: "gpt-image-2",
+      aspectRatio: "auto",
+      resolution: "2K",
+      refCount: 0,
+      swapToI2i: true,
+    })
+    expect(out.resolution).toBe("1K")
+    expect(out.identifier).toBe("gpt-image-2")
+  })
+
+  it("drops a lever the model does not have, and reports it", () => {
+    const out = resolveNormalizedImageGen({
+      provider: "recraft-upscale",
+      aspectRatio: "16:9",
+      refCount: 0,
+    })
+    expect(out.aspectRatio).toBeUndefined()
+    expect(out.adjustments).toHaveLength(1)
+    expect(out.adjustments[0].field).toBe("aspectRatio")
+    expect(out.adjustments[0].to).toBeUndefined()
+  })
+
+  // grok-i2i deliberately has NO `aspectRatios` on its catalog entry, and that
+  // is the HONEST declaration: KIE's grok-imagine/image-to-image schema accepts
+  // only prompt / image_urls / nsfw_checker — there is no aspect_ratio param
+  // (https://docs.kie.ai/market/grok-imagine/image-to-image.md). That is why
+  // kie/models.ts gives it `extraParams: {}` while its t2i sibling gets
+  // `{ aspect_ratio: "16:9" }`, and why kie/CLAUDE.md lists grok-i2i under
+  // "No aspect ratio control". Declaring the t2i ratios here to "preserve" a
+  // caller's value would put a lie in the catalog and keep forwarding a param
+  // the endpoint ignores; dropping it and disclosing that via `adjustments` is
+  // the correct behaviour. Do not "fix" this by adding GROK_RATIOS.
+  it("drops the aspect ratio when grok auto-swaps to its ratio-less i2i sibling", () => {
+    const out = resolveNormalizedImageGen({
+      provider: "grok",
+      aspectRatio: "16:9",
+      refCount: 1,
+      swapToI2i: true,
+    })
+    expect(out.modelId).toBe("grok-i2i")
+    expect(out.aspectRatio).toBeUndefined()
+    expect(out.adjustments).toHaveLength(1)
+    expect(out.adjustments[0].field).toBe("aspectRatio")
+    expect(out.adjustments[0].from).toBe("16:9")
+    expect(out.adjustments[0].to).toBeUndefined()
+    expect(out.identifier).toBe("grok-i2i")
+  })
+
+  it("snaps against the i2i variant when the T2I provider auto-swaps", () => {
+    const out = resolveNormalizedImageGen({
+      provider: "gpt-image-2",
+      aspectRatio: "3:4",
+      refCount: 2,
+      swapToI2i: true,
+    })
+    expect(out.modelId).toBe("gpt-image-2-i2i")
+    expect(out.aspectRatio).toBe("3:4")
+    expect(out.adjustments).toEqual([])
+  })
+
+  it("coerces non-string levers to undefined (the preHandler runs pre-Zod)", () => {
+    const out = resolveNormalizedImageGen({
+      provider: "gpt-image-2",
+      aspectRatio: 169,
+      resolution: null,
+      quality: {},
+      refCount: 0,
+    })
+    expect(out.aspectRatio).toBeUndefined()
+    expect(out.resolution).toBeUndefined()
+    expect(out.quality).toBeUndefined()
+    expect(out.adjustments).toEqual([])
+    expect(out.identifier).toBe("gpt-image-2")
+  })
+
+  it("passes an unknown model id through untouched", () => {
+    const out = resolveNormalizedImageGen({
+      provider: "not-a-model",
+      aspectRatio: "13:7",
+      resolution: "9K",
+      refCount: 0,
+    })
+    expect(out.aspectRatio).toBe("13:7")
+    expect(out.resolution).toBe("9K")
+    expect(out.adjustments).toEqual([])
+    expect(out.identifier).toBe("not-a-model")
+  })
+})
+
+// Regression pins: identifiers that are correct TODAY must be byte-identical
+// once resolveImageGenCreditIdentifier delegates through the normalizer.
+describe("resolveImageGenCreditIdentifier is unchanged for already-valid input", () => {
+  it.each([
+    [{ provider: "flux-2-max", refCount: 3, swapToI2i: true }, "flux-2-max:1MP:3ref"],
+    [{ provider: "flux-2-max", resolution: "4 MP", refCount: 8, swapToI2i: true }, "flux-2-max:4MP:8ref"],
+    [{ provider: "flux-2-pro", refCount: 0, swapToI2i: true }, "flux-2-pro:1MP:0ref"],
+    [{ provider: "seedream-5-lite", refCount: 1, swapToI2i: true }, "seedream-5-lite-i2i"],
+    [{ provider: "seedream", quality: "high", refCount: 0, swapToI2i: true }, "seedream:high"],
+    [{ provider: "gpt-image", quality: "high", refCount: 0, swapToI2i: true }, "gpt-image:high"],
+    [{ provider: "flux", resolution: "2K", refCount: 0, swapToI2i: true }, "flux:2K"],
+    [{ provider: "nano-banana-pro", resolution: "4K", refCount: 0, swapToI2i: true }, "nano-banana-pro:4K"],
+    [{ provider: "gpt-image-2", resolution: "4K", aspectRatio: "16:9", refCount: 0, swapToI2i: true }, "gpt-image-2:4K"],
+    [{ provider: "ideogram-v3", renderingSpeed: "TURBO", refCount: 0, swapToI2i: true }, "ideogram-v3:TURBO"],
+    [{ provider: undefined, refCount: 0, swapToI2i: true }, "nano-banana"],
+  ] as const)("%o -> %s", (opts, expected) => {
+    expect(resolveImageGenCreditIdentifier({ ...opts } as Parameters<typeof resolveImageGenCreditIdentifier>[0])).toBe(expected)
+  })
+})

package/src/__tests__/image-pricing-catalog-coverage.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect } from "vitest"
+import {
+  MODEL_CATALOG,
+  normalizeModelInput,
+} from "../model-catalog.js"
+import {
+  HIGH_QUALITY_PROVIDERS,
+  IMAGE_ASPECT_RATIO_VALUES,
+  TWO_K_RESOLUTION_PROVIDERS,
+  RESOLUTION_2K_4K_TIERED_PROVIDERS,
+} from "../model-constants.js"
+import { FLUX2_RES_MP, isFlux2Model } from "../flux2-pricing.js"
+
+/**
+ * `resolveNormalizedImageGen` prices the credit identifier off the SNAPPED
+ * lever values (see credit-identifiers.ts). That is only safe while every
+ * value a pricing set keys on is also DECLARED on that model's catalog entry:
+ * a priced value the catalog omits would be snapped away or rewritten, and the
+ * reserve would silently move to a different tier.
+ *
+ * A model that is priced on a lever but ABSENT from MODEL_CATALOG is fine —
+ * `normalizeModelInput` passes unknown ids through untouched.
+ */
+describe("composite image pricing ⊆ catalog-declared levers", () => {
+  it("every HIGH_QUALITY_PROVIDERS member in the catalog declares quality \"high\"", () => {
+    let checked = 0
+    for (const id of HIGH_QUALITY_PROVIDERS) {
+      const entry = MODEL_CATALOG[id]
+      if (!entry) continue
+      checked++
+      expect(entry.qualities, `${id}.qualities`).toBeDefined()
+      expect(entry.qualities, `${id}.qualities`).toContain("high")
+    }
+    expect(checked).toBeGreaterThan(0)
+  })
+
+  it("every TWO_K_RESOLUTION_PROVIDERS member in the catalog declares \"2K\"", () => {
+    let checked = 0
+    for (const id of TWO_K_RESOLUTION_PROVIDERS) {
+      const entry = MODEL_CATALOG[id]
+      if (!entry) continue
+      checked++
+      expect(entry.resolutions, `${id}.resolutions`).toContain("2K")
+    }
+    expect(checked).toBeGreaterThan(0)
+  })
+
+  it("every RESOLUTION_2K_4K_TIERED_PROVIDERS member in the catalog declares \"2K\" and \"4K\"", () => {
+    let checked = 0
+    for (const id of RESOLUTION_2K_4K_TIERED_PROVIDERS) {
+      const entry = MODEL_CATALOG[id]
+      if (!entry) continue
+      checked++
+      expect(entry.resolutions, `${id}.resolutions`).toContain("2K")
+      expect(entry.resolutions, `${id}.resolutions`).toContain("4K")
+    }
+    expect(checked).toBeGreaterThan(0)
+  })
+
+  it("nano-banana-pro declares \"4K\" (its own pricing branch)", () => {
+    expect(MODEL_CATALOG["nano-banana-pro"]?.resolutions).toContain("4K")
+  })
+
+  // Flux 2 stores a BARE megapixel count ("1") while the catalog lists "1 MP".
+  // normalizeModelInput canonicalizes rather than "corrects" that spelling —
+  // if it ever stopped doing so, every Flux 2 node priced from stored data
+  // would jump to defaultResolutionFor()'s tier.
+  it("Flux 2 bare-MP values canonicalize to the catalog spelling, not a different tier", () => {
+    let checked = 0
+    for (const id of Object.keys(MODEL_CATALOG)) {
+      if (!isFlux2Model(id)) continue
+      checked++
+      for (const mp of FLUX2_RES_MP) {
+        const out = normalizeModelInput(id, { resolution: mp })
+        expect(out.resolution, `${id} + "${mp}"`).toBe(`${mp} MP`)
+        expect(out.adjustments, `${id} + "${mp}" must not report a correction`).toEqual([])
+      }
+    }
+    expect(checked).toBeGreaterThan(0)
+  })
+
+  // Declared values are always identity under the snap. Cheap, and it fails
+  // loudly if someone adds a duplicate/typo'd entry to a lever list.
+  it("every declared image lever value normalizes to itself", () => {
+    for (const [id, entry] of Object.entries(MODEL_CATALOG)) {
+      if (entry.kind !== "image") continue
+      for (const a of entry.aspectRatios ?? []) {
+        expect(normalizeModelInput(id, { aspectRatio: a }).aspectRatio, `${id} ratio ${a}`).toBe(a)
+      }
+      for (const r of entry.resolutions ?? []) {
+        expect(normalizeModelInput(id, { resolution: r }).resolution, `${id} res ${r}`).toBe(r)
+      }
+      for (const q of entry.qualities ?? []) {
+        expect(normalizeModelInput(id, { quality: q }).quality, `${id} quality ${q}`).toBe(q)
+      }
+    }
+  })
+})
+
+/**
+ * `IMAGE_ASPECT_RATIO_VALUES` is the ONE ratio vocabulary the three image
+ * routes' Zod enums are built from (`/v1/generate-image`, `/v1/image-to-image`,
+ * `/v1/edit-image`). Two invariants make that safe, and both are asserted here
+ * rather than left to review:
+ *
+ *  1. It must be a SUPERSET of every ratio any image model declares. A catalog
+ *     ratio the tuple omits is a live 400 on a value the picker offers — the
+ *     exact bug that shipped twice (Wan 2.7's `8:1`/`1:8`, then Nano Banana 2
+ *     Lite's `4:1`/`1:4`). It also makes `applySnappedLevers`' "enum can't carry
+ *     the snapped value" fallback unreachable: the snap can only ever return a
+ *     value the caller sent, its canonical spelling, or a catalog-declared
+ *     option — all three are in the tuple by this test.
+ *  2. No duplicates. `z.enum` de-dupes silently, so a copy-paste repeat would
+ *     never surface at runtime.
+ *
+ * Widening the tuple is always safe: the per-model gate is the catalog snap,
+ * which CORRECTS an unsupported ratio (and discloses it) instead of rejecting.
+ */
+describe("IMAGE_ASPECT_RATIO_VALUES covers every catalog-declared image ratio", () => {
+  it("is a superset of every `kind: \"image\"` entry's aspectRatios", () => {
+    const allowed = new Set<string>(IMAGE_ASPECT_RATIO_VALUES)
+    const missing: string[] = []
+    let checked = 0
+    for (const [id, entry] of Object.entries(MODEL_CATALOG)) {
+      if (entry.kind !== "image") continue
+      for (const r of entry.aspectRatios ?? []) {
+        checked++
+        if (!allowed.has(r)) missing.push(`${id} declares "${r}"`)
+      }
+    }
+    expect(missing).toEqual([])
+    // Guard the guard: an empty catalog sweep would make this vacuous.
+    expect(checked).toBeGreaterThan(100)
+  })
+
+  it("has no duplicate entries (z.enum would swallow them)", () => {
+    expect(new Set<string>(IMAGE_ASPECT_RATIO_VALUES).size).toBe(IMAGE_ASPECT_RATIO_VALUES.length)
+  })
+})

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

@@ -59,6 +59,42 @@ describe("normalizeNodeModelParams", () => {
     expect(MODEL_PARAM_NODE_TYPES.has("image-to-video")).toBe(false)
   })
 
+  // The write boundary has to cover every image node an agent can author, not
+  // just the two that shipped first: `modify-image` carries the same
+  // provider/aspectRatio/resolution/quality trio, and `edit-image` carries
+  // provider + aspectRatio (its `targetResolution` is an upscale target, a
+  // DIFFERENT field the normalizer never reads, so there is no conflation).
+  it("covers every image node type whose data carries catalog-governed params", () => {
+    expect([...MODEL_PARAM_NODE_TYPES].sort()).toEqual([
+      "edit-image",
+      "generate-image",
+      "image-to-image",
+      "modify-image",
+    ])
+  })
+
+  it("heals a modify-image node written straight into workflow JSON", () => {
+    const { nodes, adjustments } = normalizeNodeModelParams([
+      node("m9", "modify-image", { provider: "gpt-image", aspectRatio: "16:9", quality: "basic" }),
+    ])
+    const d = nodes[0].data as Record<string, unknown>
+    expect(d.aspectRatio).not.toBe("16:9")
+    expect(d.quality).toBe("medium") // gpt-image declares ["medium", "high"]
+    expect(adjustments.map((a) => a.field).sort()).toEqual(["aspectRatio", "quality"])
+    expect(adjustments[0].nodeId).toBe("m9")
+  })
+
+  it("heals an edit-image node's ratio without touching its targetResolution", () => {
+    const { nodes, adjustments } = normalizeNodeModelParams([
+      node("e1", "edit-image", { provider: "recraft-upscale", aspectRatio: "16:9", targetResolution: "4K" }),
+    ])
+    const d = nodes[0].data as Record<string, unknown>
+    // The upscalers declare no aspectRatios at all -> the lever is dropped.
+    expect(d.aspectRatio).toBeUndefined()
+    expect(d.targetResolution).toBe("4K")
+    expect(adjustments.map((a) => a.field)).toEqual(["aspectRatio"])
+  })
+
   it("skips multi-provider nodes rather than guessing an intersection", () => {
     const input = [
       node("m1", "generate-image", {

package/src/__tests__/organizations-types.test.ts

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs"
 import { describe, expect, it } from "vitest"
 import {
   ACCESS_LEVELS,
@@ -9,13 +10,14 @@ import {
   OrgSettingsSchema,
   PRESET_SETTING_KEYS,
   PresetSettingsSchema,
+  USAGE_GROUP_BYS,
   WORKSPACE_ROLES,
   WorkspaceSettingsSchema,
 } from "../organizations/index.js"
 
 describe("organizations wire contract — enums", () => {
   it("every enum is non-empty and duplicate-free", () => {
-    for (const list of [ORG_KINDS, ORG_ROLES, WORKSPACE_ROLES, MEMBER_STATUSES, COLLABORATOR_ROLES, ACCESS_LEVELS, ORG_ERROR_CODES]) {
+    for (const list of [ORG_KINDS, ORG_ROLES, WORKSPACE_ROLES, MEMBER_STATUSES, COLLABORATOR_ROLES, ACCESS_LEVELS, ORG_ERROR_CODES, USAGE_GROUP_BYS]) {
       expect(list.length).toBeGreaterThan(0)
       expect(new Set(list).size).toBe(list.length)
     }
@@ -24,6 +26,32 @@ describe("organizations wire contract — enums", () => {
   it("error codes are snake_case identifiers", () => {
     for (const code of ORG_ERROR_CODES) expect(code).toMatch(/^[a-z][a-z_]*[a-z]$/)
   })
+
+  it("USAGE_GROUP_BYS is exactly the report groupings plus none", () => {
+    expect([...USAGE_GROUP_BYS]).toEqual(["workspace", "member", "model", "day", "none"])
+  })
+
+  it("ORG_ERROR_CODES carries the P15 CSV write-ahead-audit code", () => {
+    expect(ORG_ERROR_CODES).toContain("audit_unavailable")
+  })
+})
+
+describe("usage wire types carry no cost/economics field (pricing-leak class)", () => {
+  it("no UsageReport* / UsageLogEntry field name is cost-shaped", () => {
+    const src = readFileSync(new URL("../organizations/views.ts", import.meta.url), "utf8")
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/\/\/[^\n]*/g, "")
+    const start = src.indexOf("export interface UsageReportRow")
+    const end = src.indexOf("export interface UsageQuery")
+    expect(start).toBeGreaterThan(-1)
+    expect(end).toBeGreaterThan(start)
+    const usageTypes = src.slice(start, end)
+    // "markup" is deliberately NOT in this set: the creator-set app markup is a
+    // product term (the `app_markup` variance kind, `appMarkupAbsorbedCredits`),
+    // not platform economics — same carve-out as check-pricing-leaks'
+    // BARE_MARKUP_IS_PRODUCT_TERM. What must never appear is a $ / rate field.
+    expect(usageTypes).not.toMatch(/(cost|usd|margin|price|dollar)/i)
+  })
 })
 
 describe("organizations wire contract — settings request schemas", () => {

package/src/__tests__/prompt-length-limits.test.ts

@@ -6,6 +6,9 @@ import {
   NEGATIVE_PROMPT_MAX,
   TTS_TEXT_MAX,
   SUNO_TITLE_MAX,
+  SUNO_HARD_CEILING,
+  SUNO_TEXT_MAX,
+  SUNO_MODELS,
   MAX_IMAGE_PROMPT_CHARS_BY_PROVIDER,
   MAX_VIDEO_PROMPT_CHARS_BY_PROVIDER,
   MAX_NEGATIVE_PROMPT_CHARS_BY_PROVIDER,
@@ -123,6 +126,39 @@ describe("per-model prompt length limits", () => {
       expect(getMaxSunoStyleChars("V5")).toBe(1000)
       expect(SUNO_TITLE_MAX).toBe(80)
     })
+    it("SUNO_HARD_CEILING is a generous route ceiling that can never reject a valid prompt", () => {
+      // The routes accept up to the ceiling and CLAMP to the per-version cap;
+      // a ceiling below any real cap would hard-reject before the clamp ran.
+      // The list is SUNO_MODELS plus `undefined` (schemas without a `model`
+      // field, e.g. replace-section). `V3_5` is NOT a route-accepted model —
+      // getMaxSunoPromptChars still names it, but do not add it here.
+      const versions = [...SUNO_MODELS, undefined]
+      for (const v of versions) {
+        for (const custom of [true, false]) {
+          expect(getMaxSunoPromptChars(v, custom)).toBeLessThanOrEqual(SUNO_HARD_CEILING)
+        }
+        expect(getMaxSunoStyleChars(v)).toBeLessThanOrEqual(SUNO_HARD_CEILING)
+      }
+      expect(SUNO_TEXT_MAX).toBeLessThanOrEqual(SUNO_HARD_CEILING)
+      expect(SUNO_HARD_CEILING).toBe(30000)
+    })
+    it("SUNO_TEXT_MAX pins the max prompt cap across every version × custom-mode combo and is >= every style cap", () => {
+      // SUNO_TEXT_MAX is the shared editor-side ceiling (maxLength / warn
+      // counter) for prompt-shaped Suno fields. Derive the expected value
+      // from the real version list so a future Suno version raising its
+      // custom-mode cap above today's 5000 fails this test instead of
+      // silently under-capping the editor.
+      let maxPromptCap = 0
+      for (const v of SUNO_MODELS) {
+        for (const custom of [true, false]) {
+          maxPromptCap = Math.max(maxPromptCap, getMaxSunoPromptChars(v, custom))
+        }
+      }
+      expect(SUNO_TEXT_MAX).toBe(maxPromptCap)
+      for (const v of SUNO_MODELS) {
+        expect(SUNO_TEXT_MAX).toBeGreaterThanOrEqual(getMaxSunoStyleChars(v))
+      }
+    })
   })
 
   describe("drift guards (registry hygiene)", () => {

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

@@ -0,0 +1,47 @@
+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")
+    }
+  })
+})

package/src/__tests__/suno-credit-type.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from "vitest"
+import {
+  sunoCreditType,
+  SUNO_VERSION_PRICED_OPERATIONS,
+  SUNO_SELECT_OPERATIONS,
+  SUNO_MODELS,
+} from "../index.js"
+
+describe("sunoCreditType — the ONE implementation of the Suno route pricing contract", () => {
+  it("prices generate/cover/extend by model version", () => {
+    expect(sunoCreditType("V5_5", "suno-generate")).toBe("suno-v5_5")
+    expect(sunoCreditType("V5", "suno-cover")).toBe("suno-v5")
+    expect(sunoCreditType("V5_5", "suno-extend")).toBe("suno-v5_5")
+  })
+
+  it("falls back to the operation key for versions with no dedicated price", () => {
+    expect(sunoCreditType("V4", "suno-generate")).toBe("suno-generate")
+    expect(sunoCreditType("V4_5ALL", "suno-cover")).toBe("suno-cover")
+    expect(sunoCreditType(undefined, "suno-extend")).toBe("suno-extend")
+  })
+
+  // The reason this function is gated rather than a bare version map: these four
+  // routes charge a FLAT per-operation key no matter which version the node
+  // carries (routes/suno.ts:648, :852, :907, :1016). A quote of "suno-v5_5" for
+  // one of them is a key the route never charges.
+  it.each([
+    "suno-mashup",
+    "suno-add-instrumental",
+    "suno-add-vocals",
+    "suno-upload-extend",
+  ])("keeps the flat operation key for %s regardless of version", (operation) => {
+    for (const model of SUNO_MODELS) {
+      expect(sunoCreditType(model, operation)).toBe(operation)
+    }
+    expect(sunoCreditType(undefined, operation)).toBe(operation)
+  })
+
+  it("returns an unknown operation unchanged (never invents a key)", () => {
+    expect(sunoCreditType("V5", "suno-voice")).toBe("suno-voice")
+    expect(sunoCreditType("V5_5", "not-a-suno-op")).toBe("not-a-suno-op")
+  })
+
+  it("exports exactly the three version-priced operations", () => {
+    expect([...SUNO_VERSION_PRICED_OPERATIONS]).toEqual([
+      "suno-generate",
+      "suno-cover",
+      "suno-extend",
+    ])
+  })
+
+  it("exports exactly the seven select operations", () => {
+    expect(SUNO_SELECT_OPERATIONS.length).toBe(7)
+  })
+})

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)
+        })
+      }
+    }
+  })
+})