feat(director): a coda — the beat that knows the song happened [spec 04]

[wine-fall]

Second of two. PR #199 fixed the way into a song; this is the way out.

Stacked on #199 — it branches from zachg-0903--ducking-into-song, not main, because #199 was still awaiting merge. Merge #199 first and this PR's diff collapses to its own commit.

Why the post-song beat could never mention the song

Spec 04's look-ahead already removed the music→talk dead air — the beat after a song airs warm off the buffer. It could not make that beat about the song, and the reason is structural: the buffer is held at depth N and topped up after every consumed beat, so by the time a track starts the buffer is already full and the refill fired at the song's start is a no-op. Every post-song beat is therefore written before the song exists. And GROUNDING_RULES (correctly) forbade it to say anything that turns false when the music ends — so its only safe move was to pretend the song had not happened.

Song stops. Silence. Talk comes in cold, from somewhere else.

The coda

One beat per track that knows the track happened. Generated at the song's start, once the stream is confirmed audible and the announce is recorded, so its context carries the song and its intro. One extra nextTalks(1) per song — that is the whole added cost.

Cued coda, and the cue gives permission, not an assignment: answer the song, say why it followed the stretch of talk before it, or say nothing about it and simply carry on. Introducing or reviewing the track is explicitly not the job — a beat that had to review every song would be the "up next" formula again, wearing the other end. MUSIC_OUTLASTS_RULE ("say nothing that turns false when the music above ends") is split out of GROUNDING_RULES and omitted for this one cue; every other red line still stands.

Its own slot, not talkAhead — the depth-N invariant and its refill arithmetic are untouched. The slot holds a beat that can go on air this instant, never a promise: it is filled only once synthesis has come back with a real clip, so neither exit can make a boundary wait on TTS, and a coda whose synthesis failed simply does not exist (the ready buffered beat airs instead).

Two ways out.

1. Riding the outro — when the track's length is known, with probability CODA_RIDE_P = 0.5, the coda goes out 8-12 s before the end (uniform), racing the song's completion inside runVoice. The engine ducks the tail under it exactly as it ducks the head under an announce, so the radio talks over the fade instead of waiting for silence. Aired like a reply, not like a segment: recorded and printed, but no emitState('talk') — the track is still playing and the front-end must keep naming it.
2. The head of the queue — otherwise (length unknown, coin missed, track shorter than the lead, no coda ready) the song ends and the coda is unshifted to the front of talkAhead. The buffer momentarily holds N + 1; prefetchTalk's >= tolerates that and simply does not refill until it drains.

Chance is injected. DirectorDeps.random (default Math.random) is the only entry point for the coin and the lead, so both are pinned in tests. A talkback steer discards the coda with the rest of the look-ahead; a new track clears the slot; nothing re-fires a coda after a reply (a reply already speaks to the song it is ducked over — deliberate omission, noted in the spec).

Tests

• director-music.test.ts — generated at the song's start with cue coda and the announce in its context; airs at the head of the queue when the song ends; rides the outro with an injected random (and keeps the front-end on music while it does); falls back to the post-song head when the length is unknown and when the coin misses; a typed line discards it; each track gets its own; and it never reaches the boundary unless it is ready to play.
• prompts.test.ts — the coda prompt carries its cue text and not MUSIC_OUTLASTS_RULE, while every other prompt still does, on both the batched and the single-beat path.
• The four look-ahead tests that assert the exact post-song sequence were updated, not weakened: they now pin the coda and the beat buffered behind it (['talk one', 'the coda', 'talk two']), which is a stronger statement about the boundary than before.

pnpm test 1301 passed, pnpm run typecheck clean, oxlint clean.

Peer review (codex gpt-5.6-sol, xhigh): 4 findings, 4 applied, 0 dismissed — a coda handed to the queue as an unsettled promise could block the boundary it exists to smooth (P1); the coda's context was given the queued-but-unaired beats it airs ahead of; prefetchCoda bumped the epoch without clearing the slot; and FIND_MUSIC_CONTRACT restated the announce wording instead of rendering the shared ANNOUNCE_FIELD_DESCRIPTION (#199's own "one text, not two" claim, now actually true — asserted by string identity).

Not verified here: the coda's tone, whether the outro ride lands as talking-over-a-fade, and whether a 50/50 mix of the two exits reads as variety. Appended to the checklist on #198.

Implements specs/spec04/04-no-dead-air.md §3.3-C (constants beside the ducking knobs in specs/spec03/03-02-ducking.md §6.1).

AI coding brief

Original request — 把 talk↔music 两个过场做顺（ducking 听感）, second half: the way out of a song. Design settled with the user before the build, including the coda's own slot, the two exits, the ride probability and lead range, and the decision to tag spec 04 rather than open a new spec.

Manual interventions — none during the build. Two designer's calls were taken mid-build against the letter of the brief, both from review evidence: the coda's context does not carry the queued look-ahead beats (the brief said it should, but the coda airs ahead of them), and the slot holds a resolved clip rather than a pending one (so the "never block the air" rule cannot be violated by a slow TTS).

Retro — same lesson as #199, one level up: the findings were all about when a value exists, not what it says — a promise stored where a value was assumed, an epoch bumped without clearing what it guards, context assembled for one ordering and consumed in another. A brief that says "for every slot you add, state what is in it at each of: fired, resolved, consumed, discarded, and replaced" would have caught three of the four before the review round.

🤖 Generated with Claude Code

https://claude.ai/code/session_011L93sAUxB3SMTzMRFscUy3