> 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/phases/phase_39/session_02_depth_resolver_migration.md).

# Session 02: Depth Resolver Migration

**Session ID**: `phase39-session02-depth-resolver-migration` **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Route existing depth-based runtime decisions through level specs while preserving depth 1-3 behavior.

***

## Scope

### In Scope (MVP)

* Derive `AI_ROGUE_MAX_DEPTH` from `AI_ROGUE_LEVEL_SPECS.length` while keeping existing import surfaces stable.
* Rewrite compatibility helpers over `levelSpecForDepth()` where appropriate: `themeForDepth()`, `floorArcForDepth()`, `floorObjectiveForDepth()`, `prefabForDepth()`, `terminalForDepth()`, `musicTrackForDepth()`, and exit guard selection.
* Extend world generation to accept or resolve a level spec and use it for theme, enemy table, room modifier, exit guard, prefab, terminal, and baseline protocol placement.
* Keep floor-arc guarantees separate from baseline protocol placement.
* Introduce `applyLevelGuarantees()` or an equivalent wrapper while preserving `applyFloorArc()` as a migration shim.
* Audit `protocolForDepth()` call sites before changing rotation behavior.

### Out of Scope

* Adding new playable floors.
* Removing compatibility exports before direct consumers migrate.
* Changing shipped depth 1-3 gameplay outputs.

***

## Detailed Plan Notes

* This session moves depth policy out of scattered modules while preserving public signatures and current outputs for depths 1-3.
* Resolver coverage checked on 2026-06-30 includes `AI_ROGUE_MAX_DEPTH` in `runtime/run-factory.ts:38`, theme helpers in `runtime/themes.ts:123` and `runtime/themes.ts:128`, floor arc helpers in `runtime/floor-arc.ts:52` and `runtime/floor-arc.ts:95`, `prefabForDepth()` in `runtime/prefabs.ts:68`, `protocolForDepth()` in `runtime/protocols.ts:97`, `terminalForDepth()` in `runtime/terminals.ts:106`, `findExitGuardSpawn()` in `runtime/world-placement.ts:23`, `createAiRogueWorld()` assembly in `runtime/world-generator.ts:91`, `:163`, `:289`, `:324`, and `:340`, and `musicTrackForDepth()` in `runtime/audio.ts:1040`.
* Extend `AiRogueWorldGenerationOptions` to accept `levelSpec` or resolve one from `depth`.
* Replace `roomModifierForDepth(depth)` with `levelSpec.generation.roomModifier`.
* Use `levelSpec.themeId`, `levelSpec.enemyTable`, and `levelSpec.exitGuardKind` during generation.
* Move baseline protocol, terminal, and prefab decisions to `levelSpec.placements`.
* Keep floor-arc guarantees separate as `levelSpec.guarantees`, including the current guaranteed pickup, introduced enemies, guaranteed protocol, and optional objective.
* Protocol handling is special: the current rotating baseline protocol from `world-generator.ts` is separate from the floor-arc guaranteed protocol. Audit `protocolForDepth()` call sites before removing or changing rotation semantics.
* Deterministic route-safety tests should prove each level's exit is reachable, the guard is adjacent to the exit, prefabs never disconnect the map, and terminal or vault placement never blocks the route.

***

## Prerequisites

* [ ] Session 01 baseline tests and registry are complete.
* [ ] Golden determinism tests exist for depth 1-3.

***

## Deliverables

1. Runtime wrappers that read level specs instead of raw depth branches.
2. World-generation code that consumes one level spec for authored content decisions.
3. Deterministic route-safety tests for reachable exits, adjacent guards, connected prefabs, and non-blocking terminal or vault placement.

***

## Success Criteria

* [ ] Existing depth 1-3 tests pass without expected-output edits.
* [ ] Golden determinism tests remain byte-identical for the current three floors.
* [ ] The generator has no level-specific depth branches except fallback validation or legacy test support.
* [ ] The focused resolver gate passes:

```bash
bun run typecheck
bunx vitest run src/extensions/ai-rogue/runtime/__tests__/world.test.ts \
  src/extensions/ai-rogue/runtime/__tests__/simulation.test.ts \
  src/extensions/ai-rogue/runtime/__tests__/floor-arc.test.ts \
  src/extensions/ai-rogue/runtime/__tests__/themes.test.ts \
  src/extensions/ai-rogue/runtime/__tests__/prefabs.test.ts \
  src/extensions/ai-rogue/runtime/__tests__/protocols.test.ts \
  src/extensions/ai-rogue/runtime/__tests__/terminals.test.ts \
  src/extensions/ai-rogue/runtime/__tests__/audio.test.ts
```


---

# 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/phases/phase_39/session_02_depth_resolver_migration.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.