US07-04: Prove Concurrency and Crash Recovery (#86)

photo_pipeline/faults.py

@@ -0,0 +1,45 @@
+"""Test-only fault control points (concept §18, US07-04).
+
+Crash safety can only be proven by crashing at the exact moment a transition has
+been persisted but its consequence has not. That needs a barrier *inside* the
+production code path — but not a production capability: there is no endpoint, no
+service method, and no configuration file entry that can trigger one. The only
+switch is an environment variable naming a single point, read at the moment it is
+passed, and the only thing it does is kill the process. A deployment that never
+sets it can never reach the barrier.
+
+``os._exit`` is deliberate: it skips atexit handlers, buffered flushes, and
+``finally`` blocks, which is what a real ``SIGKILL`` or power loss does. A clean
+shutdown would prove nothing.
+
+The points are the persisted transitions of the journalled stages:
+
+    rename    moving | moved | database_updated | verified | complete
+    archive   transferring | verified | removing | source_removed | complete
+    exif      exif:written        — keywords on disk, checkpoint not yet recorded
+    upload    upload:accepted     — uploader exited, outcome not yet persisted
+    jobs      job:item_done       — item committed, job outcome not yet written
+
+Recovery for each is asserted in tests/integration/test_fault_matrix.py and
+tests/e2e/test_crash_recovery.py.
+"""
+
+from __future__ import annotations
+
+import os
+
+ENV_VAR = "PHOTO_PIPELINE_FAULT_AFTER"
+
+EXIF_WRITTEN = "exif:written"
+UPLOAD_ACCEPTED = "upload:accepted"
+JOB_ITEM_DONE = "job:item_done"
+
+
+def maybe_fault(point: str) -> None:
+    """Die abruptly when ``PHOTO_PIPELINE_FAULT_AFTER`` names ``point``.
+
+    Shared by the rename, archive, restore, EXIF, upload, and job lanes, each
+    passing its own state names. Never set the variable outside tests.
+    """
+    if os.environ.get(ENV_VAR) == point:
+        os._exit(9)