server: ingest endpoints (create source, launch ingest, progress) with long-running handling

[JArmandoAnaya]

Context

Ingest is the first long-running operation the API exposes; the pattern established here
(launch → poll) is the one the UI and MCP reuse.

Deliverables

• Register source (video upload / image upload — multipart; document size expectations),
  launch ingest with params (fps, target batch), poll progress, get result.
• Ingest execution in a background task (FastAPI/anyio) with job state persisted via the
  kernel, so polling works across requests.
• Upload writes stream to the blob path without buffering whole files in memory.

Acceptance criteria

• e2e API test: upload small generated video → ingest at 5 fps → poll to completed →
  assets listed
• Failure surfaces the kernel's structured per-file errors

[JArmandoAnaya]

Done — PR #100, squash-merged 04e9e3c, branched from 6a1e750 (#27). M3 is 6/14.

Ledger. No migration: FORMAT_VERSION stays 11, VERSION stays 0.0.1.dev0, no new error / event / domain model, and nothing added to ERROR_RULES. One new declared dependency, python-multipart>=0.0.9. 1193 tests, up from 1116. openapi.json 34 KB → 73 KB.

Acceptance criteria.

• e2e API test: upload small generated video → ingest at 5 fps → poll to completed → assets listed — tests/server/test_ingest.py::test_a_clip_uploaded_and_ingested_at_five_fps_lists_its_assets
• Failure surfaces the kernel's structured per-file errors — test_an_unreadable_item_is_reported_and_does_not_fail_the_run: the run still completed, one unsupported entry in failures, error null

The kernel was one method short of a launch-and-poll API. ingest() creates the job row and runs it, so a 202 had nothing to hand back and a refusal in transaction 1 leaves no row to poll. The vocabulary was already reserved — jobs are born pending, INGEST_TRANSITIONS allows pending → running, and resume()'s docstring names pending as "what a queued run would leave behind" — only the enqueue half was never exposed. So enqueue() is transaction 1 extracted, ingest() is now enqueue() + resume(), and all 95 existing ingest tests passed unchanged. resumable() is resume's pre-check without the work, and BatchService.assets() is what "assets listed" needed.

The rule #29/#30/#33/#35 inherit: refusals split by when they can be known. Anything the request can refuse is refused synchronously (404 unknown source, 422 blank name, 409 non-resumable job); everything after the launch is reported on the job row. batch_id targeting was deliberately left off the launch body because it was the one input that could produce a refusal with no job row to point at — #29 adds it once batches have endpoints.

Upload staging is content-addressed so SourceService's (kind, path, extraction_fps) idempotency survives the trip to HTTP: identical files under identical names reach the same <workspace>/uploads/<digest>/ and return the same Source. Registration is upload-only, which makes FileNotFoundError/NotADirectoryError unreachable — both sit outside VisionSetError and would have been 500s.

Two findings worth recording. IngestStart needs no _the_domain_accepts_it validator: that pattern earns its place only when the domain refuses with a pydantic ValidationError (a 500 via the catch-all). InvalidName is already mapped to 422 INVALID_NAME, so a validator would restate it less precisely — the first draft had one, and the test expecting VALIDATION_ERROR is what exposed it. And FastAPI emits Body_register_image_source/Body_register_video_source for multipart bodies, named off the operation id, which generate_unique_id_function already pins to the handler name.

MCP parity (#24's rule), for #35: register_image_source, register_video_source, list_sources, get_source, start_ingest, get_ingest_job, list_ingest_jobs, resume_ingest, list_batch_assets. Recorded because it does not carry over cleanly: MCP takes a local path, not multipart — the staging area exists because HTTP has no paths, and server/uploads.py must not grow an MCP caller.

Next: #29 — batch and job endpoints, the third-party-app contract. It inherits the refusal rule above, adds limit/offset and per-asset progress to GET /batches/{id}/assets (additive, by the envelope convention #27 fixed), and owns the rest of routes/batches.py.