kernel: AnnotationService — schema-validated writes (hard reject: unknown class, disallowed geometry, missing required attribute), provenance, UUID identity

[JArmandoAnaya]

Context

Severity policy (vision doc, decision F): schema violations are a hard reject at write
time, in the kernel — never delegated to the UI's good faith.

Body updated 2026-07-27 to match what #6/#8/#9 actually shipped — see the reconciliation
comment below for the diff against the original.

Deliverables

• add/update/delete annotations(job, [annotation]) — validates against the batch's pinned
  schema version: class exists, the annotation's geometry type matches the class's
  geometry (singular — one geometry per class, per kernel: SchemaService — monotonic immutable versioning, additive/destructive change classification, LabelClass/Attribute/allowed_geometries validation #6), required attributes present
  and type-correct.
• Annotation.attributes carrier: neither the model field nor the column exists today —
  this task adds the field (values keyed by attribute name) and migration 5 for the column
  (idempotent, shared schema object, _downgrade_to_version_one entry — the migration rules
  in adapters/migrations.py).
• Provenance rules enforced: model requires model_ref; confidence ∈ [0,1]
  (already in the domain model — the service must surface them as clean domain errors,
  not raw pydantic ValidationErrors).
• UUIDs generated server-side at creation if absent; updates address by UUID only.
• Batch gate: writes into a batch that is not in_annotation raise the existing
  BatchNotInAnnotation — do not add a second error for the same rule (kernel: JobService — states pending→in_progress→completed, per-asset progress (unannotated|annotated|skipped|review_pending|accepted), schema version pinned per batch #9 convention).

Out of scope (moved by #9)

Progress is marked explicitly via JobService.mark_progress, never recomputed by this
service. Open decision for this task's plan: whether mark_progress(annotated) should
start requiring ≥1 stored annotation on the asset — decide and record it, either way.

Acceptance criteria

• Each violation class has a dedicated error type + test
• Writing to a job whose batch is not in_annotation is rejected (BatchNotInAnnotation)
• Update/delete by UUID; unknown UUID is a clean domain error
• Migration 5 idempotent; fresh-vs-migrated schema equality test still green

[JArmandoAnaya]

Heads-up from #10 (PR #72): the geometry union's discriminator values are GeometryType members, not parallel string literals — Annotation.geometry.type is a real GeometryType.

So the "geometry ∈ allowed_geometries" rule here is a direct membership test with no translation layer:

if annotation.geometry.type not in label_class.allowed_geometries:
    raise DisallowedGeometryError(...)

tests/kernel/test_geometry.py::test_geometry_type_is_comparable_to_a_label_class_without_translation pins that property against today's singular LabelClass.geometry; it should be updated to the plural field once #6 lands.

[JArmandoAnaya]

Plan reconciliation (2026-07-27) — supersedes the 2026-07-26 comment above

Roadmap audit against what #6/#8/#9 actually merged. The body has been updated; the diff:

1. LabelClass.allowed_geometries (plural) never shipped. kernel: SchemaService — monotonic immutable versioning, additive/destructive change classification, LabelClass/Attribute/allowed_geometries validation #6 landed
   LabelClass.geometry: GeometryType — one class, one geometry, deliberately. The
   membership test in the earlier comment collapses to an equality check:
   annotation.geometry.type != label_class.geometry → DisallowedGeometry. The pinned
   property test (test_geometry_type_is_comparable_to_a_label_class_without_translation)
   already matches the singular field — no update needed there.
2. Annotation.attributes does not exist — no model field, no column. "Required
   attributes present and type-correct" needs a carrier, so this task includes the field
   plus migration 5 (follow the migration rules: idempotent via inspector,
   shared schema object, _downgrade_to_version_one entry).
3. The "progress recomputation hook" is dead. kernel: JobService — states pending→in_progress→completed, per-asset progress (unannotated|annotated|skipped|review_pending|accepted), schema version pinned per batch #9 made progress an explicit
   JobService.mark_progress op with no-op semantics on same-state writes. This service
   validates at write time; it does not touch progress. The one open question moved to the
   body: should mark_progress(annotated) require ≥1 stored annotation?
4. Batch gate reuses BatchNotInAnnotation (exists since kernel: JobService — states pending→in_progress→completed, per-asset progress (unannotated|annotated|skipped|review_pending|accepted), schema version pinned per batch #9) — the one error for "no
   work happens in a batch nobody opened".