release: ingest e2e (synthetic video → 50 frames → approved batch) + 0.0.1-alpha.2 close-out

[JArmandoAnaya]

Context

M2's exit criterion made executable.

Deliverables

• e2e test/example: generate a 10s synthetic video → register source → ingest at 5 fps →
  50 assets in a draft batch → approve → partition into 2 jobs → verify progress queries.
• Idempotent re-run assertion inside the same e2e.
• Close-out: all M2 issues closed, suite green, tag v0.0.1-alpha.2.

Acceptance criteria

• e2e green locally and in CI
• Tag v0.0.1-alpha.2 pushed; milestone M2 closed

[JArmandoAnaya]

Done — PR #94, squash-merged as 56fa321. Tag v0.0.1-alpha.2 pushed (56fa321).
M2 is 8/8 and closed.

Shipped

examples/ingest_end_to_end.py — M2's exit criterion made executable, beside M1's. A generated
ten-second testsrc clip and a folder of stills in; 50 hash-deduplicated assets in an approved
batch of two jobs out, with a pollable progress row and a per-file report. Nine narrated stages:
project + schema → clip written → register_video(extraction_fps=5.0) → ingest → poll the job →
approve(BySize(25)) → re-ingest → the same clip at 1 fps → the image directory with one file
that is not an image → previews.

main(dest) -> Summary returns a frozen dataclass, so tests/examples/test_ingest_end_to_end.py
(8 tests) asserts on values rather than on stdout. CI runs it twice, as it does the SDK
example: the smoke test rides the Pytest step, and a new Ingest end-to-end example step runs the
file as a plain script. Confirmed green in the merge run on main.

Docs: docs/examples.md restructured for two examples and given an ingest walkthrough,
docs/README.md, docs/ingest.md, examples/README.md, root README.md.

No new service, domain model, error, event or migration. FORMAT_VERSION stays 10, VERSION
stays 0.0.1.dev0, no openapi.json drift. 885 tests, up from 877.

Four properties demonstrated rather than described

• A clip cannot state its total, and a directory can. processed climbs to 50 while total
  stays NULL — VideoMetadata carries no frame count by design, because it would be a guess for a
  VFR clip and the number an ingest wants is what extraction produced. The directory states 4
  before reading its first file.
• One file registered at two rates is two sources whose frames are one set. Decomposition
  parameters live on the source, so 5.0 and 1.0 over the same path are two origins — and the
  coarse run still creates nothing, because identity is content and round=up lands both grids on
  whole seconds. Verified before the assertion was written: 10 of 10 coarse frames hash-match, at
  matching timestamps. The example and the test both say this is a property of this extractor,
  not a promise the port makes about every rate pair.
• A file that is not an image is reported, not skipped. One IngestFailure (UNSUPPORTED,
  reason never repeating the name) and the run still ends completed.
• Re-ingesting a source creates nothing — into a new batch, because the first froze at
  approval.

One finding worth recording

The clip is 160×120, not the fixtures' 64×48, and that is load-bearing. testsrc moves a
little between frames; below roughly 96×72 that movement falls under what the scaler and the
encoder still resolve, and consecutive frames come out byte-identical. Content addressing then
does exactly what it promises and collapses them — the first working version of this example
reported 40 assets from 50 extraction slots: the feature working, reading as a shortfall.
Measured across six sizes on ffmpeg 8.1.2 — 64×48 gives 40/50 distinct, everything from 96×72
upward gives 50/50. The constant now carries the explanation.

Two deviations from the body, recorded

1. Scope widened from the body to the milestone. release: ingest e2e (synthetic video → 50 frames → approved batch) + 0.0.1-alpha.2 close-out #23 lists the video spine (clip → 50 assets →
   2 jobs → progress → idempotent re-run). The milestone's exit criterion says "a directory of
   images and a video", so the example also ingests stills — which is what gives the
   total=4 / total=None contrast its other half, and what makes the per-file report live.
2. This example needs ffmpeg, where the SDK one needs nothing. A video is a container wrapped
   around a codec and the only honest way to write one is the tool that reads it. It checks
   shutil.which("ffmpeg") before writing anything and exits with an install hint. The generation
   command is tests/fixtures/media.write_video's, duplicated rather than imported — that
   module is a test fixture, it imports pytest, and its answer to a missing binary is
   pytest.skip, which means nothing in a script. The stills are Pillow's work rather than a
   second copy of M1's hand-rolled PNG encoder; that also retired the now-false "Pillow arrives
   with kernel: MediaProcessor adapter — Pillow for image validation/dimensions/thumbnails #16" lines in docs/examples.md and examples/README.md.

Checks

885 passed, 1 warning in 71.99s          (up from 877)
lint-imports                Contracts: 2 kept, 0 broken.
mypy src/visionset/kernel   Success: no issues found in 51 source files
mypy src/visionset          Success: no issues found in 61 source files
ruff check .                All checks passed!
ruff format --check .       116 files already formatted
scripts/export_openapi.py   no drift
uv run python examples/sdk_end_to_end.py        green
uv run python examples/ingest_end_to_end.py     green, and green again on a re-run

CI green on the PR and on main after the merge (all three jobs).

Next: M3 — Surfaces (epic #24). Nothing in M2 remains.