@nodaro/shared 1.11.0 → 1.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "1.11.0",
+  "version": "1.12.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-pricing.test.ts

@@ -7,6 +7,7 @@ import {
 } from "../video-analysis-pricing.js"
 import {
   VIDEO_ANALYSIS_LLM_MODELS, VIDEO_ANALYSIS_TIERS, VIDEO_ANALYSIS_TIER_ORDER,
+  VIDEO_ANALYSIS_MIXED_TIERS,
   DEFAULT_VIDEO_ANALYSIS_TIER, DEFAULT_VIDEO_ANALYSIS_MODEL, resolveVideoAnalysisModel,
 } from "../llm-models.js"
 
@@ -43,26 +44,51 @@ describe("video-analysis-pricing", () => {
     expect(VIDEO_ANALYSIS_LLM_MODELS).toEqual(["gemini-3-flash", "gemini-3.1-pro"])
   })
 
-  it("tier layer: every tier maps to a real model AND every model is tier-reachable (no vendor leak)", () => {
+  it("tier layer: every model-backed tier maps to a real model AND every model is tier-reachable (no vendor leak)", () => {
     // Adding a video-analysis model without a tier would silently leave it
     // unreachable / unnamed — this fails until a tier decision is made.
     const tierTargets = Object.values(VIDEO_ANALYSIS_TIERS)
     for (const m of tierTargets) expect(VIDEO_ANALYSIS_LLM_MODELS).toContain(m)
     for (const m of VIDEO_ANALYSIS_LLM_MODELS) expect(tierTargets).toContain(m)
-    expect(new Set(VIDEO_ANALYSIS_TIER_ORDER)).toEqual(new Set(Object.keys(VIDEO_ANALYSIS_TIERS)))
+    // TIER_ORDER = model-backed tiers + mixed roll-plan tiers, exactly.
+    expect(new Set(VIDEO_ANALYSIS_TIER_ORDER)).toEqual(
+      new Set([...Object.keys(VIDEO_ANALYSIS_TIERS), ...VIDEO_ANALYSIS_MIXED_TIERS]),
+    )
+    // Mixed tiers are SENTINELS, never model ids — a mixed id leaking into the
+    // model list would break the roll-plan dispatch in the analysis engine.
+    for (const t of VIDEO_ANALYSIS_MIXED_TIERS) expect(VIDEO_ANALYSIS_LLM_MODELS).not.toContain(t)
   })
 
-  it("resolveVideoAnalysisModel: tier → model, raw model passthrough, default pro on empty/unknown", () => {
+  it("resolveVideoAnalysisModel: tier → model, mixed → sentinel, raw model passthrough, default pro on empty/unknown", () => {
     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-flash")
+    expect(resolveVideoAnalysisModel("mixed")).toBe("mixed") // roll-plan sentinel passthrough
+    expect(resolveVideoAnalysisModel("mixed-fast")).toBe("mixed-fast")
     expect(resolveVideoAnalysisModel("gemini-3-flash")).toBe("gemini-3-flash") // raw passthrough
     expect(resolveVideoAnalysisModel(undefined)).toBe("gemini-3.1-pro") // default → pro
     expect(resolveVideoAnalysisModel("")).toBe("gemini-3.1-pro")
     expect(resolveVideoAnalysisModel("nonsense")).toBe("gemini-3.1-pro") // unknown → default, never throws
   })
 
+  it("mixed tiers price under ONE shared credit family (video-analysis:mixed:*)", () => {
+    // Both variants are the identical compute plan — a per-variant price split
+    // would be a phantom distinction and double the admin surface.
+    for (const bucketSec of VIDEO_ANALYSIS_DURATION_BUCKETS) {
+      expect(buildVideoAnalysisCreditId("mixed", bucketSec)).toBe(`video-analysis:mixed:${bucketSec}s`)
+      expect(buildVideoAnalysisCreditId("mixed-fast", bucketSec)).toBe(`video-analysis:mixed:${bucketSec}s`)
+      const credits = VIDEO_ANALYSIS_BUCKET_CREDITS[`video-analysis:mixed:${bucketSec}s`]
+      expect(credits, `missing mixed entry for ${bucketSec}s`).toBeDefined()
+      expect(Number.isInteger(credits)).toBe(true)
+      // Sanity: mixed (3 fast + 2 pro rolls + refine) must never price below
+      // the pro tier it supersets.
+      expect(credits).toBeGreaterThanOrEqual(
+        VIDEO_ANALYSIS_BUCKET_CREDITS[`video-analysis:gemini-3.1-pro:${bucketSec}s`],
+      )
+    }
+  })
+
   // Full drift-detection against the live $-formula lives in
   // backend/src/lib/pricing/__tests__/video-analysis-cost.test.ts (this
   // package cannot see the formula post-S5). This is a lightweight shape

package/src/index.ts

@@ -255,11 +255,15 @@ export {
   VIDEO_ANALYSIS_LLM_MODELS,
   VIDEO_ANALYSIS_TIERS,
   type VideoAnalysisTier,
+  type VideoAnalysisModelTier,
+  VIDEO_ANALYSIS_MIXED_TIERS,
+  type VideoAnalysisMixedTier,
   VIDEO_ANALYSIS_TIER_ORDER,
   DEFAULT_VIDEO_ANALYSIS_TIER,
   DEFAULT_VIDEO_ANALYSIS_MODEL,
   VIDEO_ANALYSIS_TIER_LABELS,
   isVideoAnalysisTier,
+  isVideoAnalysisMixedTier,
   resolveVideoAnalysisModel,
   LLM_FEATURE_DEFAULTS,
   LLM_MODALITY_CAPS,

package/src/llm-models.ts

@@ -396,26 +396,53 @@ export const VIDEO_ANALYSIS_LLM_MODELS: string[] = LLM_MODELS
  * so adding a video model forces a tier decision instead of silently leaking.
  */
 export const VIDEO_ANALYSIS_TIERS = { fast: "gemini-3-flash", pro: "gemini-3.1-pro" } as const
-export type VideoAnalysisTier = keyof typeof VIDEO_ANALYSIS_TIERS
+export type VideoAnalysisModelTier = keyof typeof VIDEO_ANALYSIS_TIERS
+/**
+ * MIXED tiers — advanced multi-engine analysis plans whose identifier resolves
+ * to an engine-plan SENTINEL consumed by the analysis engine, never to a single
+ * model id. Two variants, same price (one shared `video-analysis:mixed:*`
+ * credit family): `mixed` targets maximum result quality; `mixed-fast` targets
+ * run-to-run output consistency. What each plan does internally is deliberately
+ * 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 type VideoAnalysisMixedTier = (typeof VIDEO_ANALYSIS_MIXED_TIERS)[number]
 /** UI/listing order — recommended (pro) first. */
-export const VIDEO_ANALYSIS_TIER_ORDER = ["pro", "fast"] as const
+export const VIDEO_ANALYSIS_TIER_ORDER = ["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> = { fast: "Fast", pro: "Pro" }
+export const VIDEO_ANALYSIS_TIER_LABELS: Record<VideoAnalysisTier, string> = {
+  fast: "Fast",
+  pro: "Pro",
+  mixed: "Mixed",
+  "mixed-fast": "Mixed (consistent)",
+}
 
 export function isVideoAnalysisTier(v: string): v is VideoAnalysisTier {
-  return Object.prototype.hasOwnProperty.call(VIDEO_ANALYSIS_TIERS, v)
+  return (VIDEO_ANALYSIS_TIER_ORDER as readonly string[]).includes(v)
+}
+
+export function isVideoAnalysisMixedTier(v: string): v is VideoAnalysisMixedTier {
+  return (VIDEO_ANALYSIS_MIXED_TIERS as readonly string[]).includes(v)
 }
 
 /**
- * Resolve a user-supplied tier (`"fast"`/`"pro"`) OR a raw internal model id to
- * the internal analysis model id. Empty/unknown → the default tier's model.
- * Real model ids pass through (back-compat for existing stored `llmModel`
- * values); anything else falls back to the default rather than erroring.
+ * Resolve a user-supplied tier OR a raw internal model id to the analysis
+ * ENGINE IDENTIFIER carried in the worker payload:
+ *  - model-backed tiers ("fast"/"pro") → the internal model id;
+ *  - mixed tiers ("mixed"/"mixed-fast") → the sentinel ITSELF (the engine
+ *    expands it to a multi-model roll plan);
+ *  - raw model ids pass through (back-compat for stored `llmModel` values);
+ *  - empty/unknown → the default tier's model (never an error).
  */
 export function resolveVideoAnalysisModel(input?: string | null): string {
-  if (input && isVideoAnalysisTier(input)) return VIDEO_ANALYSIS_TIERS[input]
+  if (input && isVideoAnalysisMixedTier(input)) return input
+  if (input && Object.prototype.hasOwnProperty.call(VIDEO_ANALYSIS_TIERS, input)) {
+    return VIDEO_ANALYSIS_TIERS[input as VideoAnalysisModelTier]
+  }
   if (input && VIDEO_ANALYSIS_LLM_MODELS.includes(input)) return input
   return DEFAULT_VIDEO_ANALYSIS_MODEL
 }

package/src/model-catalog.ts

@@ -1839,6 +1839,26 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
       { identifier: "video-analysis:gemini-3.1-pro:600s", credits: 11, note: "10-min ceiling" },
     ],
   },
+  // Both mixed tiers are variants of the same advanced multi-engine analysis
+  // and share this ONE credit family (videoAnalysisCreditSegment maps both;
+  // plan internals live in the private analysis plugin).
+  "mixed-video-analysis": {
+    id: "mixed-video-analysis",
+    kind: "video",
+    modes: ["video-analysis"] as const,
+    family: "Nodaro",
+    label: "Video Analysis (Mixed)",
+    series: "Video Analysis",
+    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: 14, note: "10-min ceiling (no duration given)" },
+      { identifier: "video-analysis:mixed:60s", credits: 3 },
+      { identifier: "video-analysis:mixed:180s", credits: 4 },
+      { identifier: "video-analysis:mixed:360s", credits: 9 },
+      { identifier: "video-analysis:mixed:600s", credits: 14, note: "10-min ceiling" },
+    ],
+  },
 }
 
 // =============================================================================

package/src/video-analysis-pricing.ts

@@ -54,6 +54,24 @@ export const VIDEO_ANALYSIS_BUCKET_CREDITS: Record<string, number> = {
   "video-analysis:gemini-3.1-pro:180s": 3,
   "video-analysis:gemini-3.1-pro:360s": 7,
   "video-analysis:gemini-3.1-pro:600s": 11,
+  // 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": 3,
+  "video-analysis:mixed:180s": 4,
+  "video-analysis:mixed:360s": 9,
+  "video-analysis:mixed:600s": 14,
+}
+
+/**
+ * The credit-id MODEL SEGMENT for an engine identifier: both mixed-tier
+ * sentinels share the `mixed` price family (same engine plan); everything
+ * else prices under its own identifier. Single source of truth — used by
+ * `buildVideoAnalysisCreditId` below, so route/orchestrator/UI callers can
+ * never diverge on where a sentinel prices.
+ */
+export function videoAnalysisCreditSegment(modelOrSentinel: string): string {
+  return modelOrSentinel === "mixed-fast" ? "mixed" : modelOrSentinel
 }
 
 export function pickVideoAnalysisBucket(durationSec: number): number {
@@ -65,7 +83,7 @@ export function buildVideoAnalysisCreditId(model: string, durationSec?: number):
   const bucket = durationSec !== undefined && durationSec > 0
     ? pickVideoAnalysisBucket(Math.min(durationSec, VIDEO_ANALYSIS_MAX_DURATION_SEC))
     : VIDEO_ANALYSIS_MAX_DURATION_SEC // unknown → ceiling composite (the ONLY silent-ceiling path)
-  return `video-analysis:${model}:${bucket}s`
+  return `video-analysis:${videoAnalysisCreditSegment(model)}:${bucket}s`
 }
 
 export function bucketSecondsFromCreditId(creditId: string): number | null {