@nodaro/shared 2.19.0 → 2.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "2.19.0",
+  "version": "2.20.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__/credit-identifiers.test.ts

@@ -1,5 +1,7 @@
 import {
   buildCreditModelIdentifier,
+  resolveImageGenCreditIdentifier,
+  resolveNormalizedImageGen,
   buildVideoCreditModelIdentifier,
   buildMotionCreditModelIdentifier,
 } from "../credit-identifiers.js"
@@ -870,3 +872,134 @@ describe("gemini-omni-flash", () => {
     }
   })
 })
+
+// ---------------------------------------------------------------------------
+// resolveNormalizedImageGen
+// ---------------------------------------------------------------------------
+describe("resolveNormalizedImageGen", () => {
+  it("snaps an off-list aspect ratio and reports it", () => {
+    const out = resolveNormalizedImageGen({
+      provider: "gpt-image-2",
+      aspectRatio: "3:2",
+      resolution: "4K",
+      refCount: 0,
+      swapToI2i: true,
+    })
+    // 3:2 is not in GPT_IMAGE_2_RATIOS -> allowed[0] ("auto"), which then
+    // cascades resolution to 1K via the model's cross-field rule.
+    expect(out.aspectRatio).toBe("auto")
+    expect(out.resolution).toBe("1K")
+    expect(out.identifier).toBe("gpt-image-2")
+    expect(out.adjustments.map((a) => a.field)).toEqual(["aspectRatio", "resolution"])
+  })
+
+  it("prices the SNAPPED resolution — gpt-image-2 auto + 2K reserves the 1K tier", () => {
+    const out = resolveNormalizedImageGen({
+      provider: "gpt-image-2",
+      aspectRatio: "auto",
+      resolution: "2K",
+      refCount: 0,
+      swapToI2i: true,
+    })
+    expect(out.resolution).toBe("1K")
+    expect(out.identifier).toBe("gpt-image-2")
+  })
+
+  it("drops a lever the model does not have, and reports it", () => {
+    const out = resolveNormalizedImageGen({
+      provider: "recraft-upscale",
+      aspectRatio: "16:9",
+      refCount: 0,
+    })
+    expect(out.aspectRatio).toBeUndefined()
+    expect(out.adjustments).toHaveLength(1)
+    expect(out.adjustments[0].field).toBe("aspectRatio")
+    expect(out.adjustments[0].to).toBeUndefined()
+  })
+
+  // grok-i2i deliberately has NO `aspectRatios` on its catalog entry, and that
+  // is the HONEST declaration: KIE's grok-imagine/image-to-image schema accepts
+  // only prompt / image_urls / nsfw_checker — there is no aspect_ratio param
+  // (https://docs.kie.ai/market/grok-imagine/image-to-image.md). That is why
+  // kie/models.ts gives it `extraParams: {}` while its t2i sibling gets
+  // `{ aspect_ratio: "16:9" }`, and why kie/CLAUDE.md lists grok-i2i under
+  // "No aspect ratio control". Declaring the t2i ratios here to "preserve" a
+  // caller's value would put a lie in the catalog and keep forwarding a param
+  // the endpoint ignores; dropping it and disclosing that via `adjustments` is
+  // the correct behaviour. Do not "fix" this by adding GROK_RATIOS.
+  it("drops the aspect ratio when grok auto-swaps to its ratio-less i2i sibling", () => {
+    const out = resolveNormalizedImageGen({
+      provider: "grok",
+      aspectRatio: "16:9",
+      refCount: 1,
+      swapToI2i: true,
+    })
+    expect(out.modelId).toBe("grok-i2i")
+    expect(out.aspectRatio).toBeUndefined()
+    expect(out.adjustments).toHaveLength(1)
+    expect(out.adjustments[0].field).toBe("aspectRatio")
+    expect(out.adjustments[0].from).toBe("16:9")
+    expect(out.adjustments[0].to).toBeUndefined()
+    expect(out.identifier).toBe("grok-i2i")
+  })
+
+  it("snaps against the i2i variant when the T2I provider auto-swaps", () => {
+    const out = resolveNormalizedImageGen({
+      provider: "gpt-image-2",
+      aspectRatio: "3:4",
+      refCount: 2,
+      swapToI2i: true,
+    })
+    expect(out.modelId).toBe("gpt-image-2-i2i")
+    expect(out.aspectRatio).toBe("3:4")
+    expect(out.adjustments).toEqual([])
+  })
+
+  it("coerces non-string levers to undefined (the preHandler runs pre-Zod)", () => {
+    const out = resolveNormalizedImageGen({
+      provider: "gpt-image-2",
+      aspectRatio: 169,
+      resolution: null,
+      quality: {},
+      refCount: 0,
+    })
+    expect(out.aspectRatio).toBeUndefined()
+    expect(out.resolution).toBeUndefined()
+    expect(out.quality).toBeUndefined()
+    expect(out.adjustments).toEqual([])
+    expect(out.identifier).toBe("gpt-image-2")
+  })
+
+  it("passes an unknown model id through untouched", () => {
+    const out = resolveNormalizedImageGen({
+      provider: "not-a-model",
+      aspectRatio: "13:7",
+      resolution: "9K",
+      refCount: 0,
+    })
+    expect(out.aspectRatio).toBe("13:7")
+    expect(out.resolution).toBe("9K")
+    expect(out.adjustments).toEqual([])
+    expect(out.identifier).toBe("not-a-model")
+  })
+})
+
+// Regression pins: identifiers that are correct TODAY must be byte-identical
+// once resolveImageGenCreditIdentifier delegates through the normalizer.
+describe("resolveImageGenCreditIdentifier is unchanged for already-valid input", () => {
+  it.each([
+    [{ provider: "flux-2-max", refCount: 3, swapToI2i: true }, "flux-2-max:1MP:3ref"],
+    [{ provider: "flux-2-max", resolution: "4 MP", refCount: 8, swapToI2i: true }, "flux-2-max:4MP:8ref"],
+    [{ provider: "flux-2-pro", refCount: 0, swapToI2i: true }, "flux-2-pro:1MP:0ref"],
+    [{ provider: "seedream-5-lite", refCount: 1, swapToI2i: true }, "seedream-5-lite-i2i"],
+    [{ provider: "seedream", quality: "high", refCount: 0, swapToI2i: true }, "seedream:high"],
+    [{ provider: "gpt-image", quality: "high", refCount: 0, swapToI2i: true }, "gpt-image:high"],
+    [{ provider: "flux", resolution: "2K", refCount: 0, swapToI2i: true }, "flux:2K"],
+    [{ provider: "nano-banana-pro", resolution: "4K", refCount: 0, swapToI2i: true }, "nano-banana-pro:4K"],
+    [{ provider: "gpt-image-2", resolution: "4K", aspectRatio: "16:9", refCount: 0, swapToI2i: true }, "gpt-image-2:4K"],
+    [{ provider: "ideogram-v3", renderingSpeed: "TURBO", refCount: 0, swapToI2i: true }, "ideogram-v3:TURBO"],
+    [{ provider: undefined, refCount: 0, swapToI2i: true }, "nano-banana"],
+  ] as const)("%o -> %s", (opts, expected) => {
+    expect(resolveImageGenCreditIdentifier({ ...opts } as Parameters<typeof resolveImageGenCreditIdentifier>[0])).toBe(expected)
+  })
+})

package/src/__tests__/image-pricing-catalog-coverage.test.ts

@@ -0,0 +1,139 @@
+import { describe, it, expect } from "vitest"
+import {
+  MODEL_CATALOG,
+  normalizeModelInput,
+} from "../model-catalog.js"
+import {
+  HIGH_QUALITY_PROVIDERS,
+  IMAGE_ASPECT_RATIO_VALUES,
+  TWO_K_RESOLUTION_PROVIDERS,
+  RESOLUTION_2K_4K_TIERED_PROVIDERS,
+} from "../model-constants.js"
+import { FLUX2_RES_MP, isFlux2Model } from "../flux2-pricing.js"
+
+/**
+ * `resolveNormalizedImageGen` prices the credit identifier off the SNAPPED
+ * lever values (see credit-identifiers.ts). That is only safe while every
+ * value a pricing set keys on is also DECLARED on that model's catalog entry:
+ * a priced value the catalog omits would be snapped away or rewritten, and the
+ * reserve would silently move to a different tier.
+ *
+ * A model that is priced on a lever but ABSENT from MODEL_CATALOG is fine —
+ * `normalizeModelInput` passes unknown ids through untouched.
+ */
+describe("composite image pricing ⊆ catalog-declared levers", () => {
+  it("every HIGH_QUALITY_PROVIDERS member in the catalog declares quality \"high\"", () => {
+    let checked = 0
+    for (const id of HIGH_QUALITY_PROVIDERS) {
+      const entry = MODEL_CATALOG[id]
+      if (!entry) continue
+      checked++
+      expect(entry.qualities, `${id}.qualities`).toBeDefined()
+      expect(entry.qualities, `${id}.qualities`).toContain("high")
+    }
+    expect(checked).toBeGreaterThan(0)
+  })
+
+  it("every TWO_K_RESOLUTION_PROVIDERS member in the catalog declares \"2K\"", () => {
+    let checked = 0
+    for (const id of TWO_K_RESOLUTION_PROVIDERS) {
+      const entry = MODEL_CATALOG[id]
+      if (!entry) continue
+      checked++
+      expect(entry.resolutions, `${id}.resolutions`).toContain("2K")
+    }
+    expect(checked).toBeGreaterThan(0)
+  })
+
+  it("every RESOLUTION_2K_4K_TIERED_PROVIDERS member in the catalog declares \"2K\" and \"4K\"", () => {
+    let checked = 0
+    for (const id of RESOLUTION_2K_4K_TIERED_PROVIDERS) {
+      const entry = MODEL_CATALOG[id]
+      if (!entry) continue
+      checked++
+      expect(entry.resolutions, `${id}.resolutions`).toContain("2K")
+      expect(entry.resolutions, `${id}.resolutions`).toContain("4K")
+    }
+    expect(checked).toBeGreaterThan(0)
+  })
+
+  it("nano-banana-pro declares \"4K\" (its own pricing branch)", () => {
+    expect(MODEL_CATALOG["nano-banana-pro"]?.resolutions).toContain("4K")
+  })
+
+  // Flux 2 stores a BARE megapixel count ("1") while the catalog lists "1 MP".
+  // normalizeModelInput canonicalizes rather than "corrects" that spelling —
+  // if it ever stopped doing so, every Flux 2 node priced from stored data
+  // would jump to defaultResolutionFor()'s tier.
+  it("Flux 2 bare-MP values canonicalize to the catalog spelling, not a different tier", () => {
+    let checked = 0
+    for (const id of Object.keys(MODEL_CATALOG)) {
+      if (!isFlux2Model(id)) continue
+      checked++
+      for (const mp of FLUX2_RES_MP) {
+        const out = normalizeModelInput(id, { resolution: mp })
+        expect(out.resolution, `${id} + "${mp}"`).toBe(`${mp} MP`)
+        expect(out.adjustments, `${id} + "${mp}" must not report a correction`).toEqual([])
+      }
+    }
+    expect(checked).toBeGreaterThan(0)
+  })
+
+  // Declared values are always identity under the snap. Cheap, and it fails
+  // loudly if someone adds a duplicate/typo'd entry to a lever list.
+  it("every declared image lever value normalizes to itself", () => {
+    for (const [id, entry] of Object.entries(MODEL_CATALOG)) {
+      if (entry.kind !== "image") continue
+      for (const a of entry.aspectRatios ?? []) {
+        expect(normalizeModelInput(id, { aspectRatio: a }).aspectRatio, `${id} ratio ${a}`).toBe(a)
+      }
+      for (const r of entry.resolutions ?? []) {
+        expect(normalizeModelInput(id, { resolution: r }).resolution, `${id} res ${r}`).toBe(r)
+      }
+      for (const q of entry.qualities ?? []) {
+        expect(normalizeModelInput(id, { quality: q }).quality, `${id} quality ${q}`).toBe(q)
+      }
+    }
+  })
+})
+
+/**
+ * `IMAGE_ASPECT_RATIO_VALUES` is the ONE ratio vocabulary the three image
+ * routes' Zod enums are built from (`/v1/generate-image`, `/v1/image-to-image`,
+ * `/v1/edit-image`). Two invariants make that safe, and both are asserted here
+ * rather than left to review:
+ *
+ *  1. It must be a SUPERSET of every ratio any image model declares. A catalog
+ *     ratio the tuple omits is a live 400 on a value the picker offers — the
+ *     exact bug that shipped twice (Wan 2.7's `8:1`/`1:8`, then Nano Banana 2
+ *     Lite's `4:1`/`1:4`). It also makes `applySnappedLevers`' "enum can't carry
+ *     the snapped value" fallback unreachable: the snap can only ever return a
+ *     value the caller sent, its canonical spelling, or a catalog-declared
+ *     option — all three are in the tuple by this test.
+ *  2. No duplicates. `z.enum` de-dupes silently, so a copy-paste repeat would
+ *     never surface at runtime.
+ *
+ * Widening the tuple is always safe: the per-model gate is the catalog snap,
+ * which CORRECTS an unsupported ratio (and discloses it) instead of rejecting.
+ */
+describe("IMAGE_ASPECT_RATIO_VALUES covers every catalog-declared image ratio", () => {
+  it("is a superset of every `kind: \"image\"` entry's aspectRatios", () => {
+    const allowed = new Set<string>(IMAGE_ASPECT_RATIO_VALUES)
+    const missing: string[] = []
+    let checked = 0
+    for (const [id, entry] of Object.entries(MODEL_CATALOG)) {
+      if (entry.kind !== "image") continue
+      for (const r of entry.aspectRatios ?? []) {
+        checked++
+        if (!allowed.has(r)) missing.push(`${id} declares "${r}"`)
+      }
+    }
+    expect(missing).toEqual([])
+    // Guard the guard: an empty catalog sweep would make this vacuous.
+    expect(checked).toBeGreaterThan(100)
+  })
+
+  it("has no duplicate entries (z.enum would swallow them)", () => {
+    expect(new Set<string>(IMAGE_ASPECT_RATIO_VALUES).size).toBe(IMAGE_ASPECT_RATIO_VALUES.length)
+  })
+})

package/src/__tests__/normalize-node-params.test.ts

@@ -59,6 +59,42 @@ describe("normalizeNodeModelParams", () => {
     expect(MODEL_PARAM_NODE_TYPES.has("image-to-video")).toBe(false)
   })
 
+  // The write boundary has to cover every image node an agent can author, not
+  // just the two that shipped first: `modify-image` carries the same
+  // provider/aspectRatio/resolution/quality trio, and `edit-image` carries
+  // provider + aspectRatio (its `targetResolution` is an upscale target, a
+  // DIFFERENT field the normalizer never reads, so there is no conflation).
+  it("covers every image node type whose data carries catalog-governed params", () => {
+    expect([...MODEL_PARAM_NODE_TYPES].sort()).toEqual([
+      "edit-image",
+      "generate-image",
+      "image-to-image",
+      "modify-image",
+    ])
+  })
+
+  it("heals a modify-image node written straight into workflow JSON", () => {
+    const { nodes, adjustments } = normalizeNodeModelParams([
+      node("m9", "modify-image", { provider: "gpt-image", aspectRatio: "16:9", quality: "basic" }),
+    ])
+    const d = nodes[0].data as Record<string, unknown>
+    expect(d.aspectRatio).not.toBe("16:9")
+    expect(d.quality).toBe("medium") // gpt-image declares ["medium", "high"]
+    expect(adjustments.map((a) => a.field).sort()).toEqual(["aspectRatio", "quality"])
+    expect(adjustments[0].nodeId).toBe("m9")
+  })
+
+  it("heals an edit-image node's ratio without touching its targetResolution", () => {
+    const { nodes, adjustments } = normalizeNodeModelParams([
+      node("e1", "edit-image", { provider: "recraft-upscale", aspectRatio: "16:9", targetResolution: "4K" }),
+    ])
+    const d = nodes[0].data as Record<string, unknown>
+    // The upscalers declare no aspectRatios at all -> the lever is dropped.
+    expect(d.aspectRatio).toBeUndefined()
+    expect(d.targetResolution).toBe("4K")
+    expect(adjustments.map((a) => a.field)).toEqual(["aspectRatio"])
+  })
+
   it("skips multi-provider nodes rather than guessing an intersection", () => {
     const input = [
       node("m1", "generate-image", {

package/src/__tests__/organizations-types.test.ts

@@ -1,3 +1,4 @@
+import { readFileSync } from "node:fs"
 import { describe, expect, it } from "vitest"
 import {
   ACCESS_LEVELS,
@@ -9,13 +10,14 @@ import {
   OrgSettingsSchema,
   PRESET_SETTING_KEYS,
   PresetSettingsSchema,
+  USAGE_GROUP_BYS,
   WORKSPACE_ROLES,
   WorkspaceSettingsSchema,
 } from "../organizations/index.js"
 
 describe("organizations wire contract — enums", () => {
   it("every enum is non-empty and duplicate-free", () => {
-    for (const list of [ORG_KINDS, ORG_ROLES, WORKSPACE_ROLES, MEMBER_STATUSES, COLLABORATOR_ROLES, ACCESS_LEVELS, ORG_ERROR_CODES]) {
+    for (const list of [ORG_KINDS, ORG_ROLES, WORKSPACE_ROLES, MEMBER_STATUSES, COLLABORATOR_ROLES, ACCESS_LEVELS, ORG_ERROR_CODES, USAGE_GROUP_BYS]) {
       expect(list.length).toBeGreaterThan(0)
       expect(new Set(list).size).toBe(list.length)
     }
@@ -24,6 +26,32 @@ describe("organizations wire contract — enums", () => {
   it("error codes are snake_case identifiers", () => {
     for (const code of ORG_ERROR_CODES) expect(code).toMatch(/^[a-z][a-z_]*[a-z]$/)
   })
+
+  it("USAGE_GROUP_BYS is exactly the report groupings plus none", () => {
+    expect([...USAGE_GROUP_BYS]).toEqual(["workspace", "member", "model", "day", "none"])
+  })
+
+  it("ORG_ERROR_CODES carries the P15 CSV write-ahead-audit code", () => {
+    expect(ORG_ERROR_CODES).toContain("audit_unavailable")
+  })
+})
+
+describe("usage wire types carry no cost/economics field (pricing-leak class)", () => {
+  it("no UsageReport* / UsageLogEntry field name is cost-shaped", () => {
+    const src = readFileSync(new URL("../organizations/views.ts", import.meta.url), "utf8")
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/\/\/[^\n]*/g, "")
+    const start = src.indexOf("export interface UsageReportRow")
+    const end = src.indexOf("export interface UsageQuery")
+    expect(start).toBeGreaterThan(-1)
+    expect(end).toBeGreaterThan(start)
+    const usageTypes = src.slice(start, end)
+    // "markup" is deliberately NOT in this set: the creator-set app markup is a
+    // product term (the `app_markup` variance kind, `appMarkupAbsorbedCredits`),
+    // not platform economics — same carve-out as check-pricing-leaks'
+    // BARE_MARKUP_IS_PRODUCT_TERM. What must never appear is a $ / rate field.
+    expect(usageTypes).not.toMatch(/(cost|usd|margin|price|dollar)/i)
+  })
 })
 
 describe("organizations wire contract — settings request schemas", () => {

package/src/__tests__/prompt-length-limits.test.ts

@@ -6,6 +6,9 @@ import {
   NEGATIVE_PROMPT_MAX,
   TTS_TEXT_MAX,
   SUNO_TITLE_MAX,
+  SUNO_HARD_CEILING,
+  SUNO_TEXT_MAX,
+  SUNO_MODELS,
   MAX_IMAGE_PROMPT_CHARS_BY_PROVIDER,
   MAX_VIDEO_PROMPT_CHARS_BY_PROVIDER,
   MAX_NEGATIVE_PROMPT_CHARS_BY_PROVIDER,
@@ -123,6 +126,39 @@ describe("per-model prompt length limits", () => {
       expect(getMaxSunoStyleChars("V5")).toBe(1000)
       expect(SUNO_TITLE_MAX).toBe(80)
     })
+    it("SUNO_HARD_CEILING is a generous route ceiling that can never reject a valid prompt", () => {
+      // The routes accept up to the ceiling and CLAMP to the per-version cap;
+      // a ceiling below any real cap would hard-reject before the clamp ran.
+      // The list is SUNO_MODELS plus `undefined` (schemas without a `model`
+      // field, e.g. replace-section). `V3_5` is NOT a route-accepted model —
+      // getMaxSunoPromptChars still names it, but do not add it here.
+      const versions = [...SUNO_MODELS, undefined]
+      for (const v of versions) {
+        for (const custom of [true, false]) {
+          expect(getMaxSunoPromptChars(v, custom)).toBeLessThanOrEqual(SUNO_HARD_CEILING)
+        }
+        expect(getMaxSunoStyleChars(v)).toBeLessThanOrEqual(SUNO_HARD_CEILING)
+      }
+      expect(SUNO_TEXT_MAX).toBeLessThanOrEqual(SUNO_HARD_CEILING)
+      expect(SUNO_HARD_CEILING).toBe(30000)
+    })
+    it("SUNO_TEXT_MAX pins the max prompt cap across every version × custom-mode combo and is >= every style cap", () => {
+      // SUNO_TEXT_MAX is the shared editor-side ceiling (maxLength / warn
+      // counter) for prompt-shaped Suno fields. Derive the expected value
+      // from the real version list so a future Suno version raising its
+      // custom-mode cap above today's 5000 fails this test instead of
+      // silently under-capping the editor.
+      let maxPromptCap = 0
+      for (const v of SUNO_MODELS) {
+        for (const custom of [true, false]) {
+          maxPromptCap = Math.max(maxPromptCap, getMaxSunoPromptChars(v, custom))
+        }
+      }
+      expect(SUNO_TEXT_MAX).toBe(maxPromptCap)
+      for (const v of SUNO_MODELS) {
+        expect(SUNO_TEXT_MAX).toBeGreaterThanOrEqual(getMaxSunoStyleChars(v))
+      }
+    })
   })
 
   describe("drift guards (registry hygiene)", () => {

package/src/__tests__/suno-credit-type.test.ts

@@ -0,0 +1,54 @@
+import { describe, it, expect } from "vitest"
+import {
+  sunoCreditType,
+  SUNO_VERSION_PRICED_OPERATIONS,
+  SUNO_SELECT_OPERATIONS,
+  SUNO_MODELS,
+} from "../index.js"
+
+describe("sunoCreditType — the ONE implementation of the Suno route pricing contract", () => {
+  it("prices generate/cover/extend by model version", () => {
+    expect(sunoCreditType("V5_5", "suno-generate")).toBe("suno-v5_5")
+    expect(sunoCreditType("V5", "suno-cover")).toBe("suno-v5")
+    expect(sunoCreditType("V5_5", "suno-extend")).toBe("suno-v5_5")
+  })
+
+  it("falls back to the operation key for versions with no dedicated price", () => {
+    expect(sunoCreditType("V4", "suno-generate")).toBe("suno-generate")
+    expect(sunoCreditType("V4_5ALL", "suno-cover")).toBe("suno-cover")
+    expect(sunoCreditType(undefined, "suno-extend")).toBe("suno-extend")
+  })
+
+  // The reason this function is gated rather than a bare version map: these four
+  // routes charge a FLAT per-operation key no matter which version the node
+  // carries (routes/suno.ts:648, :852, :907, :1016). A quote of "suno-v5_5" for
+  // one of them is a key the route never charges.
+  it.each([
+    "suno-mashup",
+    "suno-add-instrumental",
+    "suno-add-vocals",
+    "suno-upload-extend",
+  ])("keeps the flat operation key for %s regardless of version", (operation) => {
+    for (const model of SUNO_MODELS) {
+      expect(sunoCreditType(model, operation)).toBe(operation)
+    }
+    expect(sunoCreditType(undefined, operation)).toBe(operation)
+  })
+
+  it("returns an unknown operation unchanged (never invents a key)", () => {
+    expect(sunoCreditType("V5", "suno-voice")).toBe("suno-voice")
+    expect(sunoCreditType("V5_5", "not-a-suno-op")).toBe("not-a-suno-op")
+  })
+
+  it("exports exactly the three version-priced operations", () => {
+    expect([...SUNO_VERSION_PRICED_OPERATIONS]).toEqual([
+      "suno-generate",
+      "suno-cover",
+      "suno-extend",
+    ])
+  })
+
+  it("exports exactly the seven select operations", () => {
+    expect(SUNO_SELECT_OPERATIONS.length).toBe(7)
+  })
+})

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

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "vitest"
+import { stripDerivedAnalysisFields, videoAnalysisResultSchema } from "../video-analysis.js"
+
+/** A real result shape (validated below) so the strip list is tested against
+ *  the canonical schema, not an invented fixture. */
+const analysis = {
+  meta: { durationSec: 12, width: 1920, height: 1080, aspectRatio: "16:9", title: "Clip" },
+  slots: [
+    { slotId: "hero", label: "Hero", source: "wired-character", role: "person", description: "tan man, mustache, black tee", refImageUrl: "https://r2.example/hero.png" },
+  ],
+  scenes: [
+    { sceneNumber: 1, startSec: 0, endSec: 4, label: "Hook", shotType: "Medium Close-Up", camera: "slow push-in", visual: "{slot:hero} waves", visualResolved: "Hero waves", slotRefs: ["hero"], oversized: false, audio: [] },
+    { sceneNumber: 2, startSec: 4, endSec: 12, label: "Turn", shotType: "Medium Close-Up", camera: "static", visual: "an empty street", visualResolved: "an empty street", slotRefs: [], oversized: true, audio: [] },
+  ],
+  variationFolds: [{ slotId: "hero", variationId: "v2", label: "coat" }],
+  warnings: ["auto-cast dropped one duplicate line"],
+}
+
+describe("stripDerivedAnalysisFields", () => {
+  it("the fixture is a real result (the strip list is tested against the canonical shape)", () => {
+    expect(videoAnalysisResultSchema.safeParse(analysis).success).toBe(true)
+  })
+
+  it("drops the derived top-level and per-scene keys and keeps everything else, refImageUrl included", () => {
+    const out = stripDerivedAnalysisFields(analysis) as Record<string, unknown>
+    expect(out).not.toHaveProperty("warnings")
+    expect(out).not.toHaveProperty("variationFolds")
+    expect(out.meta).toEqual(analysis.meta)
+    expect((out.slots as Array<Record<string, unknown>>)[0].refImageUrl).toBe("https://r2.example/hero.png")
+    const scenes = out.scenes as Array<Record<string, unknown>>
+    expect(scenes).toHaveLength(2)
+    for (const scene of scenes) {
+      expect(scene).not.toHaveProperty("visualResolved")
+      expect(scene).not.toHaveProperty("slotRefs")
+      expect(scene).not.toHaveProperty("oversized")
+      expect(scene).toHaveProperty("visual")
+      expect(scene).toHaveProperty("audio")
+      expect(scene).toHaveProperty("sceneNumber")
+    }
+  })
+
+  it("never mutates its input", () => {
+    const frozen = JSON.parse(JSON.stringify(analysis))
+    stripDerivedAnalysisFields(analysis)
+    expect(analysis).toEqual(frozen)
+  })
+
+  it("returns a non-object input untouched and tolerates a non-object scene entry", () => {
+    expect(stripDerivedAnalysisFields("nope")).toBe("nope")
+    expect(stripDerivedAnalysisFields(null)).toBe(null)
+    expect(stripDerivedAnalysisFields([1])).toEqual([1])
+    const out = stripDerivedAnalysisFields({ scenes: [1, "x", null] }) as { scenes: unknown[] }
+    expect(out.scenes).toEqual([1, "x", null])
+  })
+
+  it("is roughly half the bytes of the full result on a real-shaped scene", () => {
+    const full = JSON.stringify(analysis).length
+    const stripped = JSON.stringify(stripDerivedAnalysisFields(analysis)).length
+    expect(stripped).toBeLessThan(full)
+  })
+})