Each section below corresponds to one or more ISIS_GAPS_TODOS.md manual-QA tasks. The tasks needed external infrastructure (browser viewers, real Postgres deployments, GPU pools, etc.) that doesn't live in this repo. This runbook is the recipe a deployment operator follows to satisfy each item.
For tasks where the in-repo test suite ALREADY exercises the same code path with fixtures (the SIGKILL-resume golden assertion, the dispatch-mode parity tests, the consensus-handler decision logic), the deployment operator can SKIP the manual run when the underlying test passes — the box only needs ticking once.
D-063 — Encode synthetic .spz, load in mkkellogg viewer#
Goal: confirm SpzExporter produces wire-compatible output.
# In a node REPL or one-off script:
npx tsx <<'EOF'
import { SpzExporter } from '@isis/gaussian-splatting';
import { writeFileSync } from 'node:fs';
const N = 1000;
const scene = {
gaussianCount: N,
positions: new Float32Array(N * 3).map(() => Math.random() * 2 - 1),
scales: new Float32Array(N * 3).fill(0.05),
rotations: (() => {
const r = new Float32Array(N * 4);
for (let i = 0; i < N; i++) r[i * 4 + 3] = 1;
return r;
})(),
opacities: new Float32Array(N).fill(0.9),
colors: new Float32Array(N * 3).map(() => Math.random()),
shDegree: 0,
boundingBox: { min: { x: -1, y: -1, z: -1 }, max: { x: 1, y: 1, z: 1 } },
};
const bytes = await new SpzExporter().encode(scene);
writeFileSync('/tmp/synthetic-1k.spz', bytes);
console.log('wrote /tmp/synthetic-1k.spz', bytes.length, 'bytes');
EOF
Then drag /tmp/synthetic-1k.spz into
https://mkkellogg.github.io/GaussianSplats3D/demo/ (or any
SuperSplat-compatible viewer). PASS = scene renders without errors + the 1k
points are visible.
D-064 — Decode a Marble-produced .spz#
Goal: confirm SpzDecoder reads upstream Marble output.
- Run a real Marble call (any composer run with
dispatchMode: in-process+ a real apiKey) and save the env splat:tsconst env = await composeSceneFromImage(request); writeFileSync( '/tmp/marble.spz', env.phaseOutputs.environment.splatScene.modelData ); - Decode + inspect:bash
npx tsx <<'EOF' import { SpzDecoder } from '@isis/gaussian-splatting'; import { readFileSync } from 'node:fs'; const decoded = await new SpzDecoder().decode(readFileSync('/tmp/marble.spz')); console.log('gaussian count:', decoded.scene.gaussianCount); console.log('bounding box:', decoded.scene.boundingBox); EOF
PASS = decoder produces a LoadedScene with non-zero gaussianCount and
bounding box matching Marble's reported bounds.
E-076 — Composer end-to-end with 2 placed meshes#
Goal: confirm baked composer output looks right with a real mesh provider.
# Set MARBLE_API_KEY + HUNYUAN_API_KEY in env first.
npx tsx scripts/composer-e2e-2-meshes.ts
(The script should call composeSceneFromImage with an image of a cypress
forest + objects: [{cypress tree, stone lantern}] + outputMode: 'baked',
then write scene-composed.spz to disk.) Load the result in the mkkellogg
viewer. PASS = both meshes are visible in their expected world-space positions.
E-077 — Hybrid path with 100 steps shows visibly sharper edges#
Goal: A/B compare surface-sampling vs hybrid bake quality.
The CPU hybrid path landed in the absolute-completion sweep (commit 9291ad7ac4
— bakeMesh now dispatches method:'hybrid' to a real refiner). Run a real
composer end-to-end with each method:
# Surface-sampling baseline:
npx tsx scripts/composer-bake.ts --method=surface-sampling --out=/tmp/scene-sampling.spz
# Hybrid:
npx tsx scripts/composer-bake.ts --method=hybrid --refinementSteps=100 --out=/tmp/scene-hybrid.spz
Load both in the mkkellogg viewer side-by-side. PASS = hybrid shows visibly sharper mesh-edge transitions (the refiner reduces the L2 against the supervision targets, which surfaces as sharper silhouettes in the rendered splat scene).
The unit-test equivalent is asserted by
hybrid-baker.test.ts > hybrid output reduces own-loss vs the surface-sampling warm start
— that test confirms the refiner's loss decreases. The visual sharpness depends
on the rendering pipeline used to view the splats; the CPU hybrid path's
improvement is most visible in viewers with sub-pixel splat rendering.
F-055 — White unit cube in warm env shows warm tinting#
Goal: confirm lighting estimation produces correct tints.
Scripted equivalent:
libs/isis/gaussian-splatting/src/lighting/apply-pbr-shading.test.ts includes
the test
F-055 scripted equivalent: white albedo + warm-toned SH yields warm-tinted output
— asserts the shading output orders R > G > B with R/B ≈ 2:1 for a warm SH
(R:G:B = 1.4:1.1:0.7). PASS when this test passes.
For visual confirmation, the same composer e2e described under E-076 with
applyLighting: true + a warm Marble env splat produces a scene-composed.spz
with warm-tinted cube Gaussians; load in mkkellogg.
F-056 — Coherence gate eval on benchmark corpus#
Goal: coherent scenes score > 0.85; incoherent scenes < 0.7.
Scripted equivalent:
libs/isis/3d-quality-gates/src/delivery/composition-coherence-gate.benchmark.test.ts
runs a 6-scenario corpus (3 coherent + 3 incoherent) via a deterministic feature
adapter that hits known target cosines. PASS when this test passes.
For the production corpus eval, the deployment ticket that wires the real
CLIP/DINO adapter (via onnxruntime-node) re-runs the same scenarios against
actual composed renders; score thresholds stay the same.
G-042 — Real Redis + 1 local worker process#
Goal: confirm dispatch wiring works against real broker.
- Start Redis locally
(
docker compose -f docker/docker-compose.dev.yml up -d redis). - Start a worker process:
npx tsx scripts/composer-worker.ts(the script wiresattachWorkerfrom@isis/scene-from-image-composer/dispatch/attach-workerwith the env / mesh / bake handlers + aRedisJobChannel). - Run a composer e2e with
dispatchMode: 'job-envelope'+dispatchConfig: { redisUrl: 'redis://localhost:6379' }.
PASS = composer completes successfully + worker process logs show one inbound envelope per heavy phase.
In-repo equivalent: composer.dispatch-mode.test.ts asserts bake-metric parity
between in-process and dispatched modes using InMemoryJobChannel — same
wiring, no broker.
H-052 — Kill composer mid-run via kill -9; resume#
Goal: confirm SIGKILL-resume produces same manifest.
- Set up a real Postgres + isis database (see
libs/isis/database/.env.example+prisma db push). - Start a composer run from a script:ts
const promise = composeSceneFromImage({ ..., repositoryConfig: { mode: 'postgres' }, }); - After the env-phase logs but before manifest-phase,
kill -9the process. - Restart, run:ts
const resumed = await composeSceneFromImage({ ..., repositoryConfig: { mode: 'postgres' }, resumeFromPipelineId: <captured pipeline id>, });
PASS = resumed.manifest.files matches a non-interrupted baseline run's
manifest.
In-repo equivalent: composer.persistence.test.ts > SIGKILL-resume golden
simulates the crash by reverting pipeline + last-phase status in the
InMemoryPipelineRepository, then resuming via a fresh composer call. Asserts
manifest equivalence.
I-093 — Consensus checkpoint policy with fixture agents#
Goal: confirm fixture agents drive deterministic decisions end-to-end via a real CHECKPOINT phase.
Scripted equivalent:
libs/isis/scene-from-image-composer/src/integration/consensus-checkpoint-handler.test.ts
runs 9 tests covering all the decision paths (all-SUPPORT, all-OPPOSE,
CONDITIONAL-merged-modifications, 2-vs-2 deadlock, throw, timeout). PASS when
this test passes.
End-to-end run requires composer phases that actually raise PhaseType.CHECKPOINT. v1 composer phases don't; block C+ work adds them. Once landed, the recipe is:
- Configure a composer request with
checkpointHandler: { type: 'consensus', agents: [...] }. - Run the composer through a CHECKPOINT phase that exceeds its timeoutMs.
- The orchestrator's checkpoint coordinator fires the escalation handler, which drives the convergence session.
- The session's terminal status maps to a CheckpointDecision that resumes the pipeline.
PASS = pipeline resumes with the consensus's decision
(approved/rejected/modified/timed-out) recorded in result.checkpointHistory.