> 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-session01-baseline-and-registry-skeleton/spec.md).

# Session Specification

**Session ID**: `phase39-session01-baseline-and-registry-skeleton` **Phase**: 39 - AI Rogue Level Authoring Infrastructure **Status**: Not Started **Created**: 2026-06-30

***

## 1. Session Overview

This session locks the current shipped AI Rogue three-floor run before any depth routing moves. It adds behavior-preserving tests for floor identity, generated world shape, first-turn run state, and Kernel Sentinel presentation so later registry and resolver work has a stable safety net.

It also creates the initial dead-but-tested `src/extensions/ai-rogue/runtime/content/` registry. The registry captures the current three playable levels as typed source data, validates structural authoring rules, and exposes `levelSpecForDepth(depth)` with an explicit authored-main-run out-of-range policy without changing existing runtime callers.

This is next because Phase 39 Session 02 depends on these baselines before routing `themeForDepth()`, `floorArcForDepth()`, world generation, terminal, prefab, protocol, and music decisions through level specs.

***

## 2. Objectives

1. Add focused baseline coverage for depth 1-3 floor identity, routing values, objective data, audio, ambience, terminal, prefab, and guard behavior.
2. Add deterministic golden coverage for stable depth 1-3 world shape and first-turn run state using safe public runtime fields only.
3. Add the initial pure runtime content registry and structural validator for the three current playable levels.
4. Extend Kernel Sentinel presentation coverage without changing shipped boss, render, combat, audio, or runtime routing behavior.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase38-session10-hunk-reconciliation-and-release-gate` - Phase 38 closed with AI OS semantic port validation and no open security findings.

### Required Tools Or Knowledge

* Bun 1.3.14 package/runtime baseline.
* Vitest runtime test patterns under `src/extensions/ai-rogue/runtime/__tests__/`.
* Current AI Rogue depth helpers in `themes.ts`, `floor-arc.ts`, `protocols.ts`, `prefabs.ts`, `terminals.ts`, `world-generator.ts`, `world-placement.ts`, `audio.ts`, and `run-factory.ts`.

### Environment Requirements

* Local repository checkout with dependencies installed or installable through `bun install`.
* Validation commands available through `bun run typecheck` and `bunx vitest run`.

***

## 4. Scope

### In Scope (MVP)

* AI Rogue maintainer can detect accidental drift in the current three playable depths before registry migration starts - add content-baseline tests for theme, floor arc, exit guard, baseline protocol, guaranteed protocol, terminal, prefab, music, ambience, and objective routing.
* AI Rogue maintainer can detect deterministic generation drift for the current three floors - add golden tests that compare safe public world shape and first-turn state for fixed seeds.
* Future content author can inspect one typed source of level identity - add `AiRogueLevelSpec` contracts and three specs that reproduce current floors without changing runtime callers.
* Future content author gets fast failure for malformed registry structure - add validation for unique IDs, contiguous 1-based depths, non-empty enemy tables, local references used by Session 01, finale placement, and safe labels/lessons.
* Kernel Sentinel baseline stays explicit before boss generalization - extend presentation tests for frame selection, reveal, hit, telegraph, attack, shutdown, scale, and audio metadata expectations.

### Out Of Scope (Deferred)

* Routing runtime callers through `levelSpecForDepth()` - Reason: Session 02 owns migration once baselines are in place.
* Adding a fourth floor - Reason: Session 04 proves level authoring after registry and save parity gates exist.
* Adding new enemies, bosses, terminals, protocols, music, ambience, assets, or persisted IDs - Reason: later Phase 39 sessions own content expansion and save-schema parity.
* Changing current clamp or rotation behavior in existing helpers - Reason: this session records current behavior and keeps runtime callers unchanged.
* Route-visible UI, PixiJS renderer import changes, public demo changes, remote content loading, hosted writes, collectors, analytics, or telemetry - Reason: Phase 39 registry work must stay pure runtime data and local-only.

***

## 5. Technical Approach

### Architecture

Create `src/extensions/ai-rogue/runtime/content/` as a pure TypeScript runtime data module. `types.ts` owns `AiRogueLevelSpec` and related content contracts, `levels.ts` owns `AI_ROGUE_LEVEL_SPECS`, `validate.ts` owns structural validation, and `index.ts` exposes registry APIs for tests and future migration work.

The new registry imports only existing runtime type/catalog modules. It must not import React, route code, PixiJS renderer modules, browser storage, local bridges, or generated data. Existing runtime helpers remain the authoritative production path during this session.

Baseline tests should use current helper outputs and generated world/run summaries. Golden values should serialize bounded, deterministic fields such as theme, start/exit, tile kind/frame summaries, spawn summaries, pickup summaries, player baseline, objective, event types/messages, and first-turn counters. They should avoid raw private paths, prompts, transcripts, logs, credentials, or local operator data.

### Design Patterns

* Dead-but-tested registry: Adds typed data and tests before wiring runtime callers, reducing migration risk.
* Safe public-shape snapshots: Captures deterministic behavior while avoiding private or generated local data.
* Compatibility-first exports: Existing helpers and tests stay available; future wrappers are planned but not introduced here.
* Pure validation helper: Returns structured validation results with actionable messages so later content changes fail fast.

***

## 6. Deliverables

### Files To Create

| File                                                                   | Purpose                                                                                                          | Est. Lines |
| ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------- |
| `src/extensions/ai-rogue/runtime/__tests__/content-baseline.test.ts`   | Record current depth 1-3 theme, arc, guard, protocol, terminal, prefab, music, ambience, and objective behavior. | \~170      |
| `src/extensions/ai-rogue/runtime/__tests__/golden-determinism.test.ts` | Compare safe generated world and first-turn run summaries for fixed depth 1-3 seeds.                             | \~190      |
| `src/extensions/ai-rogue/runtime/content/types.ts`                     | Define `AiRogueLevelSpec`, generation, placement, guarantee, and validation result contracts.                    | \~100      |
| `src/extensions/ai-rogue/runtime/content/levels.ts`                    | Author the three current playable level specs from existing runtime helper values.                               | \~170      |
| `src/extensions/ai-rogue/runtime/content/validate.ts`                  | Validate registry structure, local references, safe labels/lessons, and finale placement.                        | \~180      |
| `src/extensions/ai-rogue/runtime/content/index.ts`                     | Export registry APIs and `levelSpecForDepth(depth)` for tests and future migration.                              | \~40       |
| `src/extensions/ai-rogue/runtime/content/__tests__/levels.test.ts`     | Prove the initial registry validates and enforces malformed-spec failure paths.                                  | \~180      |

### Files To Modify

| File                                                                  | Changes                                                                                                                          | Est. Lines |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `src/extensions/ai-rogue/runtime/__tests__/boss-presentation.test.ts` | Extend Kernel Sentinel presentation baseline for scale and audio metadata expectations without changing implementation behavior. | \~35       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Baseline tests record current depth 1-3 values for themes, arcs, exit guards, baseline protocols, guaranteed protocols, terminals, prefabs, music, ambience, and objectives.
* [ ] Golden tests prove fixed seeds for depths 1-3 produce stable safe world summaries and first-turn state summaries.
* [ ] `AI_ROGUE_LEVEL_SPECS` contains exactly the current three playable levels at first.
* [ ] `levelSpecForDepth(depth)` returns levels 1-3 and rejects out-of-range authored-main-run depths without changing current runtime helper behavior.
* [ ] Registry validation reports clear errors for duplicate IDs, non-contiguous depths, empty enemy tables, invalid local references, unsafe text, and finale placement before the last level.
* [ ] Kernel Sentinel presentation coverage remains green for idle, reveal/charge, telegraph, attack, shielded, hit, shutdown, scale, and audio metadata.

### Testing Requirements

* [ ] New baseline and registry tests written and passing.
* [ ] Existing relevant AI Rogue runtime tests still pass without expected-output edits.
* [ ] `bun run typecheck` passes.

### Non-Functional Requirements

* [ ] New content registry remains pure runtime TypeScript with no route, renderer, bridge, generated-data, or PixiJS imports.
* [ ] Test data uses safe labels and bounded deterministic summaries only.
* [ ] No remote content loading, dynamic plugin path, hosted write path, collector, analytics, or telemetry dependency is introduced.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Primary user-facing surfaces are unchanged; no debug surface is required.

***

## 8. Implementation Notes

### Working Assumptions

* Initial registry includes exactly depths 1-3 even though `AI_ROGUE_THEME_ORDER` has five themes: `run-factory.ts` defines `AI_ROGUE_MAX_DEPTH = 3`, the Phase 39 PRD says the first registry must reproduce the current three playable depths, and Session 04 owns adding depth 4.
* `levelSpecForDepth(depth)` should reject out-of-range authored-main-run depths while existing helpers continue their current clamp or rotation behavior during this session: Phase 39 recommends explicit rejection for the authored main run, and Session 01 is scoped to dead-but-tested registry code with no runtime caller migration.
* Golden determinism should capture stable public summaries rather than whole runtime objects: privacy and security guidance prohibits raw private data, while Phase 39 requires behavior-preserving coverage for world shape and first-turn state.

### Conflict Resolutions

* Phase 39 roadmap labels baseline locking and registry skeleton as separate former steps, while the executable Session 01 stub combines them. The chosen interpretation is the stub scope, because `analyze-project.sh --json` reports `phase39-session01-baseline-and-registry-skeleton` as the first unfinished candidate and the stub explicitly combines both steps.

### Key Considerations

* Keep AI Rogue browser-local state and save schemas untouched.
* Preserve compatibility exports in `simulation.ts`, `runtime/world.ts`, and `runtime/types.ts`; this session does not remove or replace migration re-exports.
* Keep PixiJS behind route/runtime boundaries and keep the registry pure runtime data.
* Avoid broad expected-output edits to make new tests pass.

### Potential Challenges

* Baseline assertions can become brittle if they snapshot too much incidental tile data: Mitigate with targeted summaries and deterministic fixed seeds.
* Registry validation can accidentally depend on implementation-only helper behavior: Mitigate by validating source data and local catalog references, not current generator internals.
* Out-of-range rejection differs from current clamp/rotation helpers: Mitigate by limiting rejection to new registry APIs and documenting that runtime migration is deferred to Session 02.

### Relevant Considerations

* \[P35] **AI Rogue compatibility exports remain**: Preserve migration exports until direct consumers migrate and boundary tests stay green.
* \[P30/P32/P34-P35] **Route-lazy runtime ownership scales**: Keep Pixi behind the Play route/local facade and avoid renderer imports in content modules.
* \[P30/P32/P34-P35] **Schema-backed browser-local state works**: Do not persist whole level specs or touch save migrations in this session.
* \[P30/P34-P38] **Visibility gates catch real issues**: Pair focused tests and typecheck before migration widens behavior impact.
* \[P30/P32/P34-P38] **Do not widen AI Rogue capabilities without review**: Avoid remote loading, collectors, workers, hosted writes, expanded content, or rejected-art reuse.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Deterministic generated-world behavior can drift without clear failure messages.
* Registry APIs could silently accept malformed content that later breaks runtime migration.
* Test fixtures could overcapture private or incidental data instead of bounded product/runtime facts.

***

## 9. Testing Strategy

### Unit Tests

* Add `content-baseline.test.ts` for helper outputs, generated exit guard kind, baseline protocol, guaranteed protocol, terminal, prefab, music, ambience, and objective facts.
* Add `content/__tests__/levels.test.ts` for registry pass/fail validation and `levelSpecForDepth()` out-of-range behavior.
* Extend `boss-presentation.test.ts` for Kernel Sentinel scale and audio metadata expectations where existing helpers expose those facts.

### Integration Tests

* Add `golden-determinism.test.ts` using `createAiRogueWorld()` and `createAiRogueRun()` for fixed seeds at depths 1, 2, and 3.
* Re-run existing focused suites that own the affected contracts: world, simulation, floor arc, themes, prefabs, protocols, terminals, audio, and boss presentation.

### Runtime Verification

* No browser runtime verification is required because this session does not touch route-visible UI, PixiJS mounting, controls, audio unlock behavior, or public demo surfaces.

### Edge Cases

* Depth values outside 1-3 for `levelSpecForDepth()`.
* Duplicate or non-contiguous registry entries.
* Empty enemy tables.
* Invalid local references for theme, enemy, protocol, prefab, terminal, objective pickup, music, and ambience fields used by the initial level specs.
* Unsafe labels and lessons that look like private paths, command bodies, or credential-shaped strings.

***

## 10. Dependencies

### Other Sessions

* Depends on: Phase 38 completion and Phase 39 stubs.
* Depended by: `phase39-session02-depth-resolver-migration`, `phase39-session03-registry-validation-and-save-parity`, `phase39-session04-existing-media-floor-four`, and all later Phase 39 content sessions.

***

## 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-session01-baseline-and-registry-skeleton/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.