@nodaro/shared 2.20.0 → 2.21.1

package/src/safety-retry-policy.ts

@@ -0,0 +1,37 @@
+import { getModel } from "./model-catalog.js"
+
+/**
+ * Retry/fallback behavior derived from a catalog entry's `safetyFilter`
+ * flag (see `ModelCatalogEntry.safetyFilter` in `model-catalog.ts`).
+ */
+export interface SafetyRetryPolicy {
+  /** 2 when the model declares `safetyFilter.stochastic`, else 1. */
+  maxAttempts: 1 | 2
+  /**
+   * Catalog model id to offer when the retry also blocks. Only present
+   * when the entry declares one AND it resolves to a real catalog entry.
+   */
+  fallback?: string
+}
+
+/**
+ * The provider's safety filter is known to be non-deterministic on some
+ * catalog models — a benign prompt can trip it once and pass on an
+ * identical retry. For those models the platform retries a blocked
+ * request once (`maxAttempts: 2`) before giving up; `fallback` names the
+ * catalog model to offer the user when the retry also blocks.
+ *
+ * Every model not flagged this way — including an unrecognized id —
+ * gets a single attempt and no fallback.
+ */
+export function safetyRetryPolicy(modelId: string): SafetyRetryPolicy {
+  const entry = getModel(modelId)
+  const safetyFilter = entry?.safetyFilter
+  if (!safetyFilter?.stochastic) return { maxAttempts: 1 }
+
+  const fallback = safetyFilter.fallback
+  if (fallback && getModel(fallback)) {
+    return { maxAttempts: 2, fallback }
+  }
+  return { maxAttempts: 2 }
+}

package/src/topaz-upscale.ts

@@ -0,0 +1,163 @@
+/**
+ * Topaz image upscale — the single authority for "which lever did the user
+ * pull, what do we send, and what do we charge".
+ *
+ * KIE's `topaz/image-upscale` takes exactly ONE quality lever:
+ *   upscale_factor: "1" | "2" | "4"   (default "2")
+ * There is no target-resolution parameter (docs.kie.ai/market/topaz/image-upscale,
+ * verified 2026-09-02). The editor nevertheless shipped TWO controls — an
+ * `upscaleFactor` select AND a `targetResolution` select (2K/4K/8K) — and billed
+ * on the second one, which never reached the worker. Everyone who bought 4K or
+ * 8K got a 2x render at 2x/4x the price (app-reports triage 2026-09-01 §4.3).
+ *
+ * So: the FACTOR is the lever. `targetResolution` survives only as a legacy
+ * input (stored node data, old API/MCP callers) and is mapped forward here.
+ * The credit tier is derived from the SAME resolution, which is why callers
+ * must pass `creditTier` into `buildCreditModelIdentifier` rather than the raw
+ * request value — that is what makes CHECK = DEBIT = SENT.
+ *
+ * The composite `topaz-image-upscale:4K` is retained as the id of the 4x tier
+ * (migration 288 wrote that row; renaming it would need a pricing migration for
+ * zero user-visible gain). Read it as "the top Topaz tier", not as a promise of
+ * 4096 pixels. `topaz-image-upscale:8K` stays priced in STATIC_CREDIT_COSTS so
+ * historical usage_logs still resolve, but nothing can reserve it any more.
+ *
+ * Resolution order (fix round 1, 2026-09-02 review):
+ *   1. Resolve the WINNING factor first — a valid `upscaleFactor` always wins;
+ *      an invalid one falls through to `targetResolution` exactly as if it had
+ *      never been sent, rather than freezing the default before the legacy
+ *      tier gets a chance to raise it (an invalid factor + a stored 4K/8K tier
+ *      must still resolve — and bill — at the tier's factor, not the default).
+ *   2. Only THEN build `adjustments`, so every `to` reflects the resolved
+ *      factor rather than an intermediate guess, and every `from` is the raw,
+ *      untransformed input string (never the trimmed/uppercased copy used
+ *      internally to match).
+ *   3. A valid `upscaleFactor` alongside a `targetResolution` it disagrees
+ *      with emits an informational (not corrective) adjustment — the stored
+ *      legacy choice is being overridden, not silently dropped — with
+ *      `to: undefined` because nothing was actually sent for that field.
+ *      Agreement (they resolve to the same factor) is reported as nothing:
+ *      there is no override to disclose.
+ */
+
+export type TopazUpscaleFactor = "1" | "2" | "4"
+
+export const TOPAZ_UPSCALE_FACTORS: readonly TopazUpscaleFactor[] = ["1", "2", "4"]
+
+/** KIE's own default when `upscale_factor` is omitted (providers/kie/models.ts). */
+export const TOPAZ_DEFAULT_UPSCALE_FACTOR: TopazUpscaleFactor = "2"
+
+export interface TopazUpscaleAdjustment {
+  field: "upscaleFactor" | "targetResolution"
+  /** The raw, untransformed value as received — never trimmed or case-normalized. */
+  from: string
+  /**
+   * The resolved factor this adjustment corresponds to, or `undefined` for the
+   * informational "your stored targetResolution was overridden" notice, which
+   * names nothing to switch TO — `upscaleFactor` already won.
+   */
+  to: string | undefined
+  reason: string
+}
+
+export interface TopazUpscaleResolution {
+  /** Sent to KIE as `upscale_factor`. Always set — never rely on the model default. */
+  upscaleFactor: TopazUpscaleFactor
+  /**
+   * Passed VERBATIM as `buildCreditModelIdentifier`'s `targetResolution` arg.
+   * `undefined` = the bare id (1x / 2x); `"4K"` = the 4x tier.
+   */
+  creditTier: "4K" | undefined
+  /** Non-empty when a legacy or out-of-enum value was coerced or overridden. */
+  adjustments: TopazUpscaleAdjustment[]
+}
+
+/** Legacy 2K/4K/8K tier → the factor the provider can actually deliver. */
+const LEGACY_TIER_TO_FACTOR: Record<string, TopazUpscaleFactor> = {
+  "2K": "2",
+  "4K": "4",
+  "8K": "4",
+}
+
+function isFactor(v: string): v is TopazUpscaleFactor {
+  return (TOPAZ_UPSCALE_FACTORS as readonly string[]).includes(v)
+}
+
+export function resolveTopazUpscale(input: {
+  upscaleFactor?: string | null
+  targetResolution?: string | null
+}): TopazUpscaleResolution {
+  const adjustments: TopazUpscaleAdjustment[] = []
+
+  // Raw, untransformed inputs — these are what every adjustment's `from` reports.
+  const rawFactor = typeof input.upscaleFactor === "string" ? input.upscaleFactor : ""
+  const rawTier = typeof input.targetResolution === "string" ? input.targetResolution : ""
+
+  // Trimmed/normalized copies used ONLY for matching, never for display.
+  const trimmedFactor = rawFactor.trim()
+  const normalizedTier = rawTier.trim().toUpperCase()
+
+  const factorGiven = trimmedFactor.length > 0
+  const factorValid = factorGiven && isFactor(trimmedFactor)
+
+  const tierGiven = normalizedTier.length > 0
+  const tierMappedFactor = tierGiven ? LEGACY_TIER_TO_FACTOR[normalizedTier] : undefined
+
+  // --- 1. Resolve the winning factor FIRST. ---
+  // A valid factor always wins. An invalid (or absent) one falls through to
+  // whatever the legacy tier maps to; only if that also comes up empty do we
+  // land on the provider default.
+  const finalFactor: TopazUpscaleFactor = factorValid
+    ? (trimmedFactor as TopazUpscaleFactor)
+    : (tierMappedFactor ?? TOPAZ_DEFAULT_UPSCALE_FACTOR)
+
+  // --- 2. Emit adjustments LAST, against the already-resolved factor. ---
+  if (factorGiven && !factorValid) {
+    adjustments.push({
+      field: "upscaleFactor",
+      from: rawFactor,
+      to: finalFactor,
+      reason: `Topaz upscale accepts a factor of 1, 2 or 4 — "${rawFactor}" was replaced with ${finalFactor}.`,
+    })
+  }
+
+  if (factorValid && tierGiven) {
+    // The factor won outright. Say so if it disagrees with the stored legacy
+    // tier — otherwise the tier silently vanishes with no record. Agreement
+    // needs no note: nothing was overridden.
+    if (tierMappedFactor !== finalFactor) {
+      adjustments.push({
+        field: "targetResolution",
+        from: rawTier,
+        to: undefined,
+        reason: "upscaleFactor takes precedence over the legacy targetResolution.",
+      })
+    }
+  } else if (!factorValid && tierGiven) {
+    // No valid explicit factor — the legacy tier is the (partial) source of
+    // the resolved factor, or was consulted and found unusable.
+    if (tierMappedFactor) {
+      if (normalizedTier === "8K") {
+        adjustments.push({
+          field: "targetResolution",
+          from: rawTier,
+          to: finalFactor,
+          reason: "Topaz upscale offers factors up to 4x — an 8K target renders and bills at the 4x tier.",
+        })
+      }
+    } else {
+      adjustments.push({
+        field: "targetResolution",
+        from: rawTier,
+        to: finalFactor,
+        reason: `Unknown Topaz target "${rawTier}" — rendering at ${finalFactor}x.`,
+      })
+    }
+  }
+
+  return {
+    upscaleFactor: finalFactor,
+    creditTier: finalFactor === "4" ? "4K" : undefined,
+    adjustments,
+  }
+}

package/src/video-analysis.ts

@@ -175,6 +175,26 @@ export const clipLookSchema = z.object({
    * insert) states the deviation in that scene's `visual`, as with `lighting`.
    */
   style: z.string().optional(),
+  /**
+   * The Style picker CATALOG ID the prose in `style` corresponds to — the
+   * analyzer's PICK ("pixar-3d" beside "3D stylized animation"), not a second
+   * description of it.
+   *
+   * Worth strictly more than the prose it accompanies: an id addresses the
+   * catalog, so a recreation renders the same medium the product's own Style
+   * picker would render, instead of re-interpreting a sentence. Absent when the
+   * analyzer read a medium it could not place in the catalog — `style` then
+   * carries the whole answer, as it always did.
+   *
+   * A free `string` here on purpose. The PRODUCER validates it against the
+   * catalog (the analyzer plugin's wire schema is an enum generated from
+   * `STYLES`, so an invented id never leaves it), while this package must not
+   * carry the catalog itself. A closed enum here would only add a second copy
+   * of the vocabulary to drift out of date — and, worse, would REJECT a
+   * catalog entry newer than the installed `@nodaro/shared`, which is exactly
+   * the analysis a consumer most wants to read.
+   */
+  styleId: z.string().optional(),
   /** Colour grade / palette — "muted teal-and-orange, crushed blacks". */
   grade: z.string().optional(),
   /** Camera or film FORMAT and stock — "anamorphic digital", "16mm film grain". */
@@ -265,14 +285,32 @@ export const entitySlotSchema = z.object({
 })
 export type EntitySlot = z.infer<typeof entitySlotSchema>
 
+/**
+ * The sound LAYER vocabulary — what kind of thing this layer is.
+ *
+ * `ambience` is deliberately its own member rather than a flavour of `sfx`:
+ * they are different layers of a real mix and they are recreated by different
+ * means — ambience is the continuous bed a scene sits in (room tone, distant
+ * traffic, wind), an sfx is a discrete hit (a door slam, a gunshot). Folded
+ * together, a scene's bed and its one-off noises arrive indistinguishable and
+ * anything recreating the mix has to guess which it was told.
+ *
+ * Exported so a consumer keying its own document by these modes imports the
+ * vocabulary instead of restating it — the same reason every other closed
+ * vocabulary in this file is a const.
+ */
+export const VIDEO_ANALYSIS_AUDIO_MODES = ["speech", "music", "sfx", "ambience"] as const
+export type VideoAnalysisAudioMode = (typeof VIDEO_ANALYSIS_AUDIO_MODES)[number]
+
 /**
  * One concurrent sound layer in a scene. Real footage stacks sound (music bed
- * under dialogue over ambient sfx), so a scene carries an ARRAY of these — an
- * empty array means genuine silence. `content`: speech = verbatim words;
- * music/sfx = gen-ready description. `voice` is speech-only voice-casting.
+ * under dialogue over ambient room tone), so a scene carries an ARRAY of these
+ * — an empty array means genuine silence. `content`: speech = verbatim words;
+ * music/sfx/ambience = gen-ready description. `voice` is speech-only
+ * voice-casting.
  */
 const audioLayerSchema = z.object({
-  mode: z.enum(["speech", "music", "sfx"]),
+  mode: z.enum(VIDEO_ANALYSIS_AUDIO_MODES),
   content: z.string().min(1),
   voice: z.string().optional(),
   /**
@@ -296,6 +334,33 @@ const audioLayerSchema = z.object({
    * defect that `stripOrphanSlots` exists to kill.
    */
   speakerSlot: z.string().optional(),
+  /**
+   * SPEECH ONLY — WHO says these words, by NAME.
+   *
+   * The second of two ways to name a speaker, and the one for documents that
+   * have no slots: `speakerSlot` addresses an `EntitySlot` of THIS analysis by
+   * id, while `speaker` is the plain cast name a production keys its own cast
+   * by ("Jack Mercer"). A layer may legitimately carry both — the id for the
+   * analysis it came from, the name for the document it is going into — and a
+   * consumer that understands only one reads the one it understands.
+   *
+   * Optional, and not refined against `mode`, for the same reason
+   * `speakerSlot` is not: the window schema is the enforced decode grammar and
+   * must not throw away a whole roll over one mis-tagged field.
+   *
+   * NOT swept by `dropUnknownSpeakers`. That function is the SLOT channel's
+   * sanitizer — it judges an id against the surviving slot list, and a name has
+   * no id space to be unknown in. The asymmetry is deliberate and pinned by
+   * test; whoever owns the name's vocabulary sanitizes the name.
+   *
+   * The residual that leaves: a layer can keep a `speaker` naming someone
+   * `stripOrphanSlots` already pruned as a phantom, where the same claim spelled
+   * `speakerSlot` would have been dropped — the invented-narrator defect, in the
+   * one spelling the sweep cannot see. LATENT today, since nothing in this
+   * repo emits `speaker`; the day the analyzer does, that sweep is what has to
+   * grow, not this field.
+   */
+  speaker: z.string().optional(),
 })
 export type AudioLayer = z.infer<typeof audioLayerSchema>
 
@@ -502,7 +567,7 @@ export function rewriteSpeakerSlots(audio: AudioLayer[], slotRenames: Record<str
  * Strip attribution that no scene can honour — the `dropUnknownBindings` mirror
  * for the `audio` channel. Two cases, both model sloppiness rather than errors
  * worth failing a roll over:
- *   - a `speakerSlot` on a `music`/`sfx` layer (nobody is speaking)
+ *   - a `speakerSlot` on any non-`speech` layer (nobody is speaking)
  *   - a `speakerSlot` naming a slot that is not in the final list
  *
  * MUST run AFTER the orphan-slot sweep, and attribution must NEVER count as a