> 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-session04-existing-media-floor-four/spec.md).

# Session Specification

**Session ID**: `phase39-session04-existing-media-floor-four` **Phase**: 39 - AI Rogue Level Authoring Infrastructure **Status**: Not Started **Created**: 2026-06-30

***

## 1. Session Overview

This session proves the Phase 39 authoring path by adding one playable fourth AI Rogue floor from existing registry data, runtime catalogs, media IDs, and browser-local save contracts. Sessions 01 through 03 created the level registry, routed depth decisions through it, and made malformed content or save ID drift fail fast; the next executable step is to use those gates on a real authored floor.

The floor should be data-first. Implementation appends one `AiRogueLevelSpec` for depth 4, updates expectations that currently treat depth 4 as out of range, and proves deterministic generation, route safety, objective behavior, and save round-trip parsing without adding renderer, audio, simulation, route, asset, or save-schema branches.

Depth 4 reuses the existing firewall media lane because current non-authored depth-4 fallback helpers already resolve to `firewall`, `hazard-cache`, `patch-mirror`, `trace-lance`, `sector_3`, and `theme_firewall_ambience`. Moving those existing decisions into the registry keeps this session focused on authoring infrastructure rather than new content production.

***

## 2. Objectives

1. Add a fourth authored level spec that increases `AI_ROGUE_MAX_DEPTH` from 3 to 4 through `AI_ROGUE_LEVEL_SPECS.length`.
2. Reuse only existing AI Rogue themes, enemies, prefabs, terminals, protocols, music, ambience, frames, objective kinds, and boss IDs.
3. Update focused runtime and content tests so depth 4 is deterministic, route-safe, objective-aware, and covered by save round-trip parsing.
4. Preserve save schema version 1, browser-local privacy boundaries, route-lazy PixiJS ownership, public-demo safety, and no remote content loading.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase39-session01-baseline-and-registry-skeleton` - Adds the initial level registry, lookup API, baseline tests, and pure validator.
* [x] `phase39-session02-depth-resolver-migration` - Routes depth helpers, world generation, run creation, and descent through level specs.
* [x] `phase39-session03-registry-validation-and-save-parity` - Adds active registry reference checks and save-schema ID parity gates.

### Required Tools Or Knowledge

* Bun 1.3.14 package/runtime baseline.
* AI Rogue content registry files in `src/extensions/ai-rogue/runtime/content/`.
* Existing runtime catalogs for themes, enemies, prefabs, terminals, protocols, music, ambience, and save-schema persisted IDs.
* Focused Vitest suites for AI Rogue content, generation, run loop, objective, golden determinism, and save-schema 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 players can enter a fourth floor because max depth is derived from authored content - append one depth-4 `AiRogueLevelSpec` in `content/levels.ts`.
* Content authors get a concrete reused-media example - define the depth-4 label, lesson, enemy table, guard, prefab, terminal, protocol choices, objective, reward profile, generation profile, and finale metadata.
* Existing IDs remain the only persisted content surface - reuse current enemy, theme, protocol, terminal, prefab, music, ambience, objective, pickup, and boss IDs.
* Deterministic generation covers depth 4 - add route-safety and golden determinism expectations for reachable exit, no spawn overlap, adjacent guard placement, objective lock coverage, terminal/prefab behavior, and stable first-turn summary.
* Browser-local saves can round-trip a depth-4 run - extend save-schema tests without a schema version bump or new compatibility IDs.

### Out Of Scope (Deferred)

* Adding new monsters, bosses, music, ambience, frames, assets, or persisted save IDs - Reason: this session proves reuse before new content expansion.
* Adding renderer, audio switch, simulation, route-import, public-demo, or save-schema branches - Reason: all depth-4 references must already be registry-readable and parser-covered.
* Generalizing Kernel Sentinel boss/finale helpers - Reason: Session 06 owns the reusable boss and finale contract after this reused-media proof.
* Moving final-defense presentation fully off raw depth checks - Reason: Session 06 owns the final boss/finale refactor; Session 04 may only adjust focused expectations needed for the authored depth-4 run to pass.
* Browser UI copy or product-route redesign - Reason: this is a runtime content authoring session, not a route or visual polish session.

***

## 5. Technical Approach

### Architecture

Append one depth-4 level spec to `AI_ROGUE_LEVEL_SPECS` and let existing resolver paths pick it up. The new spec should use a stable ID such as `firewall-gauntlet`, label it as an intentional firewall reuse, and set its generation profile to the current depth-4 fallback lane: `themeId: "firewall"`, `roomModifier: "threat-dense"`, `baselineProtocolId: "trace-lance"`, `musicTrackId: "sector_3"`, and `ambienceId: "theme_firewall_ambience"`.

Keep the floor authored but media-neutral. Reuse `kernel-sentinel` as the exit guard and final boss, `hazard-cache` as the prefab, `patch-mirror` as the terminal, current firewall enemy-table IDs, and existing objective/pickup and protocol IDs for the reward profile. Because the validator requires the last authored level to own the finale, depth 3 should stop carrying final-authored metadata while preserving its current generation, guard, objective, and route behavior.

Update tests along the existing ownership boundaries. Content and resolver tests prove the registry values, world tests prove route safety, golden determinism captures the new depth-4 world and first-turn snapshot, run-loop tests prove max-depth/descent behavior, objective tests cover lock semantics, and save-schema tests prove depth-4 persisted snapshots hydrate without schema changes.

### Design Patterns

* Registry-owned authored content: Add one level row and let existing projection helpers consume it.
* Reused-ID proof: Treat save-schema parity as a guardrail and avoid any parser or persisted ID change.
* Deterministic expectation update: Add depth 4 to the existing golden and baseline suites rather than relying on manual playthrough claims.
* Boundary preservation: Keep route, renderer, PixiJS, public demo, bridge, remote loading, and hosted write behavior out of this session.

***

## 6. Deliverables

### Files To Create

| File | Purpose                                                           | Est. Lines |
| ---- | ----------------------------------------------------------------- | ---------- |
| None | Existing source and test files cover the reused-media floor work. | 0          |

### Files To Modify

| File                                                                   | Changes                                                                                                     | Est. Lines |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ---------- |
| `src/extensions/ai-rogue/runtime/content/levels.ts`                    | Append the depth-4 level spec and move final-authored metadata to depth 4 while reusing existing IDs.       | \~55       |
| `src/extensions/ai-rogue/runtime/content/__tests__/levels.test.ts`     | Expect four authored levels, validate the depth-4 spec, and change out-of-range lookup coverage to depth 5. | \~45       |
| `src/extensions/ai-rogue/runtime/__tests__/content-baseline.test.ts`   | Add depth-4 helper, generation, objective, reward, and max-depth expectations.                              | \~55       |
| `src/extensions/ai-rogue/runtime/__tests__/depth-resolver.test.ts`     | Update authored depth and legacy fallback assertions after depth 4 becomes authored.                        | \~30       |
| `src/extensions/ai-rogue/runtime/__tests__/world.test.ts`              | Add depth-4 route-safety, guard, prefab, terminal, vault, and no-overlap assertions.                        | \~45       |
| `src/extensions/ai-rogue/runtime/__tests__/golden-determinism.test.ts` | Extend deterministic world and first-turn summaries to depth 4.                                             | \~220      |
| `src/extensions/ai-rogue/runtime/__tests__/roguelike-loop.test.ts`     | Prove playable max depth is 4, depth 3 descends, and depth 4 wins.                                          | \~35       |
| `src/extensions/ai-rogue/runtime/__tests__/objective-lock.test.ts`     | Cover depth-4 objective lock or unlock behavior when the final floor uses a floor objective.                | \~30       |
| `src/extensions/ai-rogue/__tests__/save-schema.test.ts`                | Add durable snapshot and hydration coverage for a depth-4 run without changing schema version.              | \~45       |
| `src/extensions/ai-rogue/runtime/__tests__/biome-final.test.ts`        | Keep final presentation tests explicit about fixture finality after authored max depth moves to 4.          | \~25       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `AI_ROGUE_LEVEL_SPECS` contains depths `[1, 2, 3, 4]` and `AI_ROGUE_MAX_DEPTH` resolves to 4.
* [ ] `levelSpecForDepth(4)` returns a firewall reused-media floor with only existing IDs and `levelSpecForDepth(5)` remains out of range.
* [ ] Depth 4 has reachable exit, no spawn overlap, adjacent exit guard, expected terminal/prefab behavior, and deterministic generated output.
* [ ] Depth 3 can descend to depth 4, and depth 4 is the final winning floor in max-depth run-loop tests.
* [ ] A depth-4 run state parses and hydrates through the current save schema without a schema version bump.

### Testing Requirements

* [ ] Focused content registry and resolver tests pass.
* [ ] Focused world, run-loop, objective, and golden determinism tests pass.
* [ ] Focused save-schema tests pass.
* [ ] `bun run typecheck` passes.

### Non-Functional Requirements

* [ ] No new runtime media, committed assets, save IDs, remote loading, public demo behavior, hosted writes, collectors, analytics, bridge calls, or PixiJS imports are introduced.
* [ ] Save schema version remains `1`.
* [ ] Content registry and save-schema boundaries stay pure and browser-local.
* [ ] Any final-defense depth assumptions left in place are covered by tests and remain scheduled for the Session 06 boss/finale contract.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Primary user-facing surfaces are unchanged except existing in-game floor labels and event-log lesson copy.

***

## 8. Implementation Notes

### Working Assumptions

* Use `firewall` for depth 4: current legacy depth-4 helper behavior already resolves to `firewall`, `hazard-cache`, `patch-mirror`, `trace-lance`, `sector_3`, and `theme_firewall_ambience`, so promoting that lane into an authored spec proves data-driven authoring with the smallest behavior delta.
* Make depth 4 the final authored level: Session 03 validation requires the last authored level to carry `isFinalAuthoredLevel: true`, so adding depth 4 safely requires moving finale metadata from depth 3 to depth 4 rather than weakening the validator.
* Keep save schema unchanged: Session 04 reuses active runtime IDs already covered by Session 03 parity tests, so a schema version bump or compatibility ID addition would be unnecessary churn.

### Conflict Resolutions

* Session 04 needs a playable fourth floor, while current depth-3 registry data marks Kernel Arena as final. The chosen interpretation is that max depth and final authored ownership move with the new last level, because `validateAiRogueContentRegistry()` rejects finales before the last authored level and Phase 39 explicitly wants max depth to increase from authored content.
* Session 06 owns the broader boss/finale abstraction, while Session 04 must still pass current validation. The chosen interpretation is to reuse `kernel-sentinel` through the existing finale fields and update only focused tests needed for depth 4, leaving boss helper generalization to Session 06.

### Key Considerations

* The committed depth-4 floor label and lesson are browser-facing game copy and must stay safe, short, and product-facing.
* The registry validator must remain strict; implementation should not loosen finale placement or save ID parity to make depth 4 easier.
* Depth-4 golden output should be regenerated deliberately from deterministic helpers, then locked in tests.

### Potential Challenges

* Existing tests hard-code depth 3 as the final depth: update only tests whose purpose is authored max-depth behavior, and keep fixture-specific final presentation tests explicit about their crafted snapshots.
* Depth-4 objective behavior may expose assumptions in final-defense visuals: cover lock/unlock and run-loop behavior in focused tests while preserving Session 06 as the place for the full finale contract refactor.
* Golden determinism output will be large: keep the assertion format identical to the current file so future diffs remain reviewable.

### Relevant Considerations

* \[P30/P32/P34-P35] **Route-lazy runtime ownership scales**: Keep PixiJS behind the Play route/local facade; this session should stay in runtime content and tests.
* \[P30/P34-P38] **Visibility gates catch real issues**: Pair focused runtime tests, typecheck, and save/privacy boundaries before widening content.
* \[P30/P32/P34-P38] **Do not widen AI Rogue capabilities without review**: Reuse approved local assets and browser-local state; do not add remote loading, collectors, workers, hosted writes, or rejected-art reuse.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Authored depth 4 accidentally bypasses registry validation or save ID parity.
* Run-loop finality stays hard-coded to depth 3 after max depth becomes 4.
* Generated floor placement creates unreachable exits, sealed terminals, or overlapping guards, pickups, prefabs, and vaults.

***

## 9. Testing Strategy

### Unit Tests

* Update registry, resolver, content-baseline, world, objective, run-loop, golden determinism, biome-final, and save-schema tests named in the deliverables.

### Integration Tests

* Run focused AI Rogue Vitest suites covering content registry, generated worlds, run-loop descent/finality, and durable save hydration.

### Runtime Verification

* Use deterministic tests to prove depth 4 is generated, reachable, guarded, objective-aware, and save-hydratable. No browser route proof is required unless implementation touches route or renderer surfaces.

### Edge Cases

* Depth 5 remains rejected by authored-main-run lookup.
* Depth 3 descends instead of winning when max depth is 4.
* Depth 4 wins only after objective/finality conditions are satisfied.
* Unsafe floor labels, lessons, and save metadata remain rejected by existing validation.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase39-session01-baseline-and-registry-skeleton`, `phase39-session02-depth-resolver-migration`, `phase39-session03-registry-validation-and-save-parity`.
* Depended by: `phase39-session05-enemy-metadata-and-derived-asset-checks`, `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-session04-existing-media-floor-four/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.