@nodaro/shared 1.11.0 → 1.13.0

package/package.json

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

@@ -12,6 +12,7 @@ import {
   effectiveReasoningEffort,
 } from "../llm-models.js"
 import type { LlmModelDef, LlmTier, LlmFeature } from "../llm-models.js"
+import { PIPELINE_PINNABLE_SCRIPT_LLMS } from "../pipeline-types.js"
 
 // The provider-$ per-token rate table and `calculateLlmCost` moved to
 // backend/src/lib/pricing/llm-cost.ts (S5) — its tests live in
@@ -128,6 +129,32 @@ describe("LLM_MODEL_IDS", () => {
 // getLlmModel
 // ---------------------------------------------------------------------------
 describe("getLlmModel", () => {
+  // Dash-alias resolution: wire contracts (PIPELINE_PINNABLE_SCRIPT_LLMS,
+  // provider slugs, persisted configs) carry dash forms while LLM_MODELS keys
+  // canonical dot ids — getLlmModel must accept both or the film pipeline's
+  // own script default throws "Unknown LLM model" at run time.
+  it("resolves dash-form aliases to their canonical dot-form models", () => {
+    expect(getLlmModel("claude-sonnet-4-6")?.id).toBe("claude-sonnet-4.6")
+    expect(getLlmModel("claude-opus-4-7")?.id).toBe("claude-opus-4.7")
+    expect(getLlmModel("claude-haiku-4-5")?.id).toBe("claude-haiku-4.5")
+  })
+
+  it("resolves every PIPELINE_PINNABLE_SCRIPT_LLMS member (the film pipeline's pin surface)", () => {
+    for (const id of PIPELINE_PINNABLE_SCRIPT_LLMS) {
+      expect(getLlmModel(id), `pinnable script llm ${id} must resolve`).toBeDefined()
+    }
+  })
+
+  it("resolves provider slugs as historical aliases", () => {
+    const dated = LLM_MODELS.find((m) => m.directFallbackModel && m.directFallbackModel !== m.id)
+    if (dated) expect(getLlmModel(dated.directFallbackModel!)?.id).toBe(dated.id)
+  })
+
+  it("still returns undefined for a genuinely unknown id", () => {
+    expect(getLlmModel("claude-sonnet-9-9")).toBeUndefined()
+    expect(getLlmModel("not-a-model")).toBeUndefined()
+  })
+
   it('returns model def for "gemini-3-flash"', () => {
     const model = getLlmModel("gemini-3-flash")
     expect(model).toBeDefined()

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,
@@ -463,6 +467,7 @@ export type { LocationCatalogRef } from "./location-preset-catalog-map.js"
 
 export {
   PARAMETER_NODE_TYPES,
+  HINT_EXEMPT_PARAMETER_TYPES,
   getParameterValue,
 } from "./parameter-node-value.js"
 

package/src/llm-models.ts

@@ -327,8 +327,29 @@ export function getLlmModalityCaps(modelId: string | undefined): { image: boolea
   return LLM_MODALITY_CAPS[modelId] ?? { image: true, video: false, audio: false }
 }
 
+/**
+ * Dash-form aliases resolve to their canonical dot-form ids. Several wire
+ * contracts carry dash forms (`PIPELINE_PINNABLE_SCRIPT_LLMS`, provider slugs,
+ * configs persisted before the id scheme settled), while `LLM_MODELS` keys the
+ * canonical `major.minor` form — an exact-only lookup makes every such caller
+ * throw "Unknown LLM model" at run time. Normalizing here (instead of editing
+ * the enums) keeps stored configs and published-package consumers valid.
+ */
+function dashAliasToCanonical(id: string): string {
+  return id.replace(/-(\d+)-(\d+)$/, "-$1.$2")
+}
+
 export function getLlmModel(id: string): LlmModelDef | undefined {
-  return LLM_MODELS.find((m) => m.id === id)
+  const exact = LLM_MODELS.find((m) => m.id === id)
+  if (exact) return exact
+  const canonical = dashAliasToCanonical(id)
+  if (canonical !== id) {
+    const aliased = LLM_MODELS.find((m) => m.id === canonical)
+    if (aliased) return aliased
+  }
+  // Last resort: provider slugs double as historical aliases (e.g. the
+  // dated Anthropic slugs) — accept any model whose slug matches exactly.
+  return LLM_MODELS.find((m) => m.kieSlugOrModel === id || m.directFallbackModel === id)
 }
 
 export function getLlmTier(id: string): LlmTier {
@@ -396,26 +417,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/parameter-node-value.ts

@@ -57,6 +57,26 @@ export const PARAMETER_NODE_TYPES: ReadonlySet<string> = new Set([
   "voice-delivery",
 ])
 
+/**
+ * Parameter types that intentionally produce NO prompt hint from
+ * `getParameterPromptHint` (in `@nodaro/prompts`). They carry pure runtime
+ * parameters — counts, durations, aspect ratios, legacy motion intensity —
+ * consumed by the executor directly, never appended to a downstream prompt.
+ *
+ * Consumers that treat "parameter node" as "text producer" (the `{Label}`
+ * auto-fill in `main-text-handle.ts`, ref-map builders) must exclude these:
+ * their extracted output is undefined, so an auto-filled `{Label}` would stay
+ * in the outgoing prompt as literal brace text. Guarded by
+ * `parameter-registry-sync.test.ts` (each member really returns "") and
+ * `main-text-handle.test.ts` (members are not text-producing).
+ */
+export const HINT_EXEMPT_PARAMETER_TYPES: ReadonlySet<string> = new Set([
+  "motion",
+  "scene-count",
+  "duration",
+  "aspect-ratio",
+])
+
 export function getParameterValue(
   data: Record<string, unknown>,
   nodeType: string,

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 {