Correction-batch prerequisites: batch lineage and annotation provenance (G3, G4)

[JArmandoAnaya]

Task 8 of the 2026-08 checkpoint audit remediation. Closes G4 (F21) and G3 (F20). The first migrations since the chain was collapsed — FORMAT_VERSION 1 → 3.

Two facts, recorded before anything needs them

Column	Answers	NULL means
batch.parent_batch_id	which batch this one was cut from	not a correction of anything — complete
annotation.job_id	which round of work produced this label	genuinely unknown

They land now rather than with the feature because the alternative is discovering at that point that recording them takes a migration.

The backfill is honest about what it cannot know

An annotation records only its asset_id; a job records which assets it carries. So a label whose asset belongs to exactly one job can be attributed with certainty, and one whose asset is carried by two cannot be attributed at all — because the schema never recorded which. The UPDATE sets a value only where the count is one.

Writing "the first job we found" would put a confident wrong answer where an honest absent one belongs, and nothing downstream could tell which it had. It is also guarded on job_id IS NULL, so a re-run cannot overwrite an attribution a service has since written — which matters because migration 1 is create_all of today's metadata, so a fresh database already carries the column and runs the migration anyway.

Neither column is a foreign key, and neither had a choice

Both arrive by ALTER TABLE, which cannot express a key the way create_all does, and neither table can be rebuilt to escape that:

• batch carries batch_asset children whose ON DELETE CASCADE a DROP TABLE would follow silently under PRAGMA foreign_keys = ON;
• annotation is not empty in any workspace that has ever been annotated.

A rebuild is available only for a table that is childless and provably empty. asset.source_id is the precedent, and both new columns record the same debt: a future delete of a parent has to clear them itself and say so.

The fresh-vs-migrated test comes back

test_a_fresh_database_and_a_migrated_one_have_the_same_schema is the comparison that catches a column declared in the wrong position — nothing else in the suite would notice, because each creation path is internally consistent. It was reduced to a tautology when the chain collapsed; a second generation restores it.

It builds its generation-1 file by dropping the two columns rather than by walking a current one backwards: there are no downgrade paths, and inventing one here would be inventing the thing under test. Dropping works for exactly the reason the columns are shaped as they are — SQLite refuses to drop a column carrying a key.

The service stamps, and update stamps the replacing job

job_id is stamped exactly as schema_version is. Without it the column would only ever hold what the migration could reconstruct.

On update, job_id and asset_id deliberately go opposite ways. asset_id keeps the stored value, because relocating a label is a delete and an add rather than an edit. job_id takes the replacing job, because it answers which round produced the label as it now stands — preserving the original would make it mean "first written in", which goes stale the moment a correction round edits.

This is a fact about who wrote a label, not a policy about which label wins in the trunk. G5 (trunk supersession) is untouched and remains the halt condition it was.

A new server field is not automatically additive — and this is the proof

@visionset/annotator's parseAnnotation checks the key set exactly (that is what #73 built it for), so a payload carrying a field the TS mirror omits is refused outright, not ignored. job_id had to land in three places at once: AnnotationOut, the annotator's Annotation, and ui-core's WireAnnotation.

draftAnnotation mints it null — the engine takes a document, not a workflow, and has no idea which job it is being driven inside.

Decisions taken autonomously

• Two migrations, not one. Each is one fact with its own backfill argument; a combined one would make the ambiguity note apply to a column that has none.
• job_id on the wire read model only — absent from AnnotationCreate/AnnotationUpdate, on the schema_version precedent.
• update stamps rather than preserves (above).
• samples.py carries populated values for both, because that module holds fully populated instances on purpose: a None where a value belongs lets that projection go unchecked.

Found, not fixed

• Nothing reads either column yet — no correction-batch creation surface (G1, T9) and no asset→batches reverse lookup (G2, T9).
• annotation.job_id is unindexed. Nothing queries by it; the one future caller (labels of a round) would go through the job's assets.

Test plan

All four suites:

• bash scripts/check.sh — green (python, vitest 489, annotator 764, all linters, import-linter, openapi + generated-client + wire-fixture + mcp drift).
• CI=1 npx playwright test — 176 green.
• CI=1 npx playwright test -c playwright.cycle.config.ts — green.

New: 5 migration tests (fresh-vs-migrated equivalence; the backfill attributing a single-job label; leaving an ambiguous one alone; not overwriting on a second run; lineage starting null), 4 annotation-service tests (stamped on add, caller cannot claim otherwise, stamped on update while asset_id is preserved, survives a store round-trip), 3 batch-lineage tests, 3 wire-serialization tests.

_DECLARED_TAILS gains both tables — the column-order guard the migrations module's rules exist for, and the one that turns from tautology back into a real check now that a second generation exists.