# 06 — Rollout Plan

Three phases. Each has explicit deliverables, exit criteria, and what it
unblocks downstream. Phase boundaries are merge points, not just dates.

## Phase 1 · MVP slice

**Goal:** prove the composer's surface end-to-end with the smallest viable
implementation. Surfaces stable enough that downstream blocks can extend without
reshaping.

**Estimate:** ~2 weeks.

**Blocks shipped:**

| Block | Scope in phase 1                                                                                                                                                          |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A     | Minimal — only the `approveCheckpoint` API + `AWAITING_APPROVAL` state + auto-approve timeout policy. No persistence yet (in-memory). No `escalation-handler`.            |
| B     | Composer with **explicit prompts only** for `ObjectSpec`. Transform-only output (no bake). In-process providers. No grounding required (skipped if adapter not supplied). |

**Deliverables:**

- `libs/isis/operation-orchestrator/src/checkpoint/` (in-memory only).
- `libs/isis/scene-from-image-composer/` library scaffolded and exported.
- `composeSceneFromImage` and `createSceneFromImagePipeline` public APIs
  callable.
- Manifest extension (`metadata.sceneFromImage.placements`) shipped.
- `align-mesh-to-splat-frame.ts` + tests.
- E2E test: composer with fixture providers produces a manifest with splat + 1
  mesh + 1 placement transform + (optional) ambient SFX + preview thumbnail.
- README documenting both APIs.

**Exit criteria:**

- All phase 1 tests pass.
- `npx tsc --noEmit` clean.
- Stub-indicator scan clean.
- A manual end-to-end run with **real Marble** + **fixture mesh provider**
  - **fixture SFX** completes in < 10 min and produces a valid manifest.
- The composer's public API is signed off (no breaking changes anticipated);
  downstream blocks can be developed against it.

**What this unblocks:** every other block. Phase 2 starts immediately.

---

## Phase 2 · Thorough version

**Goal:** every gap from `02-gap-analysis.md` closed. Composer produces a single
composed `.spz` with consistent lighting, full object-source flexibility,
persistent state, and resume-from-checkpoint.

**Estimate:** ~10 weeks. Several blocks parallelisable (see DAG).

**Blocks shipped:**

| Block | Scope in phase 2                                                                                                                                                                                     |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| C     | Full — all four object-source modes; foreground detection subphase; IoU merge; foreground/background classifier; cost estimator; `MeshProviderRouter`; full `AnchorSpec` DSL with constraint solver. |
| D     | Full — bit-exact `.spz` encoder + decoder, validated against Niantic reference.                                                                                                                      |
| E     | Full — surface-sampling baseline + hybrid path (with CPU reference rasteriser; GPU dispatch in phase 3). Splat merging with depth sort + occlusion cull + dedupe. `bake-phase` in composer.          |
| F     | Full — environment SH light field estimation; PBR shading at sample time; composition coherence gate.                                                                                                |
| H     | Full — Postgres-backed pipeline state via Prisma; `resumePipeline` API; in-memory implementation kept for tests.                                                                                     |

**Parallel work groups:**

- Group A (sequential): block C → block I integration prep
- Group B (sequential): block D → block E baseline → block E hybrid → block F
- Group C (independent): block H

Three engineers can work in parallel on the three groups.

**Deliverables:**

- All blocks above ship their files per their respective block plans.
- E2E test matrix from `05-test-strategy.md` rows 1–14 + 16 pass.
- Visual QA: composer-produced composed `.spz` loads in
  `mkkellogg/GaussianSplats3D` viewer with meshes correctly placed and lit.
  Screenshot in PR.
- Performance: end-to-end real-provider single-mesh run completes in < 15 min.

**Exit criteria:**

- All phase 2 tests pass; CI green.
- Composer can run unattended via `auto-approve` checkpoint policy and produces
  a fully baked `.spz` in a single artefact.
- Persistence verified via SIGKILL-resume test.
- Composition coherence gate scores > 0.85 on benign reference inputs.

**What this unblocks:** production deployment (after phase 3).

---

## Phase 3 · Production hardening

**Goal:** composer runs at scale. GPU work off the BFF, full observability,
policy enforcement, anomaly drift watch, agent-consensus checkpoints,
load-tested.

**Estimate:** ~6 weeks.

**Blocks shipped:**

| Block | Scope in phase 3                                                                                                                                          |
| ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| G     | Full — job-envelope dispatch for all heavy phases; Redis channel; per-handler implementations; composer's `dispatchMode: 'job-envelope'`.                 |
| I     | Full — gallery registration; lineage edges; budget enforcer; license compliance via `model-governance-3d`; anomaly sampler; consensus checkpoint handler. |

**Plus:**

- Reference corpus runs (20 images from `05-test-strategy.md`) on real
  providers; baseline metrics recorded.
- Load test: 50 concurrent composer runs against staging; assert no BFF
  saturation, no Postgres connection leaks, no Redis backlog.
- Documentation: production runbook covering Marble API key rotation, Hunyuan
  rate limit handling, ElevenLabs SFX cost monitoring, Postgres maintenance.

**Exit criteria:**

- All phase 3 tests pass.
- Dispatch via Redis works end-to-end with a real GPU worker pool.
- Budget cap halts a composer run at the next checkpoint when exceeded (asserted
  via real-provider integration test).
- License gate halts a composer run when the destination license is incompatible
  (asserted).
- Load test sustains 50 concurrent runs for 1 hour without errors or resource
  leaks.
- Composer runs surface in the gallery UI with thumbnail + lineage trail.
- Consensus checkpoint policy completes a fixture-driven 3-agent decision.

**What this unblocks:** general availability of the composer to other domains
(Yemaya for creative production, Hathor for worldbuilding assets, Bellona for
engine-ready content, Lilith for meditation visuals).

---

## Phase boundaries — what doesn't move between phases

- **API stability.** Phase 1 freezes the public API. Phases 2 and 3 only add
  fields, never reshape. If a phase 2/3 design surfaces a breaking change
  requirement, it gets a new minor version and parallel-ship.
- **Test corpus growth.** Phase 1 ships 5 fixture images; phase 2 grows to 15;
  phase 3 reaches the full 20 + real-provider nightly suite.
- **Performance budgets.** Phase 1 = correctness only. Phase 2 = unit-test perf
  targets. Phase 3 = end-to-end load targets.

## Risk-weighted phasing

The phasing above optimises for **shippable utility**: phase 1 produces a usable
transform-only composer; phase 2 produces a usable single-`.spz` composer; phase
3 makes it production-grade. If any phase slips, the preceding phase still
ships.

Alternative phasing considered and rejected:

- **A → C → B → E → D → F → G → H → I** (foundation-first): would push shippable
  composer artefact 4–5 weeks later. Not worth it.
- **D first** (codec before everything): would let phase 1 ship baked output.
  But block D's reference corpus dependency is fragile and could block phase 1.
  Better to keep transform-only as the phase 1 stop-gap.

## Schedule sensitivities

The schedule will slip if:

- **Niantic `.spz` reference is harder to obtain or interpret** than expected
  (block D, +1–2w).
- **Differentiable splat fitting** doesn't converge cleanly on real meshes
  (block E hybrid path, +1–2w).
- **Lighting consistency** needs path-traced fallback rather than the SH
  approximation (block F, +1–2w).
- **GPU worker integration** surfaces unforeseen Redis/job-envelope deltas
  (block G, +0.5–1w).

Each of these is called out in `07-risks-and-open-questions.md`.

## Phase parallelism in practice

Phase 2 expects three concurrent work streams. Concretely:

- **Engineer 1 (composer-side):** blocks C → bake-phase wiring in composer →
  coherence-gate wiring in composer → dispatch-mode wiring.
- **Engineer 2 (splat-side):** blocks D → E baseline → E hybrid → F.
- **Engineer 3 (orchestrator-side):** block H → consensus-checkpoint-handler
  prep for I.

If only one engineer is available, phase 2 timeline expands to ~16–18 weeks.
Phase 3 contracts somewhat because most of its work piggybacks on finished
blocks.

## Definition of "shipped" per phase

Phase exits when:

1. All block-level acceptance criteria are met (per each `block-plans/*.md`).
2. The phase's exit-criteria tests pass on `oshun-lt-2-hetzner` and `main`.
3. Per `oshun_commit_policy`: every task committed and pushed via the two-line
   push convention.
4. PR description summarises every block's contribution with links to its
   block-plan doc.
5. Visual QA recordings (where required) attached.
6. `ISIS_GAPS_TODOS.md` boxes for the phase's tasks all checked.
