@nodaro/shared 2.19.0 → 2.20.0

package/src/credit-identifiers.ts

@@ -28,7 +28,7 @@ import {
   getVideoAudioCapability,
 } from "./model-constants.js"
 import { isFlux2Model } from "./flux2-pricing.js"
-import { MODEL_CATALOG } from "./model-catalog.js"
+import { MODEL_CATALOG, normalizeModelInput, type ModelInputAdjustment } from "./model-catalog.js"
 
 /**
  * Compute composite model identifier for variable credit pricing.
@@ -80,6 +80,90 @@ export function buildCreditModelIdentifier(
   return provider
 }
 
+/**
+ * An image request's catalog-snapped parameters PLUS the credit identifier
+ * priced off them.
+ *
+ * `adjustments` is the disclosure channel: every lever this changed, why, and
+ * to what. Routes return it in the 200 body so a caller learns their value was
+ * corrected instead of silently getting something else.
+ */
+export interface NormalizedImageGen {
+  /** Credit identifier, priced off the SNAPPED `resolution` / `quality`. */
+  identifier: string
+  /** The catalog model id the params were snapped against (post T2I→I2I swap). */
+  modelId: string
+  aspectRatio?: string
+  resolution?: string
+  quality?: string
+  /** Empty when the caller's values were already valid for `modelId`. */
+  adjustments: ModelInputAdjustment[]
+}
+
+/**
+ * Snap an image request's catalog-governed levers to a combination the model
+ * actually accepts, and price the credit identifier off the SNAPPED values.
+ *
+ * WHY THE SNAP LIVES HERE and not at the call site. Both image routes compute
+ * their credit identifier TWICE — once in the `creditGuard` preHandler (the
+ * CHECK) and once at the handler's `reserveCreditsForJob` (the DEBIT) — and a
+ * dedicated test asserts the two stay byte-identical (see
+ * `backend/src/routes/__tests__/generate-image.test.ts`, "CHECK === DEBIT").
+ * `resolution` and `quality` are pricing dimensions, so a snap applied at only
+ * one of those sites breaks that invariant, and `commit_credits` never collects
+ * an upward delta — the reserve IS the charge. Putting the snap inside the
+ * primitive makes CHECK, DEBIT and the workflow orchestrator agree by
+ * construction rather than by everyone remembering to call a normalizer.
+ *
+ * Inputs are typed `unknown` on purpose: the preHandler runs BEFORE Zod, so a
+ * caller can put a number or an object in `resolution`. Non-strings become
+ * `undefined` rather than reaching `normalizeModelInput` as a lie.
+ *
+ * Unknown model ids pass through untouched (same contract as
+ * `normalizeModelInput`) — the route's provider enum is the gate for those.
+ */
+export function resolveNormalizedImageGen(opts: {
+  provider: string | undefined
+  aspectRatio?: unknown
+  quality?: unknown
+  resolution?: unknown
+  renderingSpeed?: unknown
+  refCount: number
+  swapToI2i?: boolean
+}): NormalizedImageGen {
+  const str = (v: unknown): string | undefined =>
+    typeof v === "string" && v.length > 0 ? v : undefined
+
+  const provider = str(opts.provider) ?? "nano-banana"
+  // Same swap `resolveEffectiveProvider` applies in the route: refs attached to
+  // a bare T2I provider route the run to its i2i sibling, which has its OWN
+  // catalog entry and its own lever lists.
+  const modelId =
+    opts.swapToI2i && opts.refCount > 0 ? (T2I_TO_I2I_VARIANT[provider] ?? provider) : provider
+
+  const n = normalizeModelInput(modelId, {
+    aspectRatio: str(opts.aspectRatio),
+    resolution: str(opts.resolution),
+    quality: str(opts.quality),
+  })
+
+  return {
+    identifier: buildCreditModelIdentifier(
+      modelId,
+      n.quality,
+      n.resolution,
+      str(opts.renderingSpeed),
+      undefined,
+      opts.refCount,
+    ),
+    modelId,
+    aspectRatio: n.aspectRatio,
+    resolution: n.resolution,
+    quality: n.quality,
+    adjustments: n.adjustments,
+  }
+}
+
 /**
  * Reference-aware image-generation credit identifier — the SINGLE source of
  * truth shared by the single-node routes (`/v1/generate-image`,
@@ -107,17 +191,7 @@ export function resolveImageGenCreditIdentifier(opts: {
   refCount: number
   swapToI2i?: boolean
 }): string {
-  const provider = opts.provider || "nano-banana"
-  const effectiveProvider =
-    opts.swapToI2i && opts.refCount > 0 ? (T2I_TO_I2I_VARIANT[provider] ?? provider) : provider
-  return buildCreditModelIdentifier(
-    effectiveProvider,
-    opts.quality,
-    opts.resolution,
-    opts.renderingSpeed,
-    undefined,
-    opts.refCount,
-  )
+  return resolveNormalizedImageGen(opts).identifier
 }
 
 // T2V-specific credit overrides: some providers have different costs for T2V
@@ -365,3 +439,66 @@ export function buildMotionCreditModelIdentifier(
   const resSuffix = resolution === "1080p" ? ":1080p" : ""
   return `${base}${resSuffix}:${tier.suffix}`
 }
+
+/**
+ * The Suno operations whose credit key depends on the model VERSION.
+ *
+ * `/v1/suno/generate`, `/cover` and `/extend` resolve their creditGuard
+ * identifier through `sunoCreditType(model, <operation>)` (routes/suno.ts
+ * :247-249, :335-337, :407-409). EVERY other Suno route charges a flat
+ * per-operation key and ignores the version the node carries — mashup (:648),
+ * add-instrumental (:852), add-vocals (:907), upload-extend (:1016),
+ * replace-section (:710), style-boost (:771), convert-wav (:962),
+ * lyrics (:482), music-video (:594), voice (:1218).
+ *
+ * Anything that QUOTES a Suno price — a dropdown row, a node badge, the
+ * workflow-credit estimator — must follow the same split, or it displays a
+ * credit key the route never charges.
+ */
+export const SUNO_VERSION_PRICED_OPERATIONS = [
+  "suno-generate",
+  "suno-cover",
+  "suno-extend",
+] as const
+
+/**
+ * The seven Suno operations that appear behind a select/dropdown UI (model
+ * pickers, node badges, the credit estimator) — the three version-priced
+ * operations above, plus the four flat-key operations exercised by
+ * `sunoCreditType`'s own test suite. A readonly tuple so later tasks (the
+ * model dropdowns, node badges) can iterate or count it without redeclaring
+ * the list and drifting from this one.
+ */
+export const SUNO_SELECT_OPERATIONS = [
+  "suno-generate",
+  "suno-cover",
+  "suno-extend",
+  "suno-mashup",
+  "suno-add-instrumental",
+  "suno-add-vocals",
+  "suno-upload-extend",
+] as const
+
+/**
+ * OUR Nodaro credit key for a Suno operation, given the model version and the
+ * operation (which is also the node type and the BullMQ job name).
+ *
+ * This is the single source of truth for the Suno pricing contract, shared by
+ * the reservation path (routes/suno.ts creditGuard), the egress seam
+ * (workers/handlers/suno.ts `modelKey`, which must match what was reserved),
+ * both workflow-credit estimators (ee/billing/credits.ts and the frontend
+ * config-panels/helpers.ts), the seven Suno model dropdowns and the three Suno
+ * node badges. It is a billing key — NEVER a KIE provider id — which is what
+ * satisfies the B3 egress invariant.
+ *
+ * V5_5 → "suno-v5_5", V5 → "suno-v5", any other version → the operation key.
+ * A non-version-priced operation is returned unchanged.
+ */
+export function sunoCreditType(model: string | undefined, operation: string): string {
+  if (!(SUNO_VERSION_PRICED_OPERATIONS as readonly string[]).includes(operation)) {
+    return operation
+  }
+  if (model === "V5_5") return "suno-v5_5"
+  if (model === "V5") return "suno-v5"
+  return operation
+}

package/src/index.ts

@@ -18,6 +18,7 @@ export { usdToCredits, creditsToUsd, CREDIT_ROUNDING_RESOLUTION } from "./credit
 export {
   CREDIT_BASE_USD,
   IMAGE_PROMPT_MAX,
+  IMAGE_ASPECT_RATIO_VALUES,
   MAX_IMAGE_PROMPT_CHARS_BY_PROVIDER,
   getMaxImagePromptChars,
   PROMPT_HARD_CEILING,
@@ -35,6 +36,7 @@ export {
   getMaxSunoStyleChars,
   VIDEO_PROMPT_MAX,
   SUNO_TEXT_MAX,
+  SUNO_HARD_CEILING,
   NATIVE_NEGATIVE_PROMPT_MODELS,
   NATIVE_NEGATIVE_VIDEO_PROVIDERS,
   applyVideoNegativePrompt,
@@ -173,6 +175,7 @@ export { FEATURED_ENTITIES, getFeaturedEntities } from "./featured-entities.js"
 export type { FeaturedEntity } from "./featured-entities.js"
 
 export type {
+  ImageAspectRatio,
   ImageGenProvider,
   ImageMaskMode,
   ImageI2IProvider,
@@ -234,9 +237,14 @@ export type {
 export {
   buildCreditModelIdentifier,
   resolveImageGenCreditIdentifier,
+  resolveNormalizedImageGen,
   buildVideoCreditModelIdentifier,
   buildMotionCreditModelIdentifier,
+  sunoCreditType,
+  SUNO_VERSION_PRICED_OPERATIONS,
+  SUNO_SELECT_OPERATIONS,
 } from "./credit-identifiers.js"
+export type { NormalizedImageGen } from "./credit-identifiers.js"
 
 export * from "./credit-estimators/index.js"
 export { extractVideoDurationFromNode } from "./video-duration.js"

package/src/model-constants.ts

@@ -13,6 +13,42 @@ export const CREDIT_BASE_USD = 0.002
  *  schemas and the factory-preset guard test all read this. Prompt cap ONLY (not negativePrompt). */
 export const IMAGE_PROMPT_MAX = 5000
 
+/**
+ * The ONE aspect-ratio vocabulary the image routes' Zod enums are built from —
+ * `/v1/generate-image`, `/v1/image-to-image` and `/v1/edit-image` all declare
+ * `z.enum(IMAGE_ASPECT_RATIO_VALUES)` instead of keeping three literal lists
+ * that drift.
+ *
+ * It is the UNION of every ratio any `kind: "image"` catalog entry declares, so
+ * a value the picker offers can never 400 at the route. That gap has shipped
+ * twice — Wan 2.7's ultra-wide `8:1`/`1:8` (fixed on generate-image only) and
+ * Nano Banana 2 Lite's banner `4:1`/`1:4` (still open until this tuple landed).
+ * `packages/shared/src/__tests__/image-pricing-catalog-coverage.test.ts` fails
+ * the build if a new model declares a ratio this tuple is missing.
+ *
+ * This enum is a VOCABULARY BOUND, not a per-model gate: it only stops a
+ * free-form string from reaching a provider as `image_size`. The per-model gate
+ * is the catalog snap (`resolveNormalizedImageGen` → `normalizeModelInput`),
+ * which CORRECTS an unsupported ratio and discloses it in the response's
+ * `adjustments` — never rejects. So widening this tuple is always safe: it
+ * defers a rejection to the correcting snap, which is the desired behaviour.
+ *
+ * `auto` is model-specific (GPT Image 2 / Nano Banana 2 Lite treat it as
+ * "native"); it lives here for the same reason as the rest — the snap drops or
+ * replaces it for models that do not declare it.
+ */
+export const IMAGE_ASPECT_RATIO_VALUES = [
+  "auto",
+  "1:1", "16:9", "9:16", "4:3", "3:4",
+  "3:2", "2:3", "5:4", "4:5", "21:9",
+  // Ultra-wide / ultra-tall banner ratios: Wan 2.7 + Wan 2.7 Pro (8:1, 1:8)
+  // and Nano Banana 2 Lite (4:1, 1:4, 8:1, 1:8).
+  "4:1", "1:4", "8:1", "1:8",
+] as const
+
+/** A ratio string the image routes accept (pre-snap vocabulary, not a per-model guarantee). */
+export type ImageAspectRatio = typeof IMAGE_ASPECT_RATIO_VALUES[number]
+
 /**
  * Per-provider maximum ASSEMBLED image-prompt length (chars), VERIFIED against
  * each model's official docs.kie.ai schema (2026-06). Providers absent here use
@@ -75,15 +111,37 @@ export const VIDEO_PROMPT_MAX = 8000
 
 /**
  * Suno prompt / lyrics / content ceiling — the LARGEST any Suno version accepts
- * in custom mode (V4.5 / V4.5PLUS / V4.5ALL / V5 / V5.5 = 5000). The route Zod
- * uses this as a generous ceiling; the handler clamps to the per-version cap via
- * {@link getMaxSunoPromptChars} (V4/V3.5 = 3000, non-custom = 500). Shared with
- * the editor `maxLength` / counter (warn-don't-block at the per-version cap).
- * `style` and `title` have their own caps ({@link getMaxSunoStyleChars} /
- * {@link SUNO_TITLE_MAX}).
+ * in custom mode (V4.5 / V4.5PLUS / V4.5ALL / V5 / V5.5 = 5000). NOT the route
+ * Zod bound — the routes bind at {@link SUNO_HARD_CEILING} and clamp to the
+ * per-version cap via {@link getMaxSunoPromptChars} (3000 non-custom for every
+ * version; in custom mode 3000 for V4/V3.5, 5000 for V4.5+/V5) before the job
+ * is built. This constant is shared with the editor `maxLength` / counter
+ * (warn-don't-block at the per-version cap). `style` and `title` have their
+ * own caps ({@link getMaxSunoStyleChars} / {@link SUNO_TITLE_MAX}).
  */
 export const SUNO_TEXT_MAX = 5000
 
+/**
+ * Absolute ceiling for every Suno text field on the route Zod schemas
+ * (`prompt`, `lyrics`, `fullLyrics`, `content`, `userPrompt`).
+ *
+ * WARN-DON'T-BLOCK. The per-version caps ({@link getMaxSunoPromptChars} /
+ * {@link getMaxSunoStyleChars}) do the real work — the routes CLAMP to them
+ * before building the job. The Zod bound only exists to stop abuse, so it must
+ * stay generous: until 2026-09 the routes bounded these fields at
+ * {@link SUNO_TEXT_MAX} (5000), which meant a programmatically-set prompt (an
+ * agent, an app run, a FieldMapping) was hard-REJECTED with a 400 before the
+ * clamp could trim it — three app-report rows on 2026-08-19..31.
+ *
+ * DISTINCT FROM {@link PROMPT_HARD_CEILING} on purpose: that one is an
+ * image/video budget pinned to MAX_IMAGE/VIDEO_PROMPT_CHARS_BY_PROVIDER by its
+ * own drift guard. Coupling them would let one modality's limits move the
+ * other's. This one has a single invariant, enforced in
+ * `__tests__/prompt-length-limits.test.ts`: it MUST stay >= every value
+ * getMaxSunoPromptChars / getMaxSunoStyleChars can return.
+ */
+export const SUNO_HARD_CEILING = 30000
+
 /**
  * Absolute ceiling for the `prompt` / `negativePrompt` fields on the image and
  * video routes' Zod schemas. The PER-MODEL limits below (and the editor warning)
@@ -238,9 +296,11 @@ export function getMaxTtsChars(provider: string | undefined): number {
 }
 
 /**
- * Suno per-version field caps (from docs.kie.ai/suno-api/generate-music). The old
- * flat {@link SUNO_TEXT_MAX} (3000) was simultaneously too low for V4.5+/V5
- * prompts (5000) and too high for `style` (1000) and `title` (80).
+ * Suno per-version field caps (from docs.kie.ai/suno-api/generate-music). The
+ * original flat 3000 cap was simultaneously too low for V4.5+/V5 prompts
+ * (5000) and too high for `style` (1000) and `title` (80). ({@link
+ * SUNO_TEXT_MAX} is 5000 today — the largest per-version prompt cap; the
+ * route Zod bound is {@link SUNO_HARD_CEILING}.)
  *   - prompt / lyrics: 3000 in non-custom mode (all versions); in custom mode
  *     3000 for V4/V3.5 and 5000 for V4.5 / V4.5PLUS / V4.5ALL / V5 / V5.5.
  *   - style: 200 for V4/V3.5, 1000 for V4.5+.

package/src/normalize-node-params.ts

@@ -30,10 +30,18 @@ import { normalizeModelInput, type ModelInputAdjustment } from "./model-catalog.
  * through mode-dependent defaults (`"adaptive"` for Seedance/Hailuo, duration
  * composites tied to pricing) that this flat normalizer would flatten wrongly;
  * they get their own pass once those defaults are catalog-derived too.
+ *
+ * `modify-image` carries the same provider/aspectRatio/resolution/quality trio
+ * as `image-to-image` (it routes through the same worker), and `edit-image`
+ * carries provider + aspectRatio. `edit-image`'s `targetResolution` is an
+ * UPSCALE target, a different field this module never reads — so listing the
+ * type here heals its ratio without touching what it is priced on.
  */
 export const MODEL_PARAM_NODE_TYPES: ReadonlySet<string> = new Set([
   "generate-image",
   "image-to-image",
+  "modify-image",
+  "edit-image",
 ])
 
 export interface NodeParamAdjustment extends ModelInputAdjustment {

package/src/organizations/types.ts

@@ -56,6 +56,16 @@ export type GrantedAccess = (typeof GRANTED_ACCESS)[number]
 export const SUBMISSION_STATUSES = ["submitted", "in_review", "returned", "approved"] as const
 export type SubmissionStatus = (typeof SUBMISSION_STATUSES)[number]
 
+/**
+ * How a usage report is bucketed. `workspace` is org-scope only; `none`
+ * = flat rows. A runtime list, like `ORG_ROLES`, so the plugin route's Zod is
+ * `z.enum(USAGE_GROUP_BYS)` and the migration guard asserts the SQL
+ * `NOT IN (...)` list equals this minus `none` — one vocabulary, never three
+ * hand-copies that drift.
+ */
+export const USAGE_GROUP_BYS = ["workspace", "member", "model", "day", "none"] as const
+export type UsageGroupBy = (typeof USAGE_GROUP_BYS)[number]
+
 /**
  * Error codes the organization endpoints add to the standard envelope
  * (`{ error: { code, message } }`). Clients dispatch on the code, never on
@@ -80,6 +90,8 @@ export const ORG_ERROR_CODES = [
   "domain_not_allowed",
   "already_started",
   "collab_unavailable",
+  // A CSV usage export whose write-ahead audit row could not be written (503).
+  "audit_unavailable",
   // Organization, workspace and membership endpoints.
   "terms_required",
   "not_org_member",

package/src/organizations/views.ts

@@ -4,6 +4,7 @@ import type {
   OrgRole,
   OrgSettings,
   OrgStatus,
+  UsageGroupBy,
   WorkspaceRole,
   WorkspaceSettings,
 } from "./types.js"
@@ -218,3 +219,116 @@ export interface OrgPage<T> {
   data: T[]
   nextCursor: string | null
 }
+
+/**
+ * Usage reporting. What `GET /v1/orgs/:id/usage` and
+ * `GET /v1/workspaces/:id/usage` return. No cost/USD field appears anywhere —
+ * a report shows CREDITS a class or team spent, never the platform's own rates
+ * (pricing-leak class, guarded by organizations-types.test.ts and the
+ * migration guard).
+ */
+
+/** One bucket of a usage report. Exactly one of workspace/member/model/day is set. */
+export interface UsageReportRow {
+  key: string
+  workspace: { id: string; name: string | null; slug: string | null; archived: boolean } | null
+  member: { userId: string; displayName: string | null; email: string | null } | null
+  model: string | null
+  /** `YYYY-MM-DD` in the report's `tz`. */
+  day: string | null
+  runCount: number
+  appRunCount: number
+  /** Settled where known, the held reservation otherwise. = settledCredits + inFlightCredits. */
+  credits: number
+  settledCredits: number
+  inFlightCredits: number
+  inFlightRuns: number
+}
+
+/**
+ * A platform-absorbed line for one workspace, split by ORIGIN (never attributed
+ * to a member). Two ledgers share the `org_usage_variance` source: a
+ * `metered_overrun` (a metered run's overrun beyond the budget — it HAS a
+ * settled usage_logs counterpart) and an `app_markup` shortfall (an
+ * approved-app markup the budget could not cover — it has NO usage_logs row).
+ * `other` is a future/unrecognised origin.
+ */
+export interface UsageVarianceRow {
+  workspace: { id: string; name: string | null; slug: string | null } | null
+  kind: "metered_overrun" | "app_markup" | "other"
+  credits: number
+  rowCount: number
+}
+
+/**
+ * Totals over the WHOLE window — every usage_logs row in [from, to] after the
+ * scope / userId / workspaceId narrowing — never over the returned `rows`.
+ * Unaffected by `truncated`; equals a `groupBy=day` report's column-wise sum.
+ */
+export interface UsageReportTotals {
+  runCount: number
+  credits: number
+  settledCredits: number
+  inFlightCredits: number
+  /** Metered-overrun variance in the window — a run's overrun the platform absorbed. */
+  platformAbsorbedCredits: number
+  /** Approved-app markup shortfall the platform absorbed. It has NO usage_logs run, so it is not in the figures above. */
+  appMarkupAbsorbedCredits: number
+  /**
+   * settledCredits − platformAbsorbedCredits: the METERED settlement that
+   * reached the workspace budget(s). App markup charged to a budget (migration
+   * 352) is not a usage_logs row and is not included here; when a markup
+   * shortfall is absorbed this figure under-reports and may go negative — it is
+   * NOT `workspace_budgets.spent_credits`.
+   */
+  chargedToBudget: number
+}
+
+export interface UsageReport {
+  scope: "org" | "workspace"
+  scopeId: string
+  from: string
+  to: string
+  tz: string
+  groupBy: Exclude<UsageGroupBy, "none">
+  /** Present when a member's self-view or an admin's `?userId=` narrowed the report. */
+  userId: string | null
+  /** Present when an org report was narrowed to one workspace. */
+  workspaceId: string | null
+  rows: UsageReportRow[]
+  variance: UsageVarianceRow[]
+  totals: UsageReportTotals
+  /**
+   * True when more than 5000 buckets existed and the tail of `rows` was dropped
+   * — narrow the window. Only `rows` is incomplete; `totals` and `variance`
+   * cover the whole window regardless.
+   */
+  truncated: boolean
+}
+
+/** One usage_logs row as an organization sees it. No cost fields, ever. */
+export interface UsageLogEntry {
+  id: string
+  createdAt: string
+  workspace: { id: string; name: string | null; slug: string | null } | null
+  member: { userId: string; displayName: string | null; email: string | null } | null
+  jobId: string | null
+  model: string
+  status: "reserved" | "committed"
+  creditsReserved: number
+  creditsSettled: number | null
+  credits: number
+  isAppRun: boolean
+}
+
+/** Query parameters shared by both usage routes (dates inclusive, IANA tz). */
+export interface UsageQuery {
+  from?: string
+  to?: string
+  tz?: string
+  groupBy?: UsageGroupBy
+  workspaceId?: string
+  userId?: string
+  cursor?: string
+  limit?: number
+}

package/src/video-analysis.ts

@@ -633,3 +633,48 @@ export function inferMusicVideo(analysis: {
     }),
   )
 }
+
+// ---------------------------------------------------------------------------
+// The analysis as a BRIEF — the compact projection an LLM is handed
+// ---------------------------------------------------------------------------
+
+/** Top-level keys the analyzer derives AFTER the model's pass (merge
+ *  diagnostics, folded cast looks). A reader drafting FROM the analysis — a
+ *  production plan, a script — needs none of them. */
+const DERIVED_ANALYSIS_TOP_KEYS: ReadonlySet<string> = new Set(["warnings", "variationFolds"])
+
+/** Per-scene keys the validator computes from `visual` and the slot list. */
+const DERIVED_ANALYSIS_SCENE_KEYS: ReadonlySet<string> = new Set(["visualResolved", "slotRefs", "oversized"])
+
+const asRecord = (v: unknown): Record<string, unknown> | null =>
+  typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : null
+
+/**
+ * The analysis with its server-derived fields removed — the form an LLM is
+ * handed when the analysis IS the brief (Nodaro Studio's Director and its
+ * job-id loader). Drops `warnings` and `variationFolds` at the top and
+ * `visualResolved`, `slotRefs`, `oversized` on every scene; keeps
+ * `refImageUrl` (a downstream cast image) and everything else. Never mutates;
+ * a non-object input comes back as-is.
+ *
+ * ONE strip list, shared by the worker that composes the brief server-side
+ * (`llm-structured` jobs with a `videoUrl`) and the client that loads a
+ * finished analysis into a textarea, so the two can never drift.
+ */
+export function stripDerivedAnalysisFields(json: unknown): unknown {
+  const doc = asRecord(json)
+  if (!doc) return json
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(doc)) {
+    if (DERIVED_ANALYSIS_TOP_KEYS.has(key)) continue
+    out[key] =
+      key === "scenes" && Array.isArray(value)
+        ? value.map((scene) => {
+            const s = asRecord(scene)
+            if (!s) return scene
+            return Object.fromEntries(Object.entries(s).filter(([k]) => !DERIVED_ANALYSIS_SCENE_KEYS.has(k)))
+          })
+        : value
+  }
+  return out
+}