[preflight] document that preflight doesn't copy the library

masque/file/utils.py

@@ -33,6 +33,12 @@ def preflight(
     Run a standard set of useful operations and checks, usually done immediately prior
     to writing to a file (or immediately after reading).
 
+    Note that this helper is not copy-isolating. When `sort=True`, it constructs a new
+    `Library` wrapper around the same `Pattern` objects after sorting them in place, so
+    later mutating preflight steps such as `prune_empty_patterns` and
+    `wrap_repeated_shapes` may still mutate caller-owned patterns. Callers that need
+    isolation should deep-copy the library before calling `preflight()`.
+
     Args:
         sort: Whether to sort the patterns based on their names, and optionaly sort the pattern contents.
             Default True. Useful for reproducible builds.