> 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_03_registry_validation_and_save_parity.md).

# Session 03: Registry Validation And Save Parity

**Session ID**: `phase39-session03-registry-validation-and-save-parity` **Status**: Not Started **Estimated Tasks**: \~12-25 **Estimated Duration**: 2-4 hours

***

## Objective

Make malformed level specs and save-schema ID drift fail fast in tests before new content is added.

***

## Scope

### In Scope (MVP)

* Extend `validateAiRogueContentRegistry()` for all level references: theme, enemy, protocol, prefab, terminal, objective, music, ambience, pickup, and boss or finale ownership where applicable.
* Add parity tests for persisted runtime IDs covering enemy kinds, sector themes, protocol IDs, and terminal IDs.
* Account for current save-schema shape where protocol and enemy use named local schemas while terminal and theme are inline enums.
* Keep old IDs loadable as hidden compatibility entries if content is retired.
* Move tests and authoring paths toward level-spec lookups while leaving legacy wrappers available during migration.
* Keep the content registry pure runtime data so it does not pull renderer or PixiJS imports into shared route chunks.

### Out of Scope

* Adding new persisted IDs.
* Splitting all catalogs into new modules before expansion work requires it.
* Adding real new content.

***

## Detailed Plan Notes

* This session makes catalog/save-schema drift impossible to ship before adding content.
* Runtime ID coverage is currently split: protocol IDs are duplicated in `save-schema.ts:74`, terminal IDs inline at `save-schema.ts:141`, enemy kinds in `runtime/entities.ts`, `runtime/types-entities.ts`, and `save-schema.ts:391`, and theme IDs inline at `save-schema.ts:411`.
* Validation must verify every level reference points at a known runtime catalog entry: theme, enemy, protocol, prefab, terminal, objective, music, ambience, pickup, and boss/finale ownership where applicable.
* Save-schema parity tests must cover persisted runtime IDs: `AiRogueEnemyKind`, `AiRogueSectorThemeId`, `AiRogueProtocolId`, and `AiRogueTerminalId`.
* Account for current schema shape accurately: protocol and enemy have named local schemas, while terminal and theme are inline enums today.
* Reusable catalogs stay separate from level assembly. Catalogs define reusable things; `content/levels.ts` decides when a floor uses them.
* Remove rotating depth helpers from authoring paths. They can remain as compatibility wrappers during migration, but tests should prefer level-spec lookups.
* A content author should be able to inspect one level spec to understand a floor's identity, generation profile, encounter guarantees, rewards, audio, and finale status.

***

## Prerequisites

* [ ] Session 02 routes authored depth decisions through level specs.
* [ ] Save-schema tests and registry tests are runnable locally.

***

## Deliverables

1. Registry validation tests with clear failure messages for unknown references.
2. Save-schema parity tests for runtime IDs that can be serialized.
3. A validated split between reusable catalogs and level assembly.

***

## Success Criteria

* [ ] A deliberately invalid enemy, theme, terminal, protocol, prefab, music, or ambience reference fails a registry test.
* [ ] A deliberately missing save-schema enum value for a persisted ID fails parity coverage.
* [ ] Build and budget checks remain clean if import shape changes.
* [ ] Old IDs remain loadable as hidden compatibility entries if content is retired.


---

# 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_03_registry_validation_and_save_parity.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.