Track scoped NPC voice sessions and playback implementation lane

[JOY]

Purpose

Track the implementation and evidence lane for scoped NPC voice sessions, TTS playback, and future facial/viseme hooks after the text-first focused portrait slice is stable.

Background

Issue #262 closed the design/tracking baseline for the custom SECOND SPAWN voice and Ida Faber facial-animation lane. This successor issue tracks implementation and validation work that should remain separate from #139 text-first portrait and speaking animation.

Source Docs

• docs/design/82-alpha-npc-voice-and-facial-animation-lane.md
• docs/design/56-focused-npc-dialogue-portrait-lipsync-design.md
• docs/design/141-alpha-focused-npc-portrait-speaking-builder-brief.md
• docs/design/147-alpha-ida-faber-import-verification-builder-brief.md
• docs/design/148-open-design-decision-backlog.md
• docs/design/52-llm-role-play-provider-evaluation.md
• docs/playtests/_templates/npc-voice-session-playback/README.md

Scope

• Add or validate a Nakama/API path that mints short-lived, actor-scoped api.dos.ai voice session material without exposing provider keys to Unity.
• Add Unity NPC TTS playback only through scoped sessions.
• Keep OpenAI Realtime, ElevenLabs, Convai-style products, or self-hosted TTS as optional provider spikes behind api.dos.ai, not client dependencies.
• Preserve text-first dialogue fallback when voice is unavailable, too slow, too expensive, interrupted, or blocked.
• Prove text/audio parity: played audio, speaking state, and text line must map to the same accepted line_id, or be clearly labeled as fallback.
• Add future hooks for provider viseme data or Ida Faber blendshape profiles only after imported blendshape names are verified in Unity.
• Capture latency, cost, reliability, interruption, fallback, replay/stale-session behavior, and per-NPC voice identity evidence.

Acceptance Criteria

• Unity receives no provider API keys.
• Nakama or the approved server path mints scoped session or playback material.
• Session material is short-lived, actor-scoped, conversation-scoped, and redacted in evidence.
• Text-only fallback still works.
• Voice playback maps to the same accepted text line_id, or mismatch/fallback is labeled honestly.
• Replay, skip, interruption, failure, or stale playback does not create a new accepted dialogue turn.
• One playback path is demonstrated or honestly marked unavailable.
• Latency, cost, failure, interruption, and fallback behavior are recorded.
• Per-NPC voice_profile_id and voice identity result are recorded.
• Ida Faber facial mapping is blocked until real blendshape names are verified.

Out Of Scope

• Full voice for all NPCs in alpha.
• Provider API keys in Unity.
• Client-owned dialogue, quest, reward, TIME, SECOND, inventory, combat, or body mutations.
• Making any vendor SDK the durable NPC memory or dialogue backbone.
• Closing Track scoped NPC voice sessions and playback implementation lane #288 on a local OS speech fallback alone.

Evidence Expectations

• server-minted session or token flow evidence, redacted
• Unity playback screenshot or clip when implementation exists
• text-only fallback evidence
• text/voice parity evidence from text-voice-parity-note.md
• no provider key in client evidence
• latency and failure-mode notes
• verified blendshape-name report before any Ida Faber facial mapping is accepted

Refs #139, #251, #260, #262, #263.

[JOY]

Added the dedicated public-safe evidence template for #288.

Template:

• docs/playtests/_templates/alpha-scoped-npc-voice-session/README.md

Updated indexes/tracking:

• docs/playtests/_templates/README.md
• docs/playtests/README.md
• docs/SUMMARY.md
• docs/setup/alpha-open-issue-handoff-coverage.md
• docs/setup/github-project-tracking.md

Template covers:

• server-minted short-lived api.dos.ai voice session material
• Unity playback evidence
• text fallback and timeout evidence
• provider boundary and no-client-key checks
• latency and cost notes
• facial/viseme hooks and Ida Faber blendshape-name verification boundary

Validation run:

• tools/windows/check-backlog-sync.ps1 - OK, 74 issue refs resolved
• git diff --check -- docs ROADMAP.md - OK
• touched markdown local links - OK
• no Unicode dash matches in touched docs

[JOY]

Tracking cleanup update:

• docs/setup/github-project-tracking.md now points the voice/facial-animation lane at Track scoped NPC voice sessions and playback implementation lane #288 instead of the closed Track NPC voice session and custom Ida Faber facial-animation lane #262 predecessor.
• The Track scoped NPC voice sessions and playback implementation lane #288 row links the voice/facial source docs and the docs/playtests/_templates/alpha-scoped-npc-voice-session evidence template.
• Verified backlog sync, markdown links, and diff whitespace after the cleanup.

[JOY]

Evidence template update: docs/playtests/_templates/alpha-scoped-npc-voice-session now has concrete files for session minting, Unity playback, fallback/timeout behavior, latency/cost, provider boundary, facial hooks, security/privacy, and known gaps. This keeps #288 focused on scoped server-minted sessions and text-first fallback evidence instead of provider-specific assumptions.

[JOY]

Acceptance update: #288 now has an explicit row in docs/design/34-alpha-acceptance-matrix.md. Acceptance requires scoped server-minted voice sessions, no client provider keys, text-first fallback, provider boundary evidence, and no gameplay mutation from voice/provider output. Evidence target: docs/playtests/_templates/alpha-scoped-npc-voice-session/. This remains separate from #139 text-first focused dialogue acceptance.

[JOY]

Docs handoff update for #288:

Added docs/design/150-alpha-scoped-npc-voice-session-builder-brief.md as the implementation-facing brief for scoped NPC voice sessions and playback.

The new brief locks:

• scoped server-minted voice session flow through Nakama or api.dos.ai
• Unity playback boundaries and text-first fallback
• provider/API-key safety rules
• per-NPC voice identity expectations
• latency, cost, timeout, fallback, and security evidence
• Ida Faber/facial hook boundary: no accepted facial mapping before imported Unity blendshape names are verified
• explicit forbidden scope: no provider keys in Unity, no direct client provider calls, no provider-owned canonical memory, and no gameplay/economy/body mutation from voice output

Tracking updates:

• docs/SUMMARY.md now lists the builder brief.
• docs/design/03-systems-index.md now references it in the NPC dialogue UI lane.
• docs/setup/alpha-open-issue-handoff-coverage.md now routes Track scoped NPC voice sessions and playback implementation lane #288 to the builder brief.
• The scoped voice evidence template links back to the builder brief.

Verification:

• tools/windows/check-backlog-sync.ps1 OK
• builder brief contract coverage OK
• local markdown links OK for the touched docs
• all design docs listed in SUMMARY: 152
• all design docs referenced in systems index: 151
• open issue handoff coverage current: 35/35
• git diff --check OK for the touched docs
• no generated em/en dash characters found in the touched docs