@nodaro/shared 1.21.0 → 1.22.0

package/package.json

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

@@ -10,6 +10,8 @@ import {
   resolveLlmCreditId,
   motionGraphicsFeature,
   effectiveReasoningEffort,
+  supportsAdvancedMode,
+  availableReasoningEfforts,
 } from "../llm-models.js"
 import type { LlmModelDef, LlmTier, LlmFeature } from "../llm-models.js"
 import { PIPELINE_PINNABLE_SCRIPT_LLMS } from "../pipeline-types.js"
@@ -609,3 +611,139 @@ describe("buildLlmCreditIdentifier effort bump (xhigh/max only)", () => {
     expect(resolveLlmCreditId("llm-chat", { llmModel: "gpt-5.6-terra", reasoningEffort: "max" })).toBe("llm-chat:premium")
   })
 })
+
+describe("direct-vendor lane declarations", () => {
+  it("no model declares BOTH preferKie and preferDirect", () => {
+    // They are the two halves of one idea (which lane goes first). Declaring
+    // both is meaningless and would make routing depend on branch order in
+    // llm-client rather than on the registry.
+    const conflicted = LLM_MODELS.filter((m) => m.preferKie && m.preferDirect).map((m) => m.id)
+    expect(conflicted).toEqual([])
+  })
+
+  it("preferDirect is only meaningful alongside a directGeminiModel", () => {
+    const orphaned = LLM_MODELS.filter((m) => m.preferDirect && !m.directGeminiModel).map((m) => m.id)
+    expect(orphaned).toEqual([])
+  })
+
+  it("every direct-lane model id is a non-empty, non-placeholder string", () => {
+    for (const m of LLM_MODELS.filter((x) => x.directGeminiModel)) {
+      expect(m.directGeminiModel!.length, m.id).toBeGreaterThan(0)
+      expect(m.directGeminiModel, m.id).not.toContain(" ")
+    }
+  })
+
+  it("only google-vendor models carry a Gemini direct lane", () => {
+    const misvendored = LLM_MODELS.filter((m) => m.directGeminiModel && m.vendor !== "google").map((m) => m.id)
+    expect(misvendored).toEqual([])
+  })
+
+  it("getLlmModel resolves a model by its direct Google id", () => {
+    // The `-preview`-suffixed Google ids differ from our canonical ids, and
+    // cost/usage reconciliation looks models up by whatever id the wire used.
+    expect(getLlmModel("gemini-3.1-pro-preview")?.id).toBe("gemini-3.1-pro")
+    expect(getLlmModel("gemini-3-flash-preview")?.id).toBe("gemini-3-flash")
+  })
+})
+
+describe("advanced mode", () => {
+  it("is available exactly on models with a direct Gemini lane", () => {
+    for (const m of LLM_MODELS) {
+      expect(supportsAdvancedMode(m.id), m.id).toBe(Boolean(m.directGeminiModel))
+    }
+  })
+
+  it("is unavailable for an unknown or missing model id", () => {
+    expect(supportsAdvancedMode(undefined)).toBe(false)
+    expect(supportsAdvancedMode("not-a-real-model")).toBe(false)
+  })
+
+  it("bumps the credit tier one step", () => {
+    // gemini-3-flash is economy → standard (standard renders as the bare feature)
+    expect(buildLlmCreditIdentifier("llm-chat", "gemini-3-flash")).toBe("llm-chat:economy")
+    expect(buildLlmCreditIdentifier("llm-chat", "gemini-3-flash", undefined, true)).toBe("llm-chat")
+  })
+
+  it("is independent of the effort bump — advanced adds exactly one step", () => {
+    // No Gemini model declares xhigh/max today (their KIE-safe ceiling is
+    // `high`, which never bumps), so the two bumps cannot currently stack in
+    // practice — `max` clamps to `high` first. What must hold regardless is
+    // that advanced adds exactly one step on top of whatever the
+    // effort-clamped tier already is.
+    for (const effort of [undefined, "low", "high", "max"]) {
+      const plain = buildLlmCreditIdentifier("llm-chat", "gemini-3.6-flash", effort)
+      const advanced = buildLlmCreditIdentifier("llm-chat", "gemini-3.6-flash", effort, true)
+      expect(plain, `effort=${effort}`).toBe("llm-chat:economy")
+      expect(advanced, `effort=${effort}`).toBe("llm-chat")
+    }
+  })
+
+  it("never bumps past premium", () => {
+    expect(buildLlmCreditIdentifier("llm-chat", "gemini-3.1-pro", "max", true)).toBe("llm-chat:premium")
+  })
+
+  it("ignores the flag on a model that cannot run advanced (no silent overcharge)", () => {
+    // gpt-5.2 has no direct lane — a stale advancedMode flag must not inflate it.
+    expect(buildLlmCreditIdentifier("llm-chat", "gpt-5.2", undefined, true))
+      .toBe(buildLlmCreditIdentifier("llm-chat", "gpt-5.2"))
+    expect(buildLlmCreditIdentifier("llm-chat", "claude-opus-4.7", undefined, true))
+      .toBe(buildLlmCreditIdentifier("llm-chat", "claude-opus-4.7"))
+  })
+
+  it("back-compat: omitting the 4th arg is identical to before for every model", () => {
+    for (const m of LLM_MODELS) {
+      expect(buildLlmCreditIdentifier("x", m.id, "high", false)).toBe(buildLlmCreditIdentifier("x", m.id, "high"))
+    }
+  })
+
+  it("resolveLlmCreditId reads advancedMode from the raw body", () => {
+    expect(resolveLlmCreditId("llm-chat", { llmModel: "gemini-3-flash", advancedMode: true })).toBe("llm-chat")
+    expect(resolveLlmCreditId("llm-chat", { llmModel: "gemini-3-flash" })).toBe("llm-chat:economy")
+    // Only a real boolean true counts — a truthy string must not bump.
+    expect(resolveLlmCreditId("llm-chat", { llmModel: "gemini-3-flash", advancedMode: "yes" })).toBe("llm-chat:economy")
+  })
+})
+
+describe("lane-aware reasoning efforts", () => {
+  it("widens the ladder on the direct lane where the vendor accepts more", () => {
+    expect(availableReasoningEfforts("gemini-3.6-flash")).toEqual(["low", "high"])
+    expect(availableReasoningEfforts("gemini-3.6-flash", true)).toEqual(["none", "low", "medium", "high"])
+  })
+
+  it("exposes an effort lever on models that have none via KIE", () => {
+    // gemini-3-flash declares no reasoningEfforts at all — Advanced is the
+    // only way its effort picker appears.
+    expect(availableReasoningEfforts("gemini-3-flash")).toEqual([])
+    expect(availableReasoningEfforts("gemini-3-flash", true)).toEqual(["none", "low", "medium", "high"])
+  })
+
+  it("respects a shorter direct ladder (3.1 Pro has no minimal tier)", () => {
+    expect(availableReasoningEfforts("gemini-3.1-pro", true)).toEqual(["low", "medium", "high"])
+  })
+
+  it("ignores the advanced flag on a model with no direct lane", () => {
+    const claude = availableReasoningEfforts("claude-sonnet-4.6")
+    expect(availableReasoningEfforts("claude-sonnet-4.6", true)).toEqual(claude)
+  })
+
+  it("clamps against the lane's ladder, not the other lane's", () => {
+    // `medium` is not on 3.6-flash's KIE ladder → clamps down to `low`.
+    expect(effectiveReasoningEffort("gemini-3.6-flash", "medium")).toBe("low")
+    // On the direct lane `medium` is a real level → survives.
+    expect(effectiveReasoningEffort("gemini-3.6-flash", "medium", true)).toBe("medium")
+  })
+
+  it("every directReasoningEfforts entry is a valid effort, ascending", () => {
+    for (const m of LLM_MODELS.filter((x) => x.directReasoningEfforts)) {
+      const levels = m.directReasoningEfforts!
+      for (const l of levels) expect(LLM_REASONING_EFFORTS, m.id).toContain(l)
+      const ranks = levels.map((l) => LLM_REASONING_EFFORTS.indexOf(l))
+      expect(ranks, `${m.id} must be ascending`).toEqual([...ranks].sort((a, b) => a - b))
+    }
+  })
+
+  it("only advanced-capable models declare a direct ladder", () => {
+    const bad = LLM_MODELS.filter((m) => m.directReasoningEfforts && !supportsAdvancedMode(m.id)).map((m) => m.id)
+    expect(bad).toEqual([])
+  })
+})

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

@@ -0,0 +1,63 @@
+/**
+ * The model catalog hand-copies video-analysis credit values that already live
+ * in `VIDEO_ANALYSIS_BUCKET_CREDITS`. Nothing cross-checked the two, so a
+ * reprice could update the table (and the DB migration) while the catalog kept
+ * quoting the old numbers — and the catalog is what the model browser shows a
+ * user BEFORE they run anything.
+ *
+ * This is the guard that was missing.
+ */
+import { describe, it, expect } from "vitest"
+import { MODEL_CATALOG } from "../model-catalog.js"
+import {
+  VIDEO_ANALYSIS_BUCKET_CREDITS,
+  VIDEO_ANALYSIS_DURATION_BUCKETS,
+  VIDEO_ANALYSIS_MAX_DURATION_SEC,
+} from "../video-analysis-pricing.js"
+
+/** Every `video-analysis:*` pricing row declared anywhere in the catalog. */
+const catalogRows = Object.values(MODEL_CATALOG)
+  .flatMap((m) => (m.pricing ?? []) as ReadonlyArray<{ identifier: string; credits: number }>)
+  .filter((r) => r.identifier.startsWith("video-analysis:"))
+
+describe("model catalog video-analysis pricing", () => {
+  it("declares at least one row (guard is actually wired to something)", () => {
+    expect(catalogRows.length).toBeGreaterThan(0)
+  })
+
+  it("every bucketed catalog row matches VIDEO_ANALYSIS_BUCKET_CREDITS exactly", () => {
+    const bucketed = catalogRows.filter((r) => /:\d+s$/.test(r.identifier))
+    expect(bucketed.length).toBeGreaterThan(0)
+    for (const row of bucketed) {
+      expect(
+        row.credits,
+        `catalog "${row.identifier}" = ${row.credits} but the table says ${VIDEO_ANALYSIS_BUCKET_CREDITS[row.identifier]}`,
+      ).toBe(VIDEO_ANALYSIS_BUCKET_CREDITS[row.identifier])
+    }
+  })
+
+  it("every bare (no-duration) catalog row equals its max-duration ceiling", () => {
+    // A bare id means "duration unknown", which the route prices at the ceiling.
+    const bare = catalogRows.filter((r) => !/:\d+s$/.test(r.identifier))
+    expect(bare.length).toBeGreaterThan(0)
+    for (const row of bare) {
+      const ceiling = VIDEO_ANALYSIS_BUCKET_CREDITS[`${row.identifier}:${VIDEO_ANALYSIS_MAX_DURATION_SEC}s`]
+      expect(ceiling, `no ceiling row for ${row.identifier}`).toBeDefined()
+      expect(row.credits, `catalog "${row.identifier}" must equal its ${VIDEO_ANALYSIS_MAX_DURATION_SEC}s ceiling`).toBe(ceiling)
+    }
+  })
+
+  it("catalog covers every bucket it claims a model supports", () => {
+    const byModel = new Map<string, Set<number>>()
+    for (const r of catalogRows) {
+      const m = /^video-analysis:(.+):(\d+)s$/.exec(r.identifier)
+      if (!m) continue
+      if (!byModel.has(m[1]!)) byModel.set(m[1]!, new Set())
+      byModel.get(m[1]!)!.add(Number(m[2]))
+    }
+    for (const [model, buckets] of byModel) {
+      expect([...buckets].sort((a, b) => a - b), `${model} bucket coverage`)
+        .toEqual([...VIDEO_ANALYSIS_DURATION_BUCKETS])
+    }
+  })
+})

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

@@ -113,10 +113,11 @@ describe("video-analysis-pricing", () => {
     }
   })
 
-  // 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
-  // check that the precomputed table covers every legal id.
+  // Full drift-detection against the live $-formula lives in the PRIVATE
+  // plugin repo (src/plugins/video-analysis/__tests__/cost.test.ts) — the
+  // formula moved there in 2026-07 and the app-side test was deleted with it,
+  // so nothing in THIS repo can recompute these numbers. This is a lightweight
+  // shape check that the precomputed table covers every legal id.
   it("VIDEO_ANALYSIS_BUCKET_CREDITS has a positive-integer entry for every model × bucket id", () => {
     for (const model of VIDEO_ANALYSIS_LLM_MODELS) {
       for (const bucketSec of VIDEO_ANALYSIS_DURATION_BUCKETS) {

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

@@ -5,7 +5,9 @@ import {
   renderAnalyzedScene, isOversizedScene, aspectRatioFromDims,
   entitySlotSchema, analyzedSceneSchema,
   rewriteSceneBindings, dropUnknownBindings,
-  rewriteSpeakerSlots, dropUnknownSpeakers,
+  rewriteSpeakerSlots, dropUnknownSpeakers, mergeClipLook,
+  VIDEO_ANALYSIS_SPEED_EFFECTS, VIDEO_ANALYSIS_SHOT_ANGLES, VIDEO_ANALYSIS_FACELESS_ANGLES,
+  VIDEO_ANALYSIS_VISUAL_EFFECTS, VIDEO_ANALYSIS_TRANSITIONS,
   VIDEO_ANALYSIS_MAX_VARIATIONS, VIDEO_ANALYSIS_VARIATION_SLUGS, VIDEO_ANALYSIS_DEFAULT_VARIATION,
   type EntitySlot, type AudioLayer,
 } from "../video-analysis.js"
@@ -216,6 +218,136 @@ describe("speech attribution (speakerSlot)", () => {
   })
 })
 
+describe("cinematography fields (angle / speed / onScreenText / look)", () => {
+  it("carries angle and speed as closed enums through a window round-trip", () => {
+    const parsed = windowAnalysisSchema.parse({
+      slots: [slot],
+      scenes: [{ ...baseScene, angle: "low", speed: "slow-motion", onScreenText: "ACT I" }],
+    })
+    expect(parsed.scenes[0]).toMatchObject({ angle: "low", speed: "slow-motion", onScreenText: "ACT I" })
+  })
+
+  it("supports the RELATIONAL viewpoints, so shotType keeps the size", () => {
+    // These were conventions inside the `shotType` list, competing with the
+    // sizes for one slot — so an over-the-shoulder MEDIUM had to throw one away.
+    const parsed = windowAnalysisSchema.parse({
+      slots: [slot],
+      scenes: [{ ...baseScene, shotType: "Medium", angle: "over-the-shoulder" }],
+    })
+    expect(parsed.scenes[0]).toMatchObject({ shotType: "Medium", angle: "over-the-shoulder" })
+    for (const a of ["pov", "profile", "from-behind"]) {
+      expect(windowAnalysisSchema.safeParse({ slots: [slot], scenes: [{ ...baseScene, angle: a }] }).success).toBe(true)
+    }
+  })
+
+  it("carries picture EFFECTS as an array — a shot can be grainy and vignetted", () => {
+    const parsed = windowAnalysisSchema.parse({
+      slots: [slot], scenes: [{ ...baseScene, effects: ["grain", "vignette"] }],
+    })
+    expect(parsed.scenes[0]!.effects).toEqual(["grain", "vignette"])
+  })
+
+  it("keeps compositing OUT of effects — that is where the phantom slot came from", () => {
+    // A field for "there is an inset of a person here" would hand a legitimate
+    // home to the invented `{slot:creator} overlay talking to camera`. An effect
+    // is verifiable in the pixels; a claim about who is inset is not.
+    for (const bad of ["picture-in-picture", "split-screen", "overlay"]) {
+      expect(windowAnalysisSchema.safeParse({ slots: [slot], scenes: [{ ...baseScene, effects: [bad] }] }).success).toBe(false)
+    }
+  })
+
+  it("transitions distinguish DISSOLVE from FADE — they look nothing alike", () => {
+    // Collapsed onto `fade` before this, so a cross-dissolve was rendered as a
+    // fade through black.
+    expect(VIDEO_ANALYSIS_TRANSITIONS).toContain("dissolve")
+    for (const t of VIDEO_ANALYSIS_TRANSITIONS) {
+      expect(windowAnalysisSchema.safeParse({ slots: [slot], scenes: [{ ...baseScene, transitionOut: t }] }).success).toBe(true)
+    }
+  })
+
+  it("effects and transitions are NOT the same axis", () => {
+    // `dissolve`/`fade` are edits BETWEEN shots; blur/pixelate are on the picture.
+    for (const t of ["dissolve", "fade", "wipe", "cut"]) {
+      expect(VIDEO_ANALYSIS_VISUAL_EFFECTS).not.toContain(t)
+    }
+    for (const e of VIDEO_ANALYSIS_VISUAL_EFFECTS) {
+      expect(VIDEO_ANALYSIS_TRANSITIONS).not.toContain(e as never)
+    }
+  })
+
+  it("marks the viewpoints where no face is visible — auto-cast reads this", () => {
+    // A reference frame shot from behind cannot cast a face, however well framed.
+    expect([...VIDEO_ANALYSIS_FACELESS_ANGLES].sort()).toEqual(["from-behind", "over-the-shoulder"])
+    for (const a of VIDEO_ANALYSIS_FACELESS_ANGLES) {
+      expect(VIDEO_ANALYSIS_SHOT_ANGLES).toContain(a)   // never a stale literal
+    }
+  })
+
+  it("rejects free-text angle — improvising it is the failure being fixed", () => {
+    // The shipped defect: `"camera": "low angle static"`, because angle had no
+    // field. A free-text `angle` would just move the improvisation.
+    expect(windowAnalysisSchema.safeParse({
+      slots: [slot], scenes: [{ ...baseScene, angle: "low angle static" }],
+    }).success).toBe(false)
+  })
+
+  it("has NO 'normal' speed member — absence is normal, so there is one way to say it", () => {
+    expect(VIDEO_ANALYSIS_SPEED_EFFECTS).not.toContain("normal")
+    expect(windowAnalysisSchema.safeParse({
+      slots: [slot], scenes: [{ ...baseScene, speed: "normal" }],
+    }).success).toBe(false)
+    // …and omitting it is valid.
+    expect(windowAnalysisSchema.safeParse({ slots: [slot], scenes: [baseScene] }).success).toBe(true)
+  })
+
+  it("keeps every new field OPTIONAL so an older producer still validates", () => {
+    const parsed = windowAnalysisSchema.parse({ slots: [slot], scenes: [baseScene] })
+    expect(parsed.scenes[0]).not.toHaveProperty("angle")
+    expect(parsed.scenes[0]).not.toHaveProperty("speed")
+    expect(parsed.scenes[0]).not.toHaveProperty("onScreenText")
+    expect(parsed).not.toHaveProperty("look")
+  })
+
+  it("the new scene fields reach the RESULT schema, not just the window one", () => {
+    // analyzedSceneSchema extends windowSceneBase — this pins that it stays that
+    // way, since a field the merged result drops is invisible to every consumer.
+    const scene = { ...baseScene, sceneNumber: 1, visualResolved: "x", slotRefs: [], angle: "dutch", speed: "freeze", onScreenText: "THE END" }
+    expect(analyzedSceneSchema.parse(scene)).toMatchObject({ angle: "dutch", speed: "freeze", onScreenText: "THE END" })
+  })
+
+  it("look is a SIBLING of meta, not inside it — meta is measured, look is read", () => {
+    const r = videoAnalysisResultSchema.parse({
+      meta: { durationSec: 10, width: 1920, height: 1080, aspectRatio: "16:9" },
+      look: { grade: "muted teal", format: "anamorphic digital", genre: "cinematic trailer" },
+      slots: [],
+      scenes: [{ ...baseScene, sceneNumber: 1, visualResolved: "x", slotRefs: [] }],
+    })
+    expect(r.look?.format).toBe("anamorphic digital")
+    expect(r.meta).not.toHaveProperty("look")
+  })
+})
+
+describe("mergeClipLook", () => {
+  it("takes the first non-empty value PER FIELD, not the first window wholesale", () => {
+    // Windows see different footage: one may read the grade while only a later
+    // one contains the shot that reveals the format.
+    expect(mergeClipLook([
+      { grade: "muted teal" },
+      { grade: "warm", format: "16mm film grain" },
+      { lens: "anamorphic flare" },
+    ])).toEqual({ grade: "muted teal", format: "16mm film grain", lens: "anamorphic flare" })
+  })
+
+  it("ignores blank strings and trims what it keeps", () => {
+    expect(mergeClipLook([{ grade: "   " }, { grade: "  crushed blacks  " }])).toEqual({ grade: "crushed blacks" })
+  })
+
+  it("returns undefined when nothing was read — never an empty object", () => {
+    expect(mergeClipLook([])).toBeUndefined()
+    expect(mergeClipLook([undefined, {}, { grade: "" }])).toBeUndefined()
+  })
+})
+
 describe("misc", () => {
   it("isOversizedScene flags > 8s only", () => {
     expect(isOversizedScene(0, 8)).toBe(false)

package/src/index.ts

@@ -277,6 +277,9 @@ export {
   getLlmModalityCaps,
   buildLlmCreditIdentifier,
   resolveLlmCreditId,
+  supportsAdvancedMode,
+  availableReasoningEfforts,
+  ADVANCED_MODE_UNAVAILABLE_REASON,
   motionGraphicsFeature,
   effectiveReasoningEffort,
   type LlmTier,

package/src/llm-models.ts

@@ -51,8 +51,44 @@ export interface LlmModelDef {
   structuredOutputMode?: "anthropic-tool" | "kie-response-format" | "responses-json-schema"
   /** If set, fallback to direct Anthropic SDK with this model ID when KIE.ai fails */
   directFallbackModel?: string
+  /**
+   * Google Gemini API model id for the DIRECT lane (generativelanguage, keyed
+   * by `GEMINI_API_KEY`) — the Google-side twin of `directFallbackModel`.
+   * Presence declares "this model CAN be served straight from Google"; absence
+   * pins it to KIE forever. Stated, never derived: Google carries `-preview`
+   * suffixes on unreleased models, so the id routinely differs from both `id`
+   * and `kieSlugOrModel` (`gemini-3.1-pro` → `gemini-3.1-pro-preview`).
+   */
+  directGeminiModel?: string
+  /**
+   * Try the direct-vendor lane FIRST for this model, with KIE as the failure
+   * fallback. Absent (while `directGeminiModel` is set) = KIE first, direct
+   * only when KIE fails.
+   *
+   * This is a per-model COST decision, not just a routing one: the two lanes
+   * bill the same model at materially different unit rates, so a model that
+   * backs a high-volume default (see `LLM_FEATURE_DEFAULTS`) is usually better
+   * left on whichever lane is cheaper. The rate tables for both lanes live in
+   * `backend/src/lib/pricing/llm-cost.ts` — deliberately not in this package,
+   * which is published to npm.
+   *
+   * Mutually exclusive with `preferKie` — the Claude-side half of the same
+   * idea. Guarded by a registry test so the two can't both be set.
+   */
+  preferDirect?: true
   /** Effort levels this model accepts (ascending). Absent/empty = no effort lever, picker hidden. */
   reasoningEfforts?: readonly LlmReasoningEffort[]
+  /**
+   * Effort levels available on the DIRECT lane, when the vendor's own API
+   * accepts more than the aggregator does. Absent = the direct lane offers the
+   * same set as `reasoningEfforts`.
+   *
+   * This exists because `reasoningEfforts` has to stay at the KIE-safe
+   * intersection — sending a level KIE rejects is a hard failure — while the
+   * vendor API accepts the full ladder. Unlocking those extra levels is one of
+   * the concrete things Advanced mode buys.
+   */
+  directReasoningEfforts?: readonly LlmReasoningEffort[]
   /** false = model rejects `temperature` (Claude 5-era, GPT-5.6). Absent = accepts. */
   supportsTemperature?: false
   /** Claude-only: KIE is the preferred routing, direct Anthropic the fallback. */
@@ -85,6 +121,13 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     structuredOutputMode: "kie-response-format",
     supportsImages: true,
     maxOutputTokens: 8192,
+    // KIE-first: no `preferDirect` — direct is the reliability fallback only.
+    // (Per-lane rates are deliberately NOT in this published package; see
+    // backend/src/lib/pricing/llm-cost.ts.)
+    directGeminiModel: "gemini-3-flash-preview",
+    // No `reasoningEfforts` at all on the KIE lane, but the vendor API accepts
+    // the full minimal→high ladder (`none` maps to Google's `minimal`).
+    directReasoningEfforts: ["none", "low", "medium", "high"],
   },
   {
     id: "gemini-3.6-flash",
@@ -102,7 +145,19 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     maxOutputTokens: 8192,
     // KIE's 3.6 endpoint accepts `reasoning_effort: low | high` (thinking
     // level) — exactly the chat-completions wire mapping deriveParams sends.
+    // Google's own API additionally accepts `minimal` and `medium` on this
+    // model; the set stays at the KIE-safe intersection because ONE field
+    // feeds both lanes and this model is KIE-first. Widen it only if/when
+    // `preferDirect` is set here.
     reasoningEfforts: ["low", "high"],
+    // Google's own API additionally accepts `minimal` and `medium` here —
+    // live-verified 2026-07-28. Advanced mode unlocks them.
+    directReasoningEfforts: ["none", "low", "medium", "high"],
+    // KIE-first: this model backs 5 of the LLM_FEATURE_DEFAULTS plus the
+    // video-analysis fast tier, so it carries the highest call volume of any
+    // Gemini entry — the lane with the lower unit cost wins by default and
+    // direct is the reliability fallback only.
+    directGeminiModel: "gemini-3.6-flash",
   },
   {
     id: "claude-haiku-4.5",
@@ -153,6 +208,18 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     structuredOutputMode: "kie-response-format",
     supportsImages: true,
     maxOutputTokens: 16384,
+    directGeminiModel: "gemini-3.1-pro-preview",
+    // 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"],
+    // 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
+    // the direct lane's capability wins actually matter: real `thinkingLevel`
+    // control, native media ingestion, and a `responseJsonSchema` that honours
+    // `additionalProperties` (KIE's `response_format` silently DROPS
+    // record/map-shaped fields — see the z.record rule in backend/CLAUDE.md).
+    preferDirect: true,
   },
   {
     id: "claude-opus-4.7",
@@ -425,21 +492,45 @@ export function getLlmModel(id: string): LlmModelDef | undefined {
     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)
+  // dated Anthropic slugs, the `-preview`-suffixed Google ids) — accept any
+  // model whose slug matches exactly, on either lane.
+  return LLM_MODELS.find(
+    (m) => m.kieSlugOrModel === id || m.directFallbackModel === id || m.directGeminiModel === id,
+  )
 }
 
 export function getLlmTier(id: string): LlmTier {
   return getLlmModel(id)?.tier ?? "standard"
 }
 
+/**
+ * Effort levels this model actually accepts on the lane it will be served on.
+ *
+ * The two lanes do NOT offer the same ladder: the aggregator accepts a narrower
+ * set than the vendor's own API does, which is one of the concrete things
+ * Advanced mode buys. Kept as one lookup so the UI picker and the wire-side
+ * clamp can never disagree about what's selectable.
+ */
+export function availableReasoningEfforts(
+  modelId: string | undefined,
+  advanced = false,
+): readonly LlmReasoningEffort[] {
+  const model = getLlmModel(modelId ?? "")
+  if (!model) return []
+  if (advanced && supportsAdvancedMode(modelId)) {
+    return model.directReasoningEfforts ?? model.reasoningEfforts ?? []
+  }
+  return model.reasoningEfforts ?? []
+}
+
 /** Highest level the model supports that is ≤ the requested level; undefined = treat as Auto. */
 export function effectiveReasoningEffort(
   modelId: string | undefined,
   requested?: string,
+  advanced = false,
 ): LlmReasoningEffort | undefined {
   if (!requested || !(requested in EFFORT_RANK)) return undefined
-  const levels = getLlmModel(modelId ?? "")?.reasoningEfforts
+  const levels = availableReasoningEfforts(modelId, advanced)
   if (!levels || levels.length === 0) return undefined
   const req = requested as LlmReasoningEffort
   let best: LlmReasoningEffort | undefined
@@ -459,25 +550,64 @@ export function effectiveReasoningEffort(
  * premium stays premium). `high` is the Claude-family server default and
  * never bumps.
  */
-export function buildLlmCreditIdentifier(feature: string, modelId?: string, reasoningEffort?: string): string {
+/** One step up the economy → standard → premium ladder. Premium is the ceiling. */
+function bumpTier(tier: LlmTier): LlmTier {
+  if (tier === "economy") return "standard"
+  if (tier === "standard") return "premium"
+  return tier
+}
+
+/**
+ * Can this model be run in Advanced mode?
+ *
+ * Advanced mode pins the call to the vendor's own API, which is the only lane
+ * where sampling levers (`temperature`, `maxTokens`) and the full effort range
+ * actually take effect. Capability-derived from the registry — a model without
+ * a direct lane simply cannot offer it, so UI and routes both gate on this
+ * rather than on a hand-maintained model list.
+ */
+export function supportsAdvancedMode(modelId: string | undefined): boolean {
+  return Boolean(modelId && getLlmModel(modelId)?.directGeminiModel)
+}
+
+/** User-facing reason a model can't offer Advanced mode. Single-sourced so the
+ *  config panel's disabled hint and the route's 400 say the same thing. */
+export const ADVANCED_MODE_UNAVAILABLE_REASON =
+  "Advanced mode is available on Gemini models — switch the model to enable it."
+
+export function buildLlmCreditIdentifier(
+  feature: string,
+  modelId?: string,
+  reasoningEffort?: string,
+  advancedMode?: boolean,
+): string {
   if (!modelId) return feature
   let tier = getLlmTier(modelId)
   const eff = effectiveReasoningEffort(modelId, reasoningEffort)
-  if (eff !== undefined && EFFORT_TIER_BUMP.has(eff)) {
-    if (tier === "economy") tier = "standard"
-    else if (tier === "standard") tier = "premium"
-  }
+  if (eff !== undefined && EFFORT_TIER_BUMP.has(eff)) tier = bumpTier(tier)
+  // Advanced mode routes to the vendor's own API, which bills materially more
+  // per token than the aggregator. It bumps INDEPENDENTLY of the effort bump —
+  // the two are separate cost levers and genuinely stack, so a max-effort
+  // advanced economy call lands at premium. The bump is ignored on a model that
+  // can't run advanced at all, so a stale flag never inflates a bill.
+  if (advancedMode && supportsAdvancedMode(modelId)) tier = bumpTier(tier)
   if (tier === "standard") return feature
   return `${feature}:${tier}`
 }
 
 /**
- * Resolve llmModel (+ reasoningEffort) from raw body for creditGuard preHandler
- * (before Zod parsing). Returns the credit identifier for the given feature.
+ * Resolve llmModel (+ reasoningEffort, advancedMode) from raw body for the
+ * creditGuard preHandler (before Zod parsing). Returns the credit identifier
+ * for the given feature.
  */
 export function resolveLlmCreditId(feature: string, body: unknown): string {
   const b = body as Record<string, unknown> | undefined
-  return buildLlmCreditIdentifier(feature, b?.llmModel as string | undefined, b?.reasoningEffort as string | undefined)
+  return buildLlmCreditIdentifier(
+    feature,
+    b?.llmModel as string | undefined,
+    b?.reasoningEffort as string | undefined,
+    b?.advancedMode === true,
+  )
 }
 
 /** Models capable of video-analysis: capability-derived, never hand-listed (route-enum-sync convention). */