kernel: BatchService — state machine draft→approved→in_annotation→completed, membership freeze, partition into AnnotationJobs (default 1, by size, by explicit segments)

[JArmandoAnaya]

Context

The Batch is the unit of annotation work. Membership is editable only in draft; approval
freezes it and partitions it into jobs.

Deliverables

• State machine draft → approved → in_annotation → completed with guarded transitions
  (invalid transitions raise).
• add_assets/remove_assets allowed only in draft.
• approve(batch, partition=...) — partition strategies: single job (default), by size
  ("jobs of N assets"), by explicit segments. Jobs are an exact partition: disjoint,
  union = batch. Schema version pinned for the whole batch at approval.
• completed is derived: batch completes when all its jobs complete; only then are
  annotated assets promoted to the Dataset (promotion itself in DatasetService).
• Asset exclusion during annotation (skipped) is a recorded decision, never a removal.

Acceptance criteria

• Transition table fully tested, including invalid moves
• Partition property test: disjointness + exact union for all strategies
• Membership mutation after approval raises

[JArmandoAnaya]

Done — PR #78, squash-merged as d622cd1.

Shipped

• kernel/services/batch_service.py — the fourth service. create / get / list / jobs / add_assets / remove_assets / approve / start / complete / delete.
• kernel/domain/partition.py — SingleJob / BySize / BySegments as a discriminated union, plus the pure partition_assets.
• kernel/domain/batch.py — BATCH_TRANSITIONS and Batch.schema_version.
• kernel/domain/names.py — normalize_name, now shared with WorkspaceService.normalize_project_name.
• Migration 3 (batch.schema_version); FORMAT_VERSION → 3.
• Seven errors: InvalidTransition, BatchNotFound, BatchNotEditable, EmptyBatch, BatchNotComplete, InvalidPartition, AssetNotFound.
• docs/batches.md; docs/persistence.md's MIGRATIONS snippet refreshed (stale since kernel: ProjectService — project CRUD, 1:1 Dataset relationship, deletion with explicit confirmation #5).

Acceptance criteria

• Transition table fully tested, including invalid moves — test_the_transition_table_is_the_whole_of_what_is_legal is parametrized over the entire BatchState square and checks each cell against BATCH_TRANSITIONS itself, so the test cannot drift from the code it guards.
• Partition property test: disjointness + exact union for all strategies — test_every_strategy_produces_an_exact_partition runs all three strategies (six instantiations) at N = 1, 2, 3, 5, 8, 13, asserting no empty segment, no asset in two segments, union equals the batch, and the batch's own order preserved.
• Membership mutation after approval raises — BatchNotEditable, parametrized over approved / in_annotation / completed, for both add_assets and remove_assets.

Decisions with lasting consequences

1. The state machine is a table in the domain, not guards in the service. BATCH_TRANSITIONS is the single fact; _require_move consults it. Adding a state means editing one dict.
2. The lifecycle is one-way — no route back to draft. The jobs are already partitioned against the pin, so reopening membership would silently invalidate work already done. Making another batch is cheap; un-freezing one is not.
3. The pin is taken at approval and never moves. A later create_version does not touch an approved batch's schema_version. Approving a project with no schema raises SchemaNotFound — inventing v1 here would be the second door kernel: SchemaService — monotonic immutable versioning, additive/destructive change classification, LabelClass/Attribute/allowed_geometries validation #6 closed.
4. The partition invariant lives in one pure function. Disjoint + exact union, established in partition_assets, not trusted to callers. BySegments is checked against the batch and names the offending ids.
5. One TaskGroup per batch, one job per segment. The group is the round of work; a later review round is a second group beside it, with no schema change.
6. skipped is a recorded decision, never a membership removal — remove_assets refuses after draft and the error says so. The progress states themselves are kernel: JobService — states pending→in_progress→completed, per-asset progress (unannotated|annotated|skipped|review_pending|accepted), schema version pinned per batch #9's.
7. Completion is derived, which means recomputed — not automatic. complete() reads the jobs and refuses while any is outstanding.
8. Batch names are normalized but not unique per project. Unlike a project, a batch is an ephemeral work unit; two "round 2" batches are a schedule, not a collision.
9. A column migration's idempotency is an inspector check, not checkfirst — SQLite has no ADD COLUMN IF NOT EXISTS. The DDL is still compiled from the Column object in _tables (via CreateColumn) so the fresh and upgrade paths cannot drift, and _downgrade_to_version_one now walks back through both migrations so the fresh-vs-migrated test still guards the mechanism.
10. Deleting a batch leaves the annotations alone. They hang off assets, not batches — deleting the unit of work must never delete the work.

Note on #7

This session was opened asking for #7 AnnotationService, and #8 was taken instead: #7's writes go into a job whose batch must be in_annotation and whose pinned schema version decides validation, and none of that existed. That pin exists now. #7 also still needs Annotation.attributes (no model field and no column today) and therefore a migration of its own.

Also: the existing comment on #7 predicts a plural LabelClass.allowed_geometries. #6 shipped LabelClass.geometry singular, so that check is an equality against the class's geometry — or SchemaService.allowed_geometries(project_id, version) for the set. The comment is stale.

Checks

uv run pytest                             307 passed
uv run lint-imports                       2 kept, 0 broken
uv run mypy src/visionset/kernel          Success: no issues found in 38 source files
uv run ruff check . / ruff format --check All checks passed / 77 files already formatted
uv run python scripts/export_openapi.py   no drift

CI: python, frontend and OpenAPI contract drift gate all green on #78.

Next: #9 — JobService.