@nodaro/shared 1.22.0 → 1.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "1.22.0",
+  "version": "1.24.0",
   "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
   "type": "module",
   "license": "Apache-2.0",

package/src/__tests__/llm-models.test.ts

@@ -678,6 +678,25 @@ describe("advanced mode", () => {
     }
   })
 
+  it("no advanced-capable model declares xhigh/max — the UI copy depends on it", () => {
+    // `EFFORT_LABELS` in reasoning-effort-select.tsx labels xhigh/max "may bill
+    // one tier up" and its comment explains that the effort bump and the
+    // advanced bump can never both apply, because Advanced is Gemini-only and
+    // no Gemini model reaches xhigh/max. That was a note asking a future reader
+    // to remember; this is the check that fails instead.
+    //
+    // If this ever goes red, the two bumps CAN stack: reword the labels to say
+    // so and revisit whether a double bump is the price we want.
+    for (const m of LLM_MODELS) {
+      if (!supportsAdvancedMode(m.id)) continue
+      const levels = [...(m.reasoningEfforts ?? []), ...(m.directReasoningEfforts ?? [])]
+      expect(levels, `${m.id} can run advanced AND declares a tier-bumping effort`)
+        .not.toEqual(expect.arrayContaining(["xhigh"]))
+      expect(levels, `${m.id} can run advanced AND declares a tier-bumping effort`)
+        .not.toEqual(expect.arrayContaining(["max"]))
+    }
+  })
+
   it("never bumps past premium", () => {
     expect(buildLlmCreditIdentifier("llm-chat", "gemini-3.1-pro", "max", true)).toBe("llm-chat:premium")
   })

package/src/__tests__/video-analysis-catalog-sync.test.ts

@@ -13,7 +13,9 @@ import {
   VIDEO_ANALYSIS_BUCKET_CREDITS,
   VIDEO_ANALYSIS_DURATION_BUCKETS,
   VIDEO_ANALYSIS_MAX_DURATION_SEC,
+  buildVideoAnalysisCreditId,
 } from "../video-analysis-pricing.js"
+import { DEFAULT_VIDEO_ANALYSIS_MODEL } from "../llm-models.js"
 
 /** Every `video-analysis:*` pricing row declared anywhere in the catalog. */
 const catalogRows = Object.values(MODEL_CATALOG)
@@ -61,3 +63,48 @@ describe("model catalog video-analysis pricing", () => {
     }
   })
 })
+
+/**
+ * The BARE `video-analysis` node-type id — the one every colon-scoped guard misses.
+ *
+ * `getModelIdentifier` (frontend) has no video-analysis branch, so it falls through
+ * to `return nodeType` and the run-credits estimate resolves this exact id. It was
+ * seeded at 3 credits in migration 247 with the comment "= flash 600s" and then
+ * skipped by FIVE consecutive repricings (248, 259, 273, 275, 276), every one of
+ * which matched only `video-analysis:` prefixes — including this test file's own
+ * `catalogRows` filter above. A real run reserves 21-200, so the pre-run balance
+ * check was quoting 3 for a run it would then refuse.
+ *
+ * The value is the MAXIMUM of the table, not the default tier at the ceiling
+ * bucket: this test's first version pinned the latter and failed immediately,
+ * because the default (pro) tops out at 120 while `mixed` reaches 200. Reached only
+ * when BOTH model and duration are unknown, so it has to bound every row.
+ */
+describe("bare video-analysis node-type credit id", () => {
+  it("bounds EVERY bucketed row — an unknown-duration estimate must never UNDER-quote", () => {
+    const ceiling = Math.max(...Object.values(VIDEO_ANALYSIS_BUCKET_CREDITS))
+    for (const [id, credits] of Object.entries(VIDEO_ANALYSIS_BUCKET_CREDITS)) {
+      expect(credits, `${id} exceeds the bare-id ceiling ${ceiling}`).toBeLessThanOrEqual(ceiling)
+    }
+    // The migration writes this number; keep them in lockstep (277 wrote 200,
+    // 279 wrote 739, 280 writes 346 — every tier now dispatches one identical
+    // analyzer pass, so the whole schedule flattened and the ceiling fell with it).
+    expect(ceiling).toBe(346)
+  })
+
+  it("the bare id still bounds the default tier at the ceiling bucket", () => {
+    // Pins the reason the bare id is the table MAX rather than the intuitive
+    // "default model, longest video" value, so nobody re-derives it wrongly.
+    //
+    // Was `toBeLessThan`, on the premise that `mixed` cost strictly more than the
+    // default tier. That premise is gone: all tiers resolve to the same single
+    // pass, so every row at a given bucket is equal and the correct assertion is
+    // the INVARIANT (the bare id must never under-quote), not the old strict gap.
+    // Should tiers ever diverge again this still holds, and the ceiling check
+    // above catches any row that outgrows it.
+    const defaultAtCeiling = VIDEO_ANALYSIS_BUCKET_CREDITS[
+      buildVideoAnalysisCreditId(DEFAULT_VIDEO_ANALYSIS_MODEL, VIDEO_ANALYSIS_MAX_DURATION_SEC)
+    ]!
+    expect(defaultAtCeiling).toBeLessThanOrEqual(Math.max(...Object.values(VIDEO_ANALYSIS_BUCKET_CREDITS)))
+  })
+})

package/src/__tests__/video-analysis-pricing.test.ts

@@ -84,9 +84,14 @@ describe("video-analysis-pricing", () => {
     expect(DEFAULT_VIDEO_ANALYSIS_TIER).toBe("pro")
     expect(DEFAULT_VIDEO_ANALYSIS_MODEL).toBe("gemini-3.1-pro")
     expect(resolveVideoAnalysisModel("pro")).toBe("gemini-3.1-pro")
-    expect(resolveVideoAnalysisModel("fast")).toBe("gemini-3.6-flash")
+    // The economy tiers moved to the cheaper flash generation when they moved to
+    // the cheaper transport; the newer flash now sits behind the `smart` sentinel.
+    expect(resolveVideoAnalysisModel("fast")).toBe("gemini-3-flash")
     expect(resolveVideoAnalysisModel("mixed")).toBe("mixed") // roll-plan sentinel passthrough
     expect(resolveVideoAnalysisModel("mixed-fast")).toBe("mixed-fast")
+    // `smart` is a sentinel too — it names an engine plan, never a model id, so the
+    // engine behind it stays unpublished exactly as the mixed plans' does.
+    expect(resolveVideoAnalysisModel("smart")).toBe("smart")
     // Raw passthrough keeps LEGACY stored configs running (and priced) on the
     // exact model they were saved with — never silently re-tiered.
     expect(resolveVideoAnalysisModel("gemini-3-flash")).toBe("gemini-3-flash")

package/src/index.ts

@@ -279,6 +279,9 @@ export {
   resolveLlmCreditId,
   supportsAdvancedMode,
   availableReasoningEfforts,
+  LLM_ROUTE_DEFAULTS,
+  llmRouteDefaults,
+  type LlmRouteDefaults,
   ADVANCED_MODE_UNAVAILABLE_REASON,
   motionGraphicsFeature,
   effectiveReasoningEffort,

package/src/llm-models.ts

@@ -212,6 +212,17 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     // Google documents low/medium/high for 3.1 Pro — no `minimal` tier, so
     // this ladder is deliberately shorter than the flash models'.
     directReasoningEfforts: ["low", "medium", "high"],
+    // NO `reasoningEfforts` (the proxied ladder) ON PURPOSE, not an omission.
+    // That endpoint accepts `reasoning_effort: low | high` and already DEFAULTS
+    // to "high", so leaving it unset gets its deepest setting and a ladder here
+    // would unlock nothing. The two lanes are NOT equivalent at their maxima:
+    // verified 2026-07-29 on identical input, the proxy's ceiling produces
+    // roughly a quarter of the reasoning tokens that the direct lane's
+    // `thinkingLevel: HIGH` does, and it does not expose Google's deeper tiers
+    // at all. That difference is visible in fine-detail reading (small on-screen
+    // text such as a name badge), which is exactly what video-analysis casts
+    // identities from — so adding an entry here would silently move analysis to
+    // the shallower lane. Don't. Full comparison lives with the analysis engine.
     // The ONE Gemini model routed direct-first. It is the premium/low-volume
     // tier (video-analysis `pro`, no LLM_FEATURE_DEFAULTS entry), so the ~4×
     // list-price premium lands on the smallest call volume — and it is where
@@ -550,6 +561,49 @@ export function effectiveReasoningEffort(
  * premium stays premium). `high` is the Claude-family server default and
  * never bumps.
  */
+
+/**
+ * The sampling defaults each LLM feature's route sends when Advanced mode is
+ * OFF — and therefore the values its Advanced panel must seed the sliders with.
+ *
+ * SINGLE SOURCE because the two used to disagree: the routes hardcoded their
+ * own literals while the toggle fell back to 0.7/2048, so the panel displayed
+ * a temperature the run never used, and one arrow-key press on 3D Title's Max
+ * Tokens silently cut its budget from 3072 to 2048 on a node that emits
+ * structured JSON.
+ *
+ * `structuredOutput` marks the features whose prompt asks the model for JSON —
+ * a high temperature measurably degrades schema adherence there, so the panel
+ * warns. Absent `temperature` means the route sends none (vendor default).
+ */
+export interface LlmRouteDefaults {
+  temperature?: number
+  maxTokens?: number
+  structuredOutput?: true
+}
+
+export const LLM_ROUTE_DEFAULTS: Record<string, LlmRouteDefaults> = {
+  "llm-chat":                { temperature: 0.7,  maxTokens: 8192 },
+  "ai-writer":               { temperature: 0.7,  maxTokens: 8192 },
+  "prompt-helper":           { temperature: 0.7,  maxTokens: 8192, structuredOutput: true },
+  "generate-script":         { maxTokens: 16384, structuredOutput: true },
+  "qa-check":                { maxTokens: 1024,  structuredOutput: true },
+  "image-critic":            { maxTokens: 1024,  structuredOutput: true },
+  "image-to-text":           { maxTokens: 1024 },
+  "describe-to-picker":      { structuredOutput: true },
+  "scene-graph-ai":          { temperature: 0.3,  maxTokens: 4096, structuredOutput: true },
+  "after-effects":           { temperature: 0.3,  maxTokens: 2048, structuredOutput: true },
+  "lottie-overlay":          { temperature: 0.3,  maxTokens: 2048, structuredOutput: true },
+  "motion-graphics":         { temperature: 0.3,  maxTokens: 2048, structuredOutput: true },
+  "motion-graphics-lottie":  { temperature: 0.3,  maxTokens: 8192, structuredOutput: true },
+  "3d-title":                { temperature: 0.4,  maxTokens: 3072, structuredOutput: true },
+}
+
+/** Route defaults for a feature; `{}` for an unknown one. */
+export function llmRouteDefaults(feature: string | undefined): LlmRouteDefaults {
+  return (feature && LLM_ROUTE_DEFAULTS[feature]) || {}
+}
+
 /** One step up the economy → standard → premium ladder. Premium is the ceiling. */
 function bumpTier(tier: LlmTier): LlmTier {
   if (tier === "economy") return "standard"
@@ -623,7 +677,7 @@ export const VIDEO_ANALYSIS_LLM_MODELS: string[] = LLM_MODELS
  * VIDEO_ANALYSIS_LLM_MODELS member AND every such model is reachable by a tier,
  * so adding a video model forces a tier decision instead of silently leaking.
  */
-export const VIDEO_ANALYSIS_TIERS = { fast: "gemini-3.6-flash", pro: "gemini-3.1-pro" } as const
+export const VIDEO_ANALYSIS_TIERS = { fast: "gemini-3-flash", pro: "gemini-3.1-pro" } as const
 export type VideoAnalysisModelTier = keyof typeof VIDEO_ANALYSIS_TIERS
 /**
  * Models that PREVIOUSLY backed a tier, mapped to the tier they backed.
@@ -637,8 +691,13 @@ export type VideoAnalysisModelTier = keyof typeof VIDEO_ANALYSIS_TIERS
  * two-sided decision.
  */
 export const VIDEO_ANALYSIS_LEGACY_MODELS: Record<string, VideoAnalysisModelTier> = {
-  // fast tier's backing model until 2026-07 (superseded by gemini-3.6-flash)
-  "gemini-3-flash": "fast",
+  // Backed the fast tier from 2026-07 until 2026-07-29, when the economy tiers
+  // moved to the cheaper lane and the older, cheaper flash. It is now the engine
+  // behind the `smart` tier — but `smart` is a SENTINEL that never exposes a model
+  // id, so as far as this map is concerned it no longer backs a selectable tier and
+  // belongs here: stored raw `llmModel` values keep resolving and keep pricing
+  // under their own credit family.
+  "gemini-3.6-flash": "fast",
 }
 /**
  * MIXED tiers — advanced multi-engine analysis plans whose identifier resolves
@@ -649,15 +708,30 @@ export const VIDEO_ANALYSIS_LEGACY_MODELS: Record<string, VideoAnalysisModelTier
  * NOT published here (Apache irrevocability; only the wire vocabulary below is
  * contract — the engine lives in the private analysis plugin).
  */
-export const VIDEO_ANALYSIS_MIXED_TIERS = ["mixed", "mixed-fast"] as const
+export const VIDEO_ANALYSIS_MIXED_TIERS = ["mixed", "mixed-fast", "smart"] as const
 export type VideoAnalysisMixedTier = (typeof VIDEO_ANALYSIS_MIXED_TIERS)[number]
-/** UI/listing order — recommended (pro) first. */
-export const VIDEO_ANALYSIS_TIER_ORDER = ["pro", "fast", "mixed", "mixed-fast"] as const
+/**
+ * `smart` is an ENGINE-PLAN sentinel like the mixed tiers — it names a plan, not a
+ * model — but it is the opposite kind of plan, and the distinction is the whole
+ * reason it exists as a separate tier rather than a repricing of the others.
+ *
+ * The economy tiers (`fast`, `pro`, `mixed`, `mixed-fast`) run several passes on
+ * the cheaper proxied transport and vote. That transport is 3-4x cheaper per token
+ * and additionally does no deep reasoning, which is why they cost single-digit
+ * credits — and also why they are less accurate. `smart` runs ONE pass on the
+ * native transport with everything turned up, which is where the accuracy is.
+ *
+ * As with the mixed sentinels, what the plan does internally is deliberately not
+ * published here; only the wire vocabulary is contract.
+ */
+/** UI/listing order — recommended (smart) first. */
+export const VIDEO_ANALYSIS_TIER_ORDER = ["smart", "pro", "fast", "mixed", "mixed-fast"] as const
 export type VideoAnalysisTier = (typeof VIDEO_ANALYSIS_TIER_ORDER)[number]
 export const DEFAULT_VIDEO_ANALYSIS_TIER: VideoAnalysisTier = "pro"
 export const DEFAULT_VIDEO_ANALYSIS_MODEL: string = VIDEO_ANALYSIS_TIERS[DEFAULT_VIDEO_ANALYSIS_TIER]
 /** Neutral, vendor-free display labels for the UI. */
 export const VIDEO_ANALYSIS_TIER_LABELS: Record<VideoAnalysisTier, string> = {
+  smart: "Smart",
   fast: "Fast",
   pro: "Pro",
   mixed: "Mixed",

package/src/model-catalog.ts

@@ -1815,11 +1815,11 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
     description: "Legacy fast-tier analysis model (pre-2026-07). Kept so stored raw-model configs keep running and keep pricing under their own identifier; new fast-tier runs use the current fast model.",
     useCases: ["video-analysis", "shot-list", "fast"],
     pricing: [
-      { identifier: "video-analysis:gemini-3-flash", credits: 30, note: "10-min ceiling (no duration given)" },
-      { identifier: "video-analysis:gemini-3-flash:60s", credits: 6 },
-      { identifier: "video-analysis:gemini-3-flash:180s", credits: 7 },
-      { identifier: "video-analysis:gemini-3-flash:360s", credits: 18 },
-      { identifier: "video-analysis:gemini-3-flash:600s", credits: 30, note: "10-min ceiling" },
+      { identifier: "video-analysis:gemini-3-flash", credits: 14, note: "10-min ceiling (no duration given)" },
+      { identifier: "video-analysis:gemini-3-flash:60s", credits: 3 },
+      { identifier: "video-analysis:gemini-3-flash:180s", credits: 4 },
+      { identifier: "video-analysis:gemini-3-flash:360s", credits: 9 },
+      { identifier: "video-analysis:gemini-3-flash:600s", credits: 14, note: "10-min ceiling" },
     ],
   },
   "gemini-3.6-flash-video-analysis": {
@@ -1832,11 +1832,11 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
     description: "Analyze a video into a structured shot list (scenes, camera, audio) — fast, economy tier. Billed per duration bucket.",
     useCases: ["video-analysis", "shot-list", "fast"],
     pricing: [
-      { identifier: "video-analysis:gemini-3.6-flash", credits: 81, note: "10-min ceiling (no duration given)" },
-      { identifier: "video-analysis:gemini-3.6-flash:60s", credits: 14 },
-      { identifier: "video-analysis:gemini-3.6-flash:180s", credits: 19 },
-      { identifier: "video-analysis:gemini-3.6-flash:360s", credits: 49 },
-      { identifier: "video-analysis:gemini-3.6-flash:600s", credits: 81, note: "10-min ceiling" },
+      { identifier: "video-analysis:gemini-3.6-flash", credits: 38, note: "10-min ceiling (no duration given)" },
+      { identifier: "video-analysis:gemini-3.6-flash:60s", credits: 7 },
+      { identifier: "video-analysis:gemini-3.6-flash:180s", credits: 9 },
+      { identifier: "video-analysis:gemini-3.6-flash:360s", credits: 23 },
+      { identifier: "video-analysis:gemini-3.6-flash:600s", credits: 38, note: "10-min ceiling" },
     ],
   },
   "gemini-3.1-pro-video-analysis": {
@@ -1849,11 +1849,11 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
     description: "Analyze a video into a structured shot list (scenes, camera, audio) — higher-fidelity, default tier. Billed per duration bucket.",
     useCases: ["video-analysis", "shot-list", "cinematic"],
     pricing: [
-      { identifier: "video-analysis:gemini-3.1-pro", credits: 120, note: "10-min ceiling (no duration given)" },
-      { identifier: "video-analysis:gemini-3.1-pro:60s", credits: 21 },
-      { identifier: "video-analysis:gemini-3.1-pro:180s", credits: 27 },
-      { identifier: "video-analysis:gemini-3.1-pro:360s", credits: 72 },
-      { identifier: "video-analysis:gemini-3.1-pro:600s", credits: 120, note: "10-min ceiling" },
+      { identifier: "video-analysis:gemini-3.1-pro", credits: 49, note: "10-min ceiling (no duration given)" },
+      { identifier: "video-analysis:gemini-3.1-pro:60s", credits: 9 },
+      { identifier: "video-analysis:gemini-3.1-pro:180s", credits: 12 },
+      { identifier: "video-analysis:gemini-3.1-pro:360s", credits: 30 },
+      { identifier: "video-analysis:gemini-3.1-pro:600s", credits: 49, note: "10-min ceiling" },
     ],
   },
   // Both mixed tiers are variants of the same advanced multi-engine analysis
@@ -1869,11 +1869,32 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
     description: "Our most advanced analysis tier — multiple analysis engines combined into one result for maximum completeness and accuracy. Billed per duration bucket.",
     useCases: ["video-analysis", "shot-list", "premium", "most-complete"],
     pricing: [
-      { identifier: "video-analysis:mixed", credits: 200, note: "10-min ceiling (no duration given)" },
-      { identifier: "video-analysis:mixed:60s", credits: 34 },
-      { identifier: "video-analysis:mixed:180s", credits: 46 },
-      { identifier: "video-analysis:mixed:360s", credits: 120 },
-      { identifier: "video-analysis:mixed:600s", credits: 200, note: "10-min ceiling" },
+      { identifier: "video-analysis:mixed", credits: 63, note: "10-min ceiling (no duration given)" },
+      { identifier: "video-analysis:mixed:60s", credits: 11 },
+      { identifier: "video-analysis:mixed:180s", credits: 15 },
+      { identifier: "video-analysis:mixed:360s", credits: 38 },
+      { identifier: "video-analysis:mixed:600s", credits: 63, note: "10-min ceiling" },
+    ],
+  },
+  // SMART — the accuracy tier, and the only one that does not rely on voting.
+  // Every other tier runs several cheap passes and has a grader pick between them;
+  // this one runs a single pass with reasoning and frame sampling turned all the
+  // way up. Priced well above them because it genuinely costs more to run.
+  "smart-video-analysis": {
+    id: "smart-video-analysis",
+    kind: "video",
+    modes: ["video-analysis"] as const,
+    family: "Nodaro",
+    label: "Video Analysis (Smart)",
+    series: "Video Analysis",
+    description: "Highest-accuracy analysis — a single deep pass that reads the footage frame by frame, finds its own shot boundaries, and identifies the cast by appearance. Best choice when the shot list will drive regeneration. Billed per duration bucket.",
+    useCases: ["video-analysis", "shot-list", "premium", "most-accurate"],
+    pricing: [
+      { identifier: "video-analysis:smart", credits: 346, note: "10-min ceiling (no duration given)" },
+      { identifier: "video-analysis:smart:60s", credits: 42 },
+      { identifier: "video-analysis:smart:180s", credits: 94 },
+      { identifier: "video-analysis:smart:360s", credits: 207 },
+      { identifier: "video-analysis:smart:600s", credits: 346, note: "10-min ceiling" },
     ],
   },
 }

package/src/video-analysis-pricing.ts

@@ -50,27 +50,35 @@ export const VIDEO_ANALYSIS_WINDOW = { LEN: WINDOW_LEN, STRIDE: WINDOW_STRIDE, O
  */
 export const VIDEO_ANALYSIS_BUCKET_CREDITS: Record<string, number> = {
   // Legacy fast-tier model (pre-2026-07) — kept for stored raw-id configs.
-  "video-analysis:gemini-3-flash:60s": 6,
-  "video-analysis:gemini-3-flash:180s": 7,
-  "video-analysis:gemini-3-flash:360s": 18,
-  "video-analysis:gemini-3-flash:600s": 30,
+  "video-analysis:gemini-3-flash:60s": 3,
+  "video-analysis:gemini-3-flash:180s": 4,
+  "video-analysis:gemini-3-flash:360s": 9,
+  "video-analysis:gemini-3-flash:600s": 14,
   // Current fast tier — regenerated from the private formula for its backing
   // model; higher than the legacy fast schedule but still ≤ pro per bucket.
-  "video-analysis:gemini-3.6-flash:60s": 14,
-  "video-analysis:gemini-3.6-flash:180s": 19,
-  "video-analysis:gemini-3.6-flash:360s": 49,
-  "video-analysis:gemini-3.6-flash:600s": 81,
-  "video-analysis:gemini-3.1-pro:60s": 21,
-  "video-analysis:gemini-3.1-pro:180s": 27,
-  "video-analysis:gemini-3.1-pro:360s": 72,
-  "video-analysis:gemini-3.1-pro:600s": 120,
+  "video-analysis:gemini-3.6-flash:60s": 7,
+  "video-analysis:gemini-3.6-flash:180s": 9,
+  "video-analysis:gemini-3.6-flash:360s": 23,
+  "video-analysis:gemini-3.6-flash:600s": 38,
+  "video-analysis:gemini-3.1-pro:60s": 9,
+  "video-analysis:gemini-3.1-pro:180s": 12,
+  "video-analysis:gemini-3.1-pro:360s": 30,
+  "video-analysis:gemini-3.1-pro:600s": 49,
   // Mixed tiers (`mixed` + `mixed-fast`) share ONE credit family — they are
   // variants of the same engine plan (plan internals live in the private
   // analysis plugin). Admin-tunable via model_pricing like every other row.
-  "video-analysis:mixed:60s": 34,
-  "video-analysis:mixed:180s": 46,
-  "video-analysis:mixed:360s": 120,
-  "video-analysis:mixed:600s": 200,
+  "video-analysis:mixed:60s": 11,
+  "video-analysis:mixed:180s": 15,
+  "video-analysis:mixed:360s": 38,
+  "video-analysis:mixed:600s": 63,
+  // SMART — the one native-transport plan: a single pass with reasoning and
+  // frame sampling turned all the way up. Priced well above the economy tiers
+  // because it genuinely costs more to run, and it is the only tier whose
+  // accuracy was measured against a hand-counted edit list.
+  "video-analysis:smart:60s": 42,
+  "video-analysis:smart:180s": 94,
+  "video-analysis:smart:360s": 207,
+  "video-analysis:smart:600s": 346,
 }
 
 /**

package/src/video-analysis.ts

@@ -205,6 +205,19 @@ export const entitySlotSchema = z.object({
    *  where this entity is clearly visible. Optional/additive: producers may
    *  omit it; consumers use it as an identity reference for recreation. */
   refImageUrl: z.string().url().optional(),
+  /**
+   * Why `refImageUrl` is ABSENT, when the analyzer's vision pass actively
+   * refused every candidate frame rather than merely failing to produce one.
+   *
+   * Present only alongside a missing `refImageUrl`, and only for a real refusal
+   * — never for a technical failure, so its presence always carries meaning. The
+   * important case reads like "the shots bound to this slot show someone else —
+   * cast as X, but on screen: Y", which is the analyzer telling you the casting
+   * description and the footage disagree. A consumer should treat that as a
+   * reason to review the slot before spending on regeneration, since a wrong
+   * identity propagates into every regenerated shot.
+   */
+  refRejectedReason: z.string().optional(),
   /** NON-default looks only; present only when at least one exists. */
   variations: z.array(slotVariationSchema).max(VIDEO_ANALYSIS_MAX_VARIATIONS).optional(),
 })
@@ -327,6 +340,21 @@ export const videoAnalysisResultSchema = z.object({
     variationId: z.string(),
     label: z.string(),
   })).optional(),
+  /**
+   * Analyzer diagnostics for THIS result — things the analysis noticed about
+   * itself that a reader should know before spending on regeneration.
+   *
+   * Added because there was previously no channel for them at all: the merge
+   * layer has always produced a warnings list and the auto-cast pass has always
+   * had findings, and every one of them died in a `console.warn` inside a worker
+   * the user cannot see. So a run could quietly drop a duplicated line, fold a
+   * cast look, or conclude a character is not the person their own description
+   * names, and the result looked indistinguishable from a clean one.
+   *
+   * Prose, not codes, and deliberately so — these are read by a human deciding
+   * whether to re-run, not branched on. Absent when there is nothing to report.
+   */
+  warnings: z.array(z.string()).optional(),
 })
 export type VideoAnalysisResult = z.infer<typeof videoAnalysisResultSchema>