festifun/plan/00-foundation.md

Phase 1 — Foundation (serial, one agent, branch foundation)

Scope: spec milestones M0 and M3, plus scaffolding every module as a working stub. You are building the ground the four parallel lanes stand on — bias toward correct contracts over feature depth. Nothing in the lanes can start until you merge.

Deliverables

1. M0 in full (spec): repo layout, deps, git hygiene (.gitignore before anything else), synthetic.py fixture generator (fake videos with known audio offsets + fake poses + fake point cloud + a few fake seeded events with plausible event_types so lane C can render timeline markers), pytest wired, Vite hello page.
2. DB schema (db.py) exactly as spec §2, plus tiny CRUD helpers lanes will need (get videos, upsert poses, insert events/anchors/annotations).
3. M3 API in full against synthetic data — every route from spec M3 implemented and returning real (synthetic-sourced) data, including Range-request video serving (verify curl -H "Range: bytes=0-100" → 206). Lane C will treat this API as finished.
4. Stubs for all lane-owned modules: ingest.py, audio_sync.py, frames.py, sfm.py, events_ai.py exist with the final public function signatures; bodies raise NotImplementedError (or no-op with a log line where the API/CLI would otherwise crash). cli.py registers all subcommands (synthetic|ingest|sync|reconstruct|events|serve) dispatching to those functions — lanes fill bodies only, never touch cli.py/api.py.
5. Frozen geometry contract: implement geometry.py::colmap_to_threejs(q, t) -> (position, rotation_matrix) per spec M5 math with a unit test (round-trip a known pose), and the mirrored JS helper frontend/src/lib/pose.js with the same test vectors embedded as constants. Also stub (signatures + docstrings only) slerp_pose, ray_from_pixel, triangulate_rays, nearest_point_on_ray for lane B.
6. Classifier contract: MomentClassification model + MomentClassifier protocol (spec M7) defined in events_ai.py; provider classes stubbed.
7. plan/CHANGE_REQUESTS.md created empty with a one-line format note.

Acceptance (all must pass before merging to main)

• python -m festival4d synthetic → fixture videos + populated DB + points.ply + ground-truth JSONs.
• python -m festival4d serve → every M3 endpoint returns sane synthetic data; videos seekable in a browser.
• pytest green (fixture tests + geometry conversion test).
• npm run dev serves the hello page fetching /api/manifest successfully (CORS proven).
• Spec's serial acceptance criteria for M0 and M3 all pass.