> 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-session02-enemy-audio-metadata/spec.md).

# Session Specification

**Session ID**: `phase36-session02-enemy-audio-metadata` **Phase**: 36 - AI Rogue Audio Asset Finishing **Status**: Not Started **Created**: 2026-06-28

***

## 1. Session Overview

This session adds typed runtime metadata for enemy-family audio routing in AI Rogue. It does not generate new audio assets. The purpose is to make enemy attack, hit, defeated, sentry, and boss events carry stable information that the presentation-layer audio adapter can consume in Session 03 when new enemy and boss SFX are added.

This is next because Phase 36 Session 01 is complete and explicitly recorded that Session 02/03 should add typed enemy-family audio metadata before generating family and boss cue identities. The current `dispatchEventSound()` path already honors explicit `event.audioCues`, but several fallback paths still infer audio intent from broad event types or message text.

The product surface remains AI Rogue gameplay, but this session should not add or change visible UI. Diagnostics belong in tests and implementation notes. The runtime boundary stays one-way: simulation events may expose typed metadata, but audio selection remains presentation behavior and must not alter decisions, RNG, replay behavior, save contracts, hosted runtime behavior, or public-demo boundaries.

***

## 2. Objectives

1. Define an additive typed audio metadata contract for simulation events that can describe player, enemy, sentry, boss, target, and audio intent facts.
2. Emit metadata from enemy-family attack, threat, defeat, and boss-related runtime event paths without changing simulation outcomes or RNG order.
3. Update fallback audio dispatch to prefer typed metadata after explicit `audioCues` and before legacy message checks.
4. Add focused tests proving stable cue dispatch, metadata propagation, and unchanged deterministic simulation behavior.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase36-session01-current-audio-balance-audit` - Provides the current browser audio baseline, routing follow-ups, and the explicit instruction to add typed enemy-family audio metadata before enemy/boss asset work.
* [x] `phase35-session10-final-release-gate` - Provides the current AI Rogue Production Go posture, release gate evidence, asset policy, and no-open security/GDPR baseline.

### Required Tools Or Knowledge

* Bun 1.3.14 project scripts from `package.json`.
* TypeScript runtime contracts under `src/extensions/ai-rogue/runtime/`.
* Existing AI Rogue audio engine, event, combat, enemy, and simulation tests.
* Understanding that explicit `event.audioCues` must keep precedence over fallback dispatch.

### Environment Requirements

* Run from the repository root.
* Do not generate, download, or commit new audio files in this session.
* Keep all generated session artifacts ASCII-only with Unix LF line endings.
* Preserve existing public-demo, no-remote-loading, hosted-write, collector, analytics, and browser-local-state boundaries.

***

## 4. Scope

### In Scope (MVP)

* AI Rogue runtime events can carry optional typed audio metadata for actor kind, target kind, enemy kind, target enemy kind, and narrow audio intent where these facts already exist in runtime state.
* Enemy melee attacks, shielded enemy hits, player hits on enemies, enemy defeats, sentry telegraphs, sentry fires, and kernel-sentinel boss events include stable metadata for later family-specific cue selection.
* The audio engine dispatch path keeps explicit `audioCues` as the first priority, then uses typed metadata for existing safe cue IDs, then falls back to legacy message checks for older/simple events.
* Tests prove equivalent events dispatch stable cue IDs and that metadata does not affect deterministic simulation state, RNG consumption, replay behavior, or save/load compatibility.

### Out Of Scope (Deferred)

* Generating or committing enemy-family and boss SFX files - Reason: `phase36-session03-enemy-and-boss-sfx-pack` owns media generation, optimization, provenance, and final new cue wiring.
* Adding new SFX asset files or provenance entries - Reason: this metadata session should leave committed media unchanged.
* Theme music, ambience, or adaptive stinger routing - Reason: Sessions 04-07 own theme and adaptive audio contracts and assets.
* Changing AI Rogue UI copy or adding debug surfaces - Reason: routing metadata should be proven through runtime tests and implementation notes.
* Making audio routing part of deterministic game rules - Reason: the phase PRD requires audio selection to stay presentation-only.

***

## 5. Technical Approach

### Architecture

Add optional metadata to `AiRogueSimulationEvent` in `src/extensions/ai-rogue/runtime/types-simulation.ts`. The metadata should use existing domain types from `types-entities.ts` and should remain additive so older saved events and tests without metadata continue to work.

Extend `createAiRogueEvent()` in `src/extensions/ai-rogue/runtime/combat.ts` to copy metadata from event details. Then emit metadata at the points that already have typed actor and enemy state: `resolvePlayerAttack()`, `resolveEnemyAttack()`, `createRangedThreatEvent()`, and manual combat paths in `src/extensions/ai-rogue/runtime/simulation.ts` that construct attack or defeat events directly.

Update `dispatchEventSound()` in `src/extensions/ai-rogue/runtime/audio.ts` so explicit `event.audioCues` still win. Metadata-based fallback should then select existing cue IDs such as `enemy_melee`, `shield_absorb`, `shield_break`, `telegraph`, `hit`, and `enemy_defeated`, while leaving Session 03 free to add family-specific cue IDs after assets exist. Legacy message checks should remain as recovery behavior for events that have no metadata.

### Design Patterns

* Additive event contract: Optional fields preserve compatibility with older events and tests.
* Presentation-only dispatch: Metadata informs audio selection without feeding back into simulation rules.
* Explicit-cue precedence: Authored high-value cue lists stay authoritative.
* Deterministic variant seed: Equivalent events keep stable cue variants by hashing event IDs, not by consuming simulation RNG.

***

## 6. Deliverables

### Files To Create

| File                                                                                | Purpose                                                                              | Est. Lines |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------- |
| `.spec_system/specs/phase36-session02-enemy-audio-metadata/implementation-notes.md` | Record metadata coverage decisions, test evidence, and any Session 03 handoff notes. | \~180      |

### Files To Modify

| File                                                                 | Changes                                                                                         | Est. Lines |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------- |
| `src/extensions/ai-rogue/runtime/types-simulation.ts`                | Add optional typed audio metadata to `AiRogueSimulationEvent`.                                  | \~35       |
| `src/extensions/ai-rogue/runtime/combat.ts`                          | Copy metadata through `createAiRogueEvent()` and emit it from attack, defeat, and threat paths. | \~90       |
| `src/extensions/ai-rogue/runtime/simulation.ts`                      | Add metadata to direct attack/defeat events not covered by combat helpers.                      | \~70       |
| `src/extensions/ai-rogue/runtime/audio.ts`                           | Prefer typed metadata in fallback dispatch while preserving explicit cue precedence.            | \~80       |
| `src/extensions/ai-rogue/runtime/__tests__/audio.test.ts`            | Add tests for metadata-driven dispatch, explicit cue precedence, and legacy fallback recovery.  | \~120      |
| `src/extensions/ai-rogue/runtime/__tests__/combat.test.ts`           | Add tests for attack, defeat, sentry, and boss metadata emission.                               | \~120      |
| `src/extensions/ai-rogue/runtime/__tests__/simulation.test.ts`       | Add or update tests proving metadata does not change deterministic run outcomes.                | \~80       |
| `.spec_system/specs/phase36-session02-enemy-audio-metadata/tasks.md` | Mark implementation progress and command evidence during the session.                           | \~30       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Enemy-family attack, hit, defeat, sentry, and boss events carry typed metadata through real runtime event paths.
* [ ] Explicit `event.audioCues` still dispatch before metadata or message fallback logic.
* [ ] Equivalent metadata-bearing events dispatch stable cue IDs and deterministic variants.
* [ ] Legacy events without metadata still recover through safe existing fallback behavior.

### Testing Requirements

* [ ] Focused audio dispatch tests written and passing.
* [ ] Combat metadata tests written and passing.
* [ ] Simulation determinism or regression tests written and passing.
* [ ] Verification scenarios completed.

### Non-Functional Requirements

* [ ] No new audio assets, provenance entries, remote loading, hosted writes, collectors, analytics, or public-demo bridge calls are introduced.
* [ ] Audio metadata remains optional and additive for older saved events.
* [ ] Audio routing does not affect simulation decisions, RNG consumption, replay behavior, save contracts, or browser-local state transitions.
* [ ] The Session 03 handoff states which metadata fields are ready for enemy-family and boss SFX cue mapping.

### Quality Gates

* [ ] All 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

* Optional event metadata is the safest contract shape: repo evidence shows `AiRogueSimulationEvent` is part of run state and existing tests construct events without metadata. Making the fields optional allows older saved events, fixtures, and direct unit-test events to remain valid while adding typed facts for new runtime paths.
* Session 02 should not add new SFX cue IDs yet: Session 03 owns generated enemy and boss assets, provenance, and final cue mapping. Planning can proceed because Session 02 can route metadata to existing cue IDs and prove the dispatch priority order before new assets exist.
* Combat helper paths cover most enemy-family events: `resolvePlayerAttack()`, `resolveEnemyAttack()`, and `createRangedThreatEvent()` already receive typed enemy/player state. Direct attack and defeat events in `simulation.ts` can be handled with narrow edits where the source enemy is in scope.

### Key Considerations

* Preserve explicit `audioCues` precedence.
* Keep metadata as facts about already-computed runtime events, not inputs to gameplay decisions.
* Avoid widening Phase 36 boundaries: no hosted runtime, public-demo, privacy, remote-loading, collector, analytics, or media-generation work belongs here.
* Leave a clean Session 03 handoff for new family-specific cue IDs and assets.

### Potential Challenges

* Event logs are persisted in run state: keep metadata optional and avoid requiring migration for older saved events.
* Some attack/defeat events are constructed outside shared combat helpers: cover direct construction paths with targeted simulation tests.
* Message fallback behavior may still be needed for manually constructed tests: keep it as recovery after metadata handling.

### Relevant Considerations

* \[P34-P35] **AI Rogue is production default-enabled**: Preserve Production Go posture and the explicit `none` disable path.
* \[P35] **AI Rogue compatibility exports remain**: Keep runtime type changes additive and compatible with existing direct consumers.
* \[P31-P35] **Public-demo and AI Rogue gates stay bundled**: Do not introduce bridge calls, hosted writes, remote loading, collectors, analytics, or private-runtime exposure while touching runtime code.
* \[P30/P32/P34-P35] **Route-lazy runtime ownership scales**: Keep Pixi and audio runtime behavior behind the Play route/local facade and narrow runtime boundary.
* \[P30/P34-P35] **Schema-backed browser-local state works**: Treat saved-run compatibility as a required constraint when event shape changes.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Event shape drift could break older saved runs or direct tests that construct events without metadata.
* Audio metadata could accidentally become an input to simulation behavior if it is read outside presentation dispatch.
* Dispatch priority regressions could cause explicit high-value cues to be ignored or duplicate-played.

***

## 9. Testing Strategy

### Unit Tests

* `src/extensions/ai-rogue/runtime/__tests__/audio.test.ts`: verify explicit cues win, metadata dispatch chooses existing safe cue IDs, legacy message fallback still works, and equivalent events choose stable variants.
* `src/extensions/ai-rogue/runtime/__tests__/combat.test.ts`: verify enemy attack, player attack, defeat, sentry telegraph, shield, and boss events carry expected metadata.

### Integration Tests

* `src/extensions/ai-rogue/runtime/__tests__/simulation.test.ts`: verify representative runs produce the same deterministic gameplay outcome while carrying metadata on enemy-family events.
* Run focused adjacent AI Rogue runtime tests if touched paths require them, especially `shield-buffer.test.ts`, `thief.test.ts`, `protocols.test.ts`, and `runtime-boundary.test.ts`.

### Runtime Verification

* Use focused tests and implementation notes for verification. No visible UI route change is expected in this metadata-only session.

### Edge Cases

* Events with explicit `audioCues` and metadata.
* Events with metadata but no explicit `audioCues`.
* Legacy events without metadata.
* Shield absorb and shield break events.
* Sentry telegraph and sentry fire events.
* Kernel-sentinel boss attacks and defeats.
* Saved or fixture events that omit new optional metadata.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase36-session01-current-audio-balance-audit`
* Depended by: `phase36-session03-enemy-and-boss-sfx-pack`

***

## 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-session02-enemy-audio-metadata/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.