@nodaro/shared 2.5.0 → 2.8.0

package/src/llm-models.ts

@@ -15,6 +15,7 @@
 
 export type LlmTier = "economy" | "standard" | "premium"
 export type KieApiFormat = "chat-completions" | "messages" | "responses"
+export type LlmVendor = "anthropic" | "google" | "openai" | "xai"
 
 export const LLM_REASONING_EFFORTS = ["none", "low", "medium", "high", "xhigh", "max"] as const
 export type LlmReasoningEffort = (typeof LLM_REASONING_EFFORTS)[number]
@@ -32,7 +33,7 @@ export interface LlmModelDef {
    *  For messages: the model id sent in the body (e.g. "claude-haiku-4-5-v1messages").
    *  For responses: the model id sent in the body (e.g. "gpt-5-4"). */
   kieSlugOrModel: string
-  vendor: "anthropic" | "google" | "openai"
+  vendor: LlmVendor
   supportsImages: boolean
   maxOutputTokens: number
   /**
@@ -159,6 +160,30 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     // direct is the reliability fallback only.
     directGeminiModel: "gemini-3.6-flash",
   },
+  {
+    id: "gemini-3.7-flash",
+    displayName: "Gemini 3.7 Flash",
+    desc: "Newest fast Gemini, agentic-tuned",
+    tier: "economy",
+    kieFormat: "chat-completions",
+    // KIE serves it on the OpenAI-compatible dialect under this slug
+    // (docs.kie.ai/market/gemini/gemini-3-7-flash-openai.md) — same
+    // chat-completions path shape as gemini-3.6-flash.
+    kieSlugOrModel: "gemini-3-7-flash-openai",
+    vendor: "google",
+    structuredOutputMode: "kie-response-format",
+    supportsImages: true,
+    // Google's own cap is 65,536, but the field feeds BOTH lanes and the KIE
+    // flash endpoints cap at 8192 (the measured 3.6 posture) — stay at the
+    // KIE-safe intersection, same reasoning as `reasoningEfforts` below.
+    maxOutputTokens: 8192,
+    // KIE's 3.7 endpoint enumerates reasoning_effort low | high (verified
+    // against its OpenAPI spec 2026-08-18), identical to 3.6.
+    reasoningEfforts: ["low", "high"],
+    // Assumed parity with 3.6 pending a live probe on the direct lane.
+    directReasoningEfforts: ["none", "low", "medium", "high"],
+    directGeminiModel: "gemini-3.7-flash",
+  },
   {
     id: "claude-haiku-4.5",
     displayName: "Claude Haiku 4.5",
@@ -321,7 +346,35 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     reasoningEfforts: ["none", "low", "medium", "high", "xhigh", "max"],
     supportsTemperature: false,
   },
-  // grok-4.5 deferred — KIE chat endpoint not yet live (2026-07-13); add entry + rate row + docs when it activates.
+  {
+    id: "grok-4.6",
+    displayName: "Grok 4.6",
+    desc: "xAI flagship, strong reasoning",
+    tier: "standard",
+    kieFormat: "responses",
+    // KIE serves Grok on the responses dialect under its own family path —
+    // grok/v1/responses, NOT codex/v1/responses (llm-client derives the path
+    // from `vendor`). Live-verified end-to-end 2026-08-18: array `input`,
+    // `developer` system role, `input_image` URL vision, `text.format`
+    // json_schema enforcement, SSE `response.output_text.delta` stream, and
+    // `credits_consumed` actual-cost capture. (grok-4.5 was deferred 2026-07-13
+    // because none of this was live; 4.6 is its activation.)
+    kieSlugOrModel: "grok-4-6",
+    vendor: "xai",
+    structuredOutputMode: "responses-json-schema",
+    supportsImages: true,
+    maxOutputTokens: 16384,
+    // KIE's documented enum, each level live-verified (echoed back) 2026-08-18.
+    // No `none`: the endpoint reasons unconditionally (see thinkingDefaultOn).
+    reasoningEfforts: ["low", "medium", "high", "xhigh"],
+    // Live-probed 2026-08-18: `temperature` is silently IGNORED (request echo
+    // stays at the 0.7 default), so never send it — same treatment as GPT-5.5+.
+    supportsTemperature: false,
+    // Reasons with NO reasoning param sent (effort defaults to "low" server-side
+    // — a trivial probe spent 169 of 170 output tokens on reasoning), so every
+    // call needs output headroom, not just xhigh.
+    thinkingDefaultOn: true,
+  },
   {
     id: "claude-sonnet-5",
     displayName: "Claude Sonnet 5",
@@ -407,6 +460,55 @@ export const STRUCTURED_VISION_MODELS = LLM_MODELS.filter(
   (m) => m.supportsImages && m.structuredOutputMode != null,
 )
 
+/**
+ * Vendor presentation order + labels for model pickers. Every LlmVendor MUST
+ * appear in the order list (guarded by a registry test) so a new vendor can't
+ * ship with its models silently sorted to the end of every menu unlabeled.
+ * Alphabetical on purpose: stable, and no vendor-preference fights.
+ */
+export const LLM_VENDOR_ORDER: readonly LlmVendor[] = ["anthropic", "google", "openai", "xai"]
+export const LLM_VENDOR_LABELS: Record<LlmVendor, string> = {
+  anthropic: "Anthropic",
+  google: "Google",
+  openai: "OpenAI",
+  xai: "xAI",
+}
+
+const TIER_RANK: Record<LlmTier, number> = { economy: 0, standard: 1, premium: 2 }
+
+export interface LlmModelGroup {
+  vendor: LlmVendor
+  /** Display heading for the group (LLM_VENDOR_LABELS[vendor]). */
+  label: string
+  models: LlmModelDef[]
+}
+
+/**
+ * The ONE ordering every LLM model menu renders: grouped by vendor (in
+ * LLM_VENDOR_ORDER), and inside each group sorted economy → standard → premium
+ * (registry order breaks ties, which keeps family generations adjacent).
+ * A flat registry-order dump was genuinely hard to scan at 17 models — every
+ * picker (config panel, quick strips, quick toolbar) derives from this so the
+ * menus can't drift apart. Groups with no models (after `filter`) are omitted.
+ */
+export function groupLlmModelsByVendor(models: readonly LlmModelDef[] = LLM_MODELS): LlmModelGroup[] {
+  const groups: LlmModelGroup[] = []
+  for (const vendor of LLM_VENDOR_ORDER) {
+    const members = models
+      .filter((m) => m.vendor === vendor)
+      .sort((a, b) => TIER_RANK[a.tier] - TIER_RANK[b.tier])
+    if (members.length > 0) groups.push({ vendor, label: LLM_VENDOR_LABELS[vendor], models: members })
+  }
+  return groups
+}
+
+/** {@link groupLlmModelsByVendor} flattened — for menus that can't render
+ *  group headers (e.g. the compact node quick strips) but should still read
+ *  vendor-clustered and tier-ordered. */
+export function orderedLlmModels(models: readonly LlmModelDef[] = LLM_MODELS): LlmModelDef[] {
+  return groupLlmModelsByVendor(models).flatMap((g) => g.models)
+}
+
 export type LlmFeature =
   | "ai-writer"
   | "llm-chat"
@@ -423,6 +525,10 @@ export type LlmFeature =
   | "generate-script"
   | "translate"
   | "image-critic"
+  // Choose Best (reduce) — the pick-best-llm strategy's judge. Its own
+  // feature (not ai-writer, which it used to piggyback on) so the model
+  // default and the tiered credit ids are the strategy's own.
+  | "pick-best-llm"
 
 /** Engine-dependent LlmFeature for the motion-graphics node (design §8: every credit-id site must branch on engine). */
 export function motionGraphicsFeature(engine?: string): LlmFeature {
@@ -446,6 +552,7 @@ export const LLM_FEATURE_DEFAULTS: Record<LlmFeature, string> = {
   "generate-script": "gemini-3.6-flash",
   "translate": "gemini-3.6-flash",
   "image-critic": "claude-sonnet-4.6",
+  "pick-best-llm": "claude-sonnet-4.6",
 }
 
 /**
@@ -460,6 +567,12 @@ export const LLM_FEATURE_DEFAULTS: Record<LlmFeature, string> = {
 export const LLM_MODALITY_CAPS: Record<string, { image: boolean; video: boolean; audio: boolean }> = {
   "gemini-3-flash":    { image: true,  video: true,  audio: true  },
   "gemini-3.6-flash":  { image: true,  video: true,  audio: true  },
+  // gemini-3.7-flash is IMAGE-ONLY by DECISION, not omission: full video+audio
+  // caps would auto-enroll it in VIDEO_ANALYSIS_LLM_MODELS (derived below) and
+  // force a video-analysis tier + pricing decision that is deliberately
+  // deferred while the smart-family A/B routes this model internally (#747).
+  // Flip these two flags ONLY together with that VA-side decision.
+  "gemini-3.7-flash":  { image: true,  video: false, audio: false },
   "gemini-3.1-pro":    { image: true,  video: true,  audio: true  },
   "claude-haiku-4.5":  { image: true,  video: false, audio: false },
   "claude-sonnet-4.6": { image: true,  video: false, audio: false },
@@ -470,6 +583,7 @@ export const LLM_MODALITY_CAPS: Record<string, { image: boolean; video: boolean;
   "gpt-5.6-luna":      { image: true,  video: false, audio: false },
   "gpt-5.6-terra":     { image: true,  video: false, audio: false },
   "gpt-5.6-sol":       { image: true,  video: false, audio: false },
+  "grok-4.6":          { image: true,  video: false, audio: false },
   "claude-sonnet-5":   { image: true,  video: false, audio: false },
   "claude-opus-4.8":   { image: true,  video: false, audio: false },
   "claude-opus-5":     { image: true,  video: false, audio: false },

package/src/model-catalog.ts

@@ -872,6 +872,47 @@ const IMAGE_MODELS: Record<string, ModelCatalogEntry> = {
     useCases: ["upscale"],
     pricing: [{ identifier: "grok-upscale", credits: 25 }],
   },
+  // Grok Imagine Image 2.0 — t2i plus task-chained region editing. The edit
+  // and segment-map endpoints take a PRIOR grok-2 generation's task id (the
+  // job's `kieTaskId` output), not an image URL — same contract as
+  // grok-upscale (see TASK_CHAINED_EDIT_PROVIDERS in model-constants).
+  "grok-2": {
+    id: "grok-2",
+    kind: "image",
+    modes: ["t2i"] as const,
+    family: "xAI",
+    label: "Grok Imagine 2",
+    series: "Grok",
+    description:
+      "Grok Imagine Image 2.0 — expressive, high-contrast t2i. Generations chain into grok-2-segment (free named region masks) and grok-2-edit (region-targeted edits).",
+    useCases: ["stylized", "expressive", "general"],
+    aspectRatios: GROK_RATIOS,
+    pricing: [{ identifier: "grok-2", credits: 10 }],
+  },
+  "grok-2-edit": {
+    id: "grok-2-edit",
+    kind: "image",
+    modes: ["edit"] as const,
+    family: "xAI",
+    label: "Grok Imagine 2 Edit",
+    series: "Grok",
+    description:
+      "Prompt-edit a prior grok-2 generation by task id. Optional mask indexes (from grok-2-segment) restrict the edit to named regions.",
+    useCases: ["edit", "region-edit"],
+    pricing: [{ identifier: "grok-2-edit", credits: 10 }],
+  },
+  "grok-2-segment": {
+    id: "grok-2-segment",
+    kind: "image",
+    modes: ["edit"] as const,
+    family: "xAI",
+    label: "Grok Imagine 2 Segment Map",
+    series: "Grok",
+    description:
+      "FREE semantic segment map of a prior grok-2 generation — named region masks whose indexes feed grok-2-edit's region targeting.",
+    useCases: ["segmentation", "region-edit"],
+    pricing: [{ identifier: "grok-2-segment", credits: 0, note: "free" }],
+  },
 
   // ── Utilities ──
   "recraft-remove-bg": {
@@ -1354,7 +1395,8 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
   },
   // Seedance 2.5 — the next Seedance generation, not a tier of the 2.0 ladder.
   // Two levers differ from every 2.0 SKU and drive its own entries throughout:
-  // durations run to 30s (2.0 caps at 15s) and there is NO 1080p/4K tier.
+  // durations run to 30s (2.0 caps at 15s) and there is NO 4K tier (1080p
+  // arrived on KIE 2026-08-17 — probe-verified; 4k/2k/1440p still rejected).
   // Reference caps are also wider (30 images / 10 videos / 10 audio) — see
   // SEEDANCE_2_5_REF_LIMITS in model-constants.
   "seedance-2-5": {
@@ -1364,20 +1406,23 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
     family: "Bytedance",
     label: "Seedance 2.5",
     series: "Seedance",
-    description: "Seedance 2.5 — up to 30s in one shot, native audio, wide multimodal references. 480p/720p.",
+    description: "Seedance 2.5 — up to 30s in one shot, native audio, wide multimodal references. 480p/720p/1080p.",
     useCases: ["premium", "narrative", "long-form"],
     features: ["end-frame", "audio", "reference-image", "video-reference"],
     aspectRatios: VIDEO_RATIOS_SEEDANCE_2,
     durations: [4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30],
-    resolutions: ["480p", "720p"],
+    resolutions: ["480p", "720p", "1080p"],
     pricing: [
       { identifier: "seedance-2-5", credits: 1260, note: "default 8s 720p — see :Ns:res variants for exact" },
       { identifier: "seedance-2-5:8s:480p", credits: 560, note: "8s 480p" },
       { identifier: "seedance-2-5:8s:720p", credits: 1260, note: "8s 720p" },
+      { identifier: "seedance-2-5:8s:1080p", credits: 2280, note: "8s 1080p" },
       { identifier: "seedance-2-5:8s:480p-ref", credits: 340, note: "8s 480p with reference video" },
       { identifier: "seedance-2-5:8s:720p-ref", credits: 760, note: "8s 720p with reference video" },
+      { identifier: "seedance-2-5:8s:1080p-ref", credits: 1370, note: "8s 1080p with reference video" },
       { identifier: "seedance-2-5:30s:480p", credits: 2100, note: "30s 480p (max)" },
       { identifier: "seedance-2-5:30s:720p", credits: 4730, note: "30s 720p (max)" },
+      { identifier: "seedance-2-5:30s:1080p", credits: 8550, note: "30s 1080p (max)" },
     ],
   },
 

package/src/model-constants.ts

@@ -558,6 +558,7 @@ export const IMAGE_GEN_PROVIDERS = [
   "nano-banana-2",
   "nano-banana-2-lite",
   "grok",
+  "grok-2",
   "gpt-image",
   "gpt-image-2",
   "imagen4",
@@ -623,8 +624,29 @@ export const IMAGE_EDIT_PROVIDERS = [
   // grok-upscale takes a prior Grok generation's task_id (NOT an image URL) —
   // see edit-image route for the taskId-vs-imageUrl branching.
   "grok-upscale",
+  // Grok Imagine 2 task-chained ops — same task_id contract as grok-upscale.
+  // grok-2-edit: prompt edit of a prior grok-2 generation, optionally region-
+  // targeted via mask indexes from grok-2-segment. grok-2-segment: FREE named
+  // segment-mask map of a prior grok-2 generation.
+  "grok-2-edit",
+  "grok-2-segment",
 ] as const
 
+/**
+ * Edit providers that take a PRIOR KIE Grok generation's task id instead of
+ * an image URL. Single source of truth for the taskId-vs-imageUrl branching:
+ * the edit-image route requires `taskId` (imageUrl alone is rejected), the
+ * worker routes `taskId` into the provider call, and the KIE model config
+ * (`imageParam: "task_id"`) places it in the request body. Membership here
+ * must match the KIE configs with `imageParam: "task_id"` — guarded by
+ * backend/src/routes/__tests__/edit-image.test.ts.
+ */
+export const TASK_CHAINED_EDIT_PROVIDERS: ReadonlySet<string> = new Set([
+  "grok-upscale",
+  "grok-2-edit",
+  "grok-2-segment",
+])
+
 /** Modify image providers (I2I + edit-with-prompt) */
 export const MODIFY_IMAGE_PROVIDERS = [
   ...IMAGE_I2I_PROVIDERS,
@@ -1071,6 +1093,7 @@ export const IMAGE_MASK_MODE: Record<ImageGenProvider, ImageMaskMode> = {
   "flux": "composite",
   "flux-flex": "composite",
   "grok": "composite",
+  "grok-2": "composite",
   "imagen4": "composite",
   "imagen4-fast": "composite",
   "imagen4-ultra": "composite",

package/src/node-default-mappings.ts

@@ -184,8 +184,9 @@ const QUALITY_MAP: Record<string, QualityMapping> = {
   "seedance-2":          { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
   "seedance-2-fast":     { field: "resolution", values: { low: "480p", mid: "720p", high: "720p" } },
   "seedance-2-mini":     { field: "resolution", values: { low: "480p", mid: "720p", high: "720p" } },
-  // Seedance 2.5 tops out at 720p on KIE (1080p/4k probe-rejected 2026-08-08).
-  "seedance-2-5":        { field: "resolution", values: { low: "480p", mid: "720p", high: "720p" } },
+  // Seedance 2.5 spans 480p/720p/1080p on KIE (1080p accepted since the
+  // 2026-08-17 re-probe; 4k still rejected), so each quality rung gets its own tier.
+  "seedance-2-5":        { field: "resolution", values: { low: "480p", mid: "720p", high: "1080p" } },
   "wan-2.7-i2v":         { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
   "wan-2.7-t2v":         { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },
   "happyhorse":          { field: "resolution", values: { low: "720p", mid: "1080p", high: "1080p" } },

package/src/reduce-strategy-registry.ts

@@ -17,12 +17,23 @@ export type ReduceStrategy<TConfig = unknown> = {
   readonly defaultConfig: TConfig
   readonly outputType: OutputType
   readonly creditCostKey: string
+  /**
+   * The strategy calls an LLM (its judge model). Everything that treats
+   * "an LLM strategy" specially — the connected-install cloud proxy, the
+   * tiered credit id — reads this rather than matching on the id, so a new
+   * LLM strategy is covered by declaring it here.
+   */
+  readonly usesLlm?: boolean
 }
 
+// User-facing copy lives HERE (single source of truth) and flows into the node
+// body, the config panel dropdown, the SDK docs and the MCP tool. Written for
+// the person building the flow, not the engine: say what happens to their
+// candidates, never "survivor" / "fan-in" / "reduce" / model names.
 const PICK_BEST_LLM_STRATEGY = {
   id: "pick-best-llm",
-  label: "Pick best (LLM judge)",
-  description: "Sonnet picks the best item against your criteria.",
+  label: "AI picks the best",
+  description: "AI compares every candidate against your criteria and picks one.",
   configSchema: z.object({
     // Default to the sensible "best quality" criteria when omitted (matches
     // defaultConfig) so a reduce({strategyId:"pick-best-llm"}) call with no
@@ -30,16 +41,23 @@ const PICK_BEST_LLM_STRATEGY = {
     // rejects via min(1).
     criteria: z.string().min(1, "criteria cannot be empty").default("Pick the highest-quality result."),
     inputKind: z.enum(["text", "image-url"]).default("text"),
+    // The judge model, like every other LLM node (llmModel + LlmModelSelect).
+    // Optional: omitted → LLM_FEATURE_DEFAULTS["pick-best-llm"]. Validated
+    // against LLM_MODEL_IDS at the route (the registry can't import the model
+    // list without a cycle), and its tier drives the credit price via
+    // buildLlmCreditIdentifier — economy / standard / premium.
+    llmModel: z.string().optional(),
   }),
   defaultConfig: { criteria: "Pick the highest-quality result.", inputKind: "text" as const },
   outputType: "text" as OutputType,
   creditCostKey: "reduce:pick-best-llm",
-} as const satisfies ReduceStrategy<{ criteria: string; inputKind: "text" | "image-url" }>
+  usesLlm: true,
+} as const satisfies ReduceStrategy<{ criteria: string; inputKind: "text" | "image-url"; llmModel?: string }>
 
 const CONCAT_STRATEGY = {
   id: "concat",
-  label: "Concatenate",
-  description: "Join all survivors with a separator.",
+  label: "Join into one text",
+  description: "Puts every candidate into a single text, one after another, with a separator between them.",
   configSchema: z.object({ separator: z.string().default("\n\n") }),
   defaultConfig: { separator: "\n\n" },
   outputType: "text" as OutputType,
@@ -48,8 +66,8 @@ const CONCAT_STRATEGY = {
 
 const FIRST_NON_EMPTY_STRATEGY = {
   id: "first-non-empty",
-  label: "First non-empty",
-  description: "Return the first survivor (empty strings filtered).",
+  label: "First that has content",
+  description: "Takes the first candidate that is not empty and ignores the rest.",
   configSchema: z.object({}),
   defaultConfig: {},
   outputType: "text" as OutputType,
@@ -58,8 +76,8 @@ const FIRST_NON_EMPTY_STRATEGY = {
 
 const COUNT_STRATEGY = {
   id: "count",
-  label: "Count",
-  description: "Return how many survivors came through.",
+  label: "Count them",
+  description: "Outputs how many candidates arrived.",
   configSchema: z.object({}),
   defaultConfig: {},
   outputType: "data" as OutputType,
@@ -68,8 +86,8 @@ const COUNT_STRATEGY = {
 
 const VOTE_STRATEGY = {
   id: "vote",
-  label: "Majority vote",
-  description: "Return the most common survivor (ties → first).",
+  label: "Most common answer",
+  description: "Picks the candidate that appears most often (ties go to the first).",
   configSchema: z.object({ caseSensitive: z.boolean().default(false) }),
   defaultConfig: { caseSensitive: false },
   outputType: "text" as OutputType,
@@ -78,8 +96,8 @@ const VOTE_STRATEGY = {
 
 const MERGE_JSON_STRATEGY = {
   id: "merge-json",
-  label: "Merge JSON",
-  description: "Parse each survivor as JSON and merge into one object.",
+  label: "Merge JSON objects",
+  description: "Reads every candidate as JSON and merges them into one object.",
   configSchema: z.object({ strategy: z.enum(["deep", "shallow"]).default("deep") }),
   defaultConfig: { strategy: "deep" as const },
   outputType: "data" as OutputType,

package/src/video-analysis.ts

@@ -100,6 +100,21 @@ export type VideoAnalysisTransition = (typeof VIDEO_ANALYSIS_TRANSITIONS)[number
  * the majority of shots.
  */
 export const VIDEO_ANALYSIS_SPEED_EFFECTS = ["slow-motion", "ramp-in", "ramp-out", "timelapse", "freeze", "reverse"] as const
+
+/** CHRONICLE TIME (2026-08-17): the STORY clock, per scene, as read from the
+ *  pictures — light, sky, practicals. "ambiguous" is the honest answer for a
+ *  windowless interior; guessing day is exactly the kind of tidy inference
+ *  the analysis doctrine forbids. */
+export const VIDEO_ANALYSIS_TIMES_OF_DAY = ["dawn", "day", "dusk", "night", "ambiguous"] as const
+
+/** STORY JUMP since the PREVIOUS scene in the list: how much narrative time
+ *  passed across the cut, judged from evidence (wardrobe change, aged
+ *  subjects, season, a title card), not from the cut itself. Time outranks
+ *  location for continuity judgements (same person, new place, continuous
+ *  time ⇒ same outfit; same place, years later ⇒ anything may differ), which
+ *  is why this is a structured field and not prose. "unclear" is the honest
+ *  default; the FIRST scene of a clip is "continuous" by convention. */
+export const VIDEO_ANALYSIS_STORY_JUMPS = ["continuous", "same-day", "another-day", "years-later", "unclear"] as const
 export type VideoAnalysisSpeedEffect = (typeof VIDEO_ANALYSIS_SPEED_EFFECTS)[number]
 
 /**
@@ -268,6 +283,12 @@ const windowSceneBase = z.object({
   angle: z.enum(VIDEO_ANALYSIS_SHOT_ANGLES).optional(),
   /** Time manipulation. Absent ⇒ normal speed. */
   speed: z.enum(VIDEO_ANALYSIS_SPEED_EFFECTS).optional(),
+  /** CHRONICLE TIME (2026-08-17) — see the consts' docstrings. Both optional:
+   *  absent on every pre-2.6.0 analysis, and legitimately absent when the
+   *  analyser cannot read the clock. Enum + optional keeps the window decode
+   *  grammar congruence-safe (no ints, no maxItems). */
+  timeOfDay: z.enum(VIDEO_ANALYSIS_TIMES_OF_DAY).optional(),
+  storyJump: z.enum(VIDEO_ANALYSIS_STORY_JUMPS).optional(),
   visual: z.string().min(1),
   /**
    * Text burned into the PICTURE of this shot — titles, captions, lower-thirds,
@@ -521,3 +542,52 @@ export function aspectRatioFromDims(w: number, h: number): string {
   const g = gcd(Math.round(w), Math.round(h))
   return `${Math.round(w) / g}:${Math.round(h) / g}`
 }
+
+/** Sung-vocal evidence in a music layer's gen-ready description. Word-bounded
+ *  and deliberately WITHOUT bare "song"/"music" (an instrumental bed is
+ *  routinely described as a "pop song"). Quoted text of some length inside a
+ *  music layer counts too — analysers quote lyrics. */
+const MUSIC_VOCAL_RE = /\b(?:lyrics?|sung|sings?|singing|vocals?|chorus|verse|rap(?:ping|ped)?|a cappella)\b/i
+const MUSIC_VOCAL_QUOTE_RE = /["\u201c][^"\u201d]{6,}["\u201d]/
+/** Negated-vocal phrasing — a layer matching this contributes NO vocal
+ *  evidence (it does not veto other layers). */
+const MUSIC_NO_VOCAL_RE = /\b(?:no|without|non)[- ](?:vocals?|lyrics?|singing)\b|\binstrumental\b|\bwordless\b/i
+
+/**
+ * MUSIC-VIDEO INFERENCE (2026-08-17): is this clip a music video — one whose
+ * soundtrack IS the content, to be taken as-is with no stem separation?
+ *
+ * Lives in SHARED because two sides must agree BYTE-FOR-BYTE on the answer:
+ * the recast route derives `music.mode` from it server-side, and the client
+ * both prices the original-audio prep and GUARDS on the server's derived mode
+ * at generate time — two hand-written copies of this heuristic would drift
+ * into that guard firing on honest runs. Deterministic, throw-proof on any
+ * malformed analysis (absent fields ⇒ false).
+ *
+ * The rule is conservative toward FALSE (a false positive keeps unwanted
+ * dialogue in the render; a false negative merely runs the separation, which
+ * was yesterday's default): at least 4 scenes, at least 80% of scenes carry a
+ * music layer, and at least one music layer carries sung-vocal evidence that
+ * is not negated ("instrumental", "no vocals").
+ *
+ * An EXPLICIT analyze-time flag always wins — callers use
+ * `flag === true || inferMusicVideo(analysis)` and never let a cached false
+ * suppress the inference (the flag can only ever be set true; false means
+ * "unset", not "denied").
+ */
+export function inferMusicVideo(analysis: {
+  scenes?: ReadonlyArray<{ audio?: ReadonlyArray<{ mode?: string; content?: string }> }>
+} | undefined | null): boolean {
+  const scenes = analysis?.scenes ?? []
+  if (scenes.length < 4) return false
+  const musicLayers = (sc: (typeof scenes)[number]) => (sc.audio ?? []).filter((a) => a?.mode === "music")
+  const withMusic = scenes.filter((sc) => musicLayers(sc).length > 0).length
+  if (withMusic / scenes.length < 0.8) return false
+  return scenes.some((sc) =>
+    musicLayers(sc).some((a) => {
+      const content = typeof a.content === "string" ? a.content : ""
+      if (MUSIC_NO_VOCAL_RE.test(content)) return false
+      return MUSIC_VOCAL_RE.test(content) || MUSIC_VOCAL_QUOTE_RE.test(content)
+    }),
+  )
+}