# V38 Phase 1 Review Memo

## Status
- Date: 2026-02-19
- Scope: inventory + classification only
- Phase gate: stop after review package (no Phase 2 execution, no cutover work)

## Deliverable Coverage
- Matrix delivered: `docs/src/contrib/v38-parity-matrix.md`
- In-scope module inventory classified: `125 / 125`
- Secondary-reference inventory captured (not first-pass classified):
  - `engine/tests/integration`: 4
  - `engine/tests/loaders`: 4
  - `engine/tests/ir`: 12

## Acceptance Check Results
1. Every legacy module in scope present exactly once: **PASS** (`125` rows for `125` modules).
2. No `PORT_*` row without `target_v38_test_path`: **PASS** (`0` missing of `85` port rows).
3. Every `RETIRE_*` row includes architecture rationale: **PASS** (all retire rows include one-sentence rationale tied to v38 design choices).
4. Risk-ranked gap list + recommended Phase 2 entry slice included: **PASS** (see sections below).
5. No cutover tasks included in Phase 1 output: **PASS**.

## Coverage and Mapping Summary
- In-scope legacy modules: `125`
- Ported intent (`PORT_DIRECT` + `PORT_ADAPT`): `85`
- Retired intent (`RETIRE_*`): `40`
- Direct ports already backed by existing v38 tests: `13`
- Planned target modules required for `PORT_ADAPT` backlog: `12`

## Top 5 High-Risk Unmapped Capability Clusters

### 1. VM Provisioning/Planning Pipeline Rewrite
- Evidence: 23 mapped modules in this cluster; 15 high-risk; majority `PORT_ADAPT`.
- Why high risk: legacy planning receipts and provisioner classes were reshaped into vm38 resolver + side-effect planning semantics.
- Typical impacted tests: `engine/tests/vm/planning/*`, `engine/tests/vm/provision/*`, and vm integration tests that depended on old planning object graphs.
- Primary v38 anchors:
  - `tangl.vm.dispatch.do_provision`
  - `tangl.vm.provision.Resolver.resolve_dependency`
  - `tangl.vm.provision.Requirement`

### 2. Story Fabula Compiler/Materializer Migration
- Evidence: 28 modules; 13 high-risk; many script-manager and world-materialization tests require remapping.
- Why high risk: legacy `ScriptManager`/manager stack is replaced by `StoryCompiler` + `StoryMaterializer` and init-mode reports.
- Typical impacted tests: `engine/tests/story/fabula/test_script_manager*.py`, `test_world_*`, `test_template_*`.
- Primary v38 anchors:
  - `tangl.story.fabula.StoryCompiler.compile`
  - `tangl.story.fabula.StoryMaterializer.create_story`
  - `tangl.story.fabula.World.from_script_data`

### 3. Story Episode Journaling and Choice Availability Semantics
- Evidence: 17 modules; 11 high-risk; heavy `PORT_ADAPT` around block pipeline/order/conditions.
- Why high risk: story38 centralizes output through journal handlers and vm38 phase contracts; legacy dialog/post-process/menu behavior does not map 1:1.
- Typical impacted tests: `engine/tests/story/episode/test_block*.py`, `test_menu_block.py`, `test_complex_conditions.py`.
- Primary v38 anchors:
  - `tangl.story.system_handlers.render_block`
  - `tangl.story.system_handlers._choice_unavailable_reason`
  - `tangl.vm.system_handlers.contribute_satisfied_deps`

### 4. Service Contract Consolidation onto Service38 Gateway/Orchestrator
- Evidence: 13 modules; 6 high-risk; legacy response-model tests include retired contract assumptions.
- Why high risk: endpoint/orchestrator behavior survives, but response/info-model contract focus shifts toward service38 operation + runtime-envelope patterns.
- Typical impacted tests: `engine/tests/service/test_orchestrator*.py`, `test_api_endpoints.py`, response contract tests.
- Primary v38 anchors:
  - `tangl.service.orchestrator.Orchestrator.execute`
  - `tangl.service.api_endpoint.ApiEndpoint.annotate`
  - `tangl.service.gateway.ServiceGateway.execute`

### 5. VM Replay Simplification (Watcher/Observer Model Retirement)
- Evidence: 6 replay/event-model modules; 4 retired; remaining 2 require adaptation to diff-patch MVP.
- Why high risk: legacy event-sourcing watcher assumptions are intentionally deprecated; replay confidence now depends on patch/checkpoint invariants.
- Typical impacted tests: `engine/tests/vm/events/test_watched.py`, `test_event_canonicalize.py`, `test_stack_event_sourcing.py`.
- Primary v38 anchors:
  - `tangl.vm.replay.DiffReplayEngine.build_delta`
  - `tangl.vm.replay.Event.apply`
  - `tangl.vm.runtime.ledger.Ledger.save_snapshot`

## Proposed Phase 2 Candidate Scope (Proposal Only)
No lock or execution implied; this is a review-time recommendation for the first implementation slice.

### Candidate slice: “Runtime correctness spine”
1. VM replay and planning baseline:
   - Cover diff replay/patch/checkpoint invariants.
   - Port high-value provisioning/planning integration intent into vm38 tests.
2. Story episode correctness:
   - Port block/choice/availability/journal-order behavior into story38 tests.
   - Retire menu-block and legacy post-process/dialog couplings explicitly.
3. Service38 backbone:
   - Port orchestrator/api-endpoint/user/runtime controller core tests into service38-targeted modules.
   - Retire legacy response-contract assumptions not used by service38 gateway/runtime envelope.

Suggested first Phase 2 output target modules:
- `engine/tests/vm38/test_provision_pipeline.py` (planned)
- `engine/tests/vm38/test_call_stack.py` (planned)
- `engine/tests/story38/test_choice_availability.py` (planned)
- `engine/tests/story38/test_journal_order.py` (planned)
- `engine/tests/service38/test_orchestrator.py` (planned)
- `engine/tests/service38/test_api_endpoint.py` (planned)

## Explicit Stop Gate
Phase 1 package is complete at this point. Work should pause here for review approval before any Phase 2 implementation activity.