@nodaro/shared 1.20.0 → 1.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "1.20.0",
+  "version": "1.21.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__/video-analysis.test.ts

@@ -5,8 +5,9 @@ import {
   renderAnalyzedScene, isOversizedScene, aspectRatioFromDims,
   entitySlotSchema, analyzedSceneSchema,
   rewriteSceneBindings, dropUnknownBindings,
+  rewriteSpeakerSlots, dropUnknownSpeakers,
   VIDEO_ANALYSIS_MAX_VARIATIONS, VIDEO_ANALYSIS_VARIATION_SLUGS, VIDEO_ANALYSIS_DEFAULT_VARIATION,
-  type EntitySlot,
+  type EntitySlot, type AudioLayer,
 } from "../video-analysis.js"
 
 const slot: EntitySlot = { slotId: "hero", label: "Protagonist", source: "wired-character", role: "person", description: "tan man, mustache, black tee" }
@@ -148,6 +149,73 @@ describe("binding rewrite helpers (merge consumes — spec §4)", () => {
   })
 })
 
+describe("speech attribution (speakerSlot)", () => {
+  const speech = (content: string, over: Partial<AudioLayer> = {}): AudioLayer => ({ mode: "speech", content, ...over })
+
+  it("rides on speech layers and survives a window round-trip", () => {
+    const parsed = windowAnalysisSchema.parse({
+      slots: [slot],
+      scenes: [{ ...baseScene, audio: [speech("As a kid…", { voice: "male, warm", speakerSlot: "hero" })] }],
+    })
+    expect(parsed.scenes[0]!.audio[0]!.speakerSlot).toBe("hero")
+  })
+
+  it("is NOT refined against mode — a mis-tagged music layer must not fail the whole roll", () => {
+    // The window schema IS the enforced decode grammar. Rejecting here would
+    // throw away every scene in a window over one stray field; the sanitizer
+    // below strips it instead.
+    expect(windowAnalysisSchema.safeParse({
+      slots: [slot],
+      scenes: [{ ...baseScene, audio: [{ mode: "music", content: "synth bed", speakerSlot: "hero" }] }],
+    }).success).toBe(true)
+  })
+
+  it("rewriteSpeakerSlots follows a slot through cross-window unification", () => {
+    // Slot unification renames the loser id and rewrites {slot:…} tokens and
+    // variation bindings; attribution has to move with them or it dangles.
+    const audio = [speech("hi", { speakerSlot: "man-2" }), speech("ho", { speakerSlot: "other" })]
+    expect(rewriteSpeakerSlots(audio, { "man-2": "hero" }).map((a) => a.speakerSlot)).toEqual(["hero", "other"])
+  })
+
+  it("rewriteSpeakerSlots is copy-on-write when no layer names a renamed slot", () => {
+    const audio = [speech("hi", { speakerSlot: "hero" }), { mode: "music" as const, content: "bed" }]
+    expect(rewriteSpeakerSlots(audio, { ghost: "other" })).toBe(audio)
+  })
+
+  it("dropUnknownSpeakers strips attribution to a slot that no longer exists", () => {
+    const r = dropUnknownSpeakers([speech("hi", { speakerSlot: "ghost" })], new Set(["hero"]))
+    expect(r.audio[0]).not.toHaveProperty("speakerSlot")
+    expect(r.dropped).toEqual(["ghost"])
+  })
+
+  it("dropUnknownSpeakers strips attribution from music/sfx — nobody is speaking", () => {
+    const r = dropUnknownSpeakers(
+      [{ mode: "sfx", content: "door slam", speakerSlot: "hero" }],
+      new Set(["hero"]),
+    )
+    expect(r.audio[0]).not.toHaveProperty("speakerSlot")
+    expect(r.dropped).toEqual(["hero"])
+  })
+
+  it("dropUnknownSpeakers keeps a valid speaker and every other layer field", () => {
+    const audio = [speech("As a kid…", { voice: "male, warm", speakerSlot: "hero" })]
+    const r = dropUnknownSpeakers(audio, new Set(["hero"]))
+    expect(r.audio).toBe(audio)          // copy-on-write: untouched input returned as-is
+    expect(r.dropped).toEqual([])
+  })
+
+  it("attribution alone must NOT keep a slot alive — that is the phantom narrator", () => {
+    // A slot referenced only as a speaker is a voice with no body (doctrine §5).
+    // deriveSlotRefs reads {slot:…} tokens from `visual` ONLY, so an
+    // attribution-only slot stays invisible to the reference sweep and gets
+    // dropped — then dropUnknownSpeakers removes the dangling attribution.
+    expect(deriveSlotRefs("a lunar plain, no one in frame")).toEqual([])
+    const r = dropUnknownSpeakers([speech("that's me!", { speakerSlot: "creator" })], new Set())
+    expect(r.audio[0]).not.toHaveProperty("speakerSlot")
+    expect(r.dropped).toEqual(["creator"])
+  })
+})
+
 describe("misc", () => {
   it("isOversizedScene flags > 8s only", () => {
     expect(isOversizedScene(0, 8)).toBe(false)

package/src/video-analysis.ts

@@ -78,6 +78,27 @@ const audioLayerSchema = z.object({
   mode: z.enum(["speech", "music", "sfx"]),
   content: z.string().min(1),
   voice: z.string().optional(),
+  /**
+   * SPEECH ONLY — `slotId` of the on-screen speaker saying these words.
+   *
+   * `voice` casts a voice ("male, proud triumphant shouting"); this says WHO it
+   * belongs to, so a recreation can route the line to the right character
+   * instead of guessing. Usually one person speaks per scene and the guess is
+   * right, which is exactly why the cases with two speakers over one cut fail
+   * silently without this field.
+   *
+   * Optional by design and deliberately NOT refined against `mode` here: the
+   * window schema is the enforced decode grammar, and rejecting a whole roll
+   * because the model tagged a music layer would be a hair-trigger failure. A
+   * speaker on a non-speech layer, or one naming a slot that no longer exists,
+   * is stripped structurally by `dropUnknownSpeakers` — the same
+   * unwrap/drop/sweep philosophy the slot-token and binding channels use.
+   *
+   * An unseen narrator gets NO speaker: a voice with no body is never a slot
+   * (doctrine §5), so attribution here would resurrect the phantom-entity
+   * defect that `stripOrphanSlots` exists to kill.
+   */
+  speakerSlot: z.string().optional(),
 })
 export type AudioLayer = z.infer<typeof audioLayerSchema>
 
@@ -202,6 +223,50 @@ export function dropUnknownBindings(
   return { kept: Object.keys(kept).length > 0 ? kept : undefined, dropped }
 }
 
+/**
+ * Rewrite speech attribution after cross-window slot unification — the
+ * `rewriteSceneBindings` counterpart for the `audio` channel. Slot unification
+ * renames a loser id to its survivor and rewrites `{slot:…}` tokens and
+ * variation bindings; an un-rewritten `speakerSlot` would be left pointing at an
+ * id that no longer exists. Copy-on-write: returns the input array untouched
+ * when no layer names a renamed slot.
+ */
+export function rewriteSpeakerSlots(audio: AudioLayer[], slotRenames: Record<string, string>): AudioLayer[] {
+  if (!audio.some((a) => a.speakerSlot !== undefined && slotRenames[a.speakerSlot])) return audio
+  return audio.map((a) => {
+    const to = a.speakerSlot !== undefined ? slotRenames[a.speakerSlot] : undefined
+    return to ? { ...a, speakerSlot: to } : a
+  })
+}
+
+/**
+ * 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` naming a slot that is not in the final list
+ *
+ * MUST run AFTER the orphan-slot sweep, and attribution must NEVER count as a
+ * slot reference for that sweep: a slot reachable only as a speaker is a voice
+ * with no body — precisely the invented-narrator entity doctrine §5 forbids. The
+ * two passes compose to remove both the phantom slot and the dangling
+ * attribution pointing at it.
+ */
+export function dropUnknownSpeakers(
+  audio: AudioLayer[],
+  validSlotIds: Set<string>,
+): { audio: AudioLayer[]; dropped: string[] } {
+  const dropped: string[] = []
+  const out = audio.map((a) => {
+    if (a.speakerSlot === undefined) return a
+    if (a.mode === "speech" && validSlotIds.has(a.speakerSlot)) return a
+    dropped.push(a.speakerSlot)
+    const { speakerSlot: _drop, ...rest } = a
+    return rest
+  })
+  return { audio: dropped.length > 0 ? out : audio, dropped }
+}
+
 /** Substitute {slot:x}: castMap binding wins, else the slot's description, else literal id. */
 export function renderAnalyzedScene(scene: { visual: string }, slots: EntitySlot[], castMap?: Record<string, string>): string {
   const byId = new Map(slots.map((s) => [s.slotId, s]))