Recover malformed metadata containers, release 0.20.2

docs/known-limitations.md

@@ -178,7 +178,10 @@ cannot parse the input.
 
 `remove_ai_metadata` may copy an undecodable file through unchanged instead of
 raising. User facing callers must use `strip_and_verify` and inspect its
-surviving marker mapping before reporting success. The CLI does this.
+surviving marker mapping before reporting success. `strip_and_verify` recovers
+when `image_io` can still decode the raster by normalizing the container and
+checking again. A truly undecodable file still reports the surviving markers.
+The CLI uses this verified path.
 
 ### Sixteen bit PNG output is not preserved
 

docs/module-internals.md

@@ -114,7 +114,10 @@ Key contracts:
 - The low-level remover is fail-safe and can copy an undecodable file through
   unchanged.
 - A caller that reports success must use `strip_and_verify`, which scans the
-  written output for surviving markers.
+  written output for surviving markers. If the metadata-preserving decoder
+  rejected the container but `image_io` can still decode its raster,
+  `strip_and_verify` normalizes that raster and scans again. A truly undecodable
+  file keeps the surviving-marker result.
 
 Detection and removal must stay in parity. A new marker is incomplete until the
 scanner can find it, the remover can reach every supported placement, and a

docs/python-api.md

@@ -119,7 +119,10 @@ if has_ai_metadata(source):
 
 Use `strip_and_verify` when your application reports that stripping succeeded.
 It checks the written output and returns `(output_path, surviving_markers)`.
-Treat a nonempty `surviving_markers` mapping as a failure.
+When the first strip leaves markers in a malformed but raster-decodable image,
+it normalizes the container through `image_io` and checks again. That recovery
+path preserves the pixels but drops standard metadata. Treat a nonempty
+`surviving_markers` mapping as a failure.
 
 `remove_ai_metadata` is the lower level fail-safe transformer. It may copy an
 undecodable input through unchanged, so its return alone must not be presented