Eve library

06 — Rollout Plan

Other

Revision 1

On this page

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.