@nodaro/shared 2.23.0 → 2.26.0

package/package.json

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

@@ -35,6 +35,7 @@ const EXPECTED_MODEL_IDS = [
   "gemini-3-flash",
   "gemini-3.6-flash",
   "gemini-3.7-flash",
+  "gemini-3.8-flash",
   "claude-haiku-4.5",
   "claude-sonnet-4.6",
   "gpt-5.2",
@@ -45,6 +46,7 @@ const EXPECTED_MODEL_IDS = [
   "gpt-5.6-luna",
   "gpt-5.6-terra",
   "gpt-5.6-sol",
+  "gpt-6-astra",
   "grok-4.6",
   "claude-sonnet-5",
   "claude-opus-4.8",
@@ -94,14 +96,14 @@ describe("LLM_MODELS data integrity", () => {
     expect(new Set(ids).size).toBe(ids.length)
   })
 
-  it("has 5 economy, 5 standard, 8 premium models", () => {
+  it("has 6 economy, 5 standard, 9 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(5)
+    expect(tierCounts.economy).toBe(6)
     expect(tierCounts.standard).toBe(5)
-    expect(tierCounts.premium).toBe(8)
+    expect(tierCounts.premium).toBe(9)
   })
 
   it("all three kieFormats are represented", () => {
@@ -483,6 +485,7 @@ describe("STRUCTURED_VISION_MODELS", () => {
         "gemini-3-flash",
         "gemini-3.6-flash",
         "gemini-3.7-flash",
+        "gemini-3.8-flash",
         "gemini-3.1-pro",
         "claude-sonnet-5",
         "claude-opus-4.8",
@@ -495,6 +498,9 @@ describe("STRUCTURED_VISION_MODELS", () => {
         "gpt-5.6-luna",
         "gpt-5.6-terra",
         "gpt-5.6-sol",
+        // responses-format GPT-6 — text.format json_schema enforced (server
+        // echoed strict:true), live-verified 2026-09-06.
+        "gpt-6-astra",
         // responses-format Grok — vision + text.format live-verified 2026-08-18.
         "grok-4.6",
       ].sort(),
@@ -540,6 +546,8 @@ describe("reasoning effort registry", () => {
     expect(getLlmTier("gpt-5.6-luna")).toBe("economy")
     expect(getLlmTier("gpt-5.6-terra")).toBe("standard")
     expect(getLlmTier("gpt-5.6-sol")).toBe("premium")
+    expect(getLlmTier("gpt-6-astra")).toBe("premium")
+    expect(getLlmTier("gemini-3.8-flash")).toBe("economy")
     expect(getLlmTier("grok-4.6")).toBe("standard")
     expect(getLlmTier("claude-sonnet-5")).toBe("standard")
     expect(getLlmTier("claude-opus-4.8")).toBe("premium")
@@ -630,6 +638,117 @@ describe("gemini-3.7-flash exposure", () => {
   })
 })
 
+// ---------------------------------------------------------------------------
+// gemini-3.8-flash exposure (KIE lane live-verified 2026-09-06: enforced
+// response_format json_schema, reasoning_tokens in usage, and a 20k max_tokens
+// request honored for 14,892 completion tokens with finish_reason "stop")
+// ---------------------------------------------------------------------------
+describe("gemini-3.8-flash exposure", () => {
+  it("KIE-first chat-completions with a direct lane — 3.7-flash's proven shape", () => {
+    const m = getLlmModel("gemini-3.8-flash")
+    expect(m?.tier).toBe("economy")
+    expect(m?.vendor).toBe("google")
+    expect(m?.kieFormat).toBe("chat-completions")
+    expect(m?.kieSlugOrModel).toBe("gemini-3-8-flash-openai")
+    // KIE-first on purpose (no preferDirect): the cheap lane serves the A/B,
+    // the direct lane is Advanced mode + the reliability fallback.
+    expect(m?.preferDirect).toBeUndefined()
+    expect(m?.directGeminiModel).toBe("gemini-3.8-flash")
+    expect(m?.reasoningEfforts).toEqual(["low", "high"])
+    expect(m?.structuredOutputMode).toBe("kie-response-format")
+    expect(supportsAdvancedMode("gemini-3.8-flash")).toBe(true)
+    expect(availableReasoningEfforts("gemini-3.8-flash")).toEqual(["low", "high"])
+    expect(availableReasoningEfforts("gemini-3.8-flash", true)).toEqual(["none", "low", "medium", "high"])
+  })
+
+  it("carries a 16384 output cap — measured, not inherited from its 8192 siblings", () => {
+    // 3.6 / 3.7 sit at 8192 as the KIE-safe intersection because nobody
+    // measured their endpoints past it. 3.8's WAS measured (2026-09-06:
+    // max_tokens 20000 honored, 14,892 completion tokens, finish_reason
+    // "stop"), so it is not pinned to its siblings' unmeasured floor.
+    expect(getLlmModel("gemini-3.8-flash")?.maxOutputTokens).toBe(16384)
+  })
+
+  it("resolves by canonical id and by its KIE slug (cost reconciliation reads whatever the wire used)", () => {
+    expect(getLlmModel("gemini-3.8-flash")?.id).toBe("gemini-3.8-flash")
+    expect(getLlmModel("gemini-3-8-flash-openai")?.id).toBe("gemini-3.8-flash")
+  })
+
+  it("stays OUT of video-analysis — image-only modality caps by decision, not omission", () => {
+    // Google's own 3.8 lane understands video (agentic video via the
+    // Interactions API), so full caps here would auto-enroll it in
+    // VIDEO_ANALYSIS_LLM_MODELS and force a VA tier + pricing decision that is
+    // deliberately deferred until the 3.8-vs-3.7 analysis A/B concludes.
+    // If this goes red, someone flipped the caps — only valid TOGETHER with
+    // that VA-side decision.
+    expect(getLlmModalityCaps("gemini-3.8-flash")).toEqual({ image: true, video: false, audio: false })
+    expect(VIDEO_ANALYSIS_LLM_MODELS).not.toContain("gemini-3.8-flash")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// gpt-6-astra exposure (KIE responses lane live-verified 2026-09-06 on the
+// streaming path: enforced text.format json_schema with strict:true, the
+// documented effort enum, temperature silently ignored, reasoning on by default)
+// ---------------------------------------------------------------------------
+describe("gpt-6-astra exposure", () => {
+  it("responses-format OpenAI premium — the GPT-5.6 family's proven shape", () => {
+    const m = getLlmModel("gpt-6-astra")
+    expect(m?.tier).toBe("premium")
+    expect(m?.vendor).toBe("openai")
+    expect(m?.kieFormat).toBe("responses")
+    expect(m?.structuredOutputMode).toBe("responses-json-schema")
+    expect(m?.maxOutputTokens).toBe(16384)
+    expect(m?.reasoningEfforts).toEqual(["low", "medium", "high", "xhigh"])
+    // Temperature is accepted-and-ignored by this endpoint (echo stayed at 1.0
+    // for a sent 0.2), so the registry must say "don't send it".
+    expect(m?.supportsTemperature).toBe(false)
+    // Reasons with NO reasoning param sent (server echoed effort "medium") —
+    // consumers floor max_tokens off this flag or the answer truncates.
+    expect(m?.thinkingDefaultOn).toBe(true)
+    // No direct lane: OpenAI models route through KIE only, so Advanced mode
+    // (a Gemini-lane capability) must stay off.
+    expect(supportsAdvancedMode("gpt-6-astra")).toBe(false)
+  })
+
+  it("resolves from its own slug — the slug is the body `model`, the path comes from vendor", () => {
+    // llm-client derives codex/v1/responses from vendor "openai" (the same
+    // derivation that keeps Grok on grok/v1/responses), so kieSlugOrModel is
+    // sent as the request body's `model` and doubles as a lookup alias.
+    const m = getLlmModel("gpt-6-astra")
+    expect(m?.kieSlugOrModel).toBe("gpt-6-astra")
+    expect(getLlmModel(m!.kieSlugOrModel)?.id).toBe("gpt-6-astra")
+  })
+
+  it("is an accepted structured-vision analyzer", () => {
+    expect(STRUCTURED_VISION_MODELS.map((m) => m.id)).toContain("gpt-6-astra")
+    expect(STRUCTURED_VISION_MODELS.map((m) => m.id)).toContain("gemini-3.8-flash")
+  })
+
+  it("is image-only — KIE's GPT-6 doc lists text + image + file inputs, no video/audio", () => {
+    expect(getLlmModalityCaps("gpt-6-astra")).toEqual({ image: true, video: false, audio: false })
+    expect(VIDEO_ANALYSIS_LLM_MODELS).not.toContain("gpt-6-astra")
+  })
+
+  it("bills premium, and xhigh cannot bump past it", () => {
+    expect(buildLlmCreditIdentifier("llm-chat", "gpt-6-astra")).toBe("llm-chat:premium")
+    expect(buildLlmCreditIdentifier("llm-chat", "gpt-6-astra", "xhigh")).toBe("llm-chat:premium")
+  })
+
+  it("is the ONLY model declaring kieCollapseStream — the condition is per model, not per lane", () => {
+    // KIE's non-stream responses endpoint 500s ~2 calls in 3 for astra
+    // (measured 2026-09-06: 2/6 non-stream vs 5/6 streaming) while serving
+    // gpt-5.4/5.5/5.6 fine, so llm-client collapses the streaming wire for
+    // THIS model only. If a second model ever legitimately needs it, add it
+    // here deliberately — a flag that spreads by copy-paste would quietly move
+    // every affected model's provider cost onto the rate-table estimate,
+    // because SSE does not reliably carry `credits_consumed`.
+    expect(getLlmModel("gpt-6-astra")?.kieCollapseStream).toBe(true)
+    const others = LLM_MODELS.filter((m) => m.id !== "gpt-6-astra")
+    expect(others.filter((m) => m.kieCollapseStream !== undefined).map((m) => m.id)).toEqual([])
+  })
+})
+
 describe("effectiveReasoningEffort", () => {
   it("passes through a supported level", () => {
     expect(effectiveReasoningEffort("claude-sonnet-5", "max")).toBe("max")

package/src/__tests__/studio-transient.test.ts

@@ -0,0 +1,205 @@
+import { describe, it, expect } from "vitest"
+
+import {
+  STUDIO_SHOT_TRANSIENT_KEYS,
+  STUDIO_TRANSIENT_KEYS,
+  stripStudioTransientSettings,
+} from "../studio-transient.js"
+
+/**
+ * The public projection of `settings.studio` (D12).
+ *
+ * A shared production is read by anyone holding the link, and the document
+ * carries the OWNER's working state beside the film: the recycle bin (every
+ * shot, still and clip they deleted, prompts and urls intact), the jobs in
+ * flight, and an unsaved editor draft.
+ *
+ * The fixture below is a real saved document, pinned here byte for byte, and
+ * the LEVEL is the whole finding this test exists for: the in-flight markers
+ * are written PER SHOT, inside `settings.studio.shots[]`, and a strip that only
+ * walks the top level hands a viewer all of them while a fixture shaped to the
+ * top level says it does not.
+ */
+
+const PENDING = {
+  jobId: "job-2",
+  provider: "seedance-2",
+  prompt: "a slow dolly in",
+  startedAt: 1_756_000_000_000,
+}
+
+const TRASHED = {
+  kind: "still",
+  id: "trash-1",
+  shotId: "s1",
+  index: 0,
+  deletedAt: "2026-09-01T10:00:00.000Z",
+  stillBase: { nodeId: "img-1", provider: "flux-2", prompt: "a lighthouse at dawn" },
+  result: { url: "https://cdn/deleted.png" },
+}
+
+/** A saved document carrying every marker its writer can write. */
+function written(): Record<string, unknown> {
+  return {
+    studio: {
+      version: 3,
+      shots: [
+        {
+          id: "s1",
+          imageNodeId: "img-1",
+          stillProvider: "flux-2",
+          pendingClips: [{ ...PENDING }],
+        },
+      ],
+      selectedShotId: "s1",
+      shotOrder: ["img-1"],
+      shared: true,
+      freecutDraftUrl: "https://cdn/draft.json",
+      trash: [{ ...TRASHED }],
+    },
+  }
+}
+
+/** `settings.studio` of a stripped document. */
+function studioOf(settings: unknown): Record<string, unknown> {
+  return (settings as { studio: Record<string, unknown> }).studio
+}
+
+describe("stripStudioTransientSettings", () => {
+  it("drops the bin and the draft the writer put at the top level", () => {
+    const settings = written()
+    // The oracle: the document really does carry these two here.
+    expect(studioOf(settings).trash).toHaveLength(1)
+    expect(studioOf(settings).freecutDraftUrl).toBe("https://cdn/draft.json")
+
+    const studio = studioOf(stripStudioTransientSettings(settings))
+    expect(studio.trash).toBeUndefined()
+    expect(studio.freecutDraftUrl).toBeUndefined()
+  })
+
+  it("drops the in-flight markers the writer put PER SHOT", () => {
+    const settings = written()
+    // The oracle again, and the whole point: `pendingClips` is a SHOT's key.
+    const stored = (studioOf(settings).shots as Array<Record<string, unknown>>)[0]
+    expect(stored.pendingClips).toEqual([PENDING])
+
+    const shots = studioOf(stripStudioTransientSettings(settings)).shots as Array<
+      Record<string, unknown>
+    >
+    expect(shots[0].pendingClips).toBeUndefined()
+    // ...and the shot itself survives, film intact.
+    expect(shots[0].id).toBe("s1")
+    expect(shots[0].imageNodeId).toBe("img-1")
+  })
+
+  it("leaves the film — the shots, the order, the share flag — untouched", () => {
+    const studio = studioOf(stripStudioTransientSettings(written()))
+    expect(studio.version).toBe(3)
+    expect(studio.shotOrder).toEqual(["img-1"])
+    expect(studio.shared).toBe(true)
+    expect(studio.selectedShotId).toBe("s1")
+  })
+
+  it("never mutates the caller's document", () => {
+    const settings = written()
+    const before = JSON.stringify(settings)
+    stripStudioTransientSettings(settings)
+    expect(JSON.stringify(settings)).toBe(before)
+  })
+
+  it("hands back the very same object when there is nothing to strip", () => {
+    // An ordinary share read of an ordinary production allocates nothing.
+    const settings: Record<string, unknown> = {
+      studio: { version: 3, shots: [{ id: "s1" }], selectedShotId: "s1", shotOrder: [] },
+    }
+    expect(stripStudioTransientSettings(settings)).toBe(settings)
+  })
+
+  it("drops a shot's pendingStills — the still marker D5 lands there", () => {
+    // `pendingStills` is additive: the generation routes write it onto the same
+    // shot entry `pendingClips` rides on, so the strip has to know the key
+    // before its writer exists — otherwise the first framing batch in flight
+    // ships to every share viewer.
+    const settings = written()
+    const studio = studioOf(settings)
+    const shots = (studio.shots as Array<Record<string, unknown>>).map((s) => ({
+      ...s,
+      pendingStills: [{ jobId: "job-1", batchId: "batch-1", count: 4 }],
+    }))
+    const withStills = { ...settings, studio: { ...studio, shots } }
+
+    const out = studioOf(stripStudioTransientSettings(withStills))
+    expect((out.shots as Array<Record<string, unknown>>)[0].pendingStills).toBeUndefined()
+  })
+
+  it("drops a legacy single `pendingClip` too", () => {
+    // Pre-concurrent-markers saves wrote one marker under the singular key; the
+    // reader still migrates it, so it is still in-flight state a viewer must
+    // not receive.
+    const settings = written()
+    const studio = studioOf(settings)
+    const shots = [{ id: "s2", pendingClip: PENDING }]
+    const legacy = { ...settings, studio: { ...studio, shots } }
+
+    const out = studioOf(stripStudioTransientSettings(legacy))
+    expect((out.shots as Array<Record<string, unknown>>)[0]).toEqual({ id: "s2" })
+  })
+
+  it("leaves a workflow that is not a production alone", () => {
+    const settings = { presentationSettings: { shareReadOnly: true } }
+    expect(stripStudioTransientSettings(settings)).toBe(settings)
+    expect(stripStudioTransientSettings(null)).toBeNull()
+    expect(stripStudioTransientSettings(undefined)).toBeUndefined()
+  })
+
+  it("survives a document whose shots are not what the editor writes", () => {
+    // The strip runs on whatever is in the column, including a row written by
+    // something that is not the studio editor. It must project, never throw.
+    const odd = { studio: { version: 3, shots: ["nonsense", null, 7] } }
+    expect(() => stripStudioTransientSettings(odd)).not.toThrow()
+    expect(studioOf(stripStudioTransientSettings(odd)).shots).toEqual(["nonsense", null, 7])
+  })
+
+  it("drops the DOCUMENT's own pendingMusic and pendingDraft (D5)", () => {
+    // The document-level twin of the per-shot pair: a soundtrack render and a
+    // Director run in flight. Same rule — they name jobs on the owner's
+    // account, and no viewer can read or land one.
+    const settings = written()
+    const studio = studioOf(settings)
+    const inFlight = {
+      ...settings,
+      studio: {
+        ...studio,
+        pendingMusic: { jobId: "job-3", startedAt: 1_756_000_000_000 },
+        pendingDraft: { jobId: "job-4", startedAt: 1_756_000_000_000 },
+      },
+    }
+    // The oracle: the document really does carry both before the public read.
+    expect(studioOf(inFlight).pendingMusic).toBeDefined()
+    expect(studioOf(inFlight).pendingDraft).toBeDefined()
+
+    const out = studioOf(stripStudioTransientSettings(inFlight))
+    expect(out.pendingMusic).toBeUndefined()
+    expect(out.pendingDraft).toBeUndefined()
+    // ...and the film is still there.
+    expect(out.version).toBe(3)
+  })
+
+  it("pins the two lists — a key added to the type alone strips nothing", () => {
+    // The lists are the contract: the codec's own strip re-exports them, so a
+    // key that falls off here falls off there too, silently, on both sides.
+    expect([...STUDIO_TRANSIENT_KEYS]).toEqual([
+      "trash",
+      "pendingStills",
+      "pendingClips",
+      "pendingMusic",
+      "pendingDraft",
+      "freecutDraftUrl",
+    ])
+    expect([...STUDIO_SHOT_TRANSIENT_KEYS]).toEqual([
+      "pendingClips",
+      "pendingClip",
+      "pendingStills",
+    ])
+  })
+})

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

@@ -164,7 +164,7 @@ describe("bare video-analysis node-type credit id", () => {
     // that prompt again, moving the pin 8_482 -> 8_706, and 357 wrote 2076:
     // the transition vocabulary v2 doctrine (twelve named values; absent =
     // nothing asserted) grew it once more, moving the pin 8_706 -> 9_082.
-    expect(ceiling).toBe(2076)
+    expect(ceiling).toBe(2081)
   })
 
   it("the bare id still bounds the default tier at the ceiling bucket", () => {

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

@@ -180,10 +180,10 @@ describe("video-audit-pricing", () => {
   it("videoAuditCreditsForBucket: table lookup by resolved bucket + family, snapping a raw duration onto the ladder", () => {
     expect(videoAuditCreditsForBucket(60, false)).toBe(215)
     expect(videoAuditCreditsForBucket(60, true)).toBe(396)
-    expect(videoAuditCreditsForBucket(180, false)).toBe(290)
-    expect(videoAuditCreditsForBucket(360, false)).toBe(663)
-    expect(videoAuditCreditsForBucket(600, false)).toBe(1073)
-    expect(videoAuditCreditsForBucket(600, true)).toBe(1921)
+    expect(videoAuditCreditsForBucket(180, false)).toBe(291)
+    expect(videoAuditCreditsForBucket(360, false)).toBe(664)
+    expect(videoAuditCreditsForBucket(600, false)).toBe(1075)
+    expect(videoAuditCreditsForBucket(600, true)).toBe(1924)
     // Not just exact ladder values — a raw duration snaps up to its bucket.
     expect(videoAuditCreditsForBucket(70, false)).toBe(VIDEO_AUDIT_BUCKET_CREDITS["video-audit:180s"])
     expect(videoAuditCreditsForBucket(9999, true)).toBe(VIDEO_AUDIT_BUCKET_CREDITS["video-audit:auto:600s"])
@@ -224,8 +224,8 @@ describe("video-audit-pricing", () => {
     // 600s bucket here, same convention as VIDEO_ANALYSIS_BUCKET_CREDITS).
     expect(Object.keys(VIDEO_AUDIT_BUCKET_CREDITS)).toHaveLength(8)
     // Bare-id values quoted in the task/catalog must equal each family's 600s ceiling.
-    expect(VIDEO_AUDIT_BUCKET_CREDITS["video-audit:600s"]).toBe(1073)
-    expect(VIDEO_AUDIT_BUCKET_CREDITS["video-audit:auto:600s"]).toBe(1921)
+    expect(VIDEO_AUDIT_BUCKET_CREDITS["video-audit:600s"]).toBe(1075)
+    expect(VIDEO_AUDIT_BUCKET_CREDITS["video-audit:auto:600s"]).toBe(1924)
   })
 
   it("auto family = base family + the gemini-3-flash (legacy fast tier) row at the same bucket, exactly — single-source, never hand-added", () => {

package/src/index.ts

@@ -1051,3 +1051,10 @@ export {
 } from "./entity-node-fields.js"
 export { ENTITY_NODE_KINDS } from "./entity-node-fields.js"
 export type { EntityNodeKind } from "./entity-node-fields.js"
+
+// --- transient studio keys — the public share read strips them ---
+export {
+  STUDIO_TRANSIENT_KEYS,
+  STUDIO_SHOT_TRANSIENT_KEYS,
+  stripStudioTransientSettings,
+} from "./studio-transient.js"

package/src/llm-models.ts

@@ -94,6 +94,22 @@ export interface LlmModelDef {
   supportsTemperature?: false
   /** Claude-only: KIE is the preferred routing, direct Anthropic the fallback. */
   preferKie?: true
+  /**
+   * KIE's NON-streaming endpoint for this model is unreliable (measured);
+   * `llmComplete` serves it by opening the streaming wire and collapsing it to
+   * one response. Streaming responses do not reliably carry
+   * `credits_consumed`, so provider cost on this path comes from the rate
+   * table (`backend/src/lib/pricing/llm-cost.ts`) rather than the real charge.
+   *
+   * Declared per model — a per-model condition on KIE's side, like the
+   * Claude-lane one behind `callKieMessagesCollapsed`. The flag says WHICH
+   * model is affected, and `llm-client` reads it instead of matching model
+   * names. Today only the `responses` dispatcher in `callKie` honours it (the
+   * one format where the condition has been measured); a chat-completions or
+   * messages model that needs the same treatment must also teach its `callKie`
+   * case to read the flag — declaring it alone changes nothing there.
+   */
+  kieCollapseStream?: true
   /**
    * true = the model reasons even when NO thinking parameter is sent, so its
    * reasoning tokens share the `max_tokens` budget on EVERY call — not just
@@ -133,7 +149,9 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
   {
     id: "gemini-3.6-flash",
     displayName: "Gemini 3.6 Flash",
-    desc: "Latest fast Gemini, sharper reasoning",
+    // Demoted 2026-09-06 alongside 3.7: superlatives belong to the CURRENT top
+    // model of a family only, and 3.8 now holds that slot.
+    desc: "Fast Gemini, sharper reasoning",
     tier: "economy",
     kieFormat: "chat-completions",
     // KIE serves Gemini 3.6 Flash on the OpenAI-compatible dialect under this
@@ -163,7 +181,11 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
   {
     id: "gemini-3.7-flash",
     displayName: "Gemini 3.7 Flash",
-    desc: "Newest fast Gemini, agentic-tuned",
+    // Demoted 2026-09-06 when 3.8 registered below: superlatives belong to the
+    // CURRENT top model of a family only (same rule the Opus entries follow) —
+    // `desc` renders in every picker, so leaving "Newest" on the older flash
+    // steers the A/B's traffic backwards.
+    desc: "Fast Gemini, agentic-tuned",
     tier: "economy",
     kieFormat: "chat-completions",
     // KIE serves it on the OpenAI-compatible dialect under this slug
@@ -184,6 +206,46 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     directReasoningEfforts: ["none", "low", "medium", "high"],
     directGeminiModel: "gemini-3.7-flash",
   },
+  {
+    id: "gemini-3.8-flash",
+    displayName: "Gemini 3.8 Flash",
+    // Inherits "Newest" from 3.7 (demoted above). Deliberately does NOT name
+    // agentic video: that capability exists only on the direct Google lane
+    // (Interactions API, not wired here) and the modality caps below withhold
+    // video — a picker desc must not promise a lever this entry cannot expose.
+    desc: "Newest fast Gemini, agentic-tuned",
+    tier: "economy",
+    kieFormat: "chat-completions",
+    // KIE serves it on the OpenAI-compatible dialect under this slug
+    // (docs.kie.ai/market/gemini/gemini-3-8-flash-openai.md) — identical
+    // chat-completions path shape to gemini-3.7-flash / gemini-3.6-flash,
+    // different slug prefix.
+    kieSlugOrModel: "gemini-3-8-flash-openai",
+    vendor: "google",
+    // Live-verified 2026-09-06 on the KIE lane: `response_format: json_schema`
+    // is ENFORCED (the reply came back exact-schema valid, credits_consumed
+    // present) — not merely accepted-and-ignored.
+    structuredOutputMode: "kie-response-format",
+    supportsImages: true,
+    // 16384 here, NOT the 8192 its 3.6 / 3.7 siblings sit at. Those two stay at
+    // the KIE-safe intersection because nobody measured their endpoints past
+    // it; 3.8's WAS measured — live-verified 2026-09-06, `max_tokens: 20000`
+    // was honored for 14,892 completion tokens with finish_reason "stop" (no
+    // truncation), so the KIE lane is not the binding constraint. 16384 keeps
+    // it level with the rest of the registry's ceiling rather than at the cap.
+    maxOutputTokens: 16384,
+    // KIE's 3.8 endpoint enumerates reasoning_effort low | high (its doc enum),
+    // and usage carries completion_tokens_details.reasoning_tokens — same
+    // KIE-safe intersection as 3.6 / 3.7, because ONE field feeds both lanes
+    // and this model is KIE-first.
+    reasoningEfforts: ["low", "high"],
+    // Google's own API accepts the full minimal→high ladder here (`none` maps
+    // to `minimal`), same as 3.7. Advanced mode is what unlocks it.
+    directReasoningEfforts: ["none", "low", "medium", "high"],
+    // KIE-first (no `preferDirect`) — 3.7's posture exactly: the cheap lane
+    // serves the A/B, direct is Advanced mode + the reliability fallback.
+    directGeminiModel: "gemini-3.8-flash",
+  },
   {
     id: "claude-haiku-4.5",
     displayName: "Claude Haiku 4.5",
@@ -280,7 +342,9 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
   {
     id: "gpt-5.4",
     displayName: "GPT-5.4",
-    desc: "Latest GPT, premium quality",
+    // Demoted 2026-09-06: two GPT generations have shipped above it, so
+    // "Latest" steered the picker at the oldest premium GPT in the registry.
+    desc: "Older GPT, premium quality",
     tier: "premium",
     kieFormat: "responses",
     kieSlugOrModel: "gpt-5-4",
@@ -335,7 +399,11 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
   {
     id: "gpt-5.6-sol",
     displayName: "GPT-5.6 Sol",
-    desc: "Flagship GPT-5.6, deepest reasoning",
+    // Demoted 2026-09-06 when gpt-6-astra registered below — "Flagship /
+    // deepest" is the current top GPT's copy only. Worded to stay distinct
+    // from gpt-5.5's "Previous flagship GPT, deep reasoning": all three read
+    // premium on the invoice, so a stale superlative mis-steers silently.
+    desc: "Previous flagship GPT-5.6, deep reasoning",
     tier: "premium",
     kieFormat: "responses",
     kieSlugOrModel: "gpt-5-6-sol",
@@ -346,6 +414,61 @@ export const LLM_MODELS: readonly LlmModelDef[] = [
     reasoningEfforts: ["none", "low", "medium", "high", "xhigh", "max"],
     supportsTemperature: false,
   },
+  {
+    id: "gpt-6-astra",
+    displayName: "GPT-6 Astra",
+    desc: "Flagship GPT-6, deepest reasoning",
+    tier: "premium",
+    kieFormat: "responses",
+    // KIE serves GPT-6 on the responses dialect under the OpenAI family path —
+    // codex/v1/responses, which llm-client DERIVES from `vendor` (the same
+    // derivation that keeps Grok on grok/v1/responses). So this field is the
+    // body `model` only, not a path segment. Live-verified 2026-09-06 on the
+    // streaming path (array `input`, SSE deltas), which is the ONLY path we
+    // serve it on — see `kieCollapseStream` below. The non-stream reply does
+    // carry `credits_consumed` (and cached_tokens/cache_write_tokens in usage)
+    // on the ~1 call in 3 that returns one, but we no longer take that reply,
+    // so provider cost here is the rate-table estimate.
+    // KIE's codex/v1/responses injects its own Codex-agent `instructions`
+    // prompt ABOVE the caller's `developer` message — observed in the
+    // 2026-07-14 live probe of that endpoint, and unchanged for GPT-6. Budget
+    // for it when a developer message has to dominate.
+    kieSlugOrModel: "gpt-6-astra",
+    vendor: "openai",
+    // Live-verified 2026-09-06: `text.format: json_schema` is passed through
+    // and ENFORCED — the server echoed `strict: true` and returned
+    // schema-valid JSON.
+    structuredOutputMode: "responses-json-schema",
+    // text + image + file inputs per KIE's doc. No video/audio — see the
+    // image-only LLM_MODALITY_CAPS row below.
+    supportsImages: true,
+    maxOutputTokens: 16384,
+    // KIE's documented enum for this endpoint. No `none` on purpose: the
+    // endpoint reasons unconditionally (see thinkingDefaultOn below), so a
+    // "none" level would be a lie the wire silently overrides.
+    reasoningEfforts: ["low", "medium", "high", "xhigh"],
+    // Live-probed 2026-09-06: `temperature: 0.2` was sent and the request echo
+    // stayed at 1.0 — silently IGNORED, so never send it. Same treatment as the
+    // GPT-5.6 family and grok-4.6.
+    supportsTemperature: false,
+    // With NO reasoning param sent, the server echoed effort "medium" — it
+    // reasons by default (2026-09-06), so reasoning tokens share `max_tokens`
+    // on EVERY call, not just effort-bearing ones. Consumers must floor output
+    // headroom off this flag or a premium answer truncates into a paid-for
+    // empty reply.
+    thinkingDefaultOn: true,
+    // Measured 2026-09-06, 12 identical requests (developer + user message,
+    // reasoning.effort low, text.format json_schema): `stream: false`
+    // succeeded 2/6 in 4–5 s and 500'd 4/6 with
+    // {"error":{"type":"server_error"}} after 34, 34, 35 and 64 s, while the
+    // same body with `stream: true` succeeded 5/6 in the same 4–5 s. An
+    // earlier non-stream probe timed out at 90 s with 0 bytes, and a
+    // non-stream call WITHOUT a schema 500'd after 65 s — the schema is not
+    // the trigger, the non-stream lane is. The very same endpoint serves
+    // gpt-5.4/5.5/5.6 non-stream reliably (live-verified 2026-07-14), which is
+    // why this is per-model and not a lane-wide flag.
+    kieCollapseStream: true,
+  },
   {
     id: "grok-4.6",
     displayName: "Grok 4.6",
@@ -577,6 +700,15 @@ export const LLM_MODALITY_CAPS: Record<string, { image: boolean; video: boolean;
   // deferred while the smart-family A/B routes this model internally (#747).
   // Flip these two flags ONLY together with that VA-side decision.
   "gemini-3.7-flash":  { image: true,  video: false, audio: false },
+  // gemini-3.8-flash is IMAGE-ONLY by DECISION, not omission — 3.7's rationale
+  // exactly: full video+audio caps would auto-enroll it in
+  // VIDEO_ANALYSIS_LLM_MODELS (derived below) and force a video-analysis tier +
+  // pricing decision that stays deferred until the 3.8-vs-3.7 analysis A/B
+  // concludes. Google's own 3.8 lane DOES understand video (agentic video, via
+  // the Interactions API we don't wire) — which is precisely why withholding it
+  // has to be a decision rather than a gap. Flip these two flags ONLY together
+  // with that VA-side decision.
+  "gemini-3.8-flash":  { image: true,  video: false, audio: false },
   "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 },
@@ -587,6 +719,8 @@ export const LLM_MODALITY_CAPS: Record<string, { image: boolean; video: boolean;
   "gpt-5.6-luna":      { image: true,  video: false, audio: false },
   "gpt-5.6-terra":     { image: true,  video: false, audio: false },
   "gpt-5.6-sol":       { image: true,  video: false, audio: false },
+  // KIE's GPT-6 doc lists text + image + file inputs only — no video, no audio.
+  "gpt-6-astra":       { image: true,  video: false, audio: false },
   "grok-4.6":          { 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 },