@nodaro/shared 2.19.0 → 2.21.0

package/src/node-refs.ts

@@ -50,6 +50,10 @@ export function canonicalVarName(label: string): string {
  * SUPPRESS auto-injection of a connected node the author already placed
  * explicitly via `{label}` (so it isn't injected twice). `matchAll` over the
  * global pattern does not mutate its lastIndex, so sharing the constant is safe.
+ *
+ * Deliberately NOT `REF_TOKEN_NAMESPACE_PREFIXES`: widening this changes
+ * run-time auto-injection on BOTH engines (follow-up ticket), not just the
+ * editor.
  */
 export function extractReferencedLabels(
   ...texts: ReadonlyArray<string | undefined | null>
@@ -251,3 +255,81 @@ export function resolveNodeRefs(
   }
   return result
 }
+
+/**
+ * Token namespaces that are NOT node-label references. `{image:1:face}` is the
+ * unified-reference grammar, `{slot:x}` is recast's, `{video:N}`/`{audio:N}`
+ * are reference handles, and `{ref:<id>}` is the id-addressed reference form —
+ * all five are substituted by their own resolvers (`resolveReferenceTokens`,
+ * `resolveRefIdTokens`, the recast slot pass), not by resolveNodeRefs. Before
+ * this list existed, only `image:` was excluded, so `{video:1}` classified as a
+ * MISSING node ref.
+ *
+ * Compared against the LOWERCASED token name: `REFERENCE_TOKEN_RE` is `/gi` and
+ * `REF_ID_TOKEN_RE` spells `[rR][eE][fF]`, so `{Image:1}` / `{Ref:x}` really do
+ * resolve downstream and must never read as a missing node ref.
+ */
+export const REF_TOKEN_NAMESPACE_PREFIXES: readonly string[] = [
+  "image:", "video:", "audio:", "slot:", "ref:",
+]
+
+export type RefTokenKind = "wired" | "reserved" | "missing" | "skip" | "unknown"
+
+/**
+ * Classify a parsed `{...}` token name against the resolvable label set.
+ * `resolvable === null` means the caller has no ref data at all — such tokens
+ * classify `unknown` and must render like wired, so "no data" never
+ * masquerades as "nothing wired".
+ *
+ * Single source of truth for the editor decoration, the missing-refs chip
+ * (frontend/src/lib/prompt-ref-scan.ts delegates here) and the execution
+ * engine's dispatch guard.
+ */
+export function classifyRefToken(
+  name: string,
+  resolvable: ReadonlySet<string> | null,
+): RefTokenKind {
+  const lower = name.toLowerCase()
+  if (name === "" || REF_TOKEN_NAMESPACE_PREFIXES.some((p) => lower.startsWith(p))) return "skip"
+  if (RESERVED_TEMPLATE_VARS.has(name)) return "reserved"
+  if (resolvable === null) return "unknown"
+  return resolvable.has(canonicalVarName(name)) ? "wired" : "missing"
+}
+
+/**
+ * The `{Label}` tokens in `text` that `resolveNodeRefs` would leave LITERAL and
+ * that no upstream node can explain — i.e. exactly what would reach a provider
+ * as the characters `{Label}`. Evidence for why this matters: `{Describe Image}`
+ * ×2 (gpt-image-2) and `{gravity flip}` / `{rewind}` (seedance-2-5) in the
+ * 2026-09-01 app-reports export.
+ *
+ * `resolvable` — labels with a value in the ref map (canonical/lowercase).
+ * `known`      — canonical labels of the nodes the caller considers to EXIST
+ *                (no state requirement; the backend passes every node in the
+ *                run's graph).
+ *
+ * A token whose label is in `known` but not `resolvable` PASSES: the node
+ * exists and simply produced nothing, which is the caller's to substitute (the
+ * backend resolves it to empty text), not this function's to refuse. A token
+ * with an explicit `|| fallback` passes too — the fallback is substituted.
+ * Returns original-cased names, de-duplicated by canonical form, for the
+ * user-facing message.
+ */
+export function unresolvedRefTokens(
+  text: string,
+  opts: { resolvable: ReadonlySet<string>; known: ReadonlySet<string> },
+): string[] {
+  if (typeof text !== "string" || text.length === 0) return []
+  const seen = new Set<string>()
+  const out: string[] = []
+  for (const m of text.matchAll(NODE_REF_PATTERN)) {
+    const { name, fallback } = parseNodeRef(m[1] ?? "")
+    if (fallback !== null) continue
+    if (classifyRefToken(name, opts.resolvable) !== "missing") continue
+    const canon = canonicalVarName(name)
+    if (opts.known.has(canon) || seen.has(canon)) continue
+    seen.add(canon)
+    out.push(name)
+  }
+  return out
+}

package/src/node-runtime-keys.ts

@@ -16,6 +16,11 @@ export const EXECUTION_DATA_KEYS: ReadonlySet<string> = new Set([
   "currentJobId",
   "currentJobProgress",
   "errorMessage",
+  // Structured detail alongside errorMessage for a safety-filter block
+  // (see `JobErrorHint` in the app's frontend/src/types/nodes.ts). Same
+  // lifecycle as errorMessage: a RESULT the user expects to survive reload,
+  // never user-edited config.
+  "errorHint",
   "isStreaming",
   "generatedImageUrl",
   "generatedVideoUrl",

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/safety-retry-policy.ts

@@ -0,0 +1,37 @@
+import { getModel } from "./model-catalog.js"
+
+/**
+ * Retry/fallback behavior derived from a catalog entry's `safetyFilter`
+ * flag (see `ModelCatalogEntry.safetyFilter` in `model-catalog.ts`).
+ */
+export interface SafetyRetryPolicy {
+  /** 2 when the model declares `safetyFilter.stochastic`, else 1. */
+  maxAttempts: 1 | 2
+  /**
+   * Catalog model id to offer when the retry also blocks. Only present
+   * when the entry declares one AND it resolves to a real catalog entry.
+   */
+  fallback?: string
+}
+
+/**
+ * The provider's safety filter is known to be non-deterministic on some
+ * catalog models — a benign prompt can trip it once and pass on an
+ * identical retry. For those models the platform retries a blocked
+ * request once (`maxAttempts: 2`) before giving up; `fallback` names the
+ * catalog model to offer the user when the retry also blocks.
+ *
+ * Every model not flagged this way — including an unrecognized id —
+ * gets a single attempt and no fallback.
+ */
+export function safetyRetryPolicy(modelId: string): SafetyRetryPolicy {
+  const entry = getModel(modelId)
+  const safetyFilter = entry?.safetyFilter
+  if (!safetyFilter?.stochastic) return { maxAttempts: 1 }
+
+  const fallback = safetyFilter.fallback
+  if (fallback && getModel(fallback)) {
+    return { maxAttempts: 2, fallback }
+  }
+  return { maxAttempts: 2 }
+}

package/src/topaz-upscale.ts

@@ -0,0 +1,163 @@
+/**
+ * Topaz image upscale — the single authority for "which lever did the user
+ * pull, what do we send, and what do we charge".
+ *
+ * KIE's `topaz/image-upscale` takes exactly ONE quality lever:
+ *   upscale_factor: "1" | "2" | "4"   (default "2")
+ * There is no target-resolution parameter (docs.kie.ai/market/topaz/image-upscale,
+ * verified 2026-09-02). The editor nevertheless shipped TWO controls — an
+ * `upscaleFactor` select AND a `targetResolution` select (2K/4K/8K) — and billed
+ * on the second one, which never reached the worker. Everyone who bought 4K or
+ * 8K got a 2x render at 2x/4x the price (app-reports triage 2026-09-01 §4.3).
+ *
+ * So: the FACTOR is the lever. `targetResolution` survives only as a legacy
+ * input (stored node data, old API/MCP callers) and is mapped forward here.
+ * The credit tier is derived from the SAME resolution, which is why callers
+ * must pass `creditTier` into `buildCreditModelIdentifier` rather than the raw
+ * request value — that is what makes CHECK = DEBIT = SENT.
+ *
+ * The composite `topaz-image-upscale:4K` is retained as the id of the 4x tier
+ * (migration 288 wrote that row; renaming it would need a pricing migration for
+ * zero user-visible gain). Read it as "the top Topaz tier", not as a promise of
+ * 4096 pixels. `topaz-image-upscale:8K` stays priced in STATIC_CREDIT_COSTS so
+ * historical usage_logs still resolve, but nothing can reserve it any more.
+ *
+ * Resolution order (fix round 1, 2026-09-02 review):
+ *   1. Resolve the WINNING factor first — a valid `upscaleFactor` always wins;
+ *      an invalid one falls through to `targetResolution` exactly as if it had
+ *      never been sent, rather than freezing the default before the legacy
+ *      tier gets a chance to raise it (an invalid factor + a stored 4K/8K tier
+ *      must still resolve — and bill — at the tier's factor, not the default).
+ *   2. Only THEN build `adjustments`, so every `to` reflects the resolved
+ *      factor rather than an intermediate guess, and every `from` is the raw,
+ *      untransformed input string (never the trimmed/uppercased copy used
+ *      internally to match).
+ *   3. A valid `upscaleFactor` alongside a `targetResolution` it disagrees
+ *      with emits an informational (not corrective) adjustment — the stored
+ *      legacy choice is being overridden, not silently dropped — with
+ *      `to: undefined` because nothing was actually sent for that field.
+ *      Agreement (they resolve to the same factor) is reported as nothing:
+ *      there is no override to disclose.
+ */
+
+export type TopazUpscaleFactor = "1" | "2" | "4"
+
+export const TOPAZ_UPSCALE_FACTORS: readonly TopazUpscaleFactor[] = ["1", "2", "4"]
+
+/** KIE's own default when `upscale_factor` is omitted (providers/kie/models.ts). */
+export const TOPAZ_DEFAULT_UPSCALE_FACTOR: TopazUpscaleFactor = "2"
+
+export interface TopazUpscaleAdjustment {
+  field: "upscaleFactor" | "targetResolution"
+  /** The raw, untransformed value as received — never trimmed or case-normalized. */
+  from: string
+  /**
+   * The resolved factor this adjustment corresponds to, or `undefined` for the
+   * informational "your stored targetResolution was overridden" notice, which
+   * names nothing to switch TO — `upscaleFactor` already won.
+   */
+  to: string | undefined
+  reason: string
+}
+
+export interface TopazUpscaleResolution {
+  /** Sent to KIE as `upscale_factor`. Always set — never rely on the model default. */
+  upscaleFactor: TopazUpscaleFactor
+  /**
+   * Passed VERBATIM as `buildCreditModelIdentifier`'s `targetResolution` arg.
+   * `undefined` = the bare id (1x / 2x); `"4K"` = the 4x tier.
+   */
+  creditTier: "4K" | undefined
+  /** Non-empty when a legacy or out-of-enum value was coerced or overridden. */
+  adjustments: TopazUpscaleAdjustment[]
+}
+
+/** Legacy 2K/4K/8K tier → the factor the provider can actually deliver. */
+const LEGACY_TIER_TO_FACTOR: Record<string, TopazUpscaleFactor> = {
+  "2K": "2",
+  "4K": "4",
+  "8K": "4",
+}
+
+function isFactor(v: string): v is TopazUpscaleFactor {
+  return (TOPAZ_UPSCALE_FACTORS as readonly string[]).includes(v)
+}
+
+export function resolveTopazUpscale(input: {
+  upscaleFactor?: string | null
+  targetResolution?: string | null
+}): TopazUpscaleResolution {
+  const adjustments: TopazUpscaleAdjustment[] = []
+
+  // Raw, untransformed inputs — these are what every adjustment's `from` reports.
+  const rawFactor = typeof input.upscaleFactor === "string" ? input.upscaleFactor : ""
+  const rawTier = typeof input.targetResolution === "string" ? input.targetResolution : ""
+
+  // Trimmed/normalized copies used ONLY for matching, never for display.
+  const trimmedFactor = rawFactor.trim()
+  const normalizedTier = rawTier.trim().toUpperCase()
+
+  const factorGiven = trimmedFactor.length > 0
+  const factorValid = factorGiven && isFactor(trimmedFactor)
+
+  const tierGiven = normalizedTier.length > 0
+  const tierMappedFactor = tierGiven ? LEGACY_TIER_TO_FACTOR[normalizedTier] : undefined
+
+  // --- 1. Resolve the winning factor FIRST. ---
+  // A valid factor always wins. An invalid (or absent) one falls through to
+  // whatever the legacy tier maps to; only if that also comes up empty do we
+  // land on the provider default.
+  const finalFactor: TopazUpscaleFactor = factorValid
+    ? (trimmedFactor as TopazUpscaleFactor)
+    : (tierMappedFactor ?? TOPAZ_DEFAULT_UPSCALE_FACTOR)
+
+  // --- 2. Emit adjustments LAST, against the already-resolved factor. ---
+  if (factorGiven && !factorValid) {
+    adjustments.push({
+      field: "upscaleFactor",
+      from: rawFactor,
+      to: finalFactor,
+      reason: `Topaz upscale accepts a factor of 1, 2 or 4 — "${rawFactor}" was replaced with ${finalFactor}.`,
+    })
+  }
+
+  if (factorValid && tierGiven) {
+    // The factor won outright. Say so if it disagrees with the stored legacy
+    // tier — otherwise the tier silently vanishes with no record. Agreement
+    // needs no note: nothing was overridden.
+    if (tierMappedFactor !== finalFactor) {
+      adjustments.push({
+        field: "targetResolution",
+        from: rawTier,
+        to: undefined,
+        reason: "upscaleFactor takes precedence over the legacy targetResolution.",
+      })
+    }
+  } else if (!factorValid && tierGiven) {
+    // No valid explicit factor — the legacy tier is the (partial) source of
+    // the resolved factor, or was consulted and found unusable.
+    if (tierMappedFactor) {
+      if (normalizedTier === "8K") {
+        adjustments.push({
+          field: "targetResolution",
+          from: rawTier,
+          to: finalFactor,
+          reason: "Topaz upscale offers factors up to 4x — an 8K target renders and bills at the 4x tier.",
+        })
+      }
+    } else {
+      adjustments.push({
+        field: "targetResolution",
+        from: rawTier,
+        to: finalFactor,
+        reason: `Unknown Topaz target "${rawTier}" — rendering at ${finalFactor}x.`,
+      })
+    }
+  }
+
+  return {
+    upscaleFactor: finalFactor,
+    creditTier: finalFactor === "4" ? "4K" : undefined,
+    adjustments,
+  }
+}

package/src/video-analysis.ts

@@ -175,6 +175,26 @@ export const clipLookSchema = z.object({
    * insert) states the deviation in that scene's `visual`, as with `lighting`.
    */
   style: z.string().optional(),
+  /**
+   * The Style picker CATALOG ID the prose in `style` corresponds to — the
+   * analyzer's PICK ("pixar-3d" beside "3D stylized animation"), not a second
+   * description of it.
+   *
+   * Worth strictly more than the prose it accompanies: an id addresses the
+   * catalog, so a recreation renders the same medium the product's own Style
+   * picker would render, instead of re-interpreting a sentence. Absent when the
+   * analyzer read a medium it could not place in the catalog — `style` then
+   * carries the whole answer, as it always did.
+   *
+   * A free `string` here on purpose. The PRODUCER validates it against the
+   * catalog (the analyzer plugin's wire schema is an enum generated from
+   * `STYLES`, so an invented id never leaves it), while this package must not
+   * carry the catalog itself. A closed enum here would only add a second copy
+   * of the vocabulary to drift out of date — and, worse, would REJECT a
+   * catalog entry newer than the installed `@nodaro/shared`, which is exactly
+   * the analysis a consumer most wants to read.
+   */
+  styleId: z.string().optional(),
   /** Colour grade / palette — "muted teal-and-orange, crushed blacks". */
   grade: z.string().optional(),
   /** Camera or film FORMAT and stock — "anamorphic digital", "16mm film grain". */
@@ -265,14 +285,32 @@ export const entitySlotSchema = z.object({
 })
 export type EntitySlot = z.infer<typeof entitySlotSchema>
 
+/**
+ * The sound LAYER vocabulary — what kind of thing this layer is.
+ *
+ * `ambience` is deliberately its own member rather than a flavour of `sfx`:
+ * they are different layers of a real mix and they are recreated by different
+ * means — ambience is the continuous bed a scene sits in (room tone, distant
+ * traffic, wind), an sfx is a discrete hit (a door slam, a gunshot). Folded
+ * together, a scene's bed and its one-off noises arrive indistinguishable and
+ * anything recreating the mix has to guess which it was told.
+ *
+ * Exported so a consumer keying its own document by these modes imports the
+ * vocabulary instead of restating it — the same reason every other closed
+ * vocabulary in this file is a const.
+ */
+export const VIDEO_ANALYSIS_AUDIO_MODES = ["speech", "music", "sfx", "ambience"] as const
+export type VideoAnalysisAudioMode = (typeof VIDEO_ANALYSIS_AUDIO_MODES)[number]
+
 /**
  * One concurrent sound layer in a scene. Real footage stacks sound (music bed
- * under dialogue over ambient sfx), so a scene carries an ARRAY of these — an
- * empty array means genuine silence. `content`: speech = verbatim words;
- * music/sfx = gen-ready description. `voice` is speech-only voice-casting.
+ * under dialogue over ambient room tone), so a scene carries an ARRAY of these
+ * — an empty array means genuine silence. `content`: speech = verbatim words;
+ * music/sfx/ambience = gen-ready description. `voice` is speech-only
+ * voice-casting.
  */
 const audioLayerSchema = z.object({
-  mode: z.enum(["speech", "music", "sfx"]),
+  mode: z.enum(VIDEO_ANALYSIS_AUDIO_MODES),
   content: z.string().min(1),
   voice: z.string().optional(),
   /**
@@ -296,6 +334,33 @@ const audioLayerSchema = z.object({
    * defect that `stripOrphanSlots` exists to kill.
    */
   speakerSlot: z.string().optional(),
+  /**
+   * SPEECH ONLY — WHO says these words, by NAME.
+   *
+   * The second of two ways to name a speaker, and the one for documents that
+   * have no slots: `speakerSlot` addresses an `EntitySlot` of THIS analysis by
+   * id, while `speaker` is the plain cast name a production keys its own cast
+   * by ("Jack Mercer"). A layer may legitimately carry both — the id for the
+   * analysis it came from, the name for the document it is going into — and a
+   * consumer that understands only one reads the one it understands.
+   *
+   * Optional, and not refined against `mode`, for the same reason
+   * `speakerSlot` is not: the window schema is the enforced decode grammar and
+   * must not throw away a whole roll over one mis-tagged field.
+   *
+   * NOT swept by `dropUnknownSpeakers`. That function is the SLOT channel's
+   * sanitizer — it judges an id against the surviving slot list, and a name has
+   * no id space to be unknown in. The asymmetry is deliberate and pinned by
+   * test; whoever owns the name's vocabulary sanitizes the name.
+   *
+   * The residual that leaves: a layer can keep a `speaker` naming someone
+   * `stripOrphanSlots` already pruned as a phantom, where the same claim spelled
+   * `speakerSlot` would have been dropped — the invented-narrator defect, in the
+   * one spelling the sweep cannot see. LATENT today, since nothing in this
+   * repo emits `speaker`; the day the analyzer does, that sweep is what has to
+   * grow, not this field.
+   */
+  speaker: z.string().optional(),
 })
 export type AudioLayer = z.infer<typeof audioLayerSchema>
 
@@ -502,7 +567,7 @@ export function rewriteSpeakerSlots(audio: AudioLayer[], slotRenames: Record<str
  * Strip attribution that no scene can honour — the `dropUnknownBindings` mirror
  * for the `audio` channel. Two cases, both model sloppiness rather than errors
  * worth failing a roll over:
- *   - a `speakerSlot` on a `music`/`sfx` layer (nobody is speaking)
+ *   - a `speakerSlot` on any non-`speech` layer (nobody is speaking)
  *   - a `speakerSlot` naming a slot that is not in the final list
  *
  * MUST run AFTER the orphan-slot sweep, and attribution must NEVER count as a
@@ -633,3 +698,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
+}