> 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/phase39-session05-enemy-metadata-and-derived-asset-checks/spec.md).

# Session Specification

**Session ID**: `phase39-session05-enemy-metadata-and-derived-asset-checks` **Phase**: 39 - AI Rogue Level Authoring Infrastructure **Status**: Not Started **Created**: 2026-06-30

***

## 1. Session Overview

This session moves AI Rogue enemy audio and runtime frame requirements out of scattered manual branches and into typed metadata owned by the existing enemy catalog. Sessions 01 through 04 created the authored level registry, routed depth decisions through it, added validation and save parity, and proved the workflow with a reused-media fourth floor. The next executable step is to make enemy additions fail fast when audio families or required frames are missing.

The implementation should keep the current gameplay, save schema, renderer, and audio output behavior unchanged. Standard enemies gain metadata for their audio family and frame set, `audioFamilyForEnemyKind()` becomes a metadata lookup with a generic fallback, and tests prove every declared SFX, music, ambience, gameplay frame, and provenance record is present before runtime.

Kernel Sentinel only receives frame-set metadata in this session. The reusable boss behavior, finale routing, and hard-coded Kernel Sentinel branch removal remain Session 06 scope.

***

## 2. Objectives

1. Add typed enemy audio-family and frame-set metadata without changing saved run state or current combat behavior.
2. Route enemy audio cue selection through metadata instead of a switch on every standard enemy kind.
3. Derive gameplay frame requirements from content metadata and keep atlas validation actionable for missing frames.
4. Validate audio asset basename maps, imported Ogg URLs, music and ambience declarations, and provenance records through focused tests.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase39-session01-baseline-and-registry-skeleton` - Adds the initial content registry, lookup API, baseline tests, and pure validator.
* [x] `phase39-session02-depth-resolver-migration` - Routes depth helpers, world generation, run creation, and descent through authored level specs.
* [x] `phase39-session03-registry-validation-and-save-parity` - Adds active registry reference checks and save-schema ID parity gates.
* [x] `phase39-session04-existing-media-floor-four` - Adds the reused-media fourth floor and proves the authored workflow on existing IDs.

### Required Tools Or Knowledge

* Bun 1.3.14 package/runtime baseline.
* AI Rogue enemy templates in `src/extensions/ai-rogue/runtime/entities.ts`.
* Audio cue routing and asset maps in `src/extensions/ai-rogue/runtime/audio.ts`.
* Atlas frame validation in `src/extensions/ai-rogue/runtime/assets.ts`.
* Content validation in `src/extensions/ai-rogue/runtime/content/validate.ts`.
* Focused Vitest suites for audio, assets, content registry, combat, boss presentation, render model, and renderer audio adapter behavior.

### Environment Requirements

* Local repository checkout with dependencies installed or installable through `bun install`.
* Focused validation available through `bunx vitest run`.
* Type validation available through `bun run typecheck`.

***

## 4. Scope

### In Scope (MVP)

* AI Rogue content authors can declare enemy audio intent in metadata - add `audioFamily: AiRogueEnemyAudioFamily` to every enemy template.
* AI Rogue content authors can declare required standard enemy frames - add idle, alternate idle, attack, hit, and defeated frame metadata where available.
* AI Rogue content authors can declare current boss frames - add Kernel Sentinel idle, charge, telegraph, attack, shielded, hit, and shutdown frame metadata without adding a generalized boss behavior spec.
* AI Rogue audio routing reads enemy metadata - reduce `audioFamilyForEnemyKind()` to a template lookup with a generic fallback for unknown or non-enemy metadata.
* AI Rogue validation derives required gameplay frames - derive coverage from themes, enemies, Kernel Sentinel frame metadata, protocols, objectives, statuses, pickups, and authored level specs.
* AI Rogue validation derives audio asset requirements - verify every declared SFX, music, and ambience ID maps to imported Ogg URLs and a provenance record.

### Out Of Scope (Deferred)

* Adding a second boss, miniboss, enemy, theme, music track, ambience track, or SFX cue - Reason: this session proves metadata and validation for existing content first.
* Replacing hard-coded Kernel Sentinel behavior in render, combat, effects, audio adapter, or finale presentation paths - Reason: Session 06 owns the reusable boss and finale contract.
* Removing manual gameplay or SFX lists before derived checks are trusted - Reason: manual lists can shrink only to shared static frames after derived coverage passes.
* Changing save schema version, persisted enemy IDs, browser-local storage, or public demo behavior - Reason: metadata is source-owned and should not widen runtime persistence or hosted surface area.
* Route-visible UI, controls, PixiJS renderer redesign, remote loading, collectors, hosted writes, telemetry, or analytics - Reason: this is runtime content validation infrastructure only.

***

## 5. Technical Approach

### Architecture

Keep enemy metadata close to the existing catalog in `AI_ROGUE_ENEMY_TEMPLATES`, but avoid turning metadata into saved or runtime state. Introduce narrow metadata types in `types-entities.ts`, update the template typing in `entities.ts`, and make `createAiRogueEnemy()` explicitly project only runtime state fields so metadata does not leak into hydrated entities.

Move audio family selection from a switch in `audio.ts` to a lookup on the enemy template metadata. Unknown, undefined, and actor-kind-only paths should continue to fall back to the existing generic, sentry, or boss cues so current combat and renderer-audio behavior remains stable.

Extend validation by deriving frame and audio requirements from the same typed source data the runtime uses. Derived frame validation should produce stable, sorted missing-reference messages and should not import PixiJS. Audio validation can export narrow asset-map helpers from `audio.ts` or a pure nearby owner, but must preserve lazy audio loading, silent fallback behavior, and the existing Web Audio test surface.

### Design Patterns

* Catalog-owned metadata: Add authoring metadata to existing enemy specs instead of creating renderer-specific branches.
* Runtime projection boundary: Keep source metadata out of saved entity state through explicit projection in `createAiRogueEnemy()`.
* Derived validation: Calculate frame and audio requirements from typed content contracts, then assert atlas, URL, and provenance coverage in tests.
* Behavior preservation: Update focused audio, combat, and renderer-audio tests so metadata routing proves the same cues as the current switch.

***

## 6. Deliverables

### Files To Create

| File | Purpose                                                                  | Est. Lines |
| ---- | ------------------------------------------------------------------------ | ---------- |
| None | Existing runtime, content, audio, and test owners can hold this session. | 0          |

### Files To Modify

| File                                                                       | Changes                                                                                                                       | Est. Lines |
| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `src/extensions/ai-rogue/runtime/types-entities.ts`                        | Add enemy audio-family, standard frame-set, boss frame-set, and template metadata types.                                      | \~60       |
| `src/extensions/ai-rogue/runtime/entities.ts`                              | Add metadata to every enemy template, add lookup helpers, and keep entity creation from persisting metadata.                  | \~180      |
| `src/extensions/ai-rogue/runtime/audio.ts`                                 | Replace enemy-kind family switch with metadata lookup and expose validation-safe audio asset maps or helpers.                 | \~70       |
| `src/extensions/ai-rogue/runtime/content/validate.ts`                      | Add derived gameplay frame and audio-reference validation helpers with stable issue messages.                                 | \~170      |
| `src/extensions/ai-rogue/runtime/assets.ts`                                | Separate shared static frame requirements from derived content gameplay frame requirements while preserving atlas validation. | \~80       |
| `src/extensions/ai-rogue/runtime/__tests__/audio.test.ts`                  | Prove metadata-based family routing, cue output, Ogg URL coverage, and provenance coverage.                                   | \~140      |
| `src/extensions/ai-rogue/runtime/__tests__/assets.test.ts`                 | Prove derived gameplay frame coverage, static-frame boundary, and actionable missing-frame failures.                          | \~120      |
| `src/extensions/ai-rogue/runtime/content/__tests__/levels.test.ts`         | Cover derived content validation behavior and malformed metadata cases.                                                       | \~90       |
| `src/extensions/ai-rogue/runtime/__tests__/ecology.test.ts`                | Assert each enemy template owns audio-family and frame-set metadata.                                                          | \~70       |
| `src/extensions/ai-rogue/runtime/__tests__/combat.test.ts`                 | Preserve combat audio metadata and cue expectations after routing moves to enemy metadata.                                    | \~30       |
| `src/extensions/ai-rogue/runtime/__tests__/renderer-audio-adapter.test.ts` | Preserve renderer audio adapter behavior for sentry and boss cue paths.                                                       | \~30       |
| `src/extensions/ai-rogue/runtime/__tests__/boss-presentation.test.ts`      | Keep Kernel Sentinel frame expectations aligned with new metadata without generalizing boss behavior.                         | \~30       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Every `AiRogueEnemyKind` has an `audioFamily` and standard frame-set metadata where the committed atlas contains frames.
* [ ] Kernel Sentinel has frame metadata for idle, charge, telegraph, attack, shielded, hit, and shutdown states.
* [ ] `audioFamilyForEnemyKind()` behavior is preserved through metadata lookup with a generic fallback for undefined or unknown metadata.
* [ ] Derived gameplay frame validation catches missing content frames before renderer runtime.
* [ ] Derived audio validation catches missing SFX, music, ambience, imported Ogg URL, or provenance mappings before runtime.

### Testing Requirements

* [ ] `audio.test.ts` passes with metadata-based cue routing.
* [ ] `assets.test.ts` passes with derived gameplay frame coverage.
* [ ] Content registry validation tests pass with explicit missing-reference failures.
* [ ] Combat, boss presentation, render model, and renderer-audio adapter tests pass for current Kernel Sentinel and standard enemy behavior.
* [ ] `bun run typecheck` passes.

### Non-Functional Requirements

* [ ] No new game content, runtime media, remote loading, public demo behavior, hosted writes, collectors, analytics, bridge calls, or PixiJS imports are introduced.
* [ ] Save schema version remains unchanged and metadata is not persisted into saved enemy state.
* [ ] Derived validation outputs are deterministic, sorted where useful, and safe from private paths, commands, credentials, prompts, or token-shaped text.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Primary user-facing surfaces are unchanged.

***

## 8. Implementation Notes

### Working Assumptions

* Keep enemy metadata in `AI_ROGUE_ENEMY_TEMPLATES`: the current enemy catalog is already the authoritative source for kind, behavior, stats, frame name, effects, and death reward; adding source-only metadata there avoids a second enemy catalog and is safe if `createAiRogueEnemy()` projects runtime fields explicitly.
* Export narrow audio validation helpers from the existing audio owner before adding a new module: `audio.ts` already owns SFX, music, ambience, and Vite Ogg URL maps; exposing read-only validation data is smaller than creating a parallel manifest unless import shape proves problematic during implementation.
* Keep Kernel Sentinel metadata narrow: Session 05 needs frame declarations so derived asset checks can reason about the current boss, but Session 06 owns reusable boss behavior and finale routing.

### Conflict Resolutions

* Session 05 asks for boss frame-set metadata while Session 06 owns boss generalization. The chosen interpretation is to add only Kernel Sentinel frame metadata in this session and defer `AiRogueBossSpec`, behavior helpers, finale ownership, and hard-coded branch removal to Session 06.
* The phase plan says to keep manual frame and SFX lists until derived checks are trusted, while this session also asks to shrink them. The chosen interpretation is to split shared static requirements from derived content requirements after tests prove parity, not to delete coverage before the derived path is green.

### Key Considerations

* Metadata must not create save-schema drift or change hydrated run state.
* Validation helpers should be pure and deterministic; tests can import atlas JSON, audio URL maps, and provenance JSON to prove committed asset coverage.
* Missing-reference messages should name the content ID and reference path without exposing local filesystem paths or generated private data.
* Boss behavior stays intentionally literal until Session 06 replaces it with a reusable contract.

### Potential Challenges

* Template metadata could leak into `AiRogueEnemyState`: mitigate by updating the template type and projecting runtime state explicitly.
* Audio map exports could accidentally widen eager asset imports: mitigate by keeping exported helpers read-only and preserving existing lazy decode and silent no-op behavior.
* Derived frame validation may miss static renderer frames: mitigate by keeping a separate shared static frame list until derived content coverage is trusted.
* Atlas or provenance JSON may be missing entries: mitigate with exact actionable test failures and no generated private path output.

### Relevant Considerations

* \[P35] **AI Rogue compatibility exports remain**: Runtime barrel and migration exports should not be removed as part of metadata work.
* \[P30/P32/P34-P35] **Schema-backed browser-local state works**: Keep metadata source-owned and avoid saved-run schema churn.
* \[P30/P34-P38] **Visibility gates catch real issues**: Pair focused tests, typecheck, asset checks, and privacy-safe validation messages before widening content authoring.
* \[P31-P38] **Public-demo, AI Rogue, and hosted-surface gates stay bundled**: Do not change public demo or hosted behavior in this runtime metadata session.
* \[P30/P32/P34-P38] **Do not widen AI Rogue capabilities without review**: Avoid remote content loading, collectors, WebGPU changes, hosted writes, or new direct asset reuse outside the reviewed media set.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Metadata/runtime boundary drift causes extra fields to persist in saves.
* Missing frames or audio files surface only during renderer/audio playback instead of deterministic validation.
* Metadata lookup changes current enemy, sentry, or boss cue selection.

***

## 9. Testing Strategy

### Unit Tests

* `audio.test.ts` for metadata-based family routing, cue selection, URL maps, fallback behavior, and provenance coverage.
* `assets.test.ts` for derived gameplay frame requirements, atlas membership, missing-frame messages, and static-frame/manual-list boundaries.
* `content/__tests__/levels.test.ts` for derived validation helpers and malformed metadata cases.
* `ecology.test.ts` for enemy metadata completeness.

### Integration Tests

* `combat.test.ts` for unchanged enemy and boss audio metadata emitted by combat paths.
* `renderer-audio-adapter.test.ts` for unchanged renderer-side cue routing.
* `boss-presentation.test.ts` and `render-model.test.ts` for unchanged Kernel Sentinel visual behavior after frame metadata is introduced.

### Runtime Verification

* No browser route verification is required unless implementation touches route-visible UI, controls, audio unlock behavior, PixiJS mount code, or renderer import shape.
* Run `bash scripts/check-asset-sizes.sh` if any asset/provenance file changes, even though no new media is expected.

### Edge Cases

* Undefined enemy kind falls back to generic audio family.
* Actor-kind-only sentry and boss metadata paths keep current cue behavior.
* Enemy templates with no alternate idle frame are handled explicitly rather than treated as missing required content.
* Derived frame lists remain deterministic and deduplicated.
* Provenance validation rejects missing records without exposing local paths.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase39-session01-baseline-and-registry-skeleton`, `phase39-session02-depth-resolver-migration`, `phase39-session03-registry-validation-and-save-parity`, `phase39-session04-existing-media-floor-four`
* Depended by: `phase39-session06-boss-and-finale-contracts`, `phase39-session07-real-content-expansion-path`, `phase39-session08-validation-and-documentation-hardening`

***

## 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/phase39-session05-enemy-metadata-and-derived-asset-checks/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.