Correction-batch surfaces: creation, corrections, and asset→batches (G1, G2, G7)

[JArmandoAnaya]

Task 9 of the 2026-08 checkpoint audit remediation. Closes G1/F22, G2/F19, G7.

Three surfaces, and the contract wired them together first

Adding create_correction to BatchAction turned four squares of the batch capability matrix red before any surface existed — tests/kernel/test_capabilities.py demands an executable path for every declared action. That is the suite doing exactly what #304 built it for.

Surface	Audit	Shape
Create a batch from a chosen asset set	G1	POST /projects/{id}/batches + create_batch (MCP)
Correct a completed batch	G7	POST /batches/{id}/corrections + create_correction_batch (MCP)
Which batches hold an asset	G2	GET /projects/{id}/assets/{id}/batches

The correction model

CORRECTABLE_STATES = {completed}. A completed batch has no exit in BATCH_TRANSITIONS and none is coming, so changing settled work means a new batch over the same assets carrying lineage back to it. Correcting an open batch is not a correction — it is the work, and it happens in the batch that is already there.

The set is its own rather than shared with PROMOTABLE_STATES, which has the same membership today. They ask different questions — is this finished enough to enter the trunk versus is this closed to further work — and a fifth state would not necessarily answer them alike.

asset_ids defaults to the parent's whole membership, because "correct this batch" is the ordinary ask and re-listing forty-eight ids to say so is a worse API than a default. Every id given must be one the parent carried — otherwise the lineage is a claim about nothing. That refusal is the new AssetNotInBatch.

The child pins the active schema at its own approval, not the parent's. That is the point of correcting under a contract that has moved on, and it is the ordinary approval mechanism rather than anything new — asserted, because it is the behaviour somebody would be tempted to "fix" by copying the parent's pin.

The port grew its first non-repository read

Repository is deliberately one parent_id filter — "no query language leaks into the port". Membership is a join table with a composite key, and every scoped read the repositories serve runs from a batch to its assets. This is the same edge backwards, which has no parent to filter on.

So UnitOfWork.batches_holding(asset_id) -> list[UUID] is a named method on the unit of work, not a widened Repository[Batch] — that protocol is generic over every entity, and a batch-specific lookup on it would appear on projects and releases and tokens as well. Ids rather than entities, for the reason member_asset_ids returns ids; BatchService.holding hydrates for the callers that want it.

Decisions taken autonomously

• BatchCreate and BatchCorrection are two models, because an empty asset_ids means no assets on one and the parent's whole membership on the other. One field meaning two opposite things across two routes is worse than two models.
• Corrections are a sub-resource of the parent (POST /batches/{id}/corrections) rather than a flag on the create route: the parent is what decides, which is exactly what the capability declares.
• AssetNotInBatch is 422, not 404 — unlike its sibling AssetNotInJob. That one is usually reached through a path segment; this one only ever arrives in a list, which makes it a payload problem.
• G2 is a dedicated route, not a field on AssetOut — a listing of fifty thousand assets would pay one join per row for a fact almost no reader of that listing wants.
• holding is declared above list — a method named list shadows the builtin for every annotation after it in the class body, so -> list[Batch] below that point fails to typecheck. mypy caught it; the module's own ordering rule predicted it.

#281 is referenced and not closed

That issue wants membership editing — DELETE /batches/{id}/assets on a draft, so the gallery's bulk bar can offer "Delete frames". This adds creation. The two overlap in motivation and not in surface.

Found, not fixed: edit_membership is a declared capability with no wire surface behind it. That is the same "declared but unreachable" shape F24 was, and it is #281's to close.

One test premise corrected mid-task

I wrote an HTTP test asserting an asset in no batch answers an empty page, and it failed: IngestService.ingest always puts what it gathered into a batch, whether or not the caller named one, so an orphan asset is unreachable through the API. The HTTP test now pins that fact, and the empty-page case moved to test_batch_service.py, where it can actually be built.

Test plan

All four suites:

• bash scripts/check.sh — green (2140 python, vitest 489, annotator 764, 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: 4 route tests for creation, 5 for corrections (including the full open-state refusal matrix, asserting the declaration and the refusal agree), 4 for the reverse lookup, 6 correction-batch kernel tests (subset, refusal, schema pin, correction-of-a-correction), 3 reverse-lookup kernel tests, and the create_correction square of the capability matrix across all four batch states.

New test module tests/server/test_assets.py. MCP registration list gains both tools.