> 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/phase35-session08-world-types-and-fixture-cleanup/spec.md).

# Session Specification

**Session ID**: `phase35-session08-world-types-and-fixture-cleanup` **Phase**: 35 - AI Rogue Audit Hardening And Refactor **Status**: Not Started **Created**: 2026-06-27

***

## 1. Session Overview

This session finishes the low-level AI Rogue world and type cleanup after the Session 06 simulation ownership refactor and the Session 07 renderer/React bridge refactor. The broad `runtime/world.ts` and `runtime/types.ts` files are the remaining audit-routed module-boundary risks for AI Rogue.

The work splits world generation, fixture parsing, placement helpers, geometry helpers, and runtime type domains into explicit owners while preserving the existing production posture: AI Rogue remains production-enabled, browser-local, and static-demo safe. The implementation should be behavior-preserving except for tightly scoped import-boundary hardening and test coverage.

This is next because the analyzer reports Sessions 01-07 complete and Session 08 is the earliest unfinished Phase 35 session with all prerequisites met.

***

## 2. Objectives

1. Split `src/extensions/ai-rogue/runtime/world.ts` into explicit generator, fixture parser, placement, geometry, and tile helper modules.
2. Split `src/extensions/ai-rogue/runtime/types.ts` into explicit asset, world/entity, simulation, progression/save, and runtime controller/event type modules.
3. Preserve same-seed world generation, fixture-row parsing, prefab placement, vault/terminal connectivity, and deterministic ordering.
4. Keep fixture-only APIs out of production route and mounted runtime entrypoints.
5. Pass focused AI Rogue runtime tests plus TypeScript, lint, ASCII, LF, and whitespace gates.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase35-session06-simulation-ownership-refactor` - settled the public runtime API and simulation-owned run-state mutation boundary.
* [x] `phase35-session07-renderer-and-react-bridge-refactor` - narrowed renderer, effects, render-model, and React runtime bridge ownership.

### Required Tools Or Knowledge

* Bun 1.3.14 project scripts from `package.json`.
* TypeScript import/type-only export behavior.
* Existing AI Rogue runtime tests under `src/extensions/ai-rogue/runtime/__tests__/`.

### Environment Requirements

* Local repo checkout with Bun dependencies installed.
* No dev server is required for this planning scope.

***

## 4. Scope

### In Scope (MVP)

* AI Rogue runtime maintainers can work in smaller world modules - extract generator pipeline, fixture row parser, prefab/spawn/vault/terminal placement, geometry helpers, and tile helpers into focused modules.
* AI Rogue runtime maintainers can work with smaller type domains - extract render asset frame names, world/entity shapes, simulation state/events, runtime controller/events, and progression/save bridge types into focused modules.
* AI Rogue production routes cannot import fixture-only APIs - preserve and extend runtime boundary tests around `simulation-fixtures`, fixture row parsing, and the mounted runtime barrel.
* AI Rogue deterministic generation remains stable - preserve same-seed, fixture parser, prefab, vault, terminal, compile, and render-model coverage.

### Out Of Scope (Deferred)

* New dungeon content packs or expanded mechanics - Reason: Session 08 is a refactor and boundary cleanup session.
* Renderer extraction beyond import updates - Reason: Session 07 already owns renderer/React bridge extraction.
* New persistence schema behavior - Reason: Session 05 owns durable schema and save contracts.
* CI workflow changes - Reason: final release gate automation belongs to later release hardening, not this module split.

***

## 5. Technical Approach

### Architecture

Use a staged, compatibility-preserving extraction. Move definitions into new single-owner modules first, then make `runtime/types.ts` and `runtime/world.ts` explicit compatibility surfaces during the migration. Update high-traffic runtime modules to import from the new owners where it clarifies boundaries, while keeping tests and older call sites compiling through re-exports where a full import rewrite would exceed the session scope.

World extraction should separate pure geometry/tile helpers from generated content. Fixture row parsing should move behind a testing-oriented module path and keep its existing validation errors. Production route code should continue to mount through `runtime/mount` and must not import simulation internals, fixture modules, or the full runtime barrel.

### Design Patterns

* Extract-and-re-export: Move definitions first, then re-export from old compatibility surfaces to preserve compile behavior during the split.
* Type-only imports: Keep domain type modules free of runtime imports wherever possible to reduce circular-import pressure.
* Behavior characterization before rewiring: Extend existing tests around deterministic generation and fixture boundaries before broad import updates.
* Static boundary tests: Keep source-inspection tests as the guard for public runtime and production route import rules.

***

## 6. Deliverables

### Files To Create

| File                                                   | Purpose                                                                             | Est. Lines |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------- | ---------- |
| `src/extensions/ai-rogue/runtime/world-geometry.ts`    | Coordinate comparison, keys, neighbors, distance, and sorting helpers.              | \~80       |
| `src/extensions/ai-rogue/runtime/world-tiles.ts`       | Tile creation, passability, sight, lookup, and snapshot helpers.                    | \~110      |
| `src/extensions/ai-rogue/runtime/world-fixtures.ts`    | Testing-oriented fixture row parser and fixture parser errors.                      | \~150      |
| `src/extensions/ai-rogue/runtime/world-placement.ts`   | Prefab, vault, terminal, exit guard, and open-position placement helpers.           | \~260      |
| `src/extensions/ai-rogue/runtime/world-generator.ts`   | Main deterministic generated-world pipeline and generation options.                 | \~360      |
| `src/extensions/ai-rogue/runtime/types-assets.ts`      | Tile, entity, fog, and relic icon frame name unions.                                | \~130      |
| `src/extensions/ai-rogue/runtime/types-world.ts`       | Position, tile, world, enemy spawn, pickup spawn, and world snapshot types.         | \~140      |
| `src/extensions/ai-rogue/runtime/types-entities.ts`    | Player, enemy, pickup, combat stats, status, objective, and entity snapshot types.  | \~220      |
| `src/extensions/ai-rogue/runtime/types-progression.ts` | Progression runtime rule and save/progression bridge type exports.                  | \~90       |
| `src/extensions/ai-rogue/runtime/types-simulation.ts`  | Run state, run snapshot, command, event, and command-result types.                  | \~220      |
| `src/extensions/ai-rogue/runtime/types-runtime.ts`     | Runtime mount, controller, command dispatch, status, size, and runtime event types. | \~240      |

### Files To Modify

| File                                                                 | Changes                                                                             | Est. Lines |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------- |
| `src/extensions/ai-rogue/runtime/world.ts`                           | Replace broad implementation with explicit compatibility exports.                   | \~40       |
| `src/extensions/ai-rogue/runtime/types.ts`                           | Replace broad definitions with explicit type/value re-exports.                      | \~80       |
| `src/extensions/ai-rogue/runtime/simulation-fixtures.ts`             | Route testing fixtures through explicit fixture/generator modules.                  | \~30       |
| `src/extensions/ai-rogue/runtime/run-factory.ts`                     | Import generated-world API from its owning module.                                  | \~20       |
| `src/extensions/ai-rogue/runtime/simulation.ts`                      | Import world helpers and simulation/domain types from focused owners.               | \~60       |
| `src/extensions/ai-rogue/runtime/fov.ts`                             | Import geometry/world helpers from focused owners.                                  | \~20       |
| `src/extensions/ai-rogue/runtime/snapshot.ts`                        | Import tile snapshot and geometry helpers from focused owners.                      | \~30       |
| `src/extensions/ai-rogue/runtime/entities.ts`                        | Import geometry helpers and entity/world types from focused owners.                 | \~30       |
| `src/extensions/ai-rogue/runtime/render-model.ts`                    | Import render/world/runtime types from focused owners.                              | \~40       |
| `src/extensions/ai-rogue/runtime/renderer.ts`                        | Import runtime command values/types from focused owners.                            | \~40       |
| `src/extensions/ai-rogue/runtime/mount.ts`                           | Import mount/controller types from focused owners.                                  | \~20       |
| `src/extensions/ai-rogue/runtime/input.ts`                           | Import runtime input types from focused owners.                                     | \~20       |
| `src/extensions/ai-rogue/runtime/__tests__/world.test.ts`            | Preserve same-seed, fixture parser, geometry, vault, terminal, and prefab coverage. | \~80       |
| `src/extensions/ai-rogue/runtime/__tests__/runtime-boundary.test.ts` | Extend production import and public barrel boundary assertions.                     | \~50       |
| `src/extensions/ai-rogue/runtime/__tests__/compile.test.ts`          | Preserve compile coverage against split simulation/world types.                     | \~20       |
| `src/extensions/ai-rogue/runtime/__tests__/prefabs.test.ts`          | Preserve prefab placement behavior after extraction.                                | \~30       |
| `src/extensions/ai-rogue/runtime/__tests__/vault.test.ts`            | Preserve vault connectivity behavior after extraction.                              | \~30       |
| `src/extensions/ai-rogue/runtime/__tests__/terminals.test.ts`        | Preserve terminal placement/connectivity behavior after extraction.                 | \~30       |
| `src/extensions/ai-rogue/save-schema.ts`                             | Update ownership comment if it still points only at `runtime/types.ts`.             | \~5        |

***

## 7. Success Criteria

### Functional Requirements

* [ ] `world.ts` no longer contains the full generator, fixture parser, placement helpers, and geometry helpers in one file.
* [ ] `types.ts` no longer contains all runtime type definitions in one file.
* [ ] Same-seed generated worlds remain equal for the same options.
* [ ] Fixture rows still parse all existing symbols and reject malformed rows with explicit errors.
* [ ] Vault and terminal placement does not sever generated-world connectivity.
* [ ] Production route and mounted runtime sources do not import fixture-only modules.

### Testing Requirements

* [ ] Focused world, prefab, vault, terminal, compile, and runtime-boundary tests are written or refreshed and passing.
* [ ] Broad AI Rogue runtime tests pass.
* [ ] TypeScript and lint gates pass.

### Non-Functional Requirements

* [ ] AI Rogue remains production-enabled by default with the explicit `none` opt-out untouched.
* [ ] No hosted write, collector, analytics, Function, remote game-content loading, WebGPU-only behavior, worker protocol, or public-demo bridge dependency is introduced.
* [ ] No dependency, asset, bundle policy, or schema contract is changed.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Runtime public barrel remains `export * from "./mount";`.

***

## 8. Implementation Notes

### Working Assumptions

* Compatibility re-exports are acceptable during the split: the import scan shows broad existing usage of `./types`, `../types`, `./world`, and `../world` across runtime code and tests. Keeping explicit compatibility surfaces lets the refactor remain behavior-preserving while new owners become available.
* Runtime boundary tests are the local import-boundary guard: `package.json` does not define a separate import-cycle script, while `runtime-boundary.test.ts` already protects the public runtime barrel and production route imports. Typecheck and lint remain the broader static gates.

### Conflict Resolutions

* The Session 08 stub asks to split broad modules, while current tests import the old world/type surfaces directly. The chosen interpretation is to move ownership to focused modules and keep old surfaces as explicit re-export compatibility layers when needed. This satisfies the split without turning the session into an all-import rewrite.

### Key Considerations

* This session should avoid visible UI changes.
* The fixture parser must remain a testing/local helper, not a product route capability.
* Type modules should prefer type-only imports to avoid reintroducing cycles.
* The final implementation should not hide failed validation behind broad re-export barrels; boundary tests must still prove production surfaces remain narrow.

### Potential Challenges

* Circular type imports: Mitigate by moving asset/world/entity/simulation and runtime controller types into dependency-ordered modules with type-only imports.
* Fixture exposure through convenience imports: Mitigate by testing production routes, `runtime/mount`, and `runtime/index.ts` for forbidden fixture imports.
* Determinism drift during generator extraction: Mitigate by moving helper code without changing placement order and by running same-seed, prefab, vault, and terminal tests after each extraction cluster.

### Relevant Considerations

* \[P34] **AI Rogue is production default-enabled**: Preserve the production default and explicit `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=none` disable path.
* \[P31-P34] **Public-demo and AI Rogue gates stay bundled**: Keep no-bridge, private-runtime, route smoke, and budget implications visible for later release validation; this session should not widen hosted capabilities.
* \[P30/P32/P34] **Route-lazy runtime ownership scales**: Keep Pixi and simulation internals behind the Play route/local mount facade.
* \[P34] **Do not expose deterministic fixtures through product routes**: Fixture scenarios and row parsing remain test/local helpers only.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Fixture parser extraction could accept malformed rows silently instead of preserving explicit parser errors.
* Type-module extraction could accidentally widen production imports or the mounted runtime public surface.
* Generator extraction could change deterministic placement order and break same-seed replay behavior.

***

## 9. Testing Strategy

### Unit Tests

* Refresh `world.test.ts` for same-seed generated worlds, row parser symbols, malformed rows, coordinate helpers, tile snapshots, vault placement, terminal placement, and prefab placement.
* Refresh `prefabs.test.ts`, `vault.test.ts`, and `terminals.test.ts` as needed after placement helpers move.
* Refresh `compile.test.ts` and compile-related runtime tests to prove split types still match simulation contracts.

### Integration Tests

* Extend `runtime-boundary.test.ts` to prove product routes and the mounted runtime entrypoint do not import fixture modules, simulation internals, or a broad runtime barrel.
* Run broad AI Rogue runtime tests after import migration.

### Runtime Verification

* No browser runtime verification is required unless implementation changes user-visible Play behavior. If it does, run the existing AI Rogue runtime Playwright smoke before validation.

### Edge Cases

* Empty fixture rows.
* Unequal fixture row widths.
* Fixture rows missing `@` or `>`.
* Vaults on dead-end access tiles.
* Terminals in one-wide chokepoints.
* Same seed with same depth and room modifier.
* Type-only imports that accidentally become runtime imports.

***

## 10. Dependencies

### Other Sessions

* Depends on: `phase35-session06-simulation-ownership-refactor`, `phase35-session07-renderer-and-react-bridge-refactor`
* Depended by: `phase35-session09-documentation-and-media-policy-sync`, `phase35-session10-final-release-gate`

***

## 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/phase35-session08-world-types-and-fixture-cleanup/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.