@nodaro/shared 1.14.0 → 1.16.0

package/package.json

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

@@ -24,8 +24,8 @@ import { PIPELINE_PINNABLE_SCRIPT_LLMS } from "../pipeline-types.js"
 // LLM_MODELS data integrity
 // ---------------------------------------------------------------------------
 describe("LLM_MODELS data integrity", () => {
-  it("should have exactly 13 models", () => {
-    expect(LLM_MODELS).toHaveLength(13)
+  it("should have exactly 15 models", () => {
+    expect(LLM_MODELS).toHaveLength(15)
   })
 
   it("each model has all required fields", () => {
@@ -60,14 +60,14 @@ describe("LLM_MODELS data integrity", () => {
     expect(new Set(ids).size).toBe(ids.length)
   })
 
-  it("has 3 economy, 4 standard, 6 premium models", () => {
+  it("has 4 economy, 4 standard, 7 premium models", () => {
     const tierCounts: Record<LlmTier, number> = { economy: 0, standard: 0, premium: 0 }
     for (const model of LLM_MODELS) {
       tierCounts[model.tier]++
     }
-    expect(tierCounts.economy).toBe(3)
+    expect(tierCounts.economy).toBe(4)
     expect(tierCounts.standard).toBe(4)
-    expect(tierCounts.premium).toBe(6)
+    expect(tierCounts.premium).toBe(7)
   })
 
   it("all three kieFormats are represented", () => {
@@ -108,6 +108,7 @@ describe("LLM_MODEL_IDS", () => {
   it("contains all expected model ids", () => {
     const expected = [
       "gemini-3-flash",
+      "gemini-3.6-flash",
       "claude-haiku-4.5",
       "claude-sonnet-4.6",
       "gpt-5.2",
@@ -120,6 +121,7 @@ describe("LLM_MODEL_IDS", () => {
       "gpt-5.6-sol",
       "claude-sonnet-5",
       "claude-opus-4.8",
+      "claude-fable-5",
     ]
     expect(LLM_MODEL_IDS).toEqual(expected)
   })
@@ -387,8 +389,8 @@ describe("LLM_FEATURE_DEFAULTS", () => {
     }
   })
 
-  it('"prompt-helper" defaults to "gemini-3-flash" (economy)', () => {
-    expect(LLM_FEATURE_DEFAULTS["prompt-helper"]).toBe("gemini-3-flash")
+  it('"prompt-helper" defaults to "gemini-3.6-flash" (economy)', () => {
+    expect(LLM_FEATURE_DEFAULTS["prompt-helper"]).toBe("gemini-3.6-flash")
     expect(getLlmTier(LLM_FEATURE_DEFAULTS["prompt-helper"])).toBe("economy")
   })
 
@@ -404,12 +406,12 @@ describe("LLM_FEATURE_DEFAULTS", () => {
     expect(STRUCTURED_VISION_MODELS.map((m) => m.id)).toContain("claude-opus-4.7")
   })
 
-  it('"generate-script" defaults to "gemini-3-flash" (economy)', () => {
-    expect(LLM_FEATURE_DEFAULTS["generate-script"]).toBe("gemini-3-flash")
+  it('"generate-script" defaults to "gemini-3.6-flash" (economy)', () => {
+    expect(LLM_FEATURE_DEFAULTS["generate-script"]).toBe("gemini-3.6-flash")
   })
 
-  it('"translate" defaults to "gemini-3-flash" (economy)', () => {
-    expect(LLM_FEATURE_DEFAULTS["translate"]).toBe("gemini-3-flash")
+  it('"translate" defaults to "gemini-3.6-flash" (economy)', () => {
+    expect(LLM_FEATURE_DEFAULTS["translate"]).toBe("gemini-3.6-flash")
   })
 
   it("composition features default to claude-sonnet-4.6", () => {
@@ -454,9 +456,11 @@ describe("STRUCTURED_VISION_MODELS", () => {
         "claude-opus-4.7",
         "claude-sonnet-4.6",
         "gemini-3-flash",
+        "gemini-3.6-flash",
         "gemini-3.1-pro",
         "claude-sonnet-5",
         "claude-opus-4.8",
+        "claude-fable-5",
         // responses-format GPTs — KIE text.format json_schema live-verified
         // 2026-07-14 (text AND vision inputs).
         "gpt-5.4",
@@ -509,6 +513,14 @@ describe("reasoning effort registry", () => {
     expect(getLlmTier("claude-sonnet-5")).toBe("standard")
     expect(getLlmTier("claude-opus-4.8")).toBe("premium")
     expect(getLlmTier("gpt-5.5")).toBe("premium")
+    expect(getLlmTier("gemini-3.6-flash")).toBe("economy")
+    expect(getLlmTier("claude-fable-5")).toBe("premium")
+  })
+
+  it("gemini-3.6-flash exposes the KIE low/high thinking levels; claude-fable-5 the full Claude ladder", () => {
+    expect(getLlmModel("gemini-3.6-flash")?.reasoningEfforts).toEqual(["low", "high"])
+    expect(getLlmModel("claude-fable-5")?.reasoningEfforts).toEqual(["low", "medium", "high", "xhigh", "max"])
+    expect(getLlmModel("claude-fable-5")?.directFallbackModel).toBe("claude-fable-5")
   })
 })
 
@@ -551,6 +563,9 @@ describe("buildLlmCreditIdentifier effort bump (xhigh/max only)", () => {
     expect(buildLlmCreditIdentifier("llm-chat", "gpt-5.4", "xhigh")).toBe("llm-chat:premium")
     // gpt-5.4 is premium anyway; the real clamp case:
     expect(buildLlmCreditIdentifier("llm-chat", "gemini-3-flash", "max")).toBe("llm-chat:economy")
+    // gemini-3.6-flash tops out at "high" — max clamps to high, never bumps.
+    expect(effectiveReasoningEffort("gemini-3.6-flash", "max")).toBe("high")
+    expect(buildLlmCreditIdentifier("llm-chat", "gemini-3.6-flash", "max")).toBe("llm-chat:economy")
   })
   it("back-compat: no effort arg → identical to today for every model", () => {
     for (const m of LLM_MODELS) {

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

@@ -7,7 +7,7 @@ import {
 } from "../video-analysis-pricing.js"
 import {
   VIDEO_ANALYSIS_LLM_MODELS, VIDEO_ANALYSIS_TIERS, VIDEO_ANALYSIS_TIER_ORDER,
-  VIDEO_ANALYSIS_MIXED_TIERS,
+  VIDEO_ANALYSIS_MIXED_TIERS, VIDEO_ANALYSIS_LEGACY_MODELS,
   DEFAULT_VIDEO_ANALYSIS_TIER, DEFAULT_VIDEO_ANALYSIS_MODEL, resolveVideoAnalysisModel,
 } from "../llm-models.js"
 
@@ -41,15 +41,28 @@ describe("video-analysis-pricing", () => {
   })
 
   it("model SSOT is capability-derived and Gemini-only today", () => {
-    expect(VIDEO_ANALYSIS_LLM_MODELS).toEqual(["gemini-3-flash", "gemini-3.1-pro"])
+    expect(VIDEO_ANALYSIS_LLM_MODELS).toEqual(["gemini-3-flash", "gemini-3.6-flash", "gemini-3.1-pro"])
   })
 
-  it("tier layer: every model-backed 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 or explicitly legacy (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.
+    // unreachable / unnamed — this fails until an explicit decision is made:
+    // either a tier targets it, or it's acknowledged in
+    // VIDEO_ANALYSIS_LEGACY_MODELS (kept only for stored raw-id configs).
     const tierTargets = Object.values(VIDEO_ANALYSIS_TIERS)
+    const legacy = Object.keys(VIDEO_ANALYSIS_LEGACY_MODELS)
     for (const m of tierTargets) expect(VIDEO_ANALYSIS_LLM_MODELS).toContain(m)
-    for (const m of VIDEO_ANALYSIS_LLM_MODELS) expect(tierTargets).toContain(m)
+    for (const m of VIDEO_ANALYSIS_LLM_MODELS) {
+      expect([...tierTargets, ...legacy], `${m} needs a tier or a legacy entry`).toContain(m)
+    }
+    // Legacy entries are strictly the OTHER side of that decision: a legacy
+    // model is never also a tier target, must still be video-capable, and must
+    // point at a real tier (the tier it used to back — UIs reverse-map via it).
+    for (const [m, tier] of Object.entries(VIDEO_ANALYSIS_LEGACY_MODELS)) {
+      expect(tierTargets).not.toContain(m)
+      expect(VIDEO_ANALYSIS_LLM_MODELS).toContain(m)
+      expect(Object.keys(VIDEO_ANALYSIS_TIERS)).toContain(tier)
+    }
     // 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]),
@@ -59,14 +72,25 @@ describe("video-analysis-pricing", () => {
     for (const t of VIDEO_ANALYSIS_MIXED_TIERS) expect(VIDEO_ANALYSIS_LLM_MODELS).not.toContain(t)
   })
 
+  it("fast tier never prices above pro in any bucket", () => {
+    for (const bucketSec of VIDEO_ANALYSIS_DURATION_BUCKETS) {
+      const fast = VIDEO_ANALYSIS_BUCKET_CREDITS[buildVideoAnalysisCreditId(VIDEO_ANALYSIS_TIERS.fast, bucketSec)]!
+      const pro = VIDEO_ANALYSIS_BUCKET_CREDITS[buildVideoAnalysisCreditId(VIDEO_ANALYSIS_TIERS.pro, bucketSec)]!
+      expect(fast, `fast > pro at ${bucketSec}s`).toBeLessThanOrEqual(pro)
+    }
+  })
+
   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("fast")).toBe("gemini-3.6-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
+    // 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")
+    expect(resolveVideoAnalysisModel("gemini-3.6-flash")).toBe("gemini-3.6-flash")
     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

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

@@ -104,6 +104,23 @@ describe("appearance variations (cast-variations spec §4)", () => {
   })
 })
 
+describe("variationFolds (cast-variations §4/§6 — review F5)", () => {
+  const meta = { durationSec: 10, width: 1920, height: 1080, aspectRatio: "16:9" }
+  const doc = {
+    meta,
+    slots: [slot],
+    scenes: [{ ...baseScene, sceneNumber: 1, visualResolved: "a man juggles", slotRefs: ["hero"] }],
+  }
+  it("videoAnalysisResultSchema round-trips variationFolds — strip-mode consumers keep the §6 fold note", () => {
+    const withFolds = { ...doc, variationFolds: [{ slotId: "hero", variationId: "era", label: "Era" }] }
+    expect(videoAnalysisResultSchema.parse(withFolds)).toEqual(withFolds)
+  })
+  it("absent variationFolds stays absent (no [] materialization)", () => {
+    const parsed = videoAnalysisResultSchema.parse(doc)
+    expect("variationFolds" in parsed && parsed.variationFolds !== undefined).toBe(false)
+  })
+})
+
 describe("binding rewrite helpers (merge consumes — spec §4)", () => {
   it("rewriteSceneBindings renames slot keys and per-slot variation values", () => {
     expect(rewriteSceneBindings({ "man-2": "dream", other: "era" }, { "man-2": "hero" }, { hero: { dream: "flashback" } }))

package/src/index.ts

@@ -256,6 +256,7 @@ export {
   STRUCTURED_VISION_MODELS,
   VIDEO_ANALYSIS_LLM_MODELS,
   VIDEO_ANALYSIS_TIERS,
+  VIDEO_ANALYSIS_LEGACY_MODELS,
   type VideoAnalysisTier,
   type VideoAnalysisModelTier,
   VIDEO_ANALYSIS_MIXED_TIERS,

package/src/llm-models.ts

@@ -72,6 +72,24 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     supportsImages: true,
     maxOutputTokens: 8192,
   },
+  {
+    id: "gemini-3.6-flash",
+    displayName: "Gemini 3.6 Flash",
+    desc: "Latest fast Gemini, sharper reasoning",
+    tier: "economy",
+    kieFormat: "chat-completions",
+    // KIE serves Gemini 3.6 Flash on the OpenAI-compatible dialect under this
+    // slug (docs.kie.ai/market/gemini/gemini-3-6-flash-openai.md) — same
+    // chat-completions path shape as gemini-3-flash, different slug prefix.
+    kieSlugOrModel: "gemini-3-6-flash-openai",
+    vendor: "google",
+    structuredOutputMode: "kie-response-format",
+    supportsImages: true,
+    maxOutputTokens: 8192,
+    // KIE's 3.6 endpoint accepts `reasoning_effort: low | high` (thinking
+    // level) — exactly the chat-completions wire mapping deriveParams sends.
+    reasoningEfforts: ["low", "high"],
+  },
   {
     id: "claude-haiku-4.5",
     displayName: "Claude Haiku 4.5",
@@ -240,6 +258,22 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     supportsTemperature: false,
     preferKie: true,
   },
+  {
+    id: "claude-fable-5",
+    displayName: "Claude Fable 5",
+    desc: "Frontier Claude above Opus, hardest problems",
+    tier: "premium",
+    kieFormat: "messages",
+    kieSlugOrModel: "claude-fable-5",
+    vendor: "anthropic",
+    structuredOutputMode: "anthropic-tool",
+    supportsImages: true,
+    maxOutputTokens: 16384,
+    directFallbackModel: "claude-fable-5",
+    reasoningEfforts: ["low", "medium", "high", "xhigh", "max"],
+    supportsTemperature: false,
+    preferKie: true,
+  },
 ] as const
 
 export const LLM_MODEL_IDS = LLM_MODELS.map((m) => m.id)
@@ -280,8 +314,8 @@ export function motionGraphicsFeature(engine?: string): LlmFeature {
 /** Feature → default model when user hasn't selected one */
 export const LLM_FEATURE_DEFAULTS: Record<LlmFeature, string> = {
   "ai-writer": "claude-sonnet-4.6",
-  "llm-chat": "gemini-3-flash",
-  "prompt-helper": "gemini-3-flash",
+  "llm-chat": "gemini-3.6-flash",
+  "prompt-helper": "gemini-3.6-flash",
   "scene-graph-ai": "claude-sonnet-4.6",
   "after-effects": "claude-sonnet-4.6",
   "motion-graphics": "claude-sonnet-4.6",
@@ -291,8 +325,8 @@ export const LLM_FEATURE_DEFAULTS: Record<LlmFeature, string> = {
   "image-to-text": "claude-sonnet-4.6",
   "describe-to-picker": "claude-opus-4.7",
   "qa-check": "claude-sonnet-4.6",
-  "generate-script": "gemini-3-flash",
-  "translate": "gemini-3-flash",
+  "generate-script": "gemini-3.6-flash",
+  "translate": "gemini-3.6-flash",
   "image-critic": "claude-sonnet-4.6",
 }
 
@@ -307,6 +341,7 @@ export const LLM_FEATURE_DEFAULTS: Record<LlmFeature, string> = {
  */
 export const LLM_MODALITY_CAPS: Record<string, { image: boolean; video: boolean; audio: boolean }> = {
   "gemini-3-flash":    { image: true,  video: true,  audio: true  },
+  "gemini-3.6-flash":  { image: true,  video: true,  audio: true  },
   "gemini-3.1-pro":    { image: true,  video: true,  audio: true  },
   "claude-haiku-4.5":  { image: true,  video: false, audio: false },
   "claude-sonnet-4.6": { image: true,  video: false, audio: false },
@@ -319,6 +354,7 @@ export const LLM_MODALITY_CAPS: Record<string, { image: boolean; video: boolean;
   "gpt-5.6-sol":       { image: true,  video: false, audio: false },
   "claude-sonnet-5":   { image: true,  video: false, audio: false },
   "claude-opus-4.8":   { image: true,  video: false, audio: false },
+  "claude-fable-5":    { image: true,  video: false, audio: false },
 }
 
 /** Capability lookup with safe default — unknown models get image-only. */
@@ -416,8 +452,23 @@ 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-flash", pro: "gemini-3.1-pro" } as const
+export const VIDEO_ANALYSIS_TIERS = { fast: "gemini-3.6-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.
+ * They stay video+audio-capable (so they remain in VIDEO_ANALYSIS_LLM_MODELS):
+ * stored raw `llmModel` values keep resolving via the passthrough in
+ * `resolveVideoAnalysisModel` and keep pricing under their own credit family —
+ * but no tier reaches them for NEW runs. UIs use this map to reverse a stored
+ * raw id to the tier the user originally chose (video-configs fail-safe).
+ * The tier guard test requires every video-capable model to be a tier target
+ * OR a key here, so replacing a tier's backing model stays an explicit,
+ * 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",
+}
 /**
  * MIXED tiers — advanced multi-engine analysis plans whose identifier resolves
  * to an engine-plan SENTINEL consumed by the analysis engine, never to a single

package/src/model-catalog.ts

@@ -1810,9 +1810,9 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
     kind: "video",
     modes: ["video-analysis"] as const,
     family: "Nodaro",
-    label: "Video Analysis (Fast)",
+    label: "Video Analysis (Fast — legacy)",
     series: "Video Analysis",
-    description: "Analyze a video into a structured shot list (scenes, camera, audio) — fast, economy tier. Billed per duration bucket.",
+    description: "Legacy fast-tier analysis model (pre-2026-07). Kept so stored raw-model configs keep running and pricing unchanged; new fast-tier runs use the current fast model.",
     useCases: ["video-analysis", "shot-list", "fast"],
     pricing: [
       { identifier: "video-analysis:gemini-3-flash", credits: 3, note: "10-min ceiling (no duration given)" },
@@ -1822,6 +1822,23 @@ const VIDEO_MODELS: Record<string, ModelCatalogEntry> = {
       { identifier: "video-analysis:gemini-3-flash:600s", credits: 3, note: "10-min ceiling" },
     ],
   },
+  "gemini-3.6-flash-video-analysis": {
+    id: "gemini-3.6-flash-video-analysis",
+    kind: "video",
+    modes: ["video-analysis"] as const,
+    family: "Nodaro",
+    label: "Video Analysis (Fast)",
+    series: "Video Analysis",
+    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: 9, note: "10-min ceiling (no duration given)" },
+      { identifier: "video-analysis:gemini-3.6-flash:60s", credits: 2 },
+      { identifier: "video-analysis:gemini-3.6-flash:180s", credits: 2 },
+      { identifier: "video-analysis:gemini-3.6-flash:360s", credits: 5 },
+      { identifier: "video-analysis:gemini-3.6-flash:600s", credits: 9, note: "10-min ceiling" },
+    ],
+  },
   "gemini-3.1-pro-video-analysis": {
     id: "gemini-3.1-pro-video-analysis",
     kind: "video",

package/src/video-analysis-pricing.ts

@@ -46,10 +46,17 @@ export const VIDEO_ANALYSIS_WINDOW = { LEN: WINDOW_LEN, STRIDE: WINDOW_STRIDE, O
  * `docs/nodes/processing-video/video-analysis.md`.
  */
 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": 1,
   "video-analysis:gemini-3-flash:180s": 1,
   "video-analysis:gemini-3-flash:360s": 2,
   "video-analysis:gemini-3-flash:600s": 3,
+  // 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": 2,
+  "video-analysis:gemini-3.6-flash:180s": 2,
+  "video-analysis:gemini-3.6-flash:360s": 5,
+  "video-analysis:gemini-3.6-flash:600s": 9,
   "video-analysis:gemini-3.1-pro:60s": 2,
   "video-analysis:gemini-3.1-pro:180s": 3,
   "video-analysis:gemini-3.1-pro:360s": 7,

package/src/video-analysis.ts

@@ -128,6 +128,16 @@ export const videoAnalysisResultSchema = z.object({
   }),
   slots: z.array(entitySlotSchema),
   scenes: z.array(analyzedSceneSchema).min(1),
+  /** CAST VARIATIONS (§4 cap handling): looks the analyzer's merge FOLDED into
+   *  the default at VIDEO_ANALYSIS_MAX_VARIATIONS — recorded, never silent. In
+   *  the wire schema so strip-mode consumers (the recast client's validated
+   *  blueprint view) keep it: the §6 "folded into default look" note is the
+   *  user's only pre-pay defense against a wrong split. */
+  variationFolds: z.array(z.object({
+    slotId: z.string(),
+    variationId: z.string(),
+    label: z.string(),
+  })).optional(),
 })
 export type VideoAnalysisResult = z.infer<typeof videoAnalysisResultSchema>