@nodaro/shared 1.23.0 → 1.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "1.23.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__/video-analysis-catalog-sync.test.ts

@@ -86,17 +86,25 @@ describe("bare video-analysis node-type credit id", () => {
     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, 278
-    // writes 739 after the measured reprice).
-    expect(ceiling).toBe(739)
+    // 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 default tier at the ceiling bucket is NOT a safe fallback — mixed costs more", () => {
-    // Pins the reason the bare id is the table max rather than the intuitive
+  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).toBeLessThan(Math.max(...Object.values(VIDEO_ANALYSIS_BUCKET_CREDITS)))
+    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/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
@@ -666,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.
@@ -680,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
@@ -692,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: 112, note: "10-min ceiling (no duration given)" },
-      { identifier: "video-analysis:gemini-3-flash:60s", credits: 21 },
-      { identifier: "video-analysis:gemini-3-flash:180s", credits: 24 },
-      { identifier: "video-analysis:gemini-3-flash:360s", credits: 68 },
-      { identifier: "video-analysis:gemini-3-flash:600s", credits: 112, 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: 291, note: "10-min ceiling (no duration given)" },
-      { identifier: "video-analysis:gemini-3.6-flash:60s", credits: 54 },
-      { identifier: "video-analysis:gemini-3.6-flash:180s", credits: 63 },
-      { identifier: "video-analysis:gemini-3.6-flash:360s", credits: 175 },
-      { identifier: "video-analysis:gemini-3.6-flash:600s", credits: 291, 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: 448, note: "10-min ceiling (no duration given)" },
-      { identifier: "video-analysis:gemini-3.1-pro:60s", credits: 84 },
-      { identifier: "video-analysis:gemini-3.1-pro:180s", credits: 96 },
-      { identifier: "video-analysis:gemini-3.1-pro:360s", credits: 269 },
-      { identifier: "video-analysis:gemini-3.1-pro:600s", credits: 448, 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: 739, note: "10-min ceiling (no duration given)" },
-      { identifier: "video-analysis:mixed:60s", credits: 137 },
-      { identifier: "video-analysis:mixed:180s", credits: 158 },
-      { identifier: "video-analysis:mixed:360s", credits: 443 },
-      { identifier: "video-analysis:mixed:600s", credits: 739, 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": 21,
-  "video-analysis:gemini-3-flash:180s": 24,
-  "video-analysis:gemini-3-flash:360s": 68,
-  "video-analysis:gemini-3-flash:600s": 112,
+  "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": 54,
-  "video-analysis:gemini-3.6-flash:180s": 63,
-  "video-analysis:gemini-3.6-flash:360s": 175,
-  "video-analysis:gemini-3.6-flash:600s": 291,
-  "video-analysis:gemini-3.1-pro:60s": 84,
-  "video-analysis:gemini-3.1-pro:180s": 96,
-  "video-analysis:gemini-3.1-pro:360s": 269,
-  "video-analysis:gemini-3.1-pro:600s": 448,
+  "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": 137,
-  "video-analysis:mixed:180s": 158,
-  "video-analysis:mixed:360s": 443,
-  "video-analysis:mixed:600s": 739,
+  "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>