kernel: SourceService — source registration with provenance metadata (origin, date, original framerate, parameters)

[JArmandoAnaya]

Context

A Source is the record of raw data entering the project; it is not annotatable itself — it
materializes into Assets via an IngestJob.

Deliverables

• Register image-directory and video sources with provenance: origin path/URI, registration
  date, capture params if provided; videos record original framerate + decomposition params
  used.
• List/get sources per project; a source can be ingested multiple times (idempotent — same
  params, same assets).

Acceptance criteria

• Source metadata persists and rehydrates completely
• Video source stores original fps from probe

[JArmandoAnaya]

Done — PR #90, squash-merged as ca97598

Branched from 326812b (#17). M2 is 4/8. FORMAT_VERSION 6 → 7; VERSION stayed 0.0.1.dev0, no openapi.json drift, no dependency change, no new domain event.

Acceptance criteria

• Source metadata persists and rehydrates completely — test_an_image_directory_source_persists_and_rehydrates_completely, test_a_video_source_rehydrates_its_whole_provenance, plus the store-level round trip of the ISO-8601 timestamp and the nested JSON in test_a_source_video_provenance_and_timestamp_round_trip.
• Video source stores original fps from probe — test_a_video_source_stores_the_original_fps_from_the_probe, asserted against GeneratedVideo rather than a literal.

Shipped

• domain/source.py — replaces the M1 placeholder. SourceKind (image_directory | video), frozen VideoProvenance = the port's own VideoMetadata + extraction_fps, and a Source of (kind, path, registered_at, capture_params, video). canonical_path is the one spelling of an origin.
• services/source_service.py — the ninth service and the one door to a Source: register_images, register_video, get, public require_source(uow, …), and list declared last.
• Migration 7 source_provenance — a rebuild, not an ALTER.
• docs/sources.md, plus docs/README.md, docs/persistence.md, docs/media.md, docs/examples.md and examples/sdk_end_to_end.py's header brought current.

Decisions a later session should not re-litigate

• uri → path. It holds str(Path.resolve(strict=True)). The rebuild made the rename free; after kernel: ingest pipeline — SHA-256 hashing, blob-store dedup, technical metadata extraction, materialization into a Batch #20 joins on asset.source_id it would not be. Asset.uri is a different thing and keeps its name.
• Decomposition params live on the source, not the job. "Same source, same assets" is only meaningful if the parameters are part of what the same source is. Consequence, deliberate: one clip at 1 fps and again at 5 fps is two sources.
• Registration is idempotent on (kind, path, extraction_fps) — excluding capture_params (a typo in a lens note must not fork one directory into two origins) and excluding the probed VideoMetadata (a clip replaced at a known path is still that path's source, so its provenance is refreshed in place). registered_at is never rewritten; it is the first registration.
• No unique index under that, and the gap is named rather than hidden. A duplicate source is inert today because nothing references one. kernel: ingest pipeline — SHA-256 hashing, blob-store dedup, technical metadata extraction, materialization into a Batch #20 — where asset.source_id gets a target and a race starts deciding an asset's origin — is where this needs the index. Written into the service module docstring and docs/sources.md.
• Migration 7 rebuilds source, on migration 6's terms: registered_at is NOT NULL with no honest default, and a pre-kernel: SourceService — source registration with provenance metadata (origin, date, original framerate, parameters) #18 row's kind='local_folder' is not a value SourceKind has. This supersedes the standing note that assumed an ALTER — with a rebuild the ALTER-adds-last rule has nothing to bite on, and SourceRow's docstring says so.
• Migration 7 counts ingest_job as well as source. ingest_job.source_id is ON DELETE CASCADE and the store sets PRAGMA foreign_keys = ON on every connection, so DROP TABLE source runs an implicit DELETE that takes the jobs with it silently, without raising. Migration 6 dropped a childless table and never met this. Both halves are covered by a parametrized refusal test that also asserts the rows survive.
• Source is the only domain model with validate_assignment=True, because the video is not None ⟺ kind is VIDEO rule is a model_validator(mode="after") and those do not re-run on assignment. require_video() is how it is read, so no caller grows an assert around VideoProvenance | None.
• SourceKind is an enum where DatasetChange.operation is a str: no foreign writer exists, the kernel branches on it, and the set grows deliberately. The argument is in the enum's docstring so it does not read as an oversight.
• SOURCES is now a hand-written mapper pair — _flat_mapping dumps in python mode and would hand a datetime to a String column. Seven non-flat entities now, not six.
• SourceNotFound is the only new error. A missing path is FileNotFoundError and a file where a directory was wanted is NotADirectoryError — both about the machine, both outside the VisionSetError tree, the line MediaToolUnavailable already sits on.

Two things #20 and #19 should read before starting

• register_video probes before the transaction opens. An out-of-process decoder inside a write transaction is how a single-writer SQLite store starts reporting "database is locked" (kernel: SQLite concurrency posture — WAL, busy_timeout, OperationalError → domain error (closes the "database is locked" gap before background ingest) #80). Corollary: re-registering a known clip still needs ffmpeg.
• Registration is not a validation pass. A truncated faststart clip has a readable header, so it registers successfully and records the intact duration; the damage surfaces at extraction. test_a_truncated_clip_registers_because_a_probe_only_reads_the_header pins that, so nothing downstream treats a successful registration as proof the file will decode.

Checks (local, ffmpeg required)

uv run ruff format .                        110 files left unchanged
uv run ruff check .                         All checks passed!
uv run mypy src/visionset/kernel            Success: no issues found in 49 source files
uv run lint-imports                         Contracts: 2 kept, 0 broken.
VISIONSET_REQUIRE_FFMPEG=1 uv run pytest    769 passed
uv run python scripts/export_openapi.py     no diff

CI: python / frontend / OpenAPI contract drift gate all green on #90.

Next: #20 — the ingest pipeline and IngestService. It carries migration 8 (asset format / origin / source link, ingest_job batch link), is the task that deletes _add_assets from examples/sdk_end_to_end.py, and is the first to emit IngestCompleted — flipping the tripwire tests/kernel/test_events.py has held since #13. It is also where the source uniqueness index above stops being optional.