From 3c746c25e6243cd00997f9ac3b29e0f4613e593a Mon Sep 17 00:00:00 2001
From: broken-circle <252359939+broken-circle@users.noreply.github.com>
Date: Fri, 10 Jul 2026 11:27:36 -0700
Subject: [PATCH] Document `SubprocessOutputSequence` precondition

---
 Sources/Subprocess/SubprocessOutputSequence.swift | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/Sources/Subprocess/SubprocessOutputSequence.swift b/Sources/Subprocess/SubprocessOutputSequence.swift
index 5b8600e3..f0ea992d 100644
--- a/Sources/Subprocess/SubprocessOutputSequence.swift
+++ b/Sources/Subprocess/SubprocessOutputSequence.swift
@@ -39,6 +39,9 @@ import os
 #endif
 
 /// An asynchronous sequence of buffers that streams output from a subprocess.
+///
+/// - Important: This sequence is single-pass and can be iterated only once.
+///   See ``makeAsyncIterator()``.
 public struct SubprocessOutputSequence: AsyncSequence, @unchecked Sendable {
     /// The failure type for the asynchronous sequence.
     public typealias Failure = any Swift.Error
@@ -110,9 +113,12 @@ public struct SubprocessOutputSequence: AsyncSequence, @unchecked Sendable {
     }
 
     /// Creates an iterator for this asynchronous sequence.
+    ///
+    /// - Precondition: `SubprocessOutputSequence` is single-pass; creating a
+    ///   second iterator results in a fatal error.
     public func makeAsyncIterator() -> Iterator {
         guard self.state.initializedCount() == 1 else {
-            fatalError("SubprocessOutputSequence is single pass. It can only be iterated once.")
+            fatalError("SubprocessOutputSequence is single-pass. It can only be iterated once.")
         }
         return Iterator(diskIO: self.diskIO, processIdentifier: self.processIdentifier)
     }