[RyanPCo]

lance_annotations.py stages a reviewed change file under
/annotations// (meta.json last) instead of
committing it, and lance_commit --source annotations commits each staged
change, oldest first, after reviewing it again against the current
tables. One that no longer applies gets REJECTED.json and waits until it
is restaged. lance_commit is now the only writer of the Lance tables.

changes gains a provenance column (JSON): a delivery batch records each
recording's meta.json provenance, an annotation commit its approver and
source file. A changes table written before the column existed gets it
added in place (old rows read null).

https://claude.ai/code/session_01HjCQBqQCr2igFEMR7yUovw

[RyanPCo]

Automated adversarial review (read-only; findings were checked by a second skeptical pass before posting): 3 low, 1 nit.

[RyanPCo]

low (correctness): read_changes (and the annotations docstring) accept a .lance change file, so cmd_stage reviews one successfully, but stage() then calls file.read_bytes() and pq.read_metadata(file) on a directory and crashes with IsADirectoryError. Either convert first (pq.write_table(read_changes(file), tmp) and stage that file) or reject non-parquet input in cmd_stage before the review.

[RyanPCo]

low (dead-code): This migration runs on every _ensure_tables call, so every append/tag/annotation commit opens changes.lance again (and _record adds another _ensure_tables just for this). CHANGES is new in this unmerged stack. If no real root was written without provenance, fold the column into CHANGES in #731 and drop the migration, the extra call and its test. If such roots exist, make it a one-off like drop_task_annotations instead of a check on every write.

[RyanPCo]

low (api-design): With --source annotations, batch_size, replace and operator are silently ignored: --operator is documented as "recorded in changes", but the meta.json approver is used. Dispatch to commit_staged_annotations from main() and error out if --replace/--operator are combined with --source annotations, or document that they don't apply.

[RyanPCo]

nit (duplication): This re-reads each meta.json that the loaders already parsed, and indexes local by vendor_recording_id, which again assumes dir name == vendor id. Consider adding provenance: dict | None to commit.Delivery, filling it in the loaders, and building the map in commit_batch.

[RyanPCo]

Review findings: status after the fixup pass. The fixes are squashed into this PR's commits, and the whole stack was force-pushed.

Fixed

• stage() only handles parquet, though change files may be .lance datasets: stage() converts a Lance change dir to parquet before hashing and uploading; test added
• Runtime provenance column migration is unnecessary and runs on every _ensure_tables: Removed the add_columns migration, the extra _ensure_tables in _record and the before-provenance test. Fixup targets 8dced58 (same PR) because that commit edits the removed test
• commit_staged silently ignores batch_size/replace/operator for annotations: main() dispatches annotations to commit_staged_annotations and errors on --replace, --operator or a non-default --batch-size there
• meta.json is re-read for provenance after the loaders already parsed it: Delivery.provenance is set by the loaders, and commit_batch builds the provenance map; commit_staged no longer re-reads meta.json for it (zarr_to_lance: vendor and robot zarr episodes into Lance, with their annotations #751 still reads meta.json for annotation spans only)