docs(fs): explain guarded cleanup invariants

src/guarded-mutation.ts

@@ -32,6 +32,9 @@ export async function withAsyncDirectoryGuards<T>(
     } catch (error) {
       if (options.onPostGuardFailure) {
         try {
+          // The mutation may have returned an owned resource before the post-guard
+          // check detected a swapped directory. Give callers one chance to close
+          // handles without letting cleanup hide the boundary failure.
           await options.onPostGuardFailure(result, error);
         } catch {
           // Preserve the boundary failure. Cleanup is best-effort.

src/pinned-write.ts

@@ -217,6 +217,8 @@ async function runPinnedWriteFallback(params: {
         ),
       {
         onPostGuardFailure: async (openedHandle) => {
+          // The parent failed verification, so targetPath may now resolve
+          // somewhere else. Close the fd, but do not clean up by path.
           await openedHandle.close().catch(() => undefined);
         },
       },

src/root-impl.ts

@@ -1627,7 +1627,7 @@ async function writeMissingFileFallback(
       },
       {
         onPostGuardFailure: async ({ handle }) => {
-          created = false;
+          created = false; // Parent is untrusted now; skip outer path cleanup by name.
           await handle.close().catch(() => undefined);
         },
       },

src/safe-path-segment.ts

@@ -30,6 +30,8 @@ export function assertSafePathSegment(
   segment: string,
   options: SafePathSegmentOptions = {},
 ): string {
+  // Validate the exact value callers will later join into paths; trimming here
+  // would let whitespace-padded ids pass and then be used verbatim.
   if (!isSafePathSegment(segment, options)) {
     throw new FsSafeError(
       "invalid-path",