@nodaro/shared 1.4.2

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

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "vitest"
+import {
+  AUDIO_PRODUCER_TYPES,
+  VIDEO_PRODUCER_TYPES,
+  DYNAMIC_PRODUCER_TYPES,
+} from "../producer-types.js"
+
+/**
+ * Producer-set membership is what every downstream node's typed-handle
+ * `accepts(sourceType)` predicate consults to decide whether an edge LEAVING
+ * a source node may land on its input. A node with audio/video OUTPUT handles
+ * that is absent from these sets can't connect its outputs anywhere — the
+ * canvas validator hard-rejects every edge (drift bug class, see file header).
+ *
+ * This guards the recurrence where `voice-changer-pro` (renamed from
+ * voice-recast in #3581) shipped with output handles but was never added to
+ * the producer sets, so "cannot connect the outputs of voice-changer-pro".
+ */
+describe("producer-types", () => {
+  const ALL_SETS = {
+    AUDIO_PRODUCER_TYPES,
+    VIDEO_PRODUCER_TYPES,
+    DYNAMIC_PRODUCER_TYPES,
+  } as const
+
+  it("registers voice-changer-pro as an audio producer (its default output)", () => {
+    expect(AUDIO_PRODUCER_TYPES.has("voice-changer-pro")).toBe(true)
+  })
+
+  it("registers voice-changer-pro as a dynamic producer (dual-mode → accepted on BOTH audio and video input handles)", () => {
+    expect(DYNAMIC_PRODUCER_TYPES.has("voice-changer-pro")).toBe(true)
+  })
+
+  // voice-changer-pro is a behavioral twin of voice-changer (identical
+  // dual-mode output: audio in → audio out; video in → video out). Their
+  // producer-set membership must never drift apart — if voice-changer is
+  // later added to/removed from any set, the same must happen for the Pro
+  // variant, or its outputs silently stop connecting in exactly one mode.
+  it("keeps voice-changer-pro's producer membership identical to its twin voice-changer", () => {
+    for (const [name, set] of Object.entries(ALL_SETS)) {
+      expect(
+        set.has("voice-changer-pro"),
+        `voice-changer-pro must match voice-changer in ${name}`,
+      ).toBe(set.has("voice-changer"))
+    }
+  })
+})

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

@@ -0,0 +1,156 @@
+import { describe, it, expect } from "vitest"
+import {
+  IMAGE_PROMPT_MAX,
+  VIDEO_PROMPT_MAX,
+  PROMPT_HARD_CEILING,
+  NEGATIVE_PROMPT_MAX,
+  TTS_TEXT_MAX,
+  SUNO_TITLE_MAX,
+  MAX_IMAGE_PROMPT_CHARS_BY_PROVIDER,
+  MAX_VIDEO_PROMPT_CHARS_BY_PROVIDER,
+  MAX_NEGATIVE_PROMPT_CHARS_BY_PROVIDER,
+  MAX_TTS_CHARS_BY_PROVIDER,
+  getMaxImagePromptChars,
+  getMaxVideoPromptChars,
+  getMaxNegativePromptChars,
+  getMaxTtsChars,
+  getMaxSunoPromptChars,
+  getMaxSunoStyleChars,
+  IMAGE_GEN_PROVIDERS,
+  IMAGE_I2I_PROVIDERS,
+  IMAGE_EDIT_PROVIDERS,
+  VIDEO_GEN_PROVIDERS,
+  VIDEO_TO_VIDEO_PROVIDERS,
+  EXTEND_VIDEO_PROVIDERS,
+} from "../model-constants.js"
+
+describe("per-model prompt length limits", () => {
+  describe("getMaxImagePromptChars", () => {
+    it("returns the verified higher caps (provider supports more than 5000)", () => {
+      expect(getMaxImagePromptChars("nano-banana-2")).toBe(20000)
+      expect(getMaxImagePromptChars("nano-banana-pro")).toBe(20000)
+      expect(getMaxImagePromptChars("gpt-image-2-i2i")).toBe(20000)
+    })
+    it("returns the verified LOWER caps (over-send risk if left at 5000)", () => {
+      expect(getMaxImagePromptChars("seedream")).toBe(3000)
+      expect(getMaxImagePromptChars("seedream-5-lite")).toBe(1000)
+      expect(getMaxImagePromptChars("qwen")).toBe(3000)
+      expect(getMaxImagePromptChars("qwen-edit")).toBe(2000)
+    })
+    it("siblings differ — does not copy the t2i number to i2i/edit", () => {
+      // seedream t2i 3000, 5-lite t2i 1000 but its i2i is 3000
+      expect(getMaxImagePromptChars("seedream-5-lite-i2i")).toBe(3000)
+    })
+    it("falls back to IMAGE_PROMPT_MAX for verified-default + unknown providers", () => {
+      expect(getMaxImagePromptChars("flux")).toBe(IMAGE_PROMPT_MAX)
+      expect(getMaxImagePromptChars("imagen4")).toBe(IMAGE_PROMPT_MAX)
+      expect(getMaxImagePromptChars("grok-i2i")).toBe(IMAGE_PROMPT_MAX) // 390000 doc = sanity-capped
+      expect(getMaxImagePromptChars("flux-kontext")).toBe(IMAGE_PROMPT_MAX) // UNVERIFIED
+      expect(getMaxImagePromptChars(undefined)).toBe(IMAGE_PROMPT_MAX)
+      expect(getMaxImagePromptChars("totally-made-up")).toBe(IMAGE_PROMPT_MAX)
+    })
+  })
+
+  describe("getMaxVideoPromptChars", () => {
+    it("returns verified per-model caps (mostly far below the old flat 8000)", () => {
+      expect(getMaxVideoPromptChars("kling")).toBe(1000)
+      expect(getMaxVideoPromptChars("kling-turbo")).toBe(2500)
+      expect(getMaxVideoPromptChars("kling-master")).toBe(5000)
+      expect(getMaxVideoPromptChars("minimax")).toBe(1500)
+      expect(getMaxVideoPromptChars("runway-kie")).toBe(1800)
+      expect(getMaxVideoPromptChars("grok-imagine-video-1.5")).toBe(4096)
+    })
+    it("returns verified higher caps", () => {
+      expect(getMaxVideoPromptChars("seedance-2")).toBe(20000)
+      expect(getMaxVideoPromptChars("gemini-omni-video")).toBe(20000)
+      expect(getMaxVideoPromptChars("bytedance-pro")).toBe(10000)
+    })
+    it("falls back to VIDEO_PROMPT_MAX for UNVERIFIED + unknown providers", () => {
+      expect(getMaxVideoPromptChars("veo3")).toBe(VIDEO_PROMPT_MAX) // no limit in schema
+      expect(getMaxVideoPromptChars("kling-3.0")).toBe(VIDEO_PROMPT_MAX)
+      expect(getMaxVideoPromptChars(undefined)).toBe(VIDEO_PROMPT_MAX)
+    })
+  })
+
+  describe("getMaxNegativePromptChars", () => {
+    it("returns verified native negative caps", () => {
+      expect(getMaxNegativePromptChars("ideogram-v3")).toBe(500)
+      expect(getMaxNegativePromptChars("qwen")).toBe(500)
+      expect(getMaxNegativePromptChars("kling-master")).toBe(500)
+      expect(getMaxNegativePromptChars("imagen4")).toBe(5000)
+    })
+    it("defaults to NEGATIVE_PROMPT_MAX otherwise", () => {
+      expect(getMaxNegativePromptChars("flux")).toBe(NEGATIVE_PROMPT_MAX)
+      expect(getMaxNegativePromptChars(undefined)).toBe(NEGATIVE_PROMPT_MAX)
+    })
+  })
+
+  describe("getMaxTtsChars", () => {
+    it("returns verified per-model TTS caps", () => {
+      expect(getMaxTtsChars("elevenlabs-turbo")).toBe(40000)
+      expect(getMaxTtsChars("elevenlabs-multilingual")).toBe(10000)
+      expect(getMaxTtsChars("elevenlabs-v3")).toBe(3000) // conservative
+      expect(getMaxTtsChars("elevenlabs-dialogue")).toBe(2000)
+    })
+    it("defaults to TTS_TEXT_MAX for the legacy/unknown provider", () => {
+      expect(getMaxTtsChars("elevenlabs")).toBe(TTS_TEXT_MAX)
+      expect(getMaxTtsChars(undefined)).toBe(TTS_TEXT_MAX)
+    })
+  })
+
+  describe("Suno per-version caps", () => {
+    it("prompt: 500 non-custom; 3000 V4 custom; 5000 V4.5+/V5 custom", () => {
+      expect(getMaxSunoPromptChars("V4", false)).toBe(500)
+      expect(getMaxSunoPromptChars("V5", false)).toBe(500)
+      expect(getMaxSunoPromptChars("V4", true)).toBe(3000)
+      expect(getMaxSunoPromptChars("V4_5", true)).toBe(5000)
+      expect(getMaxSunoPromptChars("V5", true)).toBe(5000)
+      expect(getMaxSunoPromptChars("V5_5", true)).toBe(5000)
+    })
+    it("style: 200 for V4, 1000 for V4.5+; title 80", () => {
+      expect(getMaxSunoStyleChars("V4")).toBe(200)
+      expect(getMaxSunoStyleChars("V5")).toBe(1000)
+      expect(SUNO_TITLE_MAX).toBe(80)
+    })
+  })
+
+  describe("drift guards (registry hygiene)", () => {
+    const imageProviders = new Set<string>([
+      ...IMAGE_GEN_PROVIDERS,
+      ...IMAGE_I2I_PROVIDERS,
+      ...IMAGE_EDIT_PROVIDERS,
+    ])
+    const videoProviders = new Set<string>([
+      ...VIDEO_GEN_PROVIDERS,
+      ...VIDEO_TO_VIDEO_PROVIDERS,
+      ...EXTEND_VIDEO_PROVIDERS,
+    ])
+
+    it("every image-cap key is a real image provider id", () => {
+      for (const key of Object.keys(MAX_IMAGE_PROMPT_CHARS_BY_PROVIDER)) {
+        expect(imageProviders.has(key), `${key} is not a known image provider`).toBe(true)
+      }
+    })
+    it("every video-cap key is a real video provider id", () => {
+      for (const key of Object.keys(MAX_VIDEO_PROMPT_CHARS_BY_PROVIDER)) {
+        expect(videoProviders.has(key), `${key} is not a known video provider`).toBe(true)
+      }
+    })
+    it("all caps are positive integers within the hard ceiling", () => {
+      const all = [
+        ...Object.values(MAX_IMAGE_PROMPT_CHARS_BY_PROVIDER),
+        ...Object.values(MAX_VIDEO_PROMPT_CHARS_BY_PROVIDER),
+        ...Object.values(MAX_NEGATIVE_PROMPT_CHARS_BY_PROVIDER),
+      ]
+      for (const v of all) {
+        expect(Number.isInteger(v) && v > 0).toBe(true)
+        expect(v).toBeLessThanOrEqual(PROMPT_HARD_CEILING)
+      }
+    })
+    it("TTS caps are positive integers (turbo may exceed the image/video ceiling)", () => {
+      for (const v of Object.values(MAX_TTS_CHARS_BY_PROVIDER)) {
+        expect(Number.isInteger(v) && v > 0).toBe(true)
+      }
+    })
+  })
+})

package/src/__tests__/provider-directive-defaults.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest"
+import { mapShotIntentToProviderDirectives } from "../provider-directive-defaults.js"
+
+const baseIntent = {
+  needs_multishot_reference: false,
+  is_loopable: false,
+  needs_music_suppression: true,
+  is_match_cut: false,
+}
+
+describe("mapShotIntentToProviderDirectives", () => {
+  it("seedance-2 with default intent gets disable_internal_music + allow_sfx", () => {
+    const dirs = mapShotIntentToProviderDirectives("seedance-2", baseIntent)
+    expect(dirs.disable_internal_music).toBe(true)
+    expect(dirs.allow_sfx).toBe(true)
+  })
+
+  it("seedance-2 with multishot intent adds multishot: true", () => {
+    const dirs = mapShotIntentToProviderDirectives("seedance-2", {
+      ...baseIntent,
+      needs_multishot_reference: true,
+    })
+    expect(dirs.multishot).toBe(true)
+  })
+
+  it("veo3.1 with loopable intent adds loop_seed: stable", () => {
+    const dirs = mapShotIntentToProviderDirectives("veo3.1", {
+      ...baseIntent,
+      is_loopable: true,
+    })
+    expect(dirs.loop_seed).toBe("stable")
+  })
+
+  it("hailuo with multishot intent doesn't add multishot (provider doesn't support it)", () => {
+    const dirs = mapShotIntentToProviderDirectives("hailuo-2.3-pro", {
+      ...baseIntent,
+      needs_multishot_reference: true,
+    })
+    expect(dirs.multishot).toBeUndefined()
+  })
+
+  it("unknown provider returns an empty object", () => {
+    const dirs = mapShotIntentToProviderDirectives("made-up-model", baseIntent)
+    expect(dirs).toEqual({})
+  })
+})

package/src/__tests__/reduce-strategy-registry.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest"
+import { REDUCE_STRATEGIES, REDUCE_STRATEGY_IDS, getStrategy } from "../reduce-strategy-registry"
+
+describe("reduce-strategy-registry", () => {
+  it("registers exactly the 6 v1 strategies (snapshot)", () => {
+    expect(REDUCE_STRATEGY_IDS).toEqual([
+      "pick-best-llm",
+      "concat",
+      "first-non-empty",
+      "count",
+      "vote",
+      "merge-json",
+    ])
+  })
+
+  it("every strategy has id, label, description, configSchema, defaultConfig, outputType, creditCostKey", () => {
+    for (const s of REDUCE_STRATEGIES) {
+      expect(s.id).toBeTruthy()
+      expect(s.label).toBeTruthy()
+      expect(s.description).toBeTruthy()
+      expect(s.configSchema).toBeTruthy()
+      expect(s.defaultConfig).toBeDefined()
+      expect(s.outputType).toMatch(/^(image|video|audio|text|data)$/)
+      expect(s.creditCostKey).toMatch(/^reduce:/)
+    }
+  })
+
+  it("every strategy's configSchema accepts its defaultConfig", () => {
+    for (const s of REDUCE_STRATEGIES) {
+      const result = s.configSchema.safeParse(s.defaultConfig)
+      expect(result.success, `${s.id} defaultConfig must satisfy configSchema`).toBe(true)
+    }
+  })
+
+  it("getStrategy returns the right strategy by id", () => {
+    expect(getStrategy("concat").id).toBe("concat")
+    expect(getStrategy("pick-best-llm").id).toBe("pick-best-llm")
+  })
+
+  it("getStrategy throws on unknown id", () => {
+    expect(() => getStrategy("nope" as never)).toThrow(/unknown reduce strategy/i)
+  })
+})

package/src/__tests__/reference-board-templates.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest"
+import {
+  REFERENCE_BOARD_PROVIDERS,
+  REFERENCE_BOARD_TEMPLATES,
+  buildBoardPrompt,
+  listBoardTemplates,
+} from "../reference-board-templates.js"
+
+describe("reference-board templates", () => {
+  it("ships gen providers as a subset of image providers", () => {
+    expect(REFERENCE_BOARD_PROVIDERS).toContain("nano-banana-pro")
+    expect(REFERENCE_BOARD_PROVIDERS).toContain("gpt-image-2")
+  })
+
+  it("every entity kind has a full-board template", () => {
+    for (const kind of ["character", "location", "object"] as const) {
+      const ids = listBoardTemplates(kind).map((t) => t.id)
+      expect(ids).toContain(`${kind}/full-board`)
+    }
+  })
+
+  it("full-board prompt carries the three guide tricks", () => {
+    const p = buildBoardPrompt("character/full-board", {})
+    expect(p.toLowerCase()).toContain("palette")          // 6-HEX palette panel
+    expect(p.toLowerCase()).toContain("hex")
+    expect(p).toContain("visual reference for consistent depiction") // self-referential caption
+    expect(p.toLowerCase()).toContain("aspect ratio")     // anti-rigid AR clause
+  })
+
+  it("unknown template id throws (no silent empty prompt)", () => {
+    expect(() => buildBoardPrompt("character/nope", {})).toThrow()
+  })
+})

package/src/__tests__/reference-roles.test.ts

@@ -0,0 +1,36 @@
+// packages/shared/src/__tests__/reference-roles.test.ts
+import { describe, it, expect } from "vitest"
+import { REFERENCE_ROLE_PRESETS, roleToPhrase, defaultRoleForSource } from "../reference-roles.js"
+import { DEFAULT_LABEL_BY_SOURCE } from "../types.js"
+
+describe("reference-roles registry", () => {
+  it("every source's default role is present in its preset list", () => {
+    for (const source of Object.keys(DEFAULT_LABEL_BY_SOURCE) as Array<keyof typeof DEFAULT_LABEL_BY_SOURCE>) {
+      const presets = REFERENCE_ROLE_PRESETS[source]
+      expect(presets, source).toBeTruthy()
+      expect(presets, source).toContain(defaultRoleForSource(source))
+    }
+  })
+
+  it("defaultRoleForSource mirrors DEFAULT_LABEL_BY_SOURCE", () => {
+    expect(defaultRoleForSource("wired-character")).toBe("person")
+    expect(defaultRoleForSource("wired-location")).toBe("background")
+    expect(defaultRoleForSource("wired-object")).toBe("object")
+    expect(defaultRoleForSource("wired-creature")).toBe("creature")
+  })
+
+  it("renders noun roles as 'the {role} from {binding}'", () => {
+    expect(roleToPhrase("person", "reference image A")).toBe("the person from reference image A")
+    expect(roleToPhrase("face", "@image_3")).toBe("the face from @image_3")
+  })
+
+  it("renders the non-noun specials naturally", () => {
+    expect(roleToPhrase("as-is", "reference image A")).toBe("reference image A, used as-is")
+    expect(roleToPhrase("empty background", "reference image A"))
+      .toBe("the background from reference image A (without its foreground objects)")
+  })
+
+  it("renders a custom single-word label via the default template", () => {
+    expect(roleToPhrase("hoodie", "reference image B")).toBe("the hoodie from reference image B")
+  })
+})

package/src/__tests__/resolve-field-mappings.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Tests for shared field-resolver helpers in `resolve-field-mappings.ts`.
+ *
+ * `resolveLocationFields(loc)` flattens a location's anchor image plus every
+ * variant bucket (timeOfDay/weather/seasons/angles/lighting/atmosphereMotions)
+ * into a single `Array<{ key, label, url }>` for picker UIs and ref-resolvers.
+ */
+
+import { describe, it, expect } from "vitest"
+import { resolveLocationFields } from "../resolve-field-mappings.js"
+import { resolveFieldMappings, fieldKeyFromHandle } from "../index.js"
+
+describe("resolveLocationFields", () => {
+  it("returns just the main image entry when no buckets are set", () => {
+    const loc = { sourceImageUrl: "https://r2/loc/main.png" }
+    const result = resolveLocationFields(loc)
+    expect(result).toEqual([
+      { key: "sourceImageUrl", label: "Main image", url: "https://r2/loc/main.png" },
+    ])
+  })
+
+  it("flattens every bucket into key/label/url entries with per-bucket indices", () => {
+    const loc = {
+      sourceImageUrl: "https://r2/loc/main.png",
+      timeOfDay: [
+        { name: "dawn", url: "https://r2/loc/dawn.png" },
+        { name: "dusk", url: "https://r2/loc/dusk.png" },
+      ],
+      weather: [{ name: "rainy", url: "https://r2/loc/rainy.png" }],
+      seasons: [{ name: "winter", url: "https://r2/loc/winter.png" }],
+      angles: [{ name: "wide", url: "https://r2/loc/wide.png" }],
+      lighting: [{ name: "neon", url: "https://r2/loc/neon.png" }],
+      atmosphereMotions: [
+        { name: "smoke", url: "https://r2/loc/smoke.png" },
+        { name: "rain-fall", url: "https://r2/loc/rain-fall.png" },
+      ],
+    }
+    const result = resolveLocationFields(loc)
+    expect(result).toEqual([
+      { key: "sourceImageUrl", label: "Main image", url: "https://r2/loc/main.png" },
+      { key: "timeOfDay[0]", label: "timeOfDay / dawn", url: "https://r2/loc/dawn.png" },
+      { key: "timeOfDay[1]", label: "timeOfDay / dusk", url: "https://r2/loc/dusk.png" },
+      { key: "weather[0]", label: "weather / rainy", url: "https://r2/loc/rainy.png" },
+      { key: "seasons[0]", label: "seasons / winter", url: "https://r2/loc/winter.png" },
+      { key: "angles[0]", label: "angles / wide", url: "https://r2/loc/wide.png" },
+      { key: "lighting[0]", label: "lighting / neon", url: "https://r2/loc/neon.png" },
+      { key: "atmosphereMotions[0]", label: "atmosphereMotions / smoke", url: "https://r2/loc/smoke.png" },
+      { key: "atmosphereMotions[1]", label: "atmosphereMotions / rain-fall", url: "https://r2/loc/rain-fall.png" },
+    ])
+  })
+
+  it("skips sourceImageUrl when missing", () => {
+    const loc = {
+      seasons: [{ name: "spring", url: "https://r2/loc/spring.png" }],
+    }
+    const result = resolveLocationFields(loc)
+    expect(result).toEqual([
+      { key: "seasons[0]", label: "seasons / spring", url: "https://r2/loc/spring.png" },
+    ])
+  })
+
+  it("treats missing buckets and non-array buckets as empty", () => {
+    const loc = {
+      sourceImageUrl: "https://r2/loc/main.png",
+      // bucket omitted entirely
+      weather: undefined,
+      // non-array values should not throw
+      seasons: null as unknown as Array<{ name: string; url: string }>,
+    }
+    const result = resolveLocationFields(loc)
+    expect(result).toEqual([
+      { key: "sourceImageUrl", label: "Main image", url: "https://r2/loc/main.png" },
+    ])
+  })
+
+  it("returns an empty array when the location has no fields at all", () => {
+    expect(resolveLocationFields({})).toEqual([])
+  })
+})
+
+describe("resolveFieldMappings — edgeSourceForField precedence", () => {
+  it("prefers an edge source over data.fieldMappings and over the typed value", () => {
+    const data = { style: "typed-style", fieldMappings: { style: { sourceNodeId: "mapped" } } }
+    const out = resolveFieldMappings(
+      data,
+      undefined,
+      ["style"],
+      (id) => (id === "edge" ? "EDGE TEXT" : id === "mapped" ? "MAPPED TEXT" : undefined),
+      (field) => (field === "style" ? "edge" : undefined),
+    )
+    expect(out.style).toBe("EDGE TEXT")
+  })
+
+  it("falls back to data.fieldMappings when no edge source", () => {
+    const data = { style: "x", fieldMappings: { style: { sourceNodeId: "mapped" } } }
+    const out = resolveFieldMappings(data, undefined, ["style"], () => "MAPPED TEXT", () => undefined)
+    expect(out.style).toBe("MAPPED TEXT")
+  })
+
+  it("leaves the field untouched when neither edge nor mapping resolves", () => {
+    const data = { style: "keep" }
+    const out = resolveFieldMappings(data, undefined, ["style"], () => undefined, () => undefined)
+    expect(out.style).toBe("keep")
+  })
+})
+
+describe("fieldKeyFromHandle", () => {
+  it("strips the field- prefix", () => { expect(fieldKeyFromHandle("field-style")).toBe("style") })
+  it("returns null for non-field handles", () => { expect(fieldKeyFromHandle("prompt")).toBeNull() })
+})

package/src/__tests__/resolve-pipeline-model.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect } from "vitest"
+import { resolvePipelineModel, type PipelineConfig } from "../pipeline-types.js"
+
+describe("resolvePipelineModel", () => {
+  it("returns undefined when config is null/undefined", () => {
+    expect(resolvePipelineModel(undefined, "characters_image")).toBeUndefined()
+    expect(resolvePipelineModel(null, "shots_video")).toBeUndefined()
+  })
+
+  it("returns undefined when neither stage_models nor global field is set", () => {
+    const config: Partial<PipelineConfig> = {}
+    expect(resolvePipelineModel(config, "characters_image")).toBeUndefined()
+    expect(resolvePipelineModel(config, "shots_video")).toBeUndefined()
+    expect(resolvePipelineModel(config, "script_llm")).toBeUndefined()
+  })
+
+  it("returns the global image_model for any *_image stage when stage_models is absent", () => {
+    const config: Partial<PipelineConfig> = { image_model: "flux" }
+    expect(resolvePipelineModel(config, "characters_image")).toBe("flux")
+    expect(resolvePipelineModel(config, "locations_image")).toBe("flux")
+    expect(resolvePipelineModel(config, "objects_image")).toBe("flux")
+    expect(resolvePipelineModel(config, "scene_keyframes_image")).toBe("flux")
+  })
+
+  it("returns the global video_model for *_video stages", () => {
+    const config: Partial<PipelineConfig> = { video_model: "kling" }
+    expect(resolvePipelineModel(config, "shots_video")).toBe("kling")
+  })
+
+  it("returns the global script_llm for the script_llm stage", () => {
+    const config: Partial<PipelineConfig> = { script_llm: "claude-opus-4-6" }
+    expect(resolvePipelineModel(config, "script_llm")).toBe("claude-opus-4-6")
+  })
+
+  it("per-stage override beats the matching global field", () => {
+    const config: Partial<PipelineConfig> = {
+      image_model: "flux",
+      stage_models: { characters_image: "nano-banana-pro" },
+    }
+    expect(resolvePipelineModel(config, "characters_image")).toBe("nano-banana-pro")
+    // Sibling stages still get the global pick.
+    expect(resolvePipelineModel(config, "locations_image")).toBe("flux")
+    expect(resolvePipelineModel(config, "objects_image")).toBe("flux")
+    expect(resolvePipelineModel(config, "scene_keyframes_image")).toBe("flux")
+  })
+
+  it("per-stage overrides work independently across kinds", () => {
+    const config: Partial<PipelineConfig> = {
+      image_model: "flux",
+      video_model: "kling",
+      script_llm: "claude-sonnet-4-6",
+      stage_models: {
+        scene_keyframes_image: "gpt-image",
+        shots_video: "veo3",
+        script_llm: "claude-opus-4-6",
+      },
+    }
+    expect(resolvePipelineModel(config, "scene_keyframes_image")).toBe("gpt-image")
+    expect(resolvePipelineModel(config, "shots_video")).toBe("veo3")
+    expect(resolvePipelineModel(config, "script_llm")).toBe("claude-opus-4-6")
+    // Entity image stages keep the global pick.
+    expect(resolvePipelineModel(config, "characters_image")).toBe("flux")
+  })
+
+  it("an explicit empty string in stage_models is treated as 'not set' so the global wins (defense-in-depth)", () => {
+    // The Zod schema now rejects empty strings (the enum doesn't include ""),
+    // but the resolver still defensively treats falsy stage values as
+    // unset — in case a record bypasses Zod (DB hand-edit, legacy row, etc.).
+    // The cast below acknowledges we're testing a state Zod won't produce.
+    const config = {
+      image_model: "flux",
+      stage_models: { characters_image: "" },
+    } as unknown as Partial<PipelineConfig>
+    expect(resolvePipelineModel(config, "characters_image")).toBe("flux")
+  })
+})

package/src/__tests__/scene-node-types.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from "vitest"
+import { ShotSpecSchema, MatchCutVerdictSchema } from "../scene-node-types.js"
+
+// ─── minimal valid ShotSpec fixture ─────────────────────────────────────────
+const baseShotSpec = {
+  shot_id: "shot_01",
+  camera: {
+    shot_type: "wide" as const,
+    angle: "eye_level" as const,
+    motion: "static" as const,
+  },
+  shot_intensity_kind: "establishing_shot" as const,
+  action: "Character walks through door",
+  dialogue_line: null,
+  duration_seconds: 3,
+  motion_prompt: "Slow push forward",
+  start_state: "Character at door",
+  end_state: "Character inside room",
+  continuity_with_previous: null,
+  shot_intent: {
+    needs_multishot_reference: false,
+    is_loopable: false,
+    needs_music_suppression: true,
+    is_match_cut: true,
+  },
+  visual_keyframe_prompt: "Wide shot of character walking through a doorway",
+}
+
+// ─── A1: ShotSpec.accepted_match_cut_break ───────────────────────────────────
+
+describe("ShotSpec.accepted_match_cut_break (Phase 1D.1 Method 7)", () => {
+  it("accepts accepted_match_cut_break=true", () => {
+    const result = ShotSpecSchema.safeParse({
+      ...baseShotSpec,
+      accepted_match_cut_break: true,
+    })
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.accepted_match_cut_break).toBe(true)
+    }
+  })
+
+  it("defaults to undefined when omitted", () => {
+    const result = ShotSpecSchema.safeParse(baseShotSpec)
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.accepted_match_cut_break).toBeUndefined()
+    }
+  })
+})
+
+// ─── A2: MatchCutVerdictSchema ────────────────────────────────────────────────
+
+describe("MatchCutVerdictSchema (Phase 1D.1 Method 7)", () => {
+  it("parses a valid match-cut verdict", () => {
+    const verdict = {
+      shot_pair: ["shot_01", "shot_02"] as [string, string],
+      match_strength: "strong" as const,
+      suggested_adjustments: "Align the door frame position in both shots.",
+      checked_at: new Date().toISOString(),
+    }
+    const result = MatchCutVerdictSchema.safeParse(verdict)
+    expect(result.success).toBe(true)
+    if (result.success) {
+      expect(result.data.shot_pair).toEqual(["shot_01", "shot_02"])
+      expect(result.data.match_strength).toBe("strong")
+    }
+  })
+
+  it("rejects an invalid match_strength value", () => {
+    const verdict = {
+      shot_pair: ["shot_01", "shot_02"],
+      match_strength: "excellent", // not in the enum
+      suggested_adjustments: "Some suggestion",
+      checked_at: new Date().toISOString(),
+    }
+    const result = MatchCutVerdictSchema.safeParse(verdict)
+    expect(result.success).toBe(false)
+  })
+})