> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase36-session06-adaptive-music-engine-expansion/spec.md).

# Session Specification

**Session ID**: `phase36-session06-adaptive-music-engine-expansion` **Phase**: 36 - AI Rogue Audio Asset Finishing **Status**: Not Started **Created**: 2026-06-28

***

## 1. Session Overview

This session adds the minimal adaptive-audio runtime contract needed before dedicated stinger assets are generated. It introduces an explicit adaptive request path for combat start, low HP pressure, boss reveal, objective unlock, final defense, victory transition, and defeat transition, then routes those requests through the existing Web Audio graph with cooldowns and transient music/ambience ducking.

This is next because Phase 36 Sessions 01 through 05 completed the baseline audio review, enemy metadata, enemy/boss SFX pack, theme ambience contract, and theme ambience assets. Session 06 can now focus on engine behavior and request semantics without changing the asset pack or replacing the existing title, depth, victory, defeat, SFX, heartbeat, or theme ambience behavior.

The product outcome is AI Rogue gameplay that can safely support adaptive stingers in Session 07. The shipped Session 06 behavior must stay subtle, recoverable, and presentation-only: no simulation RNG changes, no save schema changes, no remote game content, and no diagnostic UI in the normal gameplay surface.

***

## 2. Objectives

1. Define a typed adaptive-audio request contract for the seven high-value gameplay moments routed to Session 06.
2. Add transient gain automation and duplicate-trigger protection around the existing music, ambience, SFX, and heartbeat lanes.
3. Wire adaptive requests from existing renderer result events and snapshot transitions without changing deterministic simulation state.
4. Prove fallback, mute, volume, cooldown, terminal transition, browser, and documentation behavior with focused tests and review notes.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase36-session01-current-audio-balance-audit` - Provides baseline browser evidence for unlock, title queueing, sector music, SFX, mute, volume, mobile behavior, silent fallback, and manual follow-ups.
* [x] `phase36-session02-enemy-audio-metadata` - Provides the typed audio metadata precedent and keeps sound routing presentation-only.
* [x] `phase36-session03-enemy-and-boss-sfx-pack` - Provides enemy and boss cue identities that adaptive boss reveal can reuse before Session 07 adds dedicated stinger assets.
* [x] `phase36-session04-theme-audio-routing-contract` - Provides the second low-gain theme ambience lane and the rule that ambience sits beside the depth music lane.
* [x] `phase36-session05-sector-theme-audio-pack` - Provides committed theme ambience assets, browser proof, provenance, and fallback coverage.
* [x] `phase35-session10-final-release-gate` - Provides production-default, public-demo, privacy, no-remote, asset, and quality-gate constraints.

### Required Tools Or Knowledge

* Bun 1.3.14 project scripts.
* Existing Web Audio engine behavior in `src/extensions/ai-rogue/runtime/audio.ts`.
* Renderer adapter behavior in `src/extensions/ai-rogue/runtime/renderer-audio-adapter.ts`.
* Existing simulation event and snapshot contracts under `src/extensions/ai-rogue/runtime/types-simulation.ts`.
* Existing browser proof in `tests/e2e/ai-rogue-runtime.spec.ts`.
* AI Rogue game-feel docs in `docs/extensions/ai-rogue/game-feel.md`.

### Environment Requirements

* Run from the repository root.
* Do not add new audio assets in this session.
* Keep text artifacts ASCII-only with Unix LF line endings.
* Preserve the current local-only, browser-local, no-remote game-content boundary.

***

## 4. Scope

### In Scope (MVP)

* AI Rogue runtime exposes a typed adaptive-audio request method for `combat_start`, `low_hp`, `boss_reveal`, `objective_unlock`, `final_defense`, `victory_transition`, and `defeat_transition`.
* Adaptive requests apply bounded cooldowns so repeated triggers cannot stack clutter or volume spikes.
* Adaptive requests can transiently reduce the primary music and theme ambience lanes while preserving master mute, music volume, SFX volume, autoplay unlock, lazy decode, and silent fallback.
* Renderer audio adapter derives adaptive requests from existing typed events, explicit audio cues, snapshot status, player health, boss visibility, and terminal win/loss transitions.
* Session 06 uses existing cue IDs as provisional audible markers only when needed for real-path proof; dedicated stinger assets remain Session 07.
* Focused unit and adapter tests cover bus interaction, cooldown, fallback, mute, volume, event dispatch, duplicate prevention, and terminal transitions.
* Browser proof confirms the adaptive path runs through the real AI Rogue runtime without adding product-facing debug UI.
* Docs explain the new ducking/gain automation contract and identify dedicated stinger assets as Session 07 scope.

### Out Of Scope (Deferred)

* Bulk stinger asset generation - Reason: Session 07 owns generated adaptive stinger assets after this contract exists.
* Replacing existing music crossfades, title loop, depth music, theme ambience, heartbeat loop, one-shots, mute, volume preferences, autoplay unlock, or silent fallback - Reason: Session 06 extends the engine around existing behavior instead of replacing it.
* Adding a new Settings UI or saved preference field for adaptive audio - Reason: MVP inherits existing mute, music volume, and SFX volume controls.
* Simulation, RNG, save schema, IndexedDB/localStorage migration, scoring, economy, enemy balance, or run-generation changes - Reason: adaptive audio is presentation-only.
* Remote game-content loading, hosted writes, collectors, analytics, public demo bridge calls, workers, WebGPU-specific behavior, or third-party runtime dependencies - Reason: Phase 36 keeps AI Rogue's current safety boundary.
* Visual asset finishing - Reason: Phase 37 owns visual asset work.

***

## 5. Technical Approach

### Architecture

Extend `AiRogueAudioEngine` with an adaptive request API rather than adding a parallel audio system. The engine already owns master, music, theme ambience, and SFX gain nodes, so transient ducking should live next to `applyMixLevels()` and operate on the existing music-related gains. The ducking implementation must be bounded, cancelable, and safe when context creation, fetch, decode, or autoplay unlock fails.

Route adaptive requests from `renderer-audio-adapter.ts`, where simulation results, previous snapshot context, and renderer state already meet. This keeps presentation routing out of deterministic simulation modules. Existing events and cues are sufficient for MVP detection: run-started for combat start, health ratio for low HP pressure, boss enemy visibility for boss reveal, `objective_unlock` cue for objective unlock, `compile_payload` or `final_defense_survived` for final defense, and snapshot status changes for victory and defeat transitions.

Use existing SFX cue IDs as provisional audible markers only where they prove the request path. Session 07 can add dedicated assets behind the same request IDs without changing simulation semantics.

### Design Patterns

* Adapter-owned derivation: Renderer adapter converts existing state/events into audio requests; simulation stays deterministic and presentation-agnostic.
* Minimal engine extension: Add one request path and bounded gain automation rather than a new mixer or dependency.
* Cooldown-first stingers: Every adaptive moment has a stable request key and cooldown to prevent duplicate-trigger clutter.
* Existing-cue fallback: Current cue IDs prove routing until dedicated Session 07 assets exist.
* Silent-safe behavior: Missing Web Audio, missing URLs, failed fetches, failed decodes, locked autoplay, and disposal remain no-throw paths.

***

## 6. Deliverables

### Files To Create

| File                                                                                           | Purpose                                                       | Est. Lines |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------- |
| `.spec_system/specs/phase36-session06-adaptive-music-engine-expansion/implementation-notes.md` | Record implementation choices, review evidence, and commands. | \~180      |

### Files To Modify

| File                                                                            | Changes                                                                                  | Est. Lines |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------- |
| `src/extensions/ai-rogue/runtime/audio.ts`                                      | Add adaptive request types, engine method, cooldown tracking, ducking, and fallback map. | \~160      |
| `src/extensions/ai-rogue/runtime/renderer-audio-adapter.ts`                     | Derive and dispatch adaptive requests from events, health, boss reveal, and status.      | \~140      |
| `src/extensions/ai-rogue/runtime/__tests__/audio.test.ts`                       | Cover request dispatch, ducking, cooldown, mute/volume, fallback, and dispose behavior.  | \~170      |
| `src/extensions/ai-rogue/runtime/__tests__/renderer-audio-adapter.test.ts`      | Cover adapter derivation for all seven adaptive moments and duplicate prevention.        | \~170      |
| `tests/e2e/ai-rogue-runtime.spec.ts`                                            | Extend browser proof for adaptive requests, failed requests, silent fallback, and UI.    | \~80       |
| `docs/extensions/ai-rogue/game-feel.md`                                         | Document the implemented adaptive ducking/request contract and Session 07 handoff.       | \~70       |
| `docs/extensions/ai-rogue/README.md`                                            | Update current audio summary now that event-based ducking exists.                        | \~20       |
| `.spec_system/PRD/phase_36/session_06_adaptive_music_engine_expansion.md`       | Record final contract decisions, validation evidence, and remaining stinger scope.       | \~50       |
| `.spec_system/specs/phase36-session06-adaptive-music-engine-expansion/tasks.md` | Track implementation progress during the session.                                        | \~80       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Adaptive request IDs exist for combat start, low HP, boss reveal, objective unlock, final defense, victory transition, and defeat transition.
* [ ] Adaptive requests apply bounded cooldowns and cannot stack duplicate music/ambience ducking or one-shot playback during repeated triggers.
* [ ] Transient ducking affects the primary music and theme ambience lanes while preserving master mute, music volume, SFX volume, autoplay unlock, lazy decode, and silent fallback behavior.
* [ ] Renderer adapter derives requests from real runtime events and snapshot transitions without changing simulation state, RNG, replay, or save data.
* [ ] Existing music crossfades, theme ambience, heartbeat loop, one-shots, victory/defeat music, mute, volume, and no-Web-Audio silent fallback still work.
* [ ] Product outcome is proven end to end: adaptive requests execute through real runtime paths, failures recover through existing fallback behavior, and browser review confirms gameplay UI stays product-facing.

### Testing Requirements

* [ ] Focused audio engine tests pass.
* [ ] Focused renderer audio adapter tests pass.
* [ ] Focused combat/protocol or simulation tests pass if event derivation touches those fixtures.
* [ ] Desktop and mobile browser audio proof passes or records concrete non-product blockers.
* [ ] Manual browser review records repeated-trigger behavior, volume interaction, low HP pressure, boss reveal, terminal transitions, and silent fallback.

### Non-Functional Requirements

* [ ] No new audio assets, dependency, lockfile, DB, migration, or persisted browser-state schema change is introduced.
* [ ] No remote game-content loading, hosted write, collector, analytics, public-demo bridge call, worker, WebGPU-only requirement, or third-party runtime dependency is added.
* [ ] Adaptive audio remains presentation-only and does not affect simulation decisions, RNG consumption, replay behavior, save contracts, or gameplay balance.
* [ ] Documentation describes current implemented behavior and keeps generated dedicated stinger assets scoped to Session 07.

### Quality Gates

* [ ] All touched text files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Primary user-facing surfaces contain product-facing copy only.

***

## 8. Implementation Notes

### Working Assumptions

* Dedicated adaptive stinger assets are deferred, but the runtime contract should still ship now: the Session 06 stub explicitly owns engine support and Session 07 explicitly owns generated stingers. Planning can proceed by using existing cue IDs as provisional audible markers for proof.
* The current theme ambience lane is enough for MVP ducking: Session 05 added a second low-gain music-related bus, so Session 06 can implement transient gain automation without creating another long-lived bus.
* Adaptive request derivation belongs in `renderer-audio-adapter.ts`: that file already receives command results, state, previous theme, music resolver, and ambience resolver, so it can detect presentation moments without mutating simulation state or event producers.

### Conflict Resolutions

* Phase PRD wording says `audio.ts` supports one active music track and heartbeat loop, while current source now also supports theme ambience. The source and Session 05 validation win because they are newer and prove a committed second music-related lane.
* Docs currently say no event-based ducking is implemented. That remains true before Session 06 implementation, but the planned deliverables must update docs after code lands so they no longer describe planned behavior as absent.

### Key Considerations

* Keep AI Rogue production default-enabled and preserve `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=none` as the explicit opt-out.
* Keep public-demo and local runtime boundaries unchanged.
* Keep adaptive audio subtle because repeated stingers can clutter keyboard- heavy play.
* Preserve the Phase 35 caveat that bundle and asset headroom are tight; this session should not add media or dependencies.

### Potential Challenges

* Gain automation can conflict with normal music volume updates: implement ducking as a bounded overlay that recomputes base levels from current preferences and cancels scheduled values on new requests or preference updates.
* Boss reveal can retrigger every frame if derived naively: track request keys or previous visibility so the adapter only fires on the transition from not visible to visible.
* Low HP overlaps with the heartbeat loop: use the adaptive request for entry into low HP pressure and let the existing heartbeat loop own the sustained state.
* Terminal win/loss already plays music and SFX: ensure victory and defeat requests do not double-stack the current terminal music transition.

### Relevant Considerations

* \[P34-P35] **AI Rogue is production default-enabled**: Preserve Production Go posture and the explicit disable path.
* \[P31-P35] **Public-demo and AI Rogue gates stay bundled**: Keep asset-size, no-remote, privacy, no-bridge, browser, Pages, and playthrough checks bundled for final release validation.
* \[P30/P32/P34-P35] **Route-lazy runtime ownership scales**: Keep Pixi/audio behavior behind the Play route and narrow runtime boundary.
* \[P30/P34-P35] **Visibility gates catch real issues**: Pair focused audio tests with browser checks and release gates before widening behavior.
* \[P30/P32/P34-P35] **Do not widen AI Rogue capabilities without review**: Avoid collectors, WebGPU-only behavior, workers, remote loading, hosted writes, analytics, or expanded content.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Async audio decode, autoplay unlock, and disposal could leak sources or apply stale gain automation after scope exit.
* Repeated events could duplicate stingers or stack ducking into volume spikes.
* Presentation routing could accidentally affect deterministic simulation, replay, or saved browser-local state.

***

## 9. Testing Strategy

### Unit Tests

* `src/extensions/ai-rogue/runtime/__tests__/audio.test.ts`: request-to-cue mapping, cooldowns, ducking schedules, preference updates, mute behavior, missing Web Audio, decode/fetch failures, pending unlock, and disposal.
* `src/extensions/ai-rogue/runtime/__tests__/renderer-audio-adapter.test.ts`: all seven request derivations, no duplicate boss reveal, low HP entry only, terminal transition ordering, and no-op fallback when audio is null.

### Integration Tests

* Existing focused combat/protocol tests if any event fixture needs adjustment.
* `tests/e2e/ai-rogue-runtime.spec.ts` browser proof for adaptive runtime request execution, no page errors, no failed requests, and silent fallback.

### Runtime Verification

* Desktop browser review for normal start, combat entry, low HP, boss reveal, objective unlock, final defense, victory, defeat, mute, music volume, SFX volume, and repeated-trigger behavior.
* Mobile browser review for the same adaptive proof path where feasible, with no horizontal overflow or diagnostic UI regression.

### Edge Cases

* AudioContext unavailable or construction failure.
* Fetch or decode failure for a provisional cue.
* Request arrives before unlock.
* Request repeats within cooldown.
* Preferences change while a ducking envelope is active.
* Runtime is disposed before delayed decode or ducking recovery completes.
* Victory or defeat arrives while theme ambience and heartbeat are active.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase36-session01-current-audio-balance-audit`, `phase36-session02-enemy-audio-metadata`, `phase36-session03-enemy-and-boss-sfx-pack`, `phase36-session04-theme-audio-routing-contract`, `phase36-session05-sector-theme-audio-pack`, `phase35-session10-final-release-gate`
* Depended by: `phase36-session07-adaptive-stinger-pack`, `phase36-session08-final-audio-validation-and-docs`

***

## Next Steps

Run the `implement` workflow step to begin implementation.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/.spec_system/archive/sessions/phase36-session06-adaptive-music-engine-expansion/spec.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.