feat: assemble FITS sections into blocks with dirty-tracking

Realize the "preserve untouched, re-render touched" model: a section
serializes to its retained blocks byte-for-byte when unmodified, and
re-renders from its model when it needs serialization.

Because rendering can fail (an invalid keyword, a non-finite float, an
over-long record), the byte accessor is made throwing rather than
risking stale bytes after a future mutation:

- Add FITSSection.serializedData(options:) throws, routing to the
  retained blocks when clean and to the model renderer when dirty, plus
  appendSerializedData(to:options:) as the aggregation primitive.
- Turn `data` into a throwing convenience (get throws) on FITSSection
  and FITSFile, equal to serializing with the strict options.
- Add a per-section needsSerialization flag (independent of the
  isFinalized lock) and a markNeedsSerialization() hook.
- Render a header to its cards plus the END marker, space-padded to a
  whole 2880-byte block, and a data payload zero-padded to the block
  boundary, per FITS 4.0.

An unmodified parsed file still round-trips byte-for-byte.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: macmade

Docs/agent-plans/active/2026-07-11-write-support/write-support-plan.html

@@ -348,7 +348,8 @@ <h4><span class="m-num">M3</span> Render <code>FITSProperty</code> to an 80-byte
 
   <!-- M4 -->
   <div class="milestone">
-    <h4><span class="m-num">M4</span> Assemble a <code>FITSSection</code> into blocks with dirty-tracking <span class="capsule notstarted">Not started</span></h4>
+    <h4><span class="m-num">M4</span> Assemble a <code>FITSSection</code> into blocks with dirty-tracking <span class="capsule completed">Completed</span></h4>
+    <p class="meta"><strong>Completed:</strong> 2026-07-11</p>
     <div class="field goal">
       <div class="label">Goal</div>
       <div class="body">Render a whole section to 2880-byte blocks from its model, while keeping clean sections byte-for-byte identical to their retained bytes. This is where "preserve untouched, re-render touched" is realized.</div>
@@ -363,8 +364,26 @@ <h4><span class="m-num">M4</span> Assemble a <code>FITSSection</code> into block
         <li>Tests in <code>SwiftFITSTests/FITSSection.swift</code>: a clean parsed section re-serializes byte-identically; a synthetically built/dirtied section renders correct blocks and re-parses equal.</li>
       </ul>
     </div>
-    <div class="field notes-field"><div class="label">Implementation notes</div><div class="body placeholder">—</div></div>
-    <div class="field auto-field"><div class="label">Automated review</div><div class="body placeholder">—</div></div>
+    <div class="field notes-field"><div class="label">Implementation notes</div><div class="body">
+      <p>Implemented with TDD (red → green). No new files (changes to <code>FITSSection</code>, <code>FITSFile</code>, and their tests).</p>
+      <p><strong>Key design decision — throwing byte accessor (discussed with the user before coding).</strong> The plan says "route <code>data</code>/<code>appendData(to:)</code>", but rendering can throw (invalid keyword, non-finite float, over-long record from M2/M3), and a lazy dirty flag means the current bytes are only produced at serialize time. Keeping a non-throwing <code>data</code> would return <em>stale</em> bytes after a mutation. The user chose to make the byte accessor throwing so it is never stale:</p>
+      <ul>
+        <li><code>FITSSection.serializedData(options:) throws -&gt; Data</code> — the router: clean → retained blocks (byte-for-byte), dirty → render from the model. Plus <code>appendSerializedData(to:options:) throws</code> as the aggregation primitive.</li>
+        <li><code>var data: Data { get throws }</code> on both <code>FITSSection</code> and <code>FITSFile</code> — a convenience equal to <code>serializedData(options: .strict)</code>. <code>FITSFile.data</code> changed from non-throwing to <code>get throws</code>; existing reads gained <code>try</code> (incl. <code>allTestFilesRoundTrip</code>). <em>(This pulls the section-level <code>serializedData</code> forward from M5; M5 still adds the file-level <code>serializedData(options:)</code> + <code>write</code> + validation.)</em></li>
+      </ul>
+      <p><strong>Dirty-tracking:</strong> a private <code>needsSerialization</code> flag (default <code>false</code>), independent of <code>isFinalized</code> (a section can be finalized <em>and</em> dirty). <code>markNeedsSerialization()</code> is the internal hook M7's mutations will call. Parsing never sets it, so clean sections always re-emit retained bytes — <code>allTestFilesRoundTrip</code> stays byte-identical. (<code>finalize</code> now reads a new non-throwing <code>retainedBytes</code> instead of <code>data</code>, equivalent for a clean section.)</p>
+      <p><strong>Rendering</strong> (grounded in FITS 4.0 §3.3.1/§3.3.2): a header/extension renders its properties to cards (M3) + the <code>END</code> card, space-padded to a whole 2880-byte block; a data section zero-pads its payload to the boundary. A minimal internal <code>init(dataPayload:)</code> builds a synthetic dirty data section (M7/M8 foundation, and enables the data-render test).</p>
+      <p><strong>Verification:</strong> <code>xcodebuild test</code> → <em>TEST SUCCEEDED</em>; <code>swift test</code> → 183 tests passed (+3). Regression <code>allTestFilesRoundTrip</code> holds (clean path byte-identical).</p>
+      <p><strong>Automated review loop:</strong> 1 round; converged with no Critical/High/Medium findings.</p>
+    </div></div>
+    <div class="field auto-field"><div class="label">Automated review</div><div class="body">
+      <p>Round 1 — no Critical/High/Medium. The reviewer traced the clean-path byte-identity (a clean section short-circuits before the renderer even under <code>.strict</code>), the finalize equivalence, the header/data render correctness (END card, ASCII guard, space vs zero padding), the <code>payload</code>/inits, and the <code>try</code> ripple (no <code>try</code> on a non-throwing expression; assertions unchanged). Findings:</p>
+      <ul>
+        <li><strong>Low — two alignment nits</strong> from the change: a <code>let</code> group in the new data-render test, and a previously-aligned <code>#expect</code> group broken by the <code>try</code> ripple (one sibling can't take <code>try</code>). <em>Fixed both</em> (re-aligned; the three <code>#expect</code> lines share a column since <code>try file.data.count</code> matches <code>file.sections.count</code> in width).</li>
+        <li><strong>Info — empty payload renders to 0 bytes</strong> (no block). Internally consistent and only reachable via the internal init; flagged so it's a conscious decision when M7/M8 build real data segments (a real image data section should never be empty). <em>Deferred.</em></li>
+        <li><strong>Info — <code>dataSize</code> under-estimates the <code>Data(capacity:)</code> hint for a dirty section</strong> (it sums retained blocks). Harmless — it is only a reservation hint and <code>dataSize</code> is already documented as the retained size. <em>Deferred.</em></li>
+      </ul>
+    </div></div>
     <div class="field review-field"><div class="label">Review comments</div><div class="body placeholder">—</div></div>
   </div>
 

SwiftFITS/FITSFile.swift

@@ -429,18 +429,28 @@ public class FITSFile: CustomStringConvertible
         try validate?( properties[ index ].value )
     }
 
-    /// The complete file contents, reconstructed by concatenating every section.
+    /// The complete file contents, serialized with the ``strict`` options.
+    ///
+    /// A convenience for serializing every section with
+    /// ``FITSSerializationOptions/strict``. An unmodified parsed file yields its
+    /// original bytes byte-for-byte; a file whose sections were modified
+    /// re-renders those sections from their model, which can fail.
+    ///
+    /// - Throws: Any ``FITSError`` raised while rendering a modified section.
     public var data: Data
     {
-        let size = self.sections.reduce( 0 ) { $0 + $1.dataSize }
-        var data = Data( capacity: size )
-
-        self.sections.forEach
+        get throws
         {
-            $0.appendData( to: &data )
-        }
+            let size = self.sections.reduce( 0 ) { $0 + $1.dataSize }
+            var data = Data( capacity: size )
 
-        return data
+            try self.sections.forEach
+            {
+                try $0.appendSerializedData( to: &data, options: .strict )
+            }
+
+            return data
+        }
     }
 
     /// The primary header section, or `nil` if the file has no sections.

SwiftFITS/FITSSection.swift

@@ -71,6 +71,19 @@ public class FITSSection: CustomStringConvertible
     /// disagree).
     private var isFinalized = false
 
+    /// Whether the section's model has diverged from its retained ``blocks`` and
+    /// must be re-rendered on serialization instead of re-emitting those bytes.
+    ///
+    /// A freshly-parsed section is clean (`false`); building one from a model, or
+    /// (later) mutating one, sets this. It is independent of ``isFinalized``: a
+    /// section can be both finalized (locked against block appends) and in need
+    /// of re-serialization.
+    private var needsSerialization = false
+
+    /// The data payload of a synthetically-built data section, or `nil` for a
+    /// parsed section, whose bytes live in ``blocks``.
+    private let payload: Data?
+
     /// The parsed header records. Empty for data sections, and until
     /// ``finalize(options:)`` has run.
     ///
@@ -122,44 +135,174 @@ public class FITSSection: CustomStringConvertible
     ///   is not valid for the section kind.
     public init( kind: Kind, block: FITSBlock? ) throws
     {
-        self.kind = kind
+        self.kind    = kind
+        self.payload = nil
 
         if let block = block
         {
             try self.append( block: block )
         }
     }
 
-    /// The total size, in bytes, of all blocks in the section.
+    /// Creates a synthetic data section from a raw payload.
+    ///
+    /// The section is marked as needing serialization, so
+    /// ``serializedData(options:)`` renders the payload (zero-padded to the block
+    /// boundary) rather than re-emitting retained blocks, of which it has none.
+    ///
+    /// - Parameter dataPayload: The data-segment bytes, of any length.
+    internal init( dataPayload: Data )
+    {
+        self.kind               = .data
+        self.payload            = dataPayload
+        self.needsSerialization = true
+        self.isFinalized        = true
+    }
+
+    /// Marks the section as needing re-serialization from its model.
+    ///
+    /// Mutating a section's properties or data must call this so
+    /// ``serializedData(options:)`` re-renders from the model instead of
+    /// re-emitting the retained blocks.
+    internal func markNeedsSerialization()
+    {
+        self.needsSerialization = true
+    }
+
+    /// The total size, in bytes, of the section's retained blocks.
+    ///
+    /// This reflects the bytes as parsed; a section pending re-serialization may
+    /// render to a different size.
     public var dataSize: Int
     {
         self.blocks.reduce( 0 ) { $0 + $1.data.count }
     }
 
-    /// The concatenated raw bytes of every block in the section.
+    /// The section's retained raw bytes, exactly as parsed.
+    private var retainedBytes: Data
+    {
+        var data = Data( capacity: self.dataSize )
+
+        self.blocks.forEach { data.append( $0.data ) }
+
+        return data
+    }
+
+    /// The section's serialized bytes, rendered with the ``strict`` options.
+    ///
+    /// A convenience for ``serializedData(options:)`` with
+    /// ``FITSSerializationOptions/strict``. A clean parsed section yields its
+    /// retained bytes byte-for-byte; a section pending re-serialization is
+    /// rendered from its model, which can fail.
+    ///
+    /// - Throws: Any ``FITSError`` raised while rendering a section that needs
+    ///   serialization.
     public var data: Data
+    {
+        get throws
+        {
+            try self.serializedData( options: .strict )
+        }
+    }
+
+    /// The section's serialized bytes.
+    ///
+    /// Returns the retained blocks unchanged when the section is clean (so an
+    /// unmodified parsed section round-trips byte-for-byte), and renders from the
+    /// model when the section needs serialization.
+    ///
+    /// - Parameter options: The serialization options to apply when rendering.
+    /// - Returns: The section's bytes, a whole number of 2880-byte blocks.
+    /// - Throws: Any ``FITSError`` raised while rendering.
+    public func serializedData( options: FITSSerializationOptions ) throws -> Data
     {
         var data = Data( capacity: self.dataSize )
 
-        self.appendData( to: &data )
+        try self.appendSerializedData( to: &data, options: options )
 
         return data
     }
 
-    /// Appends the section's block bytes, in order, to an existing buffer.
+    /// Appends the section's serialized bytes to an existing buffer.
     ///
-    /// Lets a caller assemble several sections into one buffer without building
-    /// an intermediate ``Data`` copy per section.
+    /// Lets a caller assemble several sections into one buffer without an
+    /// intermediate ``Data`` copy per section. Routes to the retained blocks when
+    /// clean and to the model renderer when the section needs serialization.
     ///
-    /// - Parameter data: The buffer to append the section's block bytes to.
-    internal func appendData( to data: inout Data )
+    /// - Parameters:
+    ///   - data: The buffer to append to.
+    ///   - options: The serialization options to apply when rendering.
+    /// - Throws: Any ``FITSError`` raised while rendering.
+    internal func appendSerializedData( to data: inout Data, options: FITSSerializationOptions ) throws
     {
-        self.blocks.forEach
+        guard self.needsSerialization
+        else
+        {
+            data.append( self.retainedBytes )
+
+            return
+        }
+
+        switch self.kind
         {
-            data.append( $0.data )
+            case .header, .xtension: data.append( try self.renderedHeader( options: options ) )
+            case .data:              data.append( self.renderedDataSegment() )
         }
     }
 
+    /// Renders a header or extension section from its ``properties``.
+    ///
+    /// Serializes every property to its card(s), appends the `END` marker, and
+    /// blank-pads the result to a whole number of 2880-byte blocks (FITS 4.0
+    /// §3.3.1).
+    ///
+    /// - Parameter options: The serialization options to apply.
+    /// - Returns: The rendered header bytes.
+    /// - Throws: ``FITSError/cannotSerialize(reason:)`` if the rendered text is
+    ///   not ASCII, or any error raised while rendering a property.
+    private func renderedHeader( options: FITSSerializationOptions ) throws -> Data
+    {
+        let cards = try self.properties.flatMap { try $0.serialized( options: options ) }
+        let end   = "END".padding( toLength: FITSFile.cardSize, withPad: " ", startingAt: 0 )
+
+        guard let ascii = ( cards + [ end ] ).joined().data( using: .ascii )
+        else
+        {
+            throw FITSError.cannotSerialize( reason: "Header contains non-ASCII characters" )
+        }
+
+        return FITSSection.paddedToBlockBoundary( ascii, fill: 0x20 )
+    }
+
+    /// Renders a data section from its payload, zero-padded to the block boundary
+    /// (FITS 4.0 §3.3.2).
+    ///
+    /// - Returns: The rendered data-segment bytes.
+    private func renderedDataSegment() -> Data
+    {
+        FITSSection.paddedToBlockBoundary( self.payload ?? self.retainedBytes, fill: 0x00 )
+    }
+
+    /// Pads a buffer to a whole number of 2880-byte blocks.
+    ///
+    /// - Parameters:
+    ///   - data: The bytes to pad.
+    ///   - fill: The byte to pad with (ASCII space for headers, zero for data).
+    /// - Returns: `data` padded to the next block boundary, or unchanged if it is
+    ///   already block-aligned.
+    private static func paddedToBlockBoundary( _ data: Data, fill: UInt8 ) -> Data
+    {
+        let remainder = data.count % FITSFile.blockSize
+
+        guard remainder != 0
+        else
+        {
+            return data
+        }
+
+        return data + Data( repeating: fill, count: FITSFile.blockSize - remainder )
+    }
+
     /// Appends a block to the section.
     ///
     /// For header and extension sections this enforces structural rules: the
@@ -234,7 +377,7 @@ public class FITSSection: CustomStringConvertible
 
         if self.kind == .header || self.kind == .xtension
         {
-            let data = self.data
+            let data = self.retainedBytes
 
             if options.contains( .allowNonPrintableHeaderText ) == false, data.containsOnlyFITSPrintable == false
             {

SwiftFITSTests/FITSFile.swift

@@ -57,7 +57,7 @@ struct Test_FITSFile
             let data = try Data( contentsOf: url )
             let file = try FITSFile( data: data, options: .lenient )
 
-            #expect( file.data == data, "Round-trip mismatch for \( url.lastPathComponent )" )
+            #expect( try file.data == data, "Round-trip mismatch for \( url.lastPathComponent )" )
         }
     }
 
@@ -185,7 +185,7 @@ struct Test_FITSFile
         let file = try FITSFile( url: url, options: .lenient )
         let copy = try FITSFile( data: file.data, options: .lenient )
 
-        #expect( file.data        == copy.data )
+        #expect( try file.data    == copy.data )
         #expect( file.description == copy.description )
     }
 
@@ -479,7 +479,7 @@ struct Test_FITSFile
         let file = try FITSFile( data: block, options: .lenient )
 
         #expect( file.header?.properties.contains { $0.name == "CONTINUE" } == true )
-        #expect( file.data == block )
+        #expect( try file.data == block )
     }
 
     @Test
@@ -535,7 +535,7 @@ struct Test_FITSFile
         try #require( file.sections.count == 2 )
 
         #expect( file.sections[ 1 ].kind == .data )
-        #expect( file.data == header + data )
+        #expect( try file.data == header + data )
     }
 
     @Test
@@ -551,7 +551,7 @@ struct Test_FITSFile
         #expect( file.sections.count == 1 )
         #expect( file.sections.allSatisfy { $0.kind != .data } )
         #expect( file.extensions.isEmpty )
-        #expect( file.data == header + padding )
+        #expect( try file.data == header + padding )
     }
 
     @Test
@@ -592,7 +592,7 @@ struct Test_FITSFile
         #expect( file.sections[ 3 ].kind == .data )
         #expect( file.extensions.count == 1 )
 
-        #expect( file.data == header + data1 + ext + data2 )
+        #expect( try file.data == header + data1 + ext + data2 )
     }
 
     @Test
@@ -663,8 +663,8 @@ struct Test_FITSFile
         let file = try FITSFile( data: data, options: .lenient )
 
         #expect( file.sections.count == 1 )
-        #expect( file.data.count     == FITSFile.blockSize * 2 )
-        #expect( file.data           == header + partial + Data( repeating: 0x00, count: FITSFile.blockSize - 100 ) )
+        #expect( try file.data.count == FITSFile.blockSize * 2 )
+        #expect( try file.data       == header + partial + Data( repeating: 0x00, count: FITSFile.blockSize - 100 ) )
     }
 
     @Test
@@ -695,7 +695,7 @@ struct Test_FITSFile
         #expect( file.sections.count == 1 )
         #expect( file.header?.properties.last?.name          == "FOO" )
         #expect( file.header?.properties.last?.value.integer == 1 )
-        #expect( file.data == block )
+        #expect( try file.data == block )
     }
 
     @Test