@nodaro/shared 1.4.1

package/src/__tests__/video-utils.test.ts

@@ -0,0 +1,303 @@
+import { describe, it, expect } from "vitest"
+import {
+  VIDEO_UTIL_PRICING,
+  estimateLoopVideoCredits,
+  estimateTrimVideoCredits,
+  estimateCombineVideosCredits,
+} from "../credit-estimators/video-utils.js"
+import {
+  estimateLoopTrimAddonCredits,
+  type LoopTrimEstimatorInput,
+} from "../credit-estimators/video-utils.js"
+import { assembleNarratedVideoCredits } from "../credit-estimators/video-utils.js"
+
+describe("estimateLoopVideoCredits", () => {
+  describe("repeat mode", () => {
+    it("uses upstream duration when provided", () => {
+      // 4× a 5s clip = 20s output → ceil(20/5) = 4
+      expect(estimateLoopVideoCredits({ mode: "repeat", repeatCount: 4 }, 5)).toBe(4)
+    })
+
+    it("falls back to 8s per repeat when upstream duration is missing", () => {
+      // 4 × 8 = 32s → ceil(32/5) = 7
+      expect(estimateLoopVideoCredits({ mode: "repeat", repeatCount: 4 })).toBe(7)
+    })
+
+    it("defaults repeatCount to 2 when missing", () => {
+      // 2 × 8 = 16s → ceil(16/5) = 4
+      expect(estimateLoopVideoCredits({ mode: "repeat" })).toBe(4)
+    })
+  })
+
+  describe("duration mode", () => {
+    it("uses targetDuration regardless of upstream", () => {
+      // ceil(60/5) = 12
+      expect(estimateLoopVideoCredits({ mode: "duration", targetDuration: 60 }, 5)).toBe(12)
+    })
+
+    it("defaults targetDuration to fallback when missing", () => {
+      // ceil(8/5) = 2
+      expect(estimateLoopVideoCredits({ mode: "duration" })).toBe(2)
+    })
+  })
+
+  describe("smart-loop-cut adder", () => {
+    it("adds ceil(lookback/24) when enabled", () => {
+      // 30s base = 6, lookback 16 → ceil(16/24) = 1, total 7
+      expect(estimateLoopVideoCredits({
+        mode: "duration", targetDuration: 30,
+        smartLoopCutBeforeRepeat: true, smartLoopCutLookback: 16,
+      })).toBe(7)
+    })
+
+    it("uses default lookback 16 when smart-cut on but lookback missing", () => {
+      // 60s base = 12, default lookback 16 → +1 = 13
+      expect(estimateLoopVideoCredits({
+        mode: "duration", targetDuration: 60,
+        smartLoopCutBeforeRepeat: true,
+      })).toBe(13)
+    })
+
+    it("max lookback 64 stays within bound", () => {
+      // 60s base = 12, lookback 64 → ceil(64/24) = 3, total 15
+      expect(estimateLoopVideoCredits({
+        mode: "duration", targetDuration: 60,
+        smartLoopCutBeforeRepeat: true, smartLoopCutLookback: 64,
+      })).toBe(15)
+    })
+
+    it("does NOT add when smartLoopCutBeforeRepeat is false", () => {
+      expect(estimateLoopVideoCredits({
+        mode: "duration", targetDuration: 60,
+        smartLoopCutBeforeRepeat: false, smartLoopCutLookback: 64,
+      })).toBe(12)
+    })
+  })
+
+  describe("min-1 floor", () => {
+    it("never returns 0 — even for sub-second output", () => {
+      expect(estimateLoopVideoCredits({ mode: "duration", targetDuration: 0.5 })).toBe(1)
+    })
+  })
+
+  describe("constants", () => {
+    it("exports the expected pricing constants", () => {
+      expect(VIDEO_UTIL_PRICING.CREDITS_PER_5_SEC).toBe(1)
+      expect(VIDEO_UTIL_PRICING.FRAMES_PER_CREDIT).toBe(24)
+      expect(VIDEO_UTIL_PRICING.FALLBACK_DURATION_SECONDS).toBe(8)
+    })
+  })
+})
+
+describe("estimateTrimVideoCredits", () => {
+  describe("time mode (default)", () => {
+    it("computes credits from endTime - startTime", () => {
+      // 0–10s = 10s → ceil(10/5) = 2
+      expect(estimateTrimVideoCredits({ trimMode: "time", startTime: 0, endTime: 10 })).toBe(2)
+    })
+
+    it("treats missing trimMode as time mode", () => {
+      // ceil(15/5) = 3
+      expect(estimateTrimVideoCredits({ startTime: 5, endTime: 20 })).toBe(3)
+    })
+
+    it("defaults missing start/end to 0", () => {
+      // 0-0 = 0s, but min-1 → 1
+      expect(estimateTrimVideoCredits({ trimMode: "time" })).toBe(1)
+    })
+  })
+
+  describe("frames mode", () => {
+    it("subtracts trim frames from upstream duration at 24fps", () => {
+      // 10s upstream - 24/24 - 24/24 = 8s → ceil(8/5) = 2
+      expect(estimateTrimVideoCredits({
+        trimMode: "frames", trimStartFrames: 24, trimEndFrames: 24,
+      }, 10)).toBe(2)
+    })
+
+    it("uses 8s fallback when upstream missing", () => {
+      // 8s - 0 - 0 = 8s → ceil(8/5) = 2
+      expect(estimateTrimVideoCredits({ trimMode: "frames" })).toBe(2)
+    })
+
+    it("clamps to 0 if frame trim exceeds duration", () => {
+      // 5s - 240/24 - 0 = -5 clamped to 0 → max(1, ceil(0)) = 1
+      expect(estimateTrimVideoCredits({
+        trimMode: "frames", trimStartFrames: 240, trimEndFrames: 0,
+      }, 5)).toBe(1)
+    })
+  })
+
+  describe("smart-loop-cut mode", () => {
+    it("upstream-based base + lookback adder", () => {
+      // 10s upstream → base 2, lookback 16 → +1 = 3
+      expect(estimateTrimVideoCredits({
+        trimMode: "smart-loop-cut", smartLoopCutLookback: 16,
+      }, 10)).toBe(3)
+    })
+
+    it("uses default lookback 16 when missing", () => {
+      // 8s upstream → base 2, default 16 → +1 = 3
+      expect(estimateTrimVideoCredits({ trimMode: "smart-loop-cut" })).toBe(3)
+    })
+  })
+
+  describe("seconds mode (relative trim in seconds)", () => {
+    it("subtracts trim seconds from upstream duration", () => {
+      // 30s - 2 - 3 = 25s → ceil(25/5) = 5
+      expect(estimateTrimVideoCredits({
+        trimMode: "seconds", trimStartSeconds: 2, trimEndSeconds: 3,
+      }, 30)).toBe(5)
+    })
+
+    it("clamps to min 1 credit if trim exceeds duration", () => {
+      // 5s - 10 - 0 = -5 clamp to 0 → max(1, ceil(0)) = 1
+      expect(estimateTrimVideoCredits({
+        trimMode: "seconds", trimStartSeconds: 10,
+      }, 5)).toBe(1)
+    })
+  })
+
+  describe("keep-first-seconds mode", () => {
+    it("output is min(upstream, keepFirstSeconds)", () => {
+      // keepFirst=8, upstream=20 → output 8s → ceil(8/5) = 2
+      expect(estimateTrimVideoCredits({
+        trimMode: "keep-first-seconds", keepFirstSeconds: 8,
+      }, 20)).toBe(2)
+    })
+
+    it("clamps to upstream when keep > upstream", () => {
+      // keepFirst=30, upstream=5 → output 5s → ceil(5/5) = 1
+      expect(estimateTrimVideoCredits({
+        trimMode: "keep-first-seconds", keepFirstSeconds: 30,
+      }, 5)).toBe(1)
+    })
+  })
+
+  describe("keep-last-seconds mode", () => {
+    it("output is min(upstream, keepLastSeconds)", () => {
+      // keepLast=10, upstream=30 → output 10s → ceil(10/5) = 2
+      expect(estimateTrimVideoCredits({
+        trimMode: "keep-last-seconds", keepLastSeconds: 10,
+      }, 30)).toBe(2)
+    })
+
+    it("uses 8s fallback when upstream missing", () => {
+      // keepLast=10, upstream undefined → upstream=8 → min(8,10)=8 → ceil(8/5)=2
+      expect(estimateTrimVideoCredits({
+        trimMode: "keep-last-seconds", keepLastSeconds: 10,
+      })).toBe(2)
+    })
+  })
+})
+
+describe("estimateCombineVideosCredits", () => {
+  it("2 inputs with cut transition", () => {
+    // 5+5=10s, cut → 0 transition overlap, 0 frame trim, numInputs-2=0
+    // → ceil(10/5) + 0 = 2
+    expect(estimateCombineVideosCredits({ transition: "cut" }, [5, 5])).toBe(2)
+  })
+
+  it("3 inputs with fade transition (0.5s)", () => {
+    // 10+10+10=30s, 2 fades × 0.5 = 1s overlap → 29s → ceil(29/5)=6
+    // numInputs-2 = 1 → 6 + 1 = 7
+    expect(estimateCombineVideosCredits({
+      transition: "fade", transitionDuration: 0.5,
+    }, [10, 10, 10])).toBe(7)
+  })
+
+  it("5 inputs with dissolve and per-clip frame trim (24+24)", () => {
+    // 5×8=40s, 4 transitions × 0.5 = 2s overlap, frame trim 48/24=2s × 5 = 10s
+    // → 40 - 2 - 10 = 28s → ceil(28/5) = 6
+    // numInputs-2 = 3 → 6 + 3 = 9
+    expect(estimateCombineVideosCredits({
+      transition: "dissolve",
+      transitionDuration: 0.5,
+      trimStartFrames: 24,
+      trimEndFrames: 24,
+    }, [8, 8, 8, 8, 8])).toBe(9)
+  })
+
+  it("falls back to 8s per missing upstream entry", () => {
+    // [undef, undef, undef] → 3×8=24s, cut → ceil(24/5)=5, +1 (numInputs-2) = 6
+    expect(estimateCombineVideosCredits(
+      { transition: "cut" },
+      [undefined, undefined, undefined],
+    )).toBe(6)
+  })
+
+  it("treats empty input array as 2-input fallback", () => {
+    // numInputs = 0 || 2 = 2; total = 0 → max(1, …) = 1
+    expect(estimateCombineVideosCredits({ transition: "cut" }, [])).toBe(1)
+  })
+
+  it("min-1 floor when total clamps to 0", () => {
+    // 2 × 0s = 0, no overlap, num-2=0 → max(1, ceil(0)) = 1
+    expect(estimateCombineVideosCredits({ transition: "cut" }, [0, 0])).toBe(1)
+  })
+
+  it("does not subtract transition overlap on cut", () => {
+    // [10, 10] cut → ceil(20/5)=4, numInputs-2=0 → 4
+    expect(estimateCombineVideosCredits({ transition: "cut", transitionDuration: 999 }, [10, 10])).toBe(4)
+  })
+
+  it("uses default transitionDuration 0.5 when missing on a non-cut", () => {
+    // [10, 10] fade, no transitionDuration → 20 - 0.5 = 19.5 → ceil(19.5/5)=4
+    expect(estimateCombineVideosCredits({ transition: "fade" }, [10, 10])).toBe(4)
+  })
+})
+
+describe("estimateLoopTrimAddonCredits", () => {
+  it("returns 0 when loopTrim is undefined", () => {
+    expect(estimateLoopTrimAddonCredits(undefined, 8)).toBe(0)
+  })
+
+  it("returns 0 when enabled is false", () => {
+    expect(estimateLoopTrimAddonCredits({ enabled: false }, 8)).toBe(0)
+  })
+
+  it("computes ceil(duration/5) + ceil(framesToTest/24) when enabled", () => {
+    // 8s / 5 = 2 (ceil), 16 / 24 = 1 (ceil) → 3
+    expect(estimateLoopTrimAddonCredits({ enabled: true, framesToTest: 16 }, 8)).toBe(3)
+  })
+
+  it("uses default framesToTest=16 when omitted", () => {
+    // 10s / 5 = 2, 16 / 24 = 1 → 3
+    expect(estimateLoopTrimAddonCredits({ enabled: true }, 10)).toBe(3)
+  })
+
+  it("clamps framesToTest to 64 max", () => {
+    // 8s / 5 = 2, 64 / 24 = 3 → 5
+    expect(estimateLoopTrimAddonCredits({ enabled: true, framesToTest: 999 }, 8)).toBe(5)
+  })
+
+  it("clamps framesToTest to 1 min", () => {
+    // 8s / 5 = 2, 1 / 24 = 1 → 3
+    expect(estimateLoopTrimAddonCredits({ enabled: true, framesToTest: 0 }, 8)).toBe(3)
+  })
+
+  it("scales with output duration", () => {
+    // 60s / 5 = 12, 16 / 24 = 1 → 13
+    expect(estimateLoopTrimAddonCredits({ enabled: true, framesToTest: 16 }, 60)).toBe(13)
+  })
+
+  it("returns 0 when framesToTest=64 but enabled is false (precedence)", () => {
+    expect(estimateLoopTrimAddonCredits({ enabled: false, framesToTest: 64 }, 60)).toBe(0)
+  })
+})
+
+describe("assembleNarratedVideoCredits", () => {
+  it("matches the worked examples 6→4, 24→7, 60→13", () => {
+    expect(assembleNarratedVideoCredits(6)).toBe(4)
+    expect(assembleNarratedVideoCredits(24)).toBe(7)
+    expect(assembleNarratedVideoCredits(60)).toBe(13)
+  })
+
+  it("is 3 flat credits at the theoretical N=0 floor (never shown directly — call sites clamp N to 1)", () => {
+    expect(assembleNarratedVideoCredits(0)).toBe(3)
+  })
+
+  it("returns the 1-block floor of 4 credits", () => {
+    expect(assembleNarratedVideoCredits(1)).toBe(4)
+  })
+})

package/src/__tests__/voice-changer-models.test.ts

@@ -0,0 +1,33 @@
+import { describe, it, expect } from "vitest"
+import {
+  VOICE_CHANGER_MODELS,
+  VOICE_CHANGER_MODEL_IDS,
+  DEFAULT_VOICE_CHANGER_MODEL,
+} from "../voice-changer-models.js"
+
+describe("voice-changer-models", () => {
+  it("exposes the ElevenLabs speech-to-speech models", () => {
+    expect(VOICE_CHANGER_MODEL_IDS).toEqual([
+      "eleven_multilingual_sts_v2",
+      "eleven_english_sts_v2",
+    ])
+  })
+
+  it("defaults to the Multilingual model (ElevenLabs-recommended, even for English)", () => {
+    // ElevenLabs' docs recommend Multilingual v2 even for English source
+    // audio (it often outperforms the English-only model), and it's
+    // required for non-English audio — so it's the default. English v2
+    // remains selectable.
+    expect(DEFAULT_VOICE_CHANGER_MODEL).toBe("eleven_multilingual_sts_v2")
+    expect(VOICE_CHANGER_MODEL_IDS).toContain(DEFAULT_VOICE_CHANGER_MODEL)
+  })
+
+  it("gives every model a non-empty label and description for the picker", () => {
+    expect(VOICE_CHANGER_MODELS.length).toBe(VOICE_CHANGER_MODEL_IDS.length)
+    for (const m of VOICE_CHANGER_MODELS) {
+      expect(m.value.length).toBeGreaterThan(0)
+      expect(m.label.length).toBeGreaterThan(0)
+      expect(m.desc.length).toBeGreaterThan(0)
+    }
+  })
+})

package/src/__tests__/workflow-export-strip.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from "vitest"
+import { stripExportContent } from "../workflow-export.js"
+import { EXECUTION_DATA_KEYS } from "../node-runtime-keys.js"
+import type { GenericNode } from "../types.js"
+
+/**
+ * Invariant guard for the template-export leak class (audit R2-H4): a
+ * "shareable" template export must never carry runtime/result fields —
+ * generated media URLs, internal job ids, trained-LoRA identity, etc. Those
+ * are enumerated in EXECUTION_DATA_KEYS (the single source of truth), and
+ * GENERATED_FIELDS is built from it, so this test fails the moment a new
+ * runtime key is added without being covered.
+ */
+describe("stripExportContent — template export hygiene", () => {
+  // `shots` lives in EXECUTION_DATA_KEYS but is user config (Kling-3.0
+  // storyboard) — it must SURVIVE a template export, not be stripped.
+  const CONFIG_KEPT = new Set(["shots"])
+
+  it("strips runtime/result EXECUTION_DATA_KEYS while keeping config fields", () => {
+    const data: Record<string, unknown> = {}
+    for (const key of EXECUTION_DATA_KEYS) data[key] = "SENSITIVE_RUNTIME_VALUE"
+    data.prompt = "keep me" // a real config field — must survive the strip
+    data.provider = "veo3.1"
+
+    const node: GenericNode = { id: "n1", type: "generate-video", data }
+    const [out] = stripExportContent([node])
+    const outData = out.data as Record<string, unknown>
+
+    for (const key of EXECUTION_DATA_KEYS) {
+      if (CONFIG_KEPT.has(key)) continue
+      expect(outData[key], `${key} must be stripped from a template export`).toBeUndefined()
+    }
+    expect(outData.prompt).toBe("keep me")
+    expect(outData.provider).toBe("veo3.1")
+    // Regression guard: Kling-3.0 multishot config must survive template export.
+    expect(outData.shots, "shots (Kling-3 config) must NOT be stripped").toBe("SENSITIVE_RUNTIME_VALUE")
+  })
+
+  it("clears faceDbId / referencedWorkflowId on face + sub-workflow template nodes", () => {
+    const face: GenericNode = { id: "f1", type: "face", data: { faceDbId: "exporter-face-id", name: "Hero" } }
+    const sub: GenericNode = { id: "s1", type: "sub-workflow", data: { referencedWorkflowId: "exporter-wf-id" } }
+    const [outFace, outSub] = stripExportContent([face, sub])
+    expect((outFace.data as Record<string, unknown>).faceDbId).toBeUndefined()
+    expect((outSub.data as Record<string, unknown>).referencedWorkflowId).toBeUndefined()
+  })
+})

package/src/ai-avatar-pricing.ts

@@ -0,0 +1,213 @@
+/**
+ * AI Avatar (HeyGen) duration-bucketing + credit-identifier helpers.
+ * Single source of truth for the NON-monetary side of ai-avatar billing
+ * (duration estimation, bucket selection, composite credit-id construction) —
+ * imported by the frontend node UI (to build the id it hands to the
+ * `/v1/credits/model-cost` display lookup) AND the backend route/orchestrator
+ * (to resolve the credit-guard reservation id pre-Zod).
+ *
+ * The provider-$ rate table and the USD/credit cost FORMULAS derived from it
+ * live in `backend/src/lib/pricing/ai-avatar-cost.ts` (core, not ee/ — the
+ * HeyGen provider integration needs them regardless of edition). They were
+ * moved out of this package (published Apache-2.0 on npm — an irrevocable
+ * grant) per the 2026-07-06 public-flip IP audit, S5.
+ */
+
+export type AiAvatarEngine = "avatar-v" | "avatar-iv"
+export type AiAvatarResolution = "720p" | "1080p" | "4k"
+
+/**
+ * Worst-case clip duration used as the credit-reserve ceiling.
+ * A 5000-character script at voiceSpeed 0.5 ≈ 5000/12/0.5 ≈ 833s → top bucket 900s.
+ */
+export const AI_AVATAR_MAX_DURATION_SEC = 900
+
+/**
+ * Duration buckets (seconds) used to pick a reserve ceiling at creditGuard
+ * time, when the actual clip length is unknown (text-mode scripts) or only
+ * known via a server-side ffprobe (audio mode).
+ *
+ * The low end is FINE-GRAINED (5/10/15/30/60s) so short clips — the common
+ * case — don't over-reserve. A 15s clip lands in the 15s bucket, not the old
+ * coarse 30s floor (which doubled the hold). The high end stays coarse because
+ * long-form scripts are rare and the bucket-up is a one-time refundable surplus.
+ *
+ * Bucket selection:
+ *   - Text mode:  bucket = pickAiAvatarBucket(ceil(scriptChars / 12 / voiceSpeed)).
+ *   - Audio mode: bucket = pickAiAvatarBucket(ceil(probedDurationSec)) when the
+ *     ffprobe preHandler stashed `__probedDurationSec` on the body; otherwise a
+ *     MODEST 120s default (NOT the 900s top bucket — that was the bug: it
+ *     reserved ~4000+ credits for a sub-minute clip).
+ *
+ * Worst-case derivation: 5000 chars at voiceSpeed=0.5 → ceil(5000/12/0.5) = 834s
+ * → fits in 900s bucket. The 900s top bucket covers all legal text inputs.
+ *
+ * Note: audio >900s (no probe) would undercharge against the 120s default, but
+ * the commit-time metered true-up CANNOT charge more than reserved — so a long
+ * un-probed audio clip is a (small) revenue leak, not an over-charge. The probe
+ * closes it for the normal path. The 900s bucket remains available for the
+ * probed long-audio case.
+ */
+export const AI_AVATAR_DURATION_BUCKETS = [5, 10, 15, 30, 60, 120, 240, 360, 600, 900] as const
+
+/**
+ * Modest fallback bucket (seconds) for AUDIO mode when the ffprobe preHandler
+ * did NOT stash a probed duration. Replaces the old 900s top-bucket fallback
+ * that over-reserved ~4000+ credits for short clips. The commit-time metered
+ * true-up is refund-only, so this is a reserve ceiling, not a charge.
+ */
+export const AI_AVATAR_AUDIO_FALLBACK_SEC = 120
+
+/**
+ * Hard cap (seconds) on AUDIO-mode clip length. HeyGen has no natural length
+ * limit on an audio-driven avatar, so a long audio = an expensive / possibly
+ * rejected generation and a bounded under-reserve window. We cap it here:
+ *   - The worker TRIMS incoming audio longer than this down to AI_AVATAR_MAX_AUDIO_SEC
+ *     (and warns the user, non-fatal).
+ *   - The credit RESERVE is capped at this bucket too: even a 30-min probed
+ *     audio buckets at 600s, never the 900s top bucket. Because the worker
+ *     trims the actual clip to ≤600s, the metered true-up can only refund.
+ *
+ * Text mode (5000-char script) and cinematic (4–15s) are bounded elsewhere and
+ * are NOT affected by this cap.
+ */
+export const AI_AVATAR_MAX_AUDIO_SEC = 600
+
+export type AiAvatarDurationBucket = (typeof AI_AVATAR_DURATION_BUCKETS)[number]
+
+const ALLOWED_ENGINES = new Set<AiAvatarEngine>(["avatar-v", "avatar-iv"])
+const ALLOWED_RESOLUTIONS = new Set<AiAvatarResolution>(["720p", "1080p", "4k"])
+
+/**
+ * Estimate script duration in seconds from character count and voice speed.
+ *
+ * Uses ~12 chars/sec at normal speed (voiceSpeed=1) — deliberately generous
+ * (biased high) so the credit hold covers TTS pacing variations. Slower speech
+ * (voiceSpeed < 1) produces a longer clip and thus a higher estimate.
+ * Minimum 1s.
+ *
+ * @param script     Script text (undefined treated as empty).
+ * @param voiceSpeed HeyGen voice speed parameter, range 0.5–1.5 (default 1).
+ *                   Slower speed → more seconds → higher hold.
+ */
+export function estimateScriptDurationSec(script: string | undefined, voiceSpeed = 1): number {
+  const speed = Math.min(1.5, Math.max(0.5, voiceSpeed || 1))
+  return Math.max(1, Math.ceil((script?.length ?? 0) / 12 / speed))
+}
+
+/**
+ * Pick the smallest duration bucket that is ≥ sec.
+ * Falls back to the maximum bucket (900s) when sec exceeds all buckets.
+ */
+export function pickAiAvatarBucket(sec: number): AiAvatarDurationBucket {
+  for (const b of AI_AVATAR_DURATION_BUCKETS) {
+    if (sec <= b) return b
+  }
+  return 900
+}
+
+/**
+ * Composite credit identifier for a duration-bucketed reserve.
+ *
+ * Format: `"heygen-<engine>:<resolution>:<bucketSec>s"`
+ * e.g. `"heygen-avatar-iv:720p:60s"`.
+ */
+export function aiAvatarReserveCreditId(
+  engine: AiAvatarEngine,
+  resolution: AiAvatarResolution,
+  bucketSec: number,
+): string {
+  return `heygen-${engine}:${resolution}:${bucketSec}s`
+}
+
+/**
+ * Resolve the credit identifier from a raw request body BEFORE Zod validation.
+ * Called at creditGuard preHandler time — mirrors how `resolveLipSyncIdentifier`
+ * reads the raw body in `backend/src/routes/lip-sync.ts`.
+ *
+ * - `speechMode === "text"`: bucket by estimated script duration, accounting for
+ *   voiceSpeed (slower → longer clip → larger bucket). Surplus is refunded at commit.
+ * - Any other speechMode (audio / missing): bucket by `__probedDurationSec` when
+ *   the ffprobe preHandler stashed it on the raw body; otherwise a MODEST 120s
+ *   default (AI_AVATAR_AUDIO_FALLBACK_SEC) — NOT the 900s top bucket. Reserving
+ *   the 900s ceiling for a sub-minute audio clip was the over-reservation bug
+ *   (~4000+ credits held for a clip that costs ~40). The commit-time metered
+ *   true-up is refund-only, so a modest reserve never over-charges. The effective
+ *   seconds are ALSO capped at AI_AVATAR_MAX_AUDIO_SEC (600s) — the worker trims
+ *   audio longer than that, so a 30-min audio reserves the 600s bucket, never 900s.
+ *
+ * - `avatarSource === "image"`: image-source mode is IV-class (HeyGen's own
+ *   engine, no avatar_id) — bill at the avatar-iv rate regardless of the
+ *   (ignored) `engine` field, reusing the existing heygen-avatar-iv:* ids.
+ *
+ * Falls back to ("avatar-iv", "720p", 120s) when fields are missing or invalid.
+ */
+export function resolveAiAvatarCreditId(
+  body: Record<string, unknown> | undefined,
+): string {
+  const rawEngine = body?.engine as string | undefined
+  const rawResolution = body?.resolution as string | undefined
+  const speechMode = body?.speechMode as string | undefined
+  const avatarSource = body?.avatarSource as string | undefined
+
+  // Image-source mode is IV-class (its own engine, no IV/V lever) — pin the
+  // rate engine to avatar-iv and reuse the existing heygen-avatar-iv:* ids.
+  const engine: AiAvatarEngine =
+    avatarSource === "image"
+      ? "avatar-iv"
+      : rawEngine !== undefined && ALLOWED_ENGINES.has(rawEngine as AiAvatarEngine)
+        ? (rawEngine as AiAvatarEngine)
+        : "avatar-iv"
+
+  const resolution: AiAvatarResolution =
+    rawResolution !== undefined && ALLOWED_RESOLUTIONS.has(rawResolution as AiAvatarResolution)
+      ? (rawResolution as AiAvatarResolution)
+      : "720p"
+
+  let bucketSec: AiAvatarDurationBucket
+  if (speechMode === "text") {
+    // voiceSpeed is a float in [0.5, 1.5]; coerce to number, default 1.
+    // Slower speed → more seconds → larger bucket → larger hold (no undercharge).
+    const voiceSpeed = Number(body?.voiceSpeed) || 1
+    bucketSec = pickAiAvatarBucket(
+      estimateScriptDurationSec(body?.script as string | undefined, voiceSpeed),
+    )
+  } else {
+    // Audio/unknown mode. The ffprobe preHandler (video-sfx pattern) stashes
+    // the measured clip length on the raw body as `__probedDurationSec` so we
+    // can bucket by the ACTUAL audio duration. When present, bucket by it;
+    // otherwise fall back to a MODEST 120s default — NOT the 900s top bucket.
+    // The old 900s fallback over-reserved ~4000+ credits for sub-minute clips.
+    //
+    // Effective seconds are capped at AI_AVATAR_MAX_AUDIO_SEC (600s): audio mode
+    // has no natural length limit, so the worker TRIMS the actual clip to ≤600s
+    // and we cap the RESERVE at the matching 600s bucket. A 30-min probed audio
+    // thus reserves the 600s bucket, never the 900s top bucket. Since the worker
+    // trims actual to ≤600s, the metered commit can only refund.
+    const probed = Number(body?.__probedDurationSec)
+    const effectiveSec = Math.min(
+      Number.isFinite(probed) && probed > 0
+        ? Math.ceil(probed)
+        : AI_AVATAR_AUDIO_FALLBACK_SEC,
+      AI_AVATAR_MAX_AUDIO_SEC,
+    )
+    bucketSec = pickAiAvatarBucket(effectiveSec)
+  }
+
+  return aiAvatarReserveCreditId(engine, resolution, bucketSec)
+}
+
+/**
+ * All 60 reserve credit IDs — every (engine × resolution × bucket) combination.
+ * 2 engines × 3 resolutions × 10 buckets (5/10/15/30/60/120/240/360/600/900s) = 60.
+ * Seeded in STATIC_CREDIT_COSTS and the model_pricing migration so
+ * getModelCreditBaseCost never hard-fails (503 price_not_configured) for any
+ * legal creditGuard input.
+ */
+export const AI_AVATAR_RESERVE_IDS: string[] = [...ALLOWED_ENGINES].flatMap((engine) =>
+  [...ALLOWED_RESOLUTIONS].flatMap((resolution) =>
+    AI_AVATAR_DURATION_BUCKETS.map((bucketSec) =>
+      aiAvatarReserveCreditId(engine, resolution, bucketSec),
+    ),
+  ),
+)

package/src/ancestor-refs.ts

@@ -0,0 +1,48 @@
+/**
+ * Ancestor reference image collection — traverses upstream nodes to find
+ * image-producing ancestors, with passthrough for text/logic nodes.
+ * Shared between frontend and backend via a callback for extracting image URLs.
+ */
+
+import type { GenericNode, GenericEdge } from "./types.js"
+
+// Node types that produce reference images
+export const IMAGE_REF_TYPES = new Set([
+  "upload-image", "face", "character", "object", "creature", "location",
+  "generate-image", "edit-image", "image-to-image",
+])
+
+// Node types that pass through (don't produce images but connect to ancestors that do)
+export const PASSTHROUGH_TYPES = new Set([
+  "ai-writer", "llm-chat", "split-text", "combine-text", "text-prompt", "list",
+])
+
+/**
+ * Collect reference image URLs from upstream ancestor nodes.
+ * @param getImageUrl - Callback to extract an image URL from a node. Frontend uses
+ *   extractNodeOutput(), backend uses nodeStates[id]?.output?.imageUrl.
+ */
+export function collectAncestorRefs<N extends GenericNode, E extends GenericEdge>(
+  nodeId: string,
+  nodes: N[],
+  edges: E[],
+  getImageUrl: (node: N) => string | undefined,
+  visited = new Set<string>(),
+): string[] {
+  if (visited.has(nodeId)) return []
+  visited.add(nodeId)
+  const refs: string[] = []
+  const incoming = edges.filter((e) => e.target === nodeId)
+  for (const edge of incoming) {
+    const src = nodes.find((n) => n.id === edge.source)
+    if (!src) continue
+    if (IMAGE_REF_TYPES.has(src.type)) {
+      const url = getImageUrl(src)
+      if (url?.trim()) refs.push(url.trim())
+    }
+    if (PASSTHROUGH_TYPES.has(src.type)) {
+      refs.push(...collectAncestorRefs(src.id, nodes, edges, getImageUrl, visited))
+    }
+  }
+  return refs
+}