Skip to content

write_mask: roll back when the caller's provenance step fails (restore an overwritten mask) - #397

Open
guijacquemet wants to merge 3 commits into
mainfrom
claude/handoff-rollback
Open

guijacquemet wants to merge 3 commits into
mainfrom
claude/handoff-rollback

Conversation

@guijacquemet

Copy link
Copy Markdown
Contributor

What

  • write_mask: under the type's write lock, an overwrite=True write first copies the existing mask to a hidden .<name>.previous.<random> beside it (the temp-name pattern; a dot-file, which the masks discovery skips via is_system_name). on_published(path) is still called under the lock. If it raises (any BaseException, including KeyboardInterrupt), the write is rolled back under the same lock: the backup is moved back over the target with os.replace (same bytes and mode), or the new mask is removed when there was no earlier one. Then the error is raised again. If the restore or the removal fails, the result is a SegmentationError that names both files, and the backup is kept. When the callback succeeds, the backup is removed.
  • The backup is a copy rather than a move, so the earlier mask stays at its name until the new one replaces it in a single move. If the process is killed partway, the earlier mask is still in place and a stray dot-file is left beside it.
  • segmentation_record._batch: the duplicate-image check now uses a seen-set, so it runs in linear time (it used list.count once per entry).
  • Contract §15.5 and CHANGELOG are updated.

Why

External audit of #375 (22 November 2026), blockers 1–3. Rollback has to happen where the lock is held. Before this change, a failed overwrite left the new mask published, and the caller's own rollback could only remove that new mask, so the earlier valid mask was lost. With this change #375 can write its record inside on_published and drop its own _withdraw.

Tests

tests/test_segmentation_rollback.py (new). The old test "raising callback leaves the mask published" is removed because that behaviour is now intentionally different.

  • A failing callback (RuntimeError and KeyboardInterrupt) with no earlier mask leaves no file at all.
  • A failing callback with an earlier mask restores the earlier bytes exactly, with the same mode, and leaves no backup.
  • On success no backup is left; while the callback runs, the backup exists and is invisible to images_to_segment.
  • When os.replace fails during the restore (monkeypatched), the error is loud, names both paths, keeps the backup with the earlier bytes, and keeps the caller's error in the chain.
  • When removing a new mask fails, the error is loud.

All 7 fail on 7a0a521 src/. With this change: 92 passed (rollback, write_lock, handoff and record tests). tools/check.py --rules and ruff are clean.


Generated by Claude Code

Under the type's write lock, an overwrite first copies the earlier mask to a
hidden .<name>.previous.<random> beside it. If on_published raises (any
BaseException), the earlier mask is moved back byte for byte, or a new mask
is removed, still under the lock, then the error propagates. A rollback that
cannot restore or remove raises SegmentationError naming both files and
keeps the copy. The record's duplicate-image check uses a seen-set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Scma6W3LC11s3qjXHZuGDm
…ckups

An interrupt after os.replace but before _write_and_publish returned dropped
the backup while the new mask stayed. The target's inode now decides whether
the publish happened. stray_backups() reports leftover .previous copies.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Scma6W3LC11s3qjXHZuGDm
…ynced

The write_mask docstring and contract 15.5 now say that the rollback is
unconditional (a callback that commits must reconcile its own post-commit
failures) and that the record is replaced atomically but not fsynced.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Scma6W3LC11s3qjXHZuGDm
Base automatically changed from claude/segmentation-handoff to main November 22, 2026 18:05
@guijacquemet
guijacquemet marked this pull request as ready for review November 22, 2026 18:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants