SwiftSheets Implementation Spec

B.27 Stock and currency functions — formulas only Numbers can recompute (Rev 3.4)

Numbers has 6 functions that fetch quotes from the internet: STOCK, STOCKH, CURRENCY, CURRENCYH, CURRENCYCONVERT and CURRENCYCODE (function table 298 to 303). They differ from every other function in that the answer is not in the sheet but comes from Apple's quote service. Neither Excel nor OpenFormula has functions of these names.

The sample was seeded from a document the maintainer made by hand (containing STOCK("VEEV",2)), and Numbers 15.3.1 itself was made to add the full range of attribute forms over AppleScript: a numeric attribute, no attribute, a string attribute (the form Numbers itself answers with #VALUE!), and STOCKH with a nested DATE. Merely setting a cell's value to "=STOCK(…)" makes Numbers accept it as a formula and actually perform the fetch, so no UI is needed to make samples for this family.

The replacement was asked of Numbers itself

When Numbers exports the same document to Excel, all 6 functions become "the value that had been fetched", while the =E2*2+1 placed beside them went out as a formula (measured). So the replacement Numbers itself has decided on is "an ordinary formula stays a formula, a quote function becomes a value". We do the same:

• Read: the formula and the fetched value (the cache) are read as they are. An error stays an error. No fix was needed (the existing formula reading passes as is). Specimen stock-15.numbers added to the corpus
• Write to Numbers: written as a formula. Numbers fetches again when opened (in the judge run every formula survived and the values were fetched)
• Write to Excel and ODS: FormulaExpr.remoteDataFunction finds the family, writes the fetched value and reports it as degraded. With no cache, an empty cell (empty rather than a wrong value)

Judges

B.28 The remaining pivot-table shapes — levels are open, values are settled at one (Rev 3.5)

The "2 shapes we cannot write" left by B.19, 2 levels on one axis and 2 aggregated values, were resolved by growing the samples to 7. Conclusion: multiple levels can be written on both axes (measured up to 3 nested levels and a mix on both axes). Values are limited to 1, and experiment established that this is a wall in the mechanism, not a hole in the implementation.

How the samples were grown

SwiftSheets itself can write multi-level Excel pivots, so one workbook per shape was written and imported into and saved by Numbers 15.3.1: a control (1×1×1), 2 levels (row side, column side), 2 values, 2 mixes and 3 levels, 7 workbooks in all. The judgement is by the byte count and content of the CSV export (a judging basis already checked as valid even while the screen is locked).

The placement rules we read off

• Display lanes are in "children, then parent" post-order. A group's heading row (subtotal) comes right after its members, with the grand-total lane at the end. The order map (pivot_order) is in the same post-order plus a sentinel, and holds no heading lanes
• The source copy's group-bys are one each for "column-side prefix + all of the row side": the number of column levels + 1 of them (205, 206, …). With 2 column levels the 3rd (207) is only the root with no group column, and is_enabled stays true
• The formula of a cell in a total lane follows one rule: a cell at row depth r and column depth c looks up group-by (205 + column levels − c), at level c+r, with the group at the (column path + row path) node. Every formula in the 7 workbooks (body cells included) was explained by this one rule
• A group node's UUID is derived from the value path (the same sequence of values gives the same 128 bits even in another document). The derivation function need not be reproduced: rewriting the sample's 9 nodes to random values "consistently, everywhere they appear" still drew completely (an experiment rewriting 66 places). Consistency is the contract; we map through a path-to-UUID dictionary
• The label lanes have fixed UUIDs too: a level's heading lane is that level's grouping_column_uid (different per level), and the lane of heading words is the ASCII constant "aggre names row" (rows) / "aggre names col" (columns)
• A coordinate block per value: a group node holds as many agg_formula_coords as there are values, and there is one aggregator (aggregator) per value, walking the tree with the coordinates of its own block. The list's order is the reverse of the rule's (as measured)
• The contents of subtotal and grand-total rows (labels and values with formulas) go into the third model's (summary model) store, at display coordinates. The storage grid holds only headings and leaves

Why 2 values cannot be written (a door closed by measurement)

The lanes of an axis with no groups are all looked up on the map under the same marker (1,0); Numbers' own document with 2 values also lists this marker twice. A map with the same key twice cannot be told apart by binary search. Numbers' own document survives because it is not rebuilt on opening (even with the version spoofed and the aggregators stripped, no rebuild happens; it just shows zeros), whereas our document, written from the older-version template, is always rebuilt. Every arrangement we tried (the order of values, inventing lane markers, the body-cell formulas Numbers itself writes, which in our document were re-measured to erase values on recalculation) drew 1 value or 0. So it is settled: write only the first value, and drop and report the second onward. If the door opens, it will be when we can write a document that triggers no rebuild (a newer template with the dependency records written by us), the same key as B.26's array formulas.

Judges

B.29 Categories, filters and stock cells — the silence ended with hand-made samples (Rev 3.6)

The 3 items left unread had no samples, because none has vocabulary in AppleScript and they can only be made in the UI. The maintainer made 3 workbooks by hand in the UI of Numbers 15.3.1 (2 category levels, 2 filter rules, a stock cell in both the cell and the table form), and they were settled on those samples. The model for how to read them was, as always, asked of Numbers itself: we had Numbers export the same document to Excel, saw what survives and what disappears, and then decided how we read.

• Filters: Numbers' own Excel export discards the rules and passes only the hidden rows (no autoFilter element; hidden="1" on the rows that drop out; measured). The read makes the same trade: the row UIDs that are filtered in hidden_states_owner → row_hidden_state_extent → base_hidden_states are resolved to row numbers through base_column_row_uids and mapped to hidden rows, and the rules in filter_set are counted, dropped and reported. The hidden rows read survive both to Excel and on write-back to Numbers (fixed by a round-trip test). Measured, it matches Numbers' own export row for row. The document with the filter switched off, first noted as "not measured", has since been measured too, on a second sample in which the maintainer turned the same document's filter off: when it is off Numbers empties the list of hidden states (the safe-side reading was correct as meant) and keeps the rules, still off. The model has no place for them, so the off rules are counted, dropped and reported (measured that Numbers' own Excel export also discards them without a trace)
• Categories: in reality the same group-by mechanism as the pivot table, carried on an ordinary table's category_owner (kind 8, with group columns). To decide how to read them, we had Numbers itself export a categorised sample to Excel, and Numbers wrote out into cells exactly what is visible on screen: a 5-row table became 14 rows with heading-only rows such as "関西" and "大阪府" inserted between, and the whole of the data also shifted one column to the right. For a person looking at it, it is the original screen, but the row count and the addresses change, so as data it becomes a different table (read this Excel programmatically and a list that should hold 5 items looks like 14 rows). SwiftSheets' job is to carry data faithfully, so we did not adopt this "export as it looks" approach and chose instead to pass the original rows as they are and warn, naming the columns: "the categorisation by 地域, 都道府県 is dropped". It does not fire for the zero-group-column group-by held by a pivot table's summary (the discriminator is whether group columns are present). The document with categories switched off has been measured too, on a second sample: all that toggles is is_enabled; the grouped columns and the tree remain whole (the same shape as filters). The remaining setup has no place in the model and is dropped and reported, naming the columns (Numbers' own Excel export, when off, inserts no heading rows and leaves no trace of the categories; measured)
• Sort (supplement; the sample is the maintainer's hand-made 5th workbook): confirmed in the UI (by the maintainer) that the sort in the organise panel has no on/off. The rules remain in the table's sort_order as a sequence of "column number + ascending/descending", and applying them reorders the stored rows themselves. So the data is already read in sorted order, and every reader already receives it. The rules, on the other hand, have no place in the model and are dropped and reported, naming the columns. Numbers' own Excel export writes no sortState (the sort record) either, passing only the sorted rows (measured)
• Stock cells: current Numbers' "Insert ▸ Stock Quote" writes not a special cell but a plain STOCK formula (the cell form is =STOCK("AAPL",0); the table form is IFERROR(STOCK($A2,B$1),"—") referencing the heading cells, plus an attribute pop-up). So B.27 was already carrying it, and no read-side implementation was needed. The table form's attribute pop-up is dropped and reported, as is usual for a second table (existing behaviour). The warning text for the older generation's "stock control" is kept (no such specimen turned up)

Judges

B.30 An API for editing in bulk — turning the cost of value types into a dividend (Rev 4.0)

2026-08-28. The maintainer proposed an API for making several changes to a sheet within one scope — a two-stage plan of a closure-based editSheet and, later, a ~Copyable session type. Before adopting it as proposed, we reviewed the three frictions cited as motivation against the existing implementation and this spec. Conclusion: adopt the closure version only, with transaction semantics (option 2 of the proposal). The session type is deferred, with reasons.

Reviewing the motivation — two of the three were real, one was half real

The frictions the proposal cited were: (1) forgetting to write back is not a compile error (the edit vanishes in silence); (2) taking the sheet out creates sharing, and the first change copies the whole sheet; (3) what remains after a throw in the middle depends on how the code was written. (1) and (3) are as stated. The best evidence was in this spec itself — the usage example in §15.1 defined its own MyError.sheetNotFound, did a guard, and carried a line annotated "it is a value type, so write it back". In other words, the recipe collection had confessed from the start that every user was fated to hand-write the same four lines.

(2) is only half real. A one-statement edit through the name subscript (wb.sheets["Summary"]?["B4"] = 42) already benefits from the in-place editing introduced in B.11 — the sheet is taken out of the array for the duration of the edit, rewritten as its sole owner, and put back — so no copy runs. The copy runs only in the "take it into a variable and write it back" pattern. What the new API rescues is not the copy itself but being driven into the copying pattern whenever several changes are wanted together. We adopted it after restating where the friction lies in these terms.

The shape adopted

/// The changes reach the workbook only when the closure returns normally. On a throw, all of them are discarded
@discardableResult
public mutating func editSheet<R>(named name: String, _ body: (inout Sheet) throws -> R) throws -> R

/// Positional version. Out of range stops as a programmer error, the same as the collection itself (it does not throw)
@discardableResult
public mutating func editSheet<R>(at index: Int, _ body: (inout Sheet) throws -> R) rethrows -> R

The name was changed from the proposal's editSheet("Summary") (no label) to editSheet(named:). Its siblings on Workbook that name a sheet — addSheet(named:), removeSheet(named:), duplicateSheet(named:as:), moveSheet(named:to:) — all line up on named:, and this is the answer to open question 3 of the proposal. Every change inside the sheet is written within the closed scope. Renaming is one of them: change sheet.name inside the closure and the usual validation, duplicate avoidance and formula follow-through work as they always do (because the write-back goes through the Sheets subscript, which we nailed down with a regression test).

"Nothing has happened" after a throw — why option 2 was chosen

Option 1 (lend out the storage directly: zero copies, but a throw leaves the partial changes behind) and option 2 (edit a copy and swap it in only on normal completion: one copy, but after a throw nothing has happened) cannot both be had — "undoing what was changed part-way" needs the shape from before the change, and keeping that is exactly a copy. We chose option 2. "After a throw, nothing has happened" is in the same spirit as §14.1's "never create a path that drops in silence": it leaves no half-finished state behind in silence. The price of one copy is the same amount the old take-out-and-write-back pattern was already paying, so it is not a regression. For a one-statement edit that wants zero copies, the in-place editing through the name subscript (B.11) remains as it is. A reference-type model (openpyxl and the like) can only do this by hand-writing a deep copy — what has been called the cost of choosing value types becomes, here, a one-line dividend. This restatement is the core of the proposal, and it held up as is under review.

The first throws in the model layer — where the line is drawn against the Optional convention

§14.3 defines access by name as "Optional, not KeyError", and the model layer had until now been a layer that does not throw (removeSheet returns Bool, duplicateSheet returns Optional). editSheet does not cross that convention; it redraws the line — those are queries (not finding is one of the answers), and this is an operation (the requested edit not being performed at all is a failure). An API whose purpose is to remove forgotten write-backs by construction would defeat itself if a mistyped name made it do nothing in silence, so a missing name throws the new SheetError.sheetNotFound(name:). The error that §15.1 had users build by hand became part of the library's vocabulary. Only the positional version does not throw; it stops when out of range — the same treatment as sheets[i] itself and removeSheet(at:), in line with Swift's line "names are data, indices are the programmer's responsibility" and the asymmetry already present in §14.3.

Re-entrancy (touching wb itself inside the closure) needs no mechanism written to forbid it; Swift's exclusivity rule refuses it at compile time — while editSheet holds wb exclusively, a closure that tries to capture wb gets an overlapping-access diagnostic (because the closure is a non-escaping argument, and this is the answer to open question 2 of the proposal).

What was deferred — a ~Copyable session type

The proposal's second stage (an ownership-managed session type with beginEditing / commit / discard) is not added. Besides the fact that a need for edits that do not fit in a closure has not been confirmed (the proposal itself says "once the demand is confirmed"), the review added one positive difficulty: while the session is alive the workbook side is free to change, so a commit(into:) after a sheet has been deleted or renamed would have the old edit overwrite the new structure in silence (with the closure version, the exclusivity rule forbids that overlap at the syntax level). If it is ever added, the rule for detecting and refusing that overwrite is decided first.

Verification

B.31 Generating the modern protection key — stage 1 of the adoption plan (Rev 4.1)

2026-08-28. Stage 1 of the feature adoption plan drawn from a field survey of earlier libraries whose MIT licence we can keep (four stages: protection key → images → column autofit → charts). Until now the "modern key" on sheet, workbook and protected-range protection (algorithmName / saltedHash (then named hashValue) / saltValue / spinCount, Excel 2010 and later) was only carried; all we could produce was the 16-bit key of the 1990s. We implement generation and close this asymmetry.

Method — the iterated SHA-512 of ECMA-376 §18.2.29

H₀ = SHA-512(salt ‖ UTF-16LE(password)), then H_n = SHA-512(H_n−1 ‖ LE32(n−1)) for spinCount rounds (the iteration number is 0-based, 32-bit little-endian, and appended after the hash). The salt is 16 random bytes; the default spinCount is 100,000, the same as Excel. The salt and the final hash are written to the file in Base64, together with algorithmName="SHA-512". The implementation is an adaptation of XLKit's (MIT, NOTICE item 3) CoreUtils.excelModernSheetPasswordHash. We confirmed that the 0-based, appended iteration number agrees between that implementation and our reading of ECMA-376.

Design decisions

SHA-512 comes from CryptoKit. Putting the principle of never hand-writing cryptographic primitives first, SheetCore's framework dependencies widen by one, from "Foundation + Compression" to "+ CryptoKit" (B.1's zero external dependencies is unchanged — CryptoKit is an Apple-supplied framework on the same footing as Compression, and no SwiftPM dependency is added. The situation of Linux being out of reach is unchanged too — and swapping in swift-crypto would give the same API on Linux, which is if anything an advantage for a future return). (Replaced by our own implementation in Rev 4.9 — B.38. Merely having CryptoKit meant the protection key was lost altogether on Linux. swift-crypto would have been the first SwiftPM dependency, so it was not taken. The judges are the FIPS 180-4 known answers and CryptoKit itself.) The salt's randomness comes from SystemRandomNumberGenerator — documented as cryptographically secure on Apple platforms, so we do not go as far as adding the Security framework that XLKit uses. The API is added as a pair on each of the three protection types:

/// Computes the modern (SHA-512) key and stores it in the 4 attributes. nil clears them all. Salt defaults to 16 random bytes
public mutating func setModernPassword(_ password: String?, spinCount: Int = 100_000, salt: Data? = nil)
/// Checks against the stored modern key. false if there is no key
public func modernPasswordMatches(_ password: String) -> Bool

The meaning of the old setPassword(_:) (the 16-bit key) is unchanged — so as not to change the behaviour of existing calls in silence. Both methods can coexist, and Excel too accepts both sets of attributes side by side. The hash computation itself is exposed as ModernPasswordHash.hash(_:salt:spinCount:) (paired with LegacyPasswordHash, so users can do their own checking and inspection). — In Rev 4.57 both were lowered to package (B.67). passwordMatches(_:) / modernPasswordMatches(_:) are enough for checking. An empty password is defined by the method, so it is not rejected (that Excel's UI rejects it is a matter for the UI). spinCount <= 0 stops as a programmer error.

Verification — known answers from an independent implementation, and a record of the judges we could not reach

We implemented the same method independently in Python hashlib and nailed three known answers into the tests, made with a fixed salt (AAECAwQFBgcICQoLDA0ODw== = the 16 bytes 00…0F): "secret" × spinCount 10, "secret" × 100,000, and "秘密" × 100,000 — including the non-ASCII UTF-16LE path. We also check the round trip (write, read back, all 4 attributes equal), whether checking succeeds and fails as it should, and that the old method is unchanged. On 2026-08-29, the real Excel unlocked it (Microsoft Excel 16.112.2). The judge is Tests/ExcelParity/verify_with_excel_app.py — not eyes but AppleScript driving Excel, reading three points as state for each of three specimens: "protected right after opening", "the wrong password does not unlock", "the right password unlocks". The three are an ASCII password, a Japanese password (the UTF-16LE path), and workbook structure protection (a separate path with different attribute names), and every one carries only the modern key — if the old method's 4 hex digits were written alongside, we could not say which one Excel had looked at. All three specimens passed. This settled that the implementation agrees with Excel down to the position of the iteration number (appended or prepended).

There is a reason the wrong password is tried first: unprotect does nothing on a sheet that is already unprotected. If the right one went through first, the wrong password tried afterwards would also "raise no error", so an implementation that accepts any password would pass. And one more thing we learned by measurement — Excel does not refuse a wrong password with an error. It returns without a word and simply leaves the protection in place. That is why the verdict reads state, not the presence of an exception. Only ProtectedRange (an editable window inside a protected sheet) was left out, because there is no straightforward way to try unlocking it on the real application.

The misses on the way are recorded too. The attempt to make LibreOffice the judge (have it convert a protected ODS and take LO's own SHA-512 as the specimen) failed: LO does not know the plaintext, so it cannot rebuild the key and drops it. The attempt to have it apply the key from the plaintext through UNO was abandoned because the bundled Python wrapper would not run the script. On the side of driving the real Excel we stumbled three times (each is written at the top of the judge script as etiquette): AppleScript's open POSIX file summons the sandbox's file-selection dialog and silences Excel (with open -a, LaunchServices hands over just that file); a forced quit raises one more barrier, Microsoft's error-reporting dialog (use only quit saving no); and an Excel with no document open is showing the template chooser, which does not answer Apple events either.

B.32 Placing images in cells — stage 2 of the adoption plan (Rev 4.2)

2026-08-28. Stage 2 of the feature adoption plan. Until now images were only "kept as bytes if the source file had them"; there was no way to place a new one. We implement the placing side. The placement arithmetic and the shape of the drawing XML follow XLKit (MIT); the shape of the "in this cell, over this range" API and the idea of appending to an existing drawing part follow XlsxReaderWriter (MIT). The EMU conversion uses the already-introduced Units as is.

The model — images belong to the sheet and are value types

let img = try SheetImage(data: pngData)      // format (PNG / JPEG / GIF) and dimensions are determined from the bytes
sheet.addImage(img, at: "B2")                 // place at natural size (oneCellAnchor)
sheet.addImage(img, at: "B2", sizing: .fitCell) // fit into the cell's current size, keeping the aspect ratio
sheet.addImage(img, at: "B2", sizing: .resizeCellToFit) // widen the cell to fit the image instead (the XLKit way)
sheet.addImage(img, over: "B2:D6")            // stretch over the whole range (twoCellAnchor)

The format is determined from the leading bytes (PNG signature, JPEG SOI, GIF87a/89a); the dimensions are read from PNG's IHDR, GIF's header, and for JPEG by scanning for the SOF marker. An unknown format throws unsupportedFeature, a broken header throws malformedPart. .resizeCellToFit changes the column width and row height at the moment of addImage (the writer never changes the model in silence). Pixels to column width is the standard (px − 5) ÷ 7 (the MDW of Calibri 11); row height is px × 0.75 pt. We did not take XLKit's px ÷ 8 approximation.

Writing — one drawing part per sheet, so we append

By the rules of OOXML, a worksheet can point at only one drawing. So the writer has two paths: a sheet with no drawing part gets a full set generated — the part, the relationship, the content type and <drawing r:id> (the same planned approach as comments and structured tables). A sheet with a preserved drawing part (charts or existing images) has only the new anchors inserted just before that part's </xdr:wsDr>, and the image relationships are added to the part's relationship file starting from the next rId after the existing maximum. Existing anchors and references to charts are not touched at all, as strings. The inserted anchor carries its own namespace declarations on the element itself, so it does not break whatever prefixes the original part uses.

The meaning of F3 becomes one step finer here: a part that had an image added changes from "byte-identical" to "the existing portion stays byte-identical, with an appendix at the end", and the drawing part of a sheet with no image added stays byte-identical as before. We added to what PreservationTests checks that adding an image to a workbook containing charts leaves the existing anchors and relationships intact. The read side is unchanged — drawings are not interpreted but kept as bytes, so a read workbook's existing images do not appear in sheet.images (only the ones you placed yourself appear).

Other formats — what has nowhere to go is counted and dropped

When writing to Numbers or CSV, images are counted and reported as dropped (ODS became writable in Rev 4.26, B.43) (never deleted in silence; §6). Support for ODS's draw:frame and Numbers' drawing objects is left to a later stage. Streaming write (values and formats only) also remains out of scope.

Verification

Structural agreement of the part, relationship, content type and EMU (px × 9525) in a new workbook; format determination and dimension reading for the 3 formats (the specimens are real bytes cross-converted with sips); appending to a fixture with charts leaves the chart parts byte-identical; the from/to of a range anchor; the dimension effect of .resizeCellToFit; the warnings on other formats. The external judge is openpyxl — it reads the image-bearing workbook we wrote, and we confirm that the presence and dimensions of the images agree.

B.33 Column autofit — stage 3 of the adoption plan (Rev 4.3)

2026-08-28. Stage 3 of the feature adoption plan. Until now there was no side that "measures and decides" a column width (we only carried the bestFit flag). We implement it by translating into Swift the autofit of XlsxWriter (Python, BSD-2, NOTICE item 5) and its character-width table CHAR_WIDTHS (Excel's Calibri 11 as measured, the pixel widths of the 95 ASCII characters).

The measuring follows the source: a string is looked up character by character and summed (with line breaks, the maximum per line); a number is its displayed character count × 7 px; a date is a fixed width; booleans are TRUE = 31 / FALSE = 36 px; a formula is measured by its computed value, and skipped if there is none. Add a margin of 7 px to the column's maximum, add 16 px for the button on an autofilter column, and convert to character units with (px − 5) ÷ 7. The default cap is 255 characters, the same as Excel. A column the user widened by hand is moved only in the widening direction (the same rule as the source). There is one departure from the source: the source treats all non-ASCII as a flat 8 px, but that squashes Japanese text to half its width, so the East Asian full-width ranges (CJK, kana, full-width forms and so on) are 16 px. That this is an approximation is stated in the API documentation — the exact width depends on the default typeface, and the viewer itself approximates it too.

sheet.autofitColumns()                // every column with content
sheet.autofitColumn("A")              // one column only
sheet.autofitColumns(maxWidth: 60)    // with a cap (in character units)

The implementation is a mutating API on the model side — the line that the writer never changes the model in silence (the same as B.32). Verification: the sum over the character-width table agrees (known cases that come out equal to the source's Python implementation), full-width 16 px, the measuring of booleans, numbers and dates, the 7 px margin, the cap, and that an already wider column is not narrowed.

B.34 Creating charts — stage 4 of the adoption plan, the last (Rev 4.4)

2026-08-28. The final stage of the feature adoption plan. Charts were until now "kept only" — we implement the creating side. The scope is as planned: the 4 kinds that make up most of everyday work: column, bar, line and pie. Stacked, scatter, area and radar remain outside the plan's scope (the next plan, if a need appears). For the XML structure (the order of elements, the wiring of axes, the shape of a series) we read libxlsxwriter's chart.c as a structural reference (BSD-2; not a single line of code was copied — as noted in NOTICE item 5).

The model — charts too belong to the sheet and are value types

var chart = Chart(.column)                  // .column / .bar / .line / .pie
chart.title = "Monthly sales"
chart.addSeries(values: "B2:B13", categories: "A2:A13", name: "Sales")
sheet.addChart(chart, over: "D2:K16")     // the position is a range anchor (rides on the same drawing part as images)

A series range can be written without a sheet name — at write time it is qualified with the name of the sheet it is placed on and turned into an absolute reference with $ (because Excel charts accept only sheet-qualified absolute references; a reference that is already sheet-qualified is left as is). A chart with no series is not written; it is counted and reported.

Writing — on the same part as images, with a different kind of anchor

A chart is written as two things: a chart part (c:chartSpace) and an xdr:graphicFrame anchor on the drawing part. The handling of the part shares B.32's mechanism as is — generate a full set if there is no part, append only the anchor at the end if there is a preserved part, and add the image (image type) and chart (chart type) relationships to the part's relationship file under the same numbering. The chart part's number, relationship id and shape id all start from the next after the existing maximum. The order of elements follows the schema order of CT_Chart / CT_PlotArea / CT_BarChart and so on (title → plotArea → legend → plotVisOnly, barDir → grouping → varyColors → ser → axId, and inside ser idx → order → tx → cat → val). Only the pie chart has no axes. The legend is on by default (right) and disappears with legend = false.

Other formats and the second save

To ODS, Numbers and CSV they are counted and dropped (images became writable to ODS in Rev 4.26, B.43, but charts are as before). Reading back a workbook with charts we wrote ourselves leaves charts empty (the chart part and the drawing part go into the preserved bytes), and saving once more is byte-identical — B.22's nail is driven into charts as well.

Verification

The judge is openpyxl — it reads each of the 4 kinds, and the type (BarChart / LineChart / PieChart), the number of series, the reference strings and the title must agree. LibreOffice's PDF conversion must go through. Appending to a fixture with charts leaves the existing charts and images as bytes. The second save is byte-identical. Confirmed on the real Excel too — on 2026-08-28 the maintainer opened the written file containing all 4 kinds in the real Excel and confirmed there was no problem (the unlocking of B.31's protection key was also confirmed on the real application on 2026-08-29, so all 4 stages of the adoption plan reached the real applications).

B.35 A sheet that is not a worksheet — a chart sheet was silently becoming a worksheet (Rev 4.6)

2026-08-31. When we built the per-format feature support table (docs/spec-feature-matrix.html), the chart sheet row alone had no specimen and went out marked "unverified". To fill that row we had the real Excel 16.112.2 create a document with 2 sheets (a worksheet plus a chart sheet) and read it — and a defect came out.

The symptom — we were building a two-faced package, in silence

The reader parsed every <sheet> in the workbook as a worksheet. The chart sheet entered the model as a sheet with 0 cells, and not a single warning was raised. On writing back, xl/chartsheets/sheet1.xml was written with a <worksheet> root, the declaration in [Content_Types].xml became the worksheet type, and the relationship type in the workbook had changed to /worksheet. Only the relationship's name still pointed at chartsheets/ — a package that contradicts itself. LibreOffice opened it leniently, but the PDF it drew had 3 pages against the original's 2. One of the charts had turned into an ordinary sheet.

This is a counterexample to the central promise of this library, "never drop in silence", and worse for having not merely dropped but broken something.

What we decided — carry without interpreting

Besides worksheets, SpreadsheetML has chart sheets, dialog sheets and macro sheets, none of which is a grid. The model has no word for their contents (nor any need to make one — there is no need). But they too are sheets: they sit in the sheet order, have names, and formulas can use those names. So we decided to carry them without interpreting.

public struct ForeignSheet: Sendable, Hashable {
    public var root: String              // "chartsheet" / "dialogsheet" / "macrosheet"
    public var relationshipType: String  // the relationship type the workbook used to point at it
    public var contentType: String       // the type [Content_Types].xml gave it
    public var body: Data              // the part as it arrived
}
sheet.contentState == .nonGrid                // a sheet that is not a grid

The discriminator is the relationship type — if the workbook's relationship does not end in /worksheet, that part is taken as bytes without parsing (only the root element name is read, from the first 4 KB). On writing, those bytes are written to the same part path, and the content type and relationship type are the original ones. The chart parts and the drawing part go into the preserved bytes as before, so they round-trip together.

What we say

We say it on reading (degraded). This is the point: in silence, a user iterating Workbook.sheets reads "a sheet with no cells" as "it was an empty sheet". It only makes sense once told "this is not a grid". Further, if the file is saved with cells written into that sheet, the writer reports dropped — the part goes out as is, so the writes are not saved. When converting to other formats they are counted and reported too.

Verification

The specimen was made by the real Excel itself (Tests/FixtureGenerator/make_chartsheet_fixture.py, AppleScript), so that we read the chart sheet Excel writes, not one we imagined. ChartSheetTests has 5 tests — the warning on reading and the contents of ForeignSheet, the byte-identical part plus content type and relationship type on writing back, the warning when cells are written, conversion to other formats, and the judge: LibreOffice draws the written-back file with the same page count as the original (before the fix it was 2 against 3).

The one remaining row, the Numbers input form (TN.FormBasedSheetArchive), can only be created on iPhone / iPad and we have no specimen, so it is left as "unverified" in the support table. Not writing ○ or × by guesswork is this document's policy.

B.36 A tab called a form — the specimen arrived and the last "unverified" was filled in (Rev 4.7)

2026-08-31, the same day as B.35. The specimen for the other "unverified" left in the support table — the Numbers input form — arrived from the maintainer. A form can be created only in Numbers on iPhone and iPad; there is no way to make one on the Mac. So this row alone was not filled in by guesswork; we waited for a hand-made specimen to arrive (this makes 8 documents produced by the pattern of asking the maintainer for a specimen that only the UI can create).

The symptom — again, deleting in silence

The reader took only the TN.SheetArchive ones among the document's sheets references and threw the rest away without a word. The specimen that arrived has 2 tabs, one table and one form, but it reads as 1 sheet, with 0 warnings. A defect of the same shape as B.35's chart sheet (found the same way, too — it came out when we went to fill in a row we had marked "unverified").

What we decided — do not dress it up as an empty sheet; drop it by name

We treated it differently from the chart sheet. A chart sheet has contents that only that tab holds, so we carried it as bytes; but a form is a screen for typing into a table that already exists, and holds no values of its own (TN.FormBasedSheetArchive embeds a TN.SheetArchive as super and merely points at its table by table_id). Putting it into the model as an empty sheet would have the writer copy that lie and produce "a document with an empty tab". So we drop it.

Dropping means saying so. The warning names the form and the table it writes into — because what matters to the user is not only "what was lost" but also "what was not lost".

// Measured (Fixtures/numbers/form-15.numbers, made on an iPhone)
dropped  the form "表1フォーム" is dropped: a Numbers form is a way of typing into
         the table シート1::表1, not a sheet of its own, and the model has no word
         for it — the table it fills in is read as usual

Should a tab that is neither TN.SheetArchive nor TN.FormBasedSheetArchive appear in future, it is reported the same way, naming the type (so that not one path that vanishes in silence is left).

Verification

NumbersFormTests has 4 tests — that the specimen really has a form storage, that the values of the table the form fills in are read normally, that there is exactly one warning and it names both the form and the table, and that writing back keeps the table and does not bring the form back. With this, the support table's "unverified" count is 0 (all 191 rows are backed by a measurement or a code check).

B.37 An undeclared crossing — only Numbers was refusing, in silence (Rev 4.8)

2026-08-31. Having set up openpyxl through uv, we ran the pre-release checklist in MAINTENANCE.md to the end for the first time, and a document came out that Numbers.app would not open.

Narrowing down — there was one condition

A single sheet (with or without formatting)… opens / 2–3 sheets, no formatting… opens / 2 sheets, formatting on the first only… opens / 2 sheets, formatting on the second (fill, number format or font, any of them)… does not open. The 5 sheets of the sample workbook all open one at a time, and no pair of them opens.

numbers-parser, LibreOffice and our own reader all read the broken document without complaint. Only Numbers objects — a shape we saw once before in Appendix B.18.

The cause — a reference across parts cannot be followed unless declared in the inventory

Numbers follows references across components through the document's inventory (TSP.ComponentInfo.external_references). An undeclared crossing is a reference that cannot be followed, and Numbers refuses the document without giving a reason.

The style objects that a table's style list names by name live in the stylesheet's component, so the crossing needs declaring. But the component of a duplicated sheet is, while that sheet is being written, still only reserved and not yet in the inventory (flushComponents runs once, at the end — walking the inventory again for every object would take the write from 1 second to 2 minutes). So componentID(forObject:) returned nil, and the declaration itself was skipped wholesale.

The first sheet rewrites the template's table in place, so its component already exists and the declaration succeeds — that is why "formatting on the first sheet is fine, formatting on the second breaks".

The fix

Crossings are collected and registered once the parts are all present (pendingCrossings → registerPendingCrossings(), right after flushComponents()). A crossing that still has nowhere to go is reported with a degraded warning — it is not dropped in silence. NumbersDocument.addExternalReferences also stopped doing nothing in silence for a part it does not know, and now holds the reference until the part appears.

What we did not do

We did not add the general invariant "every crossing must be declared". When we measured, documents made by Numbers itself had 47 undeclared crossings (templates had 42). We do not know where Numbers draws the line between what it requires and what it does not, so we will not guess at an invariant. Instead we placed a check limited to crossings in the style list in NumbersCrossingTests — nailing down only the range that measurement backs up.

Why it slipped past 19 samples

Sample 05 has formatting but a single sheet; 09 has two sheets but no formatting; the four-sheet comprehensive sample 15 has all its formatting on the first sheet. There was not one document with formatting on a sheet other than the first. On top of that, the pre-release check starts from openpyxl and so had not run. When two holes line up, nobody looks. We added sample 19-style-on-second-sheet and NumbersCrossingTests, which needs no real application, so CI catches a recurrence.

B.38 The compression seam — removing both Apple-only parts (Rev 4.9)

2026-08-31. This resolves the state B.1 recorded as "the price is that §1.1's 'runs on Linux' is not met". To begin with, there is no external ZIP library to replace — opening and closing the envelope is our own 371 lines, and what stood in the way were the two Apple-only parts that actually fold the bytes inside it: Compression (two files for ZIP reading and writing) and CryptoKit (one file for the key of B.31's protection). Not one line of the envelope handling itself was moved.

What we decided

• The folding tools go behind a seam. SheetCore/Container/Deflate.swift gathers the one-shot compress / decompress and the streaming DeflateEncoder, with two implementations under #if canImport(Compression) && !SWIFTSHEETS_ZLIB. ZIP's method 8 is raw DEFLATE; COMPRESSION_ZLIB is exactly that, and zlib produces the same stream with windowBits = -15.
• zlib is not a SwiftPM dependency. Sources/CZlib is a single module map over the zlib.h that is already there; SwiftPM has nowhere to fetch from. It ships in Apple's SDK and on Linux from the start, so both may depend on it unconditionally (B.1's "zero external dependencies" is unchanged).
• SHA-512 goes back in-house — revising B.31's "do not hand-write cryptographic primitives". Two reasons: merely because CryptoKit exists, Linux would lose the protection key altogether, and adding swift-crypto would be the first SwiftPM dependency. Sixty lines of arithmetic; Excel's default 100,000 iterations take 0.29 seconds in a release build (measured).
• Follow Foundation's split. XMLParser lives in FoundationXML on Linux, so the eight files that use it gained #if canImport(FoundationXML).

The judge — running the whole zlib path on a Mac

Without Linux CI we cannot say "the zlib path is correct". So we added -DSWIFTSHEETS_ZLIB and run the same 941 tests through the zlib path too, on macOS, which has both toolboxes (added to the CI steps). Every xlsx / ods / numbers round trip passes under zlib. In addition, CompressionTests holds a DEFLATE blob that neither implementation produced (57 bytes made by zlib's own compressor) and confirms that whichever side was compiled can read it. The judge for SHA-512 is three known answers from FIPS 180-4 and a cross-check against CryptoKit on Apple platforms (ten boundary cases).

Even so, the behaviour of the Linux Foundation cannot be measured on a Mac (dates, decimals, the table of encodings String(data:encoding:) supports). Therefore we do not yet claim Linux support: a Linux job (swift:6.2-noble) goes into CI, and until it is green the README badge and §1.1's achievement stay as they are. No claim goes in without a judge.

What the judge said (2026-08-31, five runs on PR #1)

The Linux job went red three times, for a different reason each time. Build: the type checker could not solve two concatenated expressions (the named formats in StylesWriter, the origin cell of conditional formatting in ODSReader; the latter took 1.3 seconds even on a Mac) — rewritten statement by statement. Tests: the whole process aborted. Running suites one at a time, the report named the culprit — Illegal instruction in _NSXMLParserStartElementNs of libFoundationXML (called from libxml2). Not one frame of ours lies inside it (our innermost frame is the XMLParser.parse() line in SAXDriver.run).

With that one suite (FuzzTests) excluded, all 938 tests are green on Linux (six of them pass with the known issue of LibreOffice being absent). CSV's Shift_JIS passes too — the suspicion noted as "doubtful" above was wrong.

The specimen — reproduced to the byte

Fuzz seed 1, round 174. The material is generated.xlsx, 4131 bytes, CRC32 4279849508. Bytes 233–236 of [Content_Types].xml were mutated to ff ff ff ff, turning <Default …> into <De + 4 bytes + t …> — bytes that are invalid as UTF-8 in the middle of an element name. libxml2 reports it as a start tag, and Foundation, receiving it, crashes while turning the name into a String. Reproduction is 175 rounds with SWIFTSHEETS_FUZZ_SEEDS=1 plus -DSWIFTSHEETS_ZLIB — unless the compressed bytes of the material match, even the way the random numbers are consumed afterwards changes. That match is itself evidence that the two DEFLATE paths emit the same bytes.

This collides head-on with §12 pillar 5 (no crash on malformed input) and the promise in SECURITY.md. The fix is our responsibility — the cause of the crash lies outside, but handing over input that does not crash is our job. We are considering checking that a part is well-formed UTF-8 before handing it over, and throwing malformedPart as before when it is not (parts with a BOM, or whose declaration names an encoding other than UTF-8, pass through). Whether that closes every kind of breakage is unknown, however; the only way is to iterate while asking the judge.

The defence was added — and Linux went all green

2026-08-31. The policy: "add a defence before handing over, and only then claim Linux". An XML part is checked to be well-formed UTF-8 before it is handed to Foundation (SAXDriver.rejectUndecodableBytes). If it is not, malformedPart is thrown as before, with the byte offset attached — the reasoning being that the cause of the crash lies outside, but handing over input that does not crash is our job. A part whose BOM names another encoding, or whose XML declaration names something other than UTF-8, passes through (the parser decodes those itself, so the question does not apply). The scan reads in place with withUnsafeBytes — a part of tens of MB is not copied for the sake of a check. firstInvalidUTF8Offset moved from SheetCSV to SheetCore (TextEncodingSniffer) and is shared by both.

The specimen was taken in as Fixtures/malformed/content-types-invalid-utf8.xlsx, and a hand-made twin (confirming that the byte offset is named) and two pass-through cases (a UTF-16 BOM, a Shift_JIS declaration) were placed in MalformedInputTests.

One hole remained — "a part naming another encoding passes through" (Rev 4.24, 2026-09-05)

The judge for 0.14.0 (Linux) crashed once more in the same function (_NSXMLParserStartElementNs). At first we suspected the Snappy decoding that was running at the same time and rewrote it, but re-reading the crashed thread showed the culprit was the exception in the defence above. The mechanism is this. ① A part whose XML declaration names something other than UTF-8 was handed over unchecked, on the assumption that the parser decodes it itself. ② When a fuzz mutation breaks the declared name itself (one character of UTF-8 becomes another), libxml2 reports "unsupported encoding" and then, because Foundation runs it in recovery mode (XML_PARSE_RECOVER), keeps reading the bytes as they are. If an element name further on contains a byte that is not UTF-8, it crashes at the same place as the first hole. ③ So the pass-through was limited to "8-bit names the parser knows" (SAXDriver.decodableEncodings: ASCII, ISO-8859-x, Windows-125x, Shift_JIS, EUC-JP, ISO-2022-JP, GB, Big5, EUC-KR, KOI8-R). An unknown name is malformedPart ("encoding … is not one this library can decode"). A part that declares UTF-16 / UTF-32 over an 8-bit byte sequence with no BOM is read by libxml2 as UTF-8, so it is checked as UTF-8 (wideEncodings).

The crashing mutation itself could not be recovered from CI — from now on the fuzzer puts the mutation it is reading on disk (SWIFTSHEETS_FUZZ_KEEP_DIR, deleted once read) and brings it home as an artifact only when a crash occurs. Two tests in MalformedInputTests (an unknown name is refused; a known name and a false UTF-16 claim).

Result: 944 tests on Linux, 945 on macOS, all green (the one difference is the Apple-only check that cross-checks against CryptoKit). The fuzz suite is no longer excluded either. Locally, 6,000 rounds of fuzzing also pass. With this, §1.1's "runs on Linux" is achieved — the README badge, Limits, docs/index.html and CONTRIBUTING were rewritten. Note that we cannot say "every kind of breakage is closed": what was closed is the one kind that actually crashed, and the possibility of another kind remaining shrinks only by keeping the fuzzer running. We reported it upstream as swiftlang/swift-corelibs-foundation#5536 (2026-09-01, a one-line fix plus a regression test). Even once it is fixed, this defence stays — on a machine with an older Swift the defect would remain.

B.39 Speed and size, second round — measure, then fix (Rev 4.12 onward)

2026-09-04. The theme of 0.12.0 is speed and size. Before starting we measured reading and writing on synthetic data of one million cells (10 columns × 100,000 rows) and took a profile of the calls. Three things emerged: of the 5.7 seconds to read, about 70% is Foundation's XML part and the string handling around it, while inflating takes a mere 0.02 seconds. Writing copies the same 33 MB of sheet XML five times. Format detection already takes 0.1 milliseconds, and what needs adding is not speed but "an entry point that does not read the whole file". The bench and the raw data are kept in the workshop repository; the public side carries only the results of measurement (the numbers are cross-checked by machine, not "remembered" — as B.6 laid down). This section records each stage of 0.12.0 as a subsection, in the order it was started.

B.39.1 Rebuilding the envelope (ZIP) — beyond 4 GiB, piece-by-piece inflation, bombs

The in-house envelope handling that B.38 described with "there is no external ZIP library to replace" was this time rebuilt from the inside. Three motives. ① Parts beyond 4 GiB and more than 65,535 parts (ZIP64) could be neither read nor written (the README's Limits said "not supported" explicitly). ② A part could only be inflated whole, and the +54 MB of the streaming read (B.15) was fixed by this one point. ③ The guard against a construction that swells without limit when inflated (the so-called ZIP bomb) was only "verify the declared length" and never questioned the validity of the declaration itself.

What we decided

• Abstract where the bytes come from (ByteSource). Two implementations: a byte sequence in memory (including a mapped file) and a file read on demand by positioned reads (pread). A reader asks only for the central directory and the range of the one part in hand; there is no path that requests the whole file. It opens even where mapping is unsafe (a shared folder, say) and even an envelope larger than memory. The same implementation on Linux (pread from Glibc).
• Read and write ZIP64. Reading follows the locator at the end of the central directory → record, and fills in the 0xFFFFFFFF values of each directory entry from the extended field (0x0001). Writing emits the ZIP64 directory, record and locator only when needed (a part or an offset of 4 GiB or more, or 65,535 parts or more). A part written in streaming mode reserves a 16-byte extended field in its local header, and at the end the sizes are stamped into both the 32-bit fields and the extended field (no data descriptor — the safest shape for reader compatibility). Tests force the ZIP64 path onto small files with forceZip64, and also read a sample that Info-ZIP produced with -fz.
• Inflate a part piece by piece (ZipEntryStream / DeflateDecoder). Compressed bytes are read 256 KiB at a time, inflated, and only what was inflated is handed on. A streaming decoder was added to both the Apple Compression path and the zlib path (behind B.38's seam). The later stages of B.39 (streaming) build on this.
• Trust the declaration, but question its validity (ZipLimits, ReadOptions.limits). Inflation runs up to exactly the declared size — a stream that tries to produce more is stopped as corruption (the one-shot inflation on the Apple path allocates one extra byte to detect overrun). In addition, at the point the central directory is read, the number of parts (default 100,000), the declared total of all parts (default 16 GiB) and the compression ratio (1,000× for a part inflating to 16 MiB or more) are checked, and anything beyond is refused with corruptedContainer. Overlapping parts — several directory entries pointing at one local header, a construction in which a small file claims large contents — are refused too. All of these can be relaxed with ReadOptions.limits by a caller who knows its own files.
• Copy while still compressed (compressed(_:) / addCompressed). Parts that are not interpreted (charts, pictures, pivot-table records, VBA) can be put into the next envelope as compressed bytes, without inflating or recompressing. F3's "byte-identical" becomes literal, and the time and memory of a round trip no longer scale with the size of those parts. Moving the preservation writer (B.4) onto this is a later stage.
• CRC-32 uses zlib's implementation. A Swift table walk takes 0.09 seconds over 33 MB; zlib's (which uses processor instructions) takes 0.001 seconds (measured). zlib is at hand from the start on both paths, as B.38 says.
• Remove the surplus copy in one-shot compression. Truncating the compressed result used to copy with Data(prefix); now the length is simply shortened in place.

Judges

ZipTests: Info-ZIP's ZIP64 sample, a round trip of our own (forced) ZIP64, a round trip of 65,540 parts, positioned reads from a file matching the mapping, piece-by-piece inflation matching one-shot, byte-identity of a copy made while still compressed, refusal of the four constructions (overlap, ratio, total, part count), refusal of a stream exceeding its declaration. The existing MalformedInputTests and FuzzTests are unchanged. Everything on both paths (Apple / zlib).

B.39.2 The cell-count ceiling moves to the reading side

The cellLimit that B.9 described with "it properly belongs in ReadOptions and moves there once a user has a reason to choose it" had stayed at a default of 1,000,000 since Rev 1.5. This time the default ceiling is removed (Int.max). Two reasons. ① A million cells is large for one sheet on iOS, but on a Mac or a server it is not unusual for one file. ② Whether a ceiling is needed is the reader's business (memory, whether the sender is trusted), not something a library decides uniformly. The setting remains: for untrusted input set ReadOptions(cellLimit:), and beyond it reading stops as before with one degraded warning per sheet. ODS's judgement that "an empty repetition is a specification, not content" (paddingRepeat, §8.3) is unchanged. An entry point for asking how many cells there are before reading is added in the next subsection (B.39.3).

B.39.3 Asking before reading — Workbook.inspect

Having removed the ceiling in B.39.2, the reading side needs material to decide with. Workbook.inspect(contentsOf:) / inspect(_:) return, without creating a single cell, "which sheets there are, how many cells each sheet declares, how many bytes the envelope inflates to, and who wrote it" as a WorkbookSummary. The caller looks at this and either sets ReadOptions.cellLimit or does not read.

• XLSX: the sheets come from workbook.xml, the declared range from the <dimension> at the head of each sheet part. Only the first piece of the part is inflated (B.39.1's ZipEntryStream). Declarations lie (there are writers that write "A1" and hold 100,000 rows), so InspectOptions.countsCells provides a separate path that walks the whole part as bytes and counts <c> — this matches the count a read actually holds.
• ODS: there is no declared range, so content.xml is walked once as bytes and the cells holding values are counted by multiplying by the repeat count (without expanding). A construction that claims a billion cells in 1 KB returns that number as is.
• Numbers: the table archive declares its row and column counts, so their product. Decoding the IWA takes as long as a read does, however (the tile contents are not touched).
• CSV: the row count (number of newlines) only.

What walks is not an XML tokenizer but a byte scanner that picks out only tags (TagScanner). A tag split at a piece boundary is carried over and joined. It is the forerunner of the real tokenizer built in a later stage of B.39; the shape "read bytes without creating strings or dictionaries" was tried out here first.

B.39.4 Format detection — an entry point that does not read the whole file, and a result type that answers in one call

Detection was fast to begin with: 0.1 milliseconds for a 5 MB xlsx, 0.4 milliseconds even for 400 MB when opened by mapping (measured before starting). But the path that reads the whole file without mapping used 48 milliseconds and 390 MB, and on an iPhone or a shared folder that difference matters. What was added is not speed but shape.

• SheetFormat.detect(contentsOf:) opens with FileByteSource (B.39.1) and reads only the first 4 bytes → for an envelope, the central directory in the last 1 KiB (a 64 KiB window if it is not there) and one small part; for text, the first 64 KiB. A test nails down "a 700 KB xlsx is detected in under 16 KiB" with a double source that counts the bytes read.
• SheetFormat.probe does not make the caller ask "what format is it" and "is it encrypted" separately. FormatProbe is one of three: .spreadsheet(format) / .unopenable(reason) / .unrecognized. encryptedNumbers (.iwph) was added to the reasons, and the refusal on the Numbers side now speaks with the same word.
• Until now a Numbers document in folder form made Data(contentsOf:) fail with "is a directory", so it could not be opened (measured). NumbersDocument(folder:) gathers Index.zip (or Index/), Metadata/ and Data/ from disk into the same object as a single file. Writing stays single-file.
• Text detection no longer decodes into a String before scanning; it looks at the bytes for UTF-8 validity (reusing B.38's scanner), UTF-16 surrogate pairs and control characters. A multibyte character cut at the edge of the window is treated as a boundary, not a defect. The results of detection are unchanged (the existing tests pass as they are).

B.39.5 Small fixes with little rework — what the call profile named

Fixes that ranked high in the profile taken before starting and change not one byte of any format. Before and after were compared on the same machine at the same time (the machine itself had slowed by about 10% under prolonged load, so comparisons against a baseline from another time are discounted).

• Date-format detection once per format number. For every numeric cell, a 384-byte style was fetched and its format code scanned (8% of the profile). StylesParser.numericKind now remembers xf number → plain / date / elapsed time.
• Style indexes looked up by identity of the shared style. Writing hashed a CellStyle for every cell (about 20% of the profile). StyleRegistry.index(for: Cell) / ODSStyleRegistry.cell(of:) look up by the identity of the SharedStyle the cell points to, and do not recompute for the same object.
• The streaming write accumulates 64 KiB before going to the compressor. Handing over row by row was why it had been slower than the whole-model write.
• A short cut for ODS paragraph generation: a string containing no spaces, tabs or newlines (most values) is escaped as is, without building a character array.
• Numbers' Snappy and IWA frames are read without copying into arrays. The inflated output is also written straight into Data, not an array.

Measured (one million cells): read 5.58 → 4.17 s (−25% at the same time of day), streaming read 5.1 → 3.2 s, write 2.0 → 1.7 s, streaming write 2.4 → 1.9 s, ODS write 4.0 → 3.3 s, Numbers write (100,000 cells) 0.94 → 0.81 s. Memory is unchanged (the theme of the next stage). The ODS read was out of scope and did not change.

B.39.6 An in-house tokenizer — Foundation's XML part leaves the default

The largest item the profile named before starting. Of the 5.7 seconds to read one million cells, Foundation's XMLParser itself took 0.7 seconds, and around it the bridging strings and attribute dictionaries created per element, and the comparisons and conversions on the receiving side took about 3.5 seconds. The lower bound for cutting up the same 33 MB as bytes is 0.02 seconds. Most of the difference is the price of "make a string, then read it".

What we decided

• XMLScanner (SheetCore): a tokenizer over UTF-8 bytes. The declaration, comments, processing instructions, DOCTYPE (skipped together with its internal subset; entities are not expanded), CDATA, the five predefined entities and character references, both quote characters, attribute-value normalisation (raw tabs and newlines become spaces; character references stay as they are), newline normalisation in text (\r\n → \n). Names are compared as bytes; strings are made directly from UTF-8 (validity is guaranteed by B.38's prior check). A mismatched end tag, an unclosed element, an unclosed tag or an out-of-range character reference is malformedPart. An undefined entity is left as written (Foundation stops, but spreadsheets have no DTD).
• The handler's contract does not change. The three events of SAXHandler (start / text / end) and the preservation cut-outs stay as they are; the driver SAXDriver switches between two engines inside. The eight readers (every XLSX and ODS parser) are unchanged by a single line.
• A preserved fragment is now the original bytes themselves. Previously the attributes were reordered and regenerated. Since the cut runs from < to the end of the end tag, attribute order and whitespace are exactly as in the source file.
• UTF-16 parts, and parts naming another encoding, go to Foundation (Engine.automatic). -DSWIFTSHEETS_FOUNDATION_XML returns every part to the Foundation path. The macOS CI job runs everything under this flag too, built the same way as the zlib path. Keeping the old path for one version is so that a "path known to be correct" stands beside any defect in the tokenizer.

Judges

XMLScannerTests: every XML part of every sample (27 documents, 289 parts) is run through both engines, and the sequence of events (element name, attributes, text, end) and the root attributes must be entirely identical. The corner cases (entities, character references, CDATA, comments, DOCTYPE with internal subset, both quote characters, attribute normalisation, the three kinds of newline) also match across both engines. A cut-out fragment is the original bytes. Refusal of nine kinds of broken syntax. A UTF-16 part is routed to Foundation automatically. Abort from the handler. Two mistakes of our own found during development — whitespace outside the root was passed as text, and Swift's where applies only to the last item of a list, so newlines in text were being turned into spaces too — both of which the cross-check turned red and told us. The whole: 984 tests green on three paths (default, Foundation, zlib).

Measured (one million cells, against the previous binary at the same time): read 5.50 → 2.64 s, streaming read 4.58 → 1.81 s, ODS read 13.86 → 3.71 s. Against the 5.7 seconds before starting, 2.2× faster; ODS 3.7×. Memory is still unchanged (next stage).

B.39.7 Not holding the output — parts travel compressed, rows flow into the compressor

The write profile showed "the same 33 MB of sheet XML is copied five times" (the opening of B.39). The peak for writing one million cells was 360 MB against a model of 203 MB, and 641 MB for ODS. On top of that, opening a file, fixing one cell and saving — the reason this library exists — was paying time and memory in proportion to the size of the parts it does not interpret (charts, pictures, pivot-table records, VBA) by inflating them when reading and recompressing them when writing.

What we decided

• Uninterpreted parts travel compressed (OpaquePart.compressed). The reader takes the compressed bytes, CRC and sizes from the envelope as they are (B.39.1's compressed(_:)), and a writer of the same format copies them straight into the envelope (addCompressed). No inflation or recompression occurs, and F3's "byte-identical" became literal. The public opaqueParts became a computed property that inflates only when accessed, and names and counts are answered without inflating (opaquePartNames / opaquePartCount). FoldedPartTests: the compressed bytes of charts, pictures and themes are identical between input and output.
• XLSX sheets flow their rows into the compressor. sheetPart returns what comes before and after <sheetData> as strings, and the rows as a closure that "writes into a given buffer". The buffer is a PieceBuffer that hands itself to the compressor each time 64 KiB accumulates. Whether there is a shared-string table must be decided before the rows are written, or the directory and the content disagree, so it is decided up front from the model by "is there a text value that is not a formula" (we noticed that because PreservationTests went red on sharedStrings.xml being undeclared). The sheetXML the tests read flows the same closure into a string.
• The ODS body is set aside for a while (TextSpill). ODS must write the styles registered while building the body before the body, so the whole body has to be built first. Up to 8 MiB is held as fragments; beyond that it spills to a temporary file, and after the styles are written it is read back 1 MiB at a time and handed to the compressor. The table XML flows into the buffer row by row and is not grown as one string.

Measured (one million cells, against the previous binary at the same time): write peak 360 → 258 MB (time 1.8 → 1.7 s), ODS write 641 → 313 MB (4.0 → 3.2 s), open, fix one cell and save 6.9 → 3.8 s, 397 → 288 MB. What remains is the model itself (203 MB) and the shared-string table, a matter for the next version (the opening of B.39). Once during measurement, an incremental build on the bench mixed in stale parts and the output looked broken (2 bytes duplicated in the middle of a multibyte character). A rebuild made it vanish. We wrote "delete .build before measuring" into the bench guide.

B.39.8 Not holding the input either — a part is inflated and read piece by piece

B.39.6's tokenizer assumed the bytes of the whole part. Combined with B.39.1's ZipEntryStream, it now inflates 256 KiB of compressed bytes, reads them, and discards what has been read (XMLScanner.feed plus SAXDriver.run(stream:)). A tag split at a piece boundary, text in mid-flow and an open preservation cut-out are carried over to the head of the next piece. The carry-over starts from "the first byte still needed", and what has already become an event is not read twice (feed(startingAt:)). The UTF-8 check (B.38) is also done per piece, and a multibyte sequence cut at the boundary waits for the next piece. UTF-16 parts and parts in another encoding have their pieces collected before going to Foundation.

Four places were moved onto this: the XLSX sheet parts and shared-string table, the streaming read, and the ODS body. The handlers are unchanged by a single line. StreamingTests counts "the largest number of bytes of a part held at once" during a streaming read of 100,000 rows and nails down that it is at most two pieces plus 1 MiB — the README's "+2 MB" stands on this number.

Measured (one million cells): streaming-read peak 61 → 23 MB (most of it the shared-string table), read 254 → 221 MB, ODS read 318 → 233 MB, open, fix one cell and save 288 → 262 MB. Time is unchanged (2.8 / 1.9 / 4.0 s). Reading one million cells went from 5.7 s and 256 MB before starting to 2.8 s and 221 MB, and the streaming read from 5.1 s and 61 MB to 1.9 s and 23 MB. Of the remaining 221 MB, 203 MB is the model itself.

Fixing the UTF-8 check at the boundary (Rev 4.28, 2026-09-05): each time a piece arrives, only what arrived is checked as UTF-8, and a character cut at the boundary waits for the next piece — the starting point of this re-check had been the fixed position "3 bytes from the end of what is held". When that position lands on a continuation byte of a completed 3-byte character, the continuation byte on its own is invalid UTF-8, so a valid part was refused with "byte N is not valid UTF-8". B.39.11's 200-column benchmark found it in a 10-million-cell streaming-written XLSX (every row holding 「分類A」). The re-check now starts from where the previous check stopped (the end if everything passed; the head of the character if one was cut at the boundary). The regression test uses an uncompressed part (so a piece is exactly 1 MiB), places 「分」 at 2 MiB − 4, and confirmed that before the fix it failed at byte 2097149 (StreamingTests).

Two reasons the streaming-read peak grew with the row count, and the fixes (Rev 4.31, 2026-09-05): B.39.11's two-tier benchmark showed the streaming read alone swelling several-fold at the second tier (100 columns, 1 million → 10 million cells: XLSX 19 → 62 MB, ODS 228 → 709 MB, Numbers 53 → 329 MB; the streaming write is flat). Measuring each stage in a separate process split the cause in two.

1. One piece from the inflater was too large. ZipEntryStream read compressed bytes 256 KiB at a time and inflated all of it in one go. An XLSX sheet part swells only about 6×, so a piece is 1.7 MB, but an ODS body (content.xml, full of repeated identical values) swells 60×, and a piece becomes 15 MB. Even after the handler finishes reading the piece and discards it, the macOS allocator merely marks a release of this size "for later reuse", and the resident-memory figures (ru_maxrss / phys_footprint) do not go down. Each arriving piece stacked up another 11–15 MB, and it did not stop until the compressed bytes were exhausted (the same growth in an experiment that only discarded 1 MiB pieces; wrapping in autoreleasepool changed nothing, and stripping out the tokenizer, the carry-over and the byte source to leave only the inflater gave the same result). The fix: cap the inflater's output per call at 1 MiB (DeflateDecoder.pieceCap = pieceSize × 4, the same as an uncompressed piece). Compressed bytes not consumed when the cap is hit are kept by ZipEntryStream in its own 256 KiB copy and carried to the next call (the source's bytes are borrowed, so they are copied). The inflater now returns "the number of input bytes consumed" (on both the Apple Compression path and the zlib path). As a by-product, the hole where a part with a compression ratio of 1,000× would make a 256 MB piece is closed too. The regression test streams a 24 MiB part that compresses 50×, confirmed that before the fix a 10.7 MB piece came out, and then nails down largestPiece ≤ 1 MiB (ZipTests).
2. Opening from a URL mapped the file. StreamingReader(contentsOf:) and the readers of the three formats opened the file with Data(contentsOf:options: .mappedIfSafe), and the pages walked stay resident as they are. An experiment that did nothing but touch the whole file gave XLSX 50 MB, Numbers 275 MB (= the size of the file). It was not the reader's own belongings but the touched pages of the mapped file that sat in the peak. The fix: a streaming read opened from a URL uses positioned reads, not a mapping (FileByteSource, the same source as B.39.4). The readers of the three formats gained an entry point "build from an opened container" (init(archive:); for Numbers, NumbersObjectIndex(url:)), and the unified reader does format detection on the source as well (SheetFormat.probe(source:filename:limits:) — detected with the same limits as the reader, so that a container refused under the default limits is not answered with "unrecognised"). The refusal of compound files is also looked at on the source (UnopenableInput.probe(source:)). The public entry points that take Data stay as they are — the pages of a mapping handed in are the caller's belongings.

Measured (ru_maxrss in a separate process; walk = walking every row of the first sheet): ODS 10 million cells, open only 576 → 12 MB, walk 709 → 15 MB; XLSX 10 million cells walk 62 → 16 MB; Numbers 10 million cells walk 329 → 58 MB (the rest is the index and the string table — the reader's genuine load). The figures are the same for 1 million and 10 million cells, and the streaming read is now flat regardless of row count. Time is unchanged (the old and new builds run alternately on the same machine at the same time — the 0.17.2 record in B.39.11).

B.39.9 Reading and writing password-protected files — the two encryption formats, and our own arithmetic

§1.3 said "encrypted files — to be considered later; v1 raises an explicit error". In 0.12.0 we finished considering it. One correction before starting: rebuilding the envelope (ZIP) does not open an encrypted file. Excel's password protection is not ZIP encryption; it puts the whole ZIP inside another container (an OLE compound file) and wraps it in AES, and ODF's protection wraps each part of the ZIP individually in AES. Both are jobs separate from the envelope, and the only thing the rebuild of B.39.1 helped with was "a part can be taken out while still compressed".

The two formats we read and write

• Excel (ECMA-376 Part 2 / [MS-OFFCRYPTO] §2.3.4, the agile format) — what Excel 2010 and later write. A small XML called EncryptionInfo declares every parameter (salt, iteration count, hash, key length), and EncryptedPackage holds the ZIP wrapped in AES-CBC in 4096-byte segments. The keys are derived, one per purpose, from the password hashed 100,000 times, and tampering with the package is detected by an HMAC. Reading accepts what the XML declares (SHA-1 / 256 / 512, AES-128 / 192 / 256); writing produces Excel's own combination (AES-256, SHA-512, 100,000 iterations). The Excel 2007 standard format (SHA-1, AES-ECB) and the RC4 formats before it are refused by name — we have no tool at hand that can produce a sample, and an implementation without a judge does not ship (B.6).
• ODF (ODF 1.2 §3.4 / 1.3 §4.3) — what LibreOffice writes. Per part: deflate → W3C padding → AES-CBC; the key is derived from the SHA-256 of the password (the start key) with PBKDF2-HMAC-SHA1 using a per-part salt, and the SHA-256 of the first 1024 bytes of the compressed bytes is recorded in the manifest. mimetype and the manifest stay in plain text (which is why the file keeps being detected as .ods). The iteration count on write is the same as LibreOffice's, 1,024 — derivation is per part, so paying Excel's 100,000 once per part would make the file take seconds to open. The Blowfish format of ODF 1.1 is refused by name.

Our own arithmetic

The reasons of B.38 apply unchanged: CryptoKit is Apple's, Linux has nothing, and we do not add SwiftPM dependencies. In SheetCore/Crypto we wrote AES (FIPS 197, the table-lookup form), SHA-1, SHA-256 (FIPS 180-4), HMAC (RFC 2104), PBKDF2 (RFC 8018), and reading and writing of OLE compound files ([MS-CFB]). The existing SHA-512 was reworked into a form that keeps per-block state, so that the password's 100,000 rounds pay no allocations. The judges are the known answers of each standard itself: FIPS 197 Appendix C, SP 800-38A F.2, FIPS 180-4, RFC 4231 / 2202, RFC 6070, RFC 7914 §11 (CryptoTests).

Outside judges

• A protected file made by msoffcrypto-tool (Fixtures/encrypted/agile.xlsx) is opened with its password.
• A file protected by this library is opened by msoffcrypto-tool (EncryptionParityTests, Tests/EncryptionParity/verify_encryption.py, run with uv). The 4 DataSpaces parts of the compound file are written as the fixed byte sequences that msoffcrypto-tool's output contained.
• ODS is read by an independent decryptor that follows ODF 1.3 §4.3 with the cryptography library (the same script). Both roads to making LibreOffice itself the judge were blocked — its bundled Python is killed by macOS (signature verification), and the headless conversion has no way to pass a password. A check in the GUI goes on the pre-release checklist.
• A tampered package is refused by the HMAC, and a wrong password is answered with SheetError.wrongPassword (new).

The API is ReadOptions.password / WriteOptions.password / InspectOptions.password, and StreamingReader(data:password:) for the streaming read. A password for CSV or Numbers is unsupportedFeature (CSV is plain text by definition; Numbers' encryption is undocumented). The tests write protected files with a short iteration count to keep the time down (reading follows the count the file declares, so what can be opened does not change), and just one round-trips with the same count as Excel.

Rev 4.29 — decryption and encryption move to separate products (0.17.0)

In 0.17.0 password handling was taken out of the core. Whichever of SwiftSheets and the 5 products (SheetCore / SheetXLSX / SheetCSV / SheetODS / SheetNumbers) you link, no encryption or decryption code goes into the binary. The reason is declarations: an app that links this library may want to answer export-control or App Store questions with "uses no cryptography" or "decryption only", and a form in which whether the code is present is decided by the Package dependencies alone is the most certain and the easiest to explain. The alternative of a plug-in socket in the core (a protocol plus registration) was rejected — a forgotten registration becomes a run-time error, and reading the code does not tell you whether it was linked.

• SheetDecrypt (decryption only; depends on the umbrella SwiftSheets): the decryption side of AES (key expansion, decryptBlock, decryptCBC), key derivation, reading OLE compound files, and the procedures that open the OOXML / ODF wrappers. The entry points are SheetDecrypt.decrypt(_:password:) / decrypt(contentsOf:password:) — they detect OOXML versus ODF automatically and return the plain package. A package that is not protected is returned as it is (the same meaning as the old ReadOptions.password being ignored for a plain-text file; whether a file is protected is answered separately by SheetFormat.probe). On top of it, thin extensions give Workbook(contentsOf:password:options:), Workbook.read(…password:…), Workbook.inspect(…password:…) and StreamingReader(contentsOf:password:…). Each of them is nothing more than "decrypt, then call the core's plain API", so the decryption procedure exists in one place only.
• SheetEncrypt (encryption as well; depends on SheetDecrypt and re-exports it): the encryption side of AES (encryptBlock, encryptCBC, ECB), random salts and IVs, writing compound files, and the procedures that build the wrappers. The entry points are SheetEncrypt.encrypt(_:as:password:) (CSV / Numbers are refused with the same wording as before) and Workbook.write(to:as:options:password:) / write(as:options:password:) (the bytes are the data of the return value).
• What stays in the core: SHA-1 / SHA-256 / SHA-512, HMAC, PBKDF2 and random numbers (needed to cross-check the sheet-protection password hash and for salts — not cryptography for secrecy), and recognising and refusing by name (UnopenableInput; the detection method is unchanged; the refusal message says "can be opened with SheetDecrypt"). SheetError.wrongPassword also stays (removing a case would be a separate breakage).
• Removed API: ReadOptions.password / InspectOptions.password / WriteOptions.password, and the password: of StreamingReader / XLSXStreamingReader / ODSStreamingReader. The replacements are listed one to one in the table of CHANGELOG 0.17.0.

2 points differ from the shape of the request. (1) The name — the writing side is SheetEncrypt, not SheetCrypto: naming each product by the capability it adds suits the wording of a declaration better. (2) The direction of the dependency — SheetDecrypt depends on the umbrella SwiftSheets, not on SheetCore / XLSX / ODS. Workbook(contentsOf:) and StreamingReader live in the umbrella, and their extensions cannot be written without importing it. The reverse direction (the umbrella knowing SheetDecrypt) is never drawn — the moment it is, the point of the split is gone.

AES was split into files by decryption side and encryption side. Key expansion, the inverse S-box, the inverse tables (Td) and decryption are in SheetDecrypt; the forward tables (Te) and encryption are an extension in SheetEncrypt. Not one byte of the arithmetic changed, and the known answers of FIPS 197 Appendix C and SP 800-38A F.2 pass as they are. Speed and memory are unchanged too — the plain path merely lost one branch, and we measured before and after on 200 columns × 5,000 rows (1,000,000 cells; the first tier of the benchmark of that time — revised the same day in Rev 4.30 to 100 columns × 10,000 rows). One run each on the same machine on the same day (seconds, peak MB; the spread is about 5%):

This measurement found one defect. Passing a protected 4.5 MB XLSX to decrypt was refused as "legacy .xls". The core's detector (UnopenableInput.probe) looked only at the first 1 MiB of the compound file for the name EncryptedPackage, but a compound file's directory is placed after the parts — Office writes it that way and so does this library — so every protected file whose package exceeded 1 MiB looked like "legacy .xls" (the same with ReadOptions.password in 0.12.0). The detection method (signature plus the part name in UTF-16LE) is unchanged; the window is removed and the scan runs to the end in overlapping 1 MiB steps (SheetFormat.probe(contentsOf:) does the same scan over a ByteSource and never holds the whole file). The regression tests are a compound file with a 2 MiB part and a real protected workbook whose package exceeds 1 MiB (EncryptionTests).

The judge is the symbol table (scripts/check-no-crypto.sh, run in CI on macOS and Linux). 3 executables — one linking only the plain products, one adding SheetDecrypt, one adding SheetEncrypt — are built in a single scratch package and inspected with nm | swift demangle. After first confirming that the all-in executable does contain the encryption symbols (the positive control — if the grep is broken, it fails here), we check that the plain executable has none of SheetDecrypt / SheetEncrypt / AES / OOXMLEncryption / ODSEncryption / CompoundFile, and that the decryption-only executable has none of SheetEncrypt and encryptBlock / encryptCBC / encryptECB. An executable links only the objects it references, so the same is checked at the object level too — the .o files of the 6 plain modules have neither definitions nor references, and the .o files of SheetDecrypt have no encryption side. That is the real proof of "the product contains no such code", and the nm of the executables is the form an app can reproduce with its own hands.

B.39.10 Three API additions — choosing the sheets to read, streaming read and write of CSV, enumerating rows

• Choosing the sheets to read ReadOptions.sheets (.named / .indices). In XLSX, a sheet that was not chosen is not parsed; it is carried as the bytes that arrived (the ForeignSheet mechanism of B.35 gained a root: "worksheet" and an isUnread mark). Writing back changes not one byte — but the cells of that sheet point into the shared string table and the style table by number, so the writer places the original shared string table first, as it was (PreservationStore.sharedStrings), and keeps cellXfs in its original order too (StyleTables.cellXfs, StyleRegistry(keepCellXfs:)). The first implementation did not keep the numbers; on read-back "one" became a different string, and a test turned red to tell us. ODS and Numbers cannot carry bytes, so a sheet that was not chosen becomes an empty sheet with only its name, reported as degraded on read and dropped on write. A cell written into a sheet that was not read is dropped as well.
• Streaming read and write of CSV CSVStreamingReader / CSVStreamingWriter (SheetCSV). Reads 256 KiB at a time, and carries a multi-byte character, a surrogate pair or a CR LF split at a piece boundary over to the next piece. The dialect is inferred from the first piece (as the normal reader does from the first line). UTF-8 and UTF-16 with a BOM are decoded piece by piece; legacy encodings that do not self-synchronise (Shift_JIS and the like) are decoded whole. The RFC 4180 state machine was made resumable (a quoted field may span pieces; whether a quote at the end of a piece is a closing quote or a doubled one is decided by the next piece). The writer renders one row at a time and flushes to the file every 64 KiB.
• Enumerating rows StreamingReader.rows(inSheet:) / CSVStreamingReader.rows() — can be looped with for try await row in …. The piece feeding of B.39.8 (SAXDriver.PieceFeeder) was turned into a form pulled one piece at a time, reading only as much as the loop asks for (a break part-way means the rest is never read). It is asynchronous because that is the shape Swift gives to "an enumeration that can throw"; there is no parallelism. forEachRow stays.

B.39.11 The bench becomes a public thing — numbers are not remembered but measured and cross-checked

Every number in B.39 was taken on the bench in the workshop repository. From 0.12.0 the bench itself lives on the public side (Benchmarks/, a separate package that references the library by relative path; the library gains neither an executable nor a dependency). scripts/bench.sh rebuilds in release first (because of real harm from an incremental build mixing in stale parts), then runs one measurement per process, and writes to docs/performance.json with a description of the machine, OS, toolchain, commit and material. scripts/build-performance-page.py generates docs/performance.html from it, and --check in CI verifies "does the page match its source" and "do the 3 MB figures the README's Limits row claims match the source" — the same construction as the feature matrix (B.15), which prevents the accident of only the README's numbers going stale. Lower bounds on time are not put into tests (a check that turns red on a slow CI gets removed).

The material is synthetic data (10 columns × 100,000 rows), and the page says so. A real-world workbook (heavy in formatting and drawings) and "open, fix one cell, save" on a sample with a chart and VBA remain as the next materials to add as measurement columns (one of the 3 materials the plan's stage 1 listed). The 0.12.0 record: read 2.8 s, 221 MB; streaming read 1.9 s, 23 MB; write 1.7 s, 258 MB; streaming write 1.9 s, 11 MB; open, fix one cell, save 4.1 s, 262 MB; ODS write 3.4 s, 313 MB; ODS read 3.9 s, 234 MB; CSV streaming read 1.3 s, 10 MB; detection under 1 ms; inspect 2 ms. Set beside the figures before we started (5.7 s, 256 MB; streaming read 5.1 s, 61 MB; write 2.0 s, 360 MB; ODS write 4.0 s, 641 MB; ODS read 13.0 s): reads are 2× faster, ODS reads 3.3× faster, and streaming-read memory is down by a factor of 2.6.

B.40 Streaming read in 3 formats — a common entry point, walking the ODS body, the lazy Numbers document (Rev 4.22)

2026-09-05. This section covers together the 2 items the 0.12.0 plan (B.39) sent to "the next version" — streaming reads of ODS and Numbers — and the investigation of the deferred stage 6 (parallel read). A streaming read is a way of reading that does not assemble the whole workbook as a model but takes rows out one at a time from the start of the file, hands each to the caller and discards it as soon as it has been handed over (the StreamingReader of B.15, at that time XLSX / XLSM only). With this revision, every format is called the same one way. 3 things were decided: ① there is one entry point, and the format is detected from the content by the same rule as Workbook(contentsOf:) ② there is one row type, and the reader of every format returns the same type ③ Numbers' "several tables on one sheet" is reached through a table: argument (the default is the first table — the same as the model's Sheet.table).

The 200-column benchmark (Rev 4.27, 2026-09-05): in addition to the 1,000,000-cell record, we set a benchmark that fixes the column count at 200 and raises the row count tenfold at a time, 5,000 / 50,000 / 500,000 (1 million, 10 million and 100 million cells) (at that time scripts/bench.sh --grid → scripts/bench-grid.py, unified into scripts/bench.py in Rev 4.30; the grid of docs/performance.json, the second table on the same page). The material repeats the 10-column pattern across the width, shifts the numbers per block, and draws the strings of the second block onwards from a vocabulary of 50 words (in real-world exports the strings grow with the rows, not with the width). A size that does not fit the machine is not measured rather than crashed: a whole-model operation is not measured when its expected peak (cells × 320 B — the largest per-cell peak in the 1,000,000-cell record) exceeds 60% of physical memory, an operation that writes a file is not measured when free disk falls below 1.5 times what it needs, and both leave the reason in the record. bench-grid.py --self-test pins this judgement. The README's numbers continue to be cross-checked against the 1,000,000-cell record — so Rev 4.27 decided, but Rev 4.30 the same day revised it as follows.

Revision of the benchmark (Rev 4.30, 2026-09-05): the benchmark has 2 tiers, 100 columns × 10,000 rows (1,000,000 cells) and 100 columns × 100,000 rows (10,000,000 cells). 100 columns × 10,000 rows covers the common data-heavy case and 100 columns × 100,000 rows the bulk-data case, and the numbers are round and easy to grasp — that was the reason for adopting them. The README's headline numbers (the 9 memory figures, in MB, in the Limits row) are taken from the first tier. The 10 columns × 100,000 rows record and the 3 tiers of 200 columns are retired, and their numbers stay in this section and the CHANGELOG as history (the 100-million-cell tier could not be measured whole-model on the 8 GB machine, and two points — "the everyday amount" and "the bulk amount" — are enough for a benchmark). The driver is the single scripts/bench.sh → scripts/bench.py, and the record is the single tiers of docs/performance.json (the first tier is not held in 2 places — from the real harm, the same day, of the page and the report disagreeing on the numbers of the same tier). The read numbers are the values from reading a file written whole-model, and the values from reading a file written by streaming go in a separate "file written by streaming" row (no hidden precedence rule). The judgement not to measure on the estimate (cells × 320 B against 60% of physical memory; 1.5× free disk) stays as it is — both tiers pass on the 8 GB machine, but it is kept for a 4 GB machine. Performance is measured and checked on macOS (Rev 4.31, 2026-09-05): measuring on Linux happens only when instructed — development hands and time go towards keeping the numbers to a single source. CI's Linux stays the judge of behaviour and produces no numbers. A memory figure (MB) is always accompanied by the same operation's run time (seconds) (instruction of the same day as Rev 4.31: in a table the columns are paired, in a sentence they come as one pair, "15 MB, 4.4 s". Memory alone does not tell whether speed was sacrificed). A difference in time is stated from the old and the new build run alternately on the same machine at the same time, not from records of different days. The 0.17.1 record (first tier, 100 columns × 10,000 rows): read 2.7 s, 215 MB; streaming read 1.9 s, 19 MB; write 1.6 s, 254 MB; streaming write 1.8 s, 10 MB; ODS read 3.8 s, 233 MB; ODS streaming read 4.0 s, 228 MB (grows with the width — almost the same as whole-model, and the plan's next move); Numbers streaming read 0.8 s, 53 MB; streaming write 3.7 s, 25 MB; 8 sheets at the same time 1.1 s, 249 MB / one at a time 2.6 s, 141 MB. Second tier (× 100,000 rows): whole-model read 28 s, 1,023 MB; streaming read XLSX 62 / ODS 709 / Numbers 329 MB; streaming write flat (XLSX 11, ODS 17, Numbers 62, CSV 8 MB). What stands out against the old 10-column record is the ODS streaming read (42 → 228 MB) and the Numbers streaming write (60 → 25 MB — the unique strings are decided by the row count, and there are few at 10,000 rows).

The 0.17.2 record (Rev 4.31, 2026-09-05, after the fix of Appendix B.39.8): the first tier (100 columns × 10,000 rows) is read 3.8 s, 201 MB; streaming read 2.5 s, 13 MB; streaming write 10 MB; ODS streaming read 15 MB, streaming write 17 MB; Numbers streaming read 26 MB, streaming write 23 MB; 8 sheets at the same time 228 MB, one at a time 135 MB. The streaming reads of the second tier (100 columns × 100,000 rows) are XLSX 19 MB, ODS 14 MB, Numbers 61 MB (0.17.1 was 62 / 709 / 329 MB). They no longer grow with the size of the file: ODS is the same as the first tier, 15 → 14, and the growth that remains in XLSX and Numbers is the shared string table and the string tables and indexes — the strings a reader has to hold, the baggage the README has explained all along as "what every reader carries". Streaming writes are flat as before. Whole-model reads come down too, because the parts are inflated in the same pieces: the record is 215 → 201 MB in the first tier, and in a comparison with old and new run alternately at the same time, the 1,000,000-cell XLSX went 179–191 → 136–155 MB and ODS 175–206 → 135–144 MB (3 runs each; the seconds are the same). Time is unchanged: with old and new run alternately on the same machine at the same time, the 1,000,000-cell streaming read is XLSX 1.6–2.5 s versus 1.9 s, ODS 4.1–5.5 s versus 3.9–5.8 s (3 runs each). The seconds of the second tier in this record are not to be relied on: they were taken on the 8 GB machine with other apps running and 6 GB of swap in use (the whole-model CSV read, which we did not touch, went 21.7 → 48.6 s, and two takes of the whole-model Numbers read gave 41.5 s and 18.9 s). The memory of streaming reads and streaming writes is not affected by swap (a few tens of MB stay resident), so those can be read as they are. For the same reason the whole-model memory is not compared with 0.17.1.

B.40.1 The common entry point — StreamingReader (SwiftSheets) and the 4 per-format readers

StreamingReader is placed in the umbrella module SwiftSheets and delegates to XLSXStreamingReader (SheetXLSX), ODSStreamingReader (SheetODS), NumbersStreamingReader (SheetNumbers) and CSVStreamingReader (SheetCSV). The row types StreamedRow / StreamedCell and the options StreamingReadOptions moved from SheetXLSX to SheetCore (so that the 4 readers return the same types). The 4 readers satisfy the package-level contract StreamingRowSource — sheetNames, tableCount(inSheet:), the push form forEachRow (the reader drives the parse and calls once per row) and the pull form rowWalk (the caller asks for one row at a time, and the reader reads no further than that). The for try await sequence (rows(inSheet:)) is assembled from the pull form in one place in SheetCore (StreamingRowSequence). The walk that pulls rows out of the piece feeding (the SAXDriver.PieceFeeder of B.39.10), PieceFedRowWalk, is also placed once in SheetCore and shared by XLSX and ODS.

Rev 4.32 (B.44): the declaration of StreamingReader moved to SheetCore, and it is created by a codec's streamingReader(contentsOf:) / streamingReader(data:…) (a requirement of SpreadsheetCodec). The all-in StreamingReader(contentsOf:) is an alias for CodecSet.all.streamingReader(contentsOf:), and a user who links only the products they need gets the same object from their own CodecSet. The streaming write (B.42) is the same.

• Rename: SheetXLSX's StreamingReader became XLSXStreamingReader. A user of import SwiftSheets writes StreamingReader(contentsOf:) as before and can now open ODS, Numbers and CSV as well as XLSX. For a user who used StreamingReader with only import SheetXLSX, this is a breaking change before 1.0, stated in the CHANGELOG. A typealias for the old name is not provided — with the umbrella import two StreamingReaders would be visible and ambiguous.
• table: (default 0) exists to reach the second and later tables of Numbers. XLSX / ODS / CSV have one table per sheet, so anything other than 0 throws (not an empty walk in silence). tableCount(inSheet:) answers the same number as SheetSummary.tableCount of Workbook.inspect.
• CSV comes through the same entry point too. There is one sheet, "Sheet1" (the same name as the normal CSV reader), and every field is a cell (an empty field is a cell with value nil).
• Encryption: a protected XLSX / ODS is turned into a plain envelope whole by SheetDecrypt's decrypt before it is walked (neither a compound file nor an encrypted part can be walked row by row; up to Rev 4.29 the reader decrypted by itself). The core readers refuse by name. A protected Numbers document is refused by name too. A Numbers document in folder form is opened as well (B.39.4).
• Memory: an XLSX sheet part and the ODS body are inflated in pieces of 256 KiB (B.39.8). What every reader has no choice but to hold whole is the string tables (XLSX's shared string table; Numbers' per-table string list) and the one row in the caller's hands. ReadOptions.cellLimit has no effect — there is nothing to accumulate.

B.40.2 ODS — walk the body once, deliver only the rows of the requested table

In ODS every sheet is in the single part content.xml. Walking the third sheet means reading past the first and second; the lexer runs but not a single cell is created (each table is skipped as a subtree). Parsing stops at the end of the requested table, so the tables after it are not read. The automatic styles (automatic-styles) come before the tables in the same part, so formatting is resolved in the same single walk (styles.xml is small and is read first).

Reading a cell's text shares one part with the normal reader. The text of an ODF cell involves 5 things — paragraphs (text:p), formatting boundaries (text:span), whitespace collapsing (ODF 6.1.2), links over a string (text:a) and annotations inside the cell (office:annotation — this paragraph must not become the cell's text) — and writing it twice invites the accident where only one copy gets fixed. So this portion was cut out of ContentParser into ODSCellText, and the normal reader and the streaming reader feed the same events into the same part. Value interpretation (reading each type of office:value-type) was placed in the same part. Not one test of the normal reader was changed before or after the cut.

Repeats are expanded by the same rule as the normal reader: a row with content is delivered number-rows-repeated times (the file says so). A row without content is delivered only when includesEmptyRows is set, and only when the count is below paddingRepeat (1,000) — the trailing number-rows-repeated="1048000" is a description of the table, not content (§8.3). Column repeats are the same: an empty styled cell is delivered as a styled nil cell only below 1,000 (the same treatment as the XLSX streaming read delivering <c s="3"/>). Covered cells (in the shadow of a merge) are not delivered.

B.40.3 Numbers — build only the index first, and inflate and discard tiles as rows go by

Measured before starting (1,000,000 cells, the first time for Numbers): write 8.4 s, 413 MB; read 5.9 s, 323 MB (the model 203 MB). The document is 34 MB in 433 parts, of which 392 are tiles (Index/Tables/Tile-*.iwa, one per 256 rows). A call profile showed that nearly half the read time was decoding decimal128 — a 16-byte number was assembled with 14 Decimal multiplications and a conversion through a string (CellStorage.decodeDecimal128). The test for whether it is an integer went through a string too, Int("\(d)"). Decoding the parts (IWA → the Protobuf tree) fits in the first second; it is a memory problem, not a time problem.

The lazy document NumbersObjectIndex: it enumerates the IWA parts from the envelope's directory, undoes each part's Snappy, decodes only the archive headers (TSP.ArchiveInfo), and builds an index of object id → (part, position, type). An object's body is decoded when it is asked for and cached. For a part that holds only tiles (TST.Tile), the inflated body is discarded — it is inflated again during the walk. The other parts (the document, sheets, table models, string lists, styles) keep their inflated bodies. The normal reader's NumbersDocument (the mutable container the writer and inspect use too) was left untouched; a small contract that both satisfy, NumbersObjectStore, was placed so that style resolution (NumbersStyleResolver), text formatting boundaries and value reading (cellValue) are shared. The fuzzing of §12 applies to the streaming reads of the 3 formats as well (a mutated sample is passed to StreamingReader and the first table is walked). Building the index returns malformedPart when a header or object length a part declares is negative or larger than what remains (comparing against "what remains" so that an addition cannot overflow). Cutting out a record treats a negative column count as 0. Broken input is always returned as a SheetError, and never crashes — this is a part shared with the normal reader, so it works for both.

Row order is a promise: the normal reader does store(at:) for tiles and rows in the order they arrive, so an arbitrary order does it no harm, but the streaming read promises "top to bottom", so tiles are sorted by tileid and the rows within a tile by tile_row_index before delivery. Tiles from before BNC (last_saved_in_BNC not set) are skipped with a warning by the normal reader, but the streaming read has no channel for warnings, so it throws (it does not skip in silence). Formulas are turned back from the tree into text as in the normal reader (the names of references to other tables are collected first), and a formula that cannot be decoded is delivered as its cached value. The covered cells of an array formula (function 337) are delivered as values only (B.26).

The decimal128 decoding was fixed (this benefits the normal reader too): a number whose upper significand is 0 and fits in 64 bits (nearly every real-world number) is built directly from a UInt64 with Decimal(sign:exponent:significand:), and whether it is an integer is decided from the significand and exponent. That not a single digit of the value changes was nailed down by comparing boundary values (a single bit in the 14th byte, negative exponents, around 2^64) against the normal path. The measurements are in B.40.5.

B.40.4 Filling 3 holes in the common specification — things the formats' public specifications have but only one side had

We counted "common in the specification proper, but unimplemented in one of the formats" from the feature matrix (scripts/spec-feature-matrix.json) and the 48 rows of docs/format-support.html. There were many candidates, but those the public specification really has, for which a judge is at hand, and for which the model already has words came to 3.

• ODS workbook structure protection: <office:spreadsheet table:structure-protected="true"> of ODF 1.3 §9.1.2. The attribute written by LibreOffice's "Tools ▸ Protect Spreadsheet Structure", with the same meaning as Excel's workbookProtection locksStructure (forbids adding, deleting, renaming and reordering sheets). The feature matrix said "no such concept in ODF (na)", which was wrong. Reading gives wb.protection.locksStructure; writing writes only the flag. The key is not carried — ODF's table:protection-key is the Base64 of a SHA-family digest, compatible neither with Excel's 16-bit password hash nor with the SHA-512 of Excel 2010 and later, and writing "protected" while unable to translate the key is the honest form (LibreOffice treats structure protection without a key as protection that needs no password to lift). The "workbook protection is dropped" warning that ODS writes used to produce goes away.
• XLSX calculation properties: ECMA-376's <calcPr iterate iterateCount iterateDelta fullPrecision> is the same thing as ODF's table:iteration and table:precision-as-shown (whether iterative calculation is on, its count and convergence, and whether to calculate with the displayed digits). The model has had CalculationSettings since B.17, yet the XLSX reader did not read calcPr, and the writer rewrote <calcPr calcId="124519" fullCalcOnLoad="1"/> every time. As a result ① opening and saving an xlsx with iterative calculation enabled lost the setting in silence, and ② converting ODS to XLSX produced a warning contrary to fact, "this setting exists only in OpenDocument". Reading takes the 4 attributes into CalculationSettings in WorkbookXMLParser (precisionAsShown = !fullPrecision, default true), and writing adds them to calcPr. The other attributes of the calcPr that was read (calcMode, refMode and so on) are carried in PreservationStore.calcPrAttributes and written out as they were when writing back to the same format (the same construction as the workbookPr of B.22). openDocumentOnlyWarnings no longer says these 4 items are "dropped" when the destination is XLSX.
• The ZIP64 row of the feature matrix: xlsx.package.zip64 was read and written in B.39.1 yet still stood at "none / none" (the table's as_of was 0.11.1). The README's Limits already said "read and written"; only the table was stale. Corrected to full / full, and streaming-read rows were added for ODS and Numbers as well.

Counted, and not included (with reasons). To change a judgement, edit this table, not the body text.

B.40.5 Measured — streaming reads of the 3 formats, and Numbers before and after

(Measured on the bench of B.39.11. The numbers in this subsection are same-machine, same-material, same-time comparisons.)

Streaming read in the 3 formats (1 million cells, 2026-09-05, from the bench record): XLSX 2.0 s, 24 MB (whole-model 2.9 s, 221 MB), ODS 4.2 s, 42 MB (whole-model 4.0 s, 233 MB), Numbers 1.6 s, 85 MB (whole-model 2.6 s, 323 MB). In every format, reading row by row takes 1/5 to 1/9 of the whole-model memory. The ODS streaming read is 0.3 s slower than the whole-model read because it assembles and hands over one row at a time; the tokenising of the body is the same single pass in both. The 42 MB of ODS breaks down into the pieces (256 KiB each), the style inventory, and the mapped file itself (pages that were touched count as resident). The 85 MB of Numbers is the mapped document, 34 MB, plus the table's string list (100 thousand header strings) turned into a dictionary, and one tile in hand.

Numbers before and after (1 million cells): read 5.9 → 2.6 s (the fix to decimal128 decoding. Memory unchanged at 323 MB — the model itself is 203 MB). At 100 thousand cells, 0.58 → 0.29 s. The write, 8.0 s and 413 MB, was not touched and is a candidate for the next version (as with the read, take a call record first, then fix). From this measurement on, scripts/bench.sh measures Numbers at 1 million cells too (until then the material was an order of magnitude smaller). The MB figures the README's Limits row states go from 3 to 5 (streaming write, streaming read xlsx / ods / numbers, whole-model), each cross-checked by machine against docs/performance.json.

Two things learned while fixing. (1) The ordinary Numbers reader was hashing the whole 384-byte CellStyle per cell to look up the shared style (7% of the call record). It now looks up by the integer key the style resolver uses. (2) A tile row's cell record was copied twice: a slice of Data and a copy into [UInt8]. We added CellStorage.decode(UnsafeBufferPointer), which reads the buffer in place, and both the ordinary reader and the streaming read use it.

B.40.6 Parallel read (stage 6) — design and prototype measurements; implementation deferred to the next version (→ implemented in B.41)

Stage 6, "after reading the shared strings and the styles, read the sheets at the same time", was left out of 0.12.0 (the B.39 plan said "automatic, with no knob"). The reason is a single one: the two lazy dictionaries of StylesParser — sharedStyle(index) (the shared style per xf) and numericKind(index) (whether that format is a date or an elapsed time) — are shared by every sheet's parser, and each writes to them the first time it sees an xf. If two parsers write at once, they break. This revision does not implement it; it settles the design and measures the effect with a prototype.

Inventory — the shared things a sheet parse touches (from grep static var / nonisolated(unsafe) read against the code):

Design: move the sheet for-loop of WorkbookReader.read into SheetReadContext (an @unchecked Sendable container holding the read-only shared things) that carries the work for one sheet (resolving relationships, decompressing and parsing the part, table parts, pivots, comments), and run it once per sheet with DispatchQueue.concurrentPerform (a synchronous API that also works on Linux; the caller's Workbook(contentsOf:) stays synchronous). The results are reordered by sheet index and the warnings concatenated in sheet order. Parallelism on the write side is outside this design, because the indices in the shared string table and the style table are assigned first come, first served (as in B.39).

Prototype measurements (on a separate working copy with the design above applied to the 0.12.0 code. 1 million cells, same machine, median of 3 runs. The switch is an environment variable, so the same executable was run serially and in parallel): 1 sheet 2.80 → 2.82 s, 221 MB unchanged (no regression — with one sheet there is no work to divide). 8 sheets × 125 thousand cells: 2.73 → 1.20 s (2.3×), peak 145 → 258 MB (+113 MB). 32 sheets × 31 thousand cells: 2.70 → 1.15 s (2.3×), 136 → 183 MB (+47 MB). The floor on speed is the parsing of the shared string table, which stays serial (about 0.5 s), and the assembly of the model. Memory grows because, while 8 parsers grow their tables at the same time, the working space that dictionaries and arrays double into overlaps; the size of the tables themselves does not change.

Decision — implementation goes to the next version, the shape stays "automatic". Go parallel only when (1) there are 2 or more sheets and (2) the sum of the declared cell counts exceeds 100 thousand (to avoid the cost of spinning up threads for a small workbook. The declared counts come from the same place as inspect in B.39.3). No knob (the B.39 decision stands). But since the extra memory is a change visible to users, add an "8-sheet workbook" column to the bench and put the parallel peak in the README's Limits with machine cross-checking. What production needs: besides the 2 points prefill() and SheetReadContext, fixing the order of warnings (sheet order), an addition to the fuzz target (hand over 2 parts broken at the same time), and measurement on Linux. The prototype patch and raw data go to the experiments area of the workshop repository, not into the main tree.

B.41 Parallel read — sheets read at the same time, with a single integer as the cap (Rev 4.23)

2026-09-05. Stage 6, which B.40.6 took as far as the design and the prototype measurements and deferred "to the next version", is now in the main tree. The B.39 plan was "automatic, with no knob", but we put in one integer (ReadOptions.concurrency). The reason is that the number of sheets read at once is itself the upper bound on the extra memory (see "the memory reasoning" below), and that number was the most straightforward shape for a cap. It applies only to the whole-model read of XLSX / XLSM (Workbook(contentsOf:)). ODS has a single body part that cannot be divided, and Numbers reads from a table of contents (B.40.3), so neither reads this setting.

Mechanism (3 stages):

1. Finish first: the shared string table and the style table are read first, as before. The style table's two lazy dictionaries — the shared style per xf and "is that format a date or an elapsed time" — are filled for every xf before any sheet is read (StylesParser.prefill()). A nonexistent xf index returns the default only and does not write to the dictionary. With this, the style table is read only while the sheets are being read.
2. Move one sheet's work into a container: resolving relationships, decompressing and parsing the part, structured tables, pivots and comments become one method on SheetReadContext (an @unchecked Sendable holding the read-only shared things), and sheets are taken from a queue (SheetQueue) one at a time and run. How many run at once is decided by the rule below, and they are driven by DispatchQueue.concurrentPerform (the same on Linux). The caller's API stays synchronous.
3. Reorder the results by sheet: each sheet's result (the sheet, the consumed parts, warnings, failure) is placed in a box indexed by sheet number (SheetResultsBox) and taken out in sheet order after finishing. Warnings are concatenated in sheet order, and if 2 or more sheets failed, the first one in sheet order is thrown. Whatever order they finish in, the result is the same.

The rule — from light information available without reading: the ZIP directory declares each part's decompressed size. The read already has the directory, so summing the declared sizes of the sheet parts to be parsed (excluding those removed by ReadOptions.sheets and those that are not grids) reads nothing extra. When concurrency is nil (the default), sheets are read at the same time, up to the core count, only when there are 2 or more sheets and 4 MiB or more in total (4 MiB is roughly 100 thousand cells in SpreadsheetML; this avoids the cost of spinning up threads for a small workbook). 1 means one at a time regardless of size, and n (2 or more) means up to n at a time even for a small workbook (a value above the sheet count is rounded down to the sheet count; 0 or below becomes 1).

The memory reasoning — why one integer is enough: whichever way you read, every sheet remains in the model at the end, so what a concurrent read adds is only "the working space of sheets that are growing at the same time" (the amount arrays and dictionaries double into). That cannot exceed the number of sheets running at once. So if the caller holds the upper bound on concurrency, it holds the upper bound on the increase. We did not put in a mechanism that throttles automatically in step with physical memory: it would make the reader guess at the size of the model itself (declared cell count × 100–200 bytes), which the caller knows better through Workbook.inspect and cellLimit. The prototype numbers (+113 MB with 8 sheets at once, +47 MB with 32 sheets × 31 thousand cells) say "the smaller each sheet, the smaller the increase", consistent with the increase being the working space of the sheets running at once.

Measured (a workbook of 1 million cells split into 8 sheets, same machine, release, added to the bench scripts/bench.sh as writeSheets / readSheetsSerial / readSheets): one at a time 2.7 s, 145 MB → concurrent 1.2 s, 257 MB (2.4×, +112 MB). A one-sheet workbook stays at 2.8 s, 214 MB (unchanged, since there is no work to divide). The README's Limits states these 2 MB figures from the readme of docs/performance.json with machine cross-checking. On Linux, CI runs the same checks to judge correctness, but speed is not measured.

Promises that do not change: warnings are in sheet order. The first failure is in sheet order. Compatible with ReadOptions.sheets (removed sheets are not parsed and are not included in the declared total). formulaCells and preservesUnknownParts pass through unchanged to each sheet's container. Parallelism on the write side is outside this design, because the indices in the shared string table and the style table are assigned first come, first served (as in B.39).

Tests: ParallelReadTests — the one-at-a-time and concurrent reads agree on both the model and the warnings (6 sheets with shared strings, 2 styles, formulas, links, comments and merges) / the warnings for a selection that removes 4 sheets are in sheet order (repeated 5 times) / when 2 sheets are missing their parts at the same time, the one thrown is the earlier sheet (repeated 5 times) / the rule table (sheet count, size, setting, core count) / the dictionaries are filled up front and do not grow on a missing xf. A 3-sheet workbook was added to the fuzz (§12) samples, and every format's mutations are read with concurrency: 4 — even when 2 broken parts arrive at once, the result is a SheetError.

What we did not do: restoring Numbers tiles concurrently (the read is 2.5 s, and structurally the table of contents is built first — measure first, next time). Parallelism on the write side (above). ODS (a single part).

B.42 Streaming write in 3 formats — the umbrella's StreamingWriter, ODS spilling to a temporary file, Numbers tile streaming (Rev 4.25)

2026-09-05. We built the same shape as the streaming read (B.40) on the write side. The caller only hands rows to StreamingWriter(url:) and calls close(), and can write XLSX / XLSM, ODS, Numbers or CSV without assembling a workbook.

Shape (a mirror of the read):

• In SheetCore, the package-level contract StreamingRowSink (addSheet(named:) / append([Cell]) / close() / warnings). The values-only append([CellValue?]) is a default implementation.
• The SwiftSheets umbrella's StreamingWriter(url:format:sheetName:epoch:csv:). The format is decided from the extension by the same rule as Workbook.write(to:) (XLSX if none), and can be overridden with format:. The per-format writers XLSXStreamingWriter (the former SheetXLSX.StreamingWriter, renamed — to pair with the reader's XLSXStreamingReader) / ODSStreamingWriter / NumbersStreamingWriter / CSVStreamingWriter can also be used on their own.
• Everyone has warnings, finalised at close(). Anything the format cannot carry always appears here (§6). A second addSheet for CSV throws rather than folding into one sheet in silence.

The ODS pressure point — one part, with styles before the body: the ODS body is a single content.xml, and the styles cells wear (office:automatic-styles) must by rule come before the tables, so rows cannot be streamed into the envelope in arrival order as in XLSX. Each row is turned into XML as it arrives (sharing ODSWriter.cellXML; styles grow in the register ODSStyleRegistry) and spilled to a TextSpill (in memory up to 8 MiB, then a temporary file); at close(), the head, the accumulated styles, each sheet's table:table with its column declarations (the column count is that of the widest row), the spilled rows and the tail are streamed in that order into one streamed entry. Trailing empty cells are not written, empty cells in the middle are written with repetition, and a row with no cells gets one empty cell (an ODF table row has at least one cell). Memory is a few MB regardless of the row count, and one uncompressed copy of the body on disk remains until close() — the price a single-part format pays.

The way to read the spill back is read(2) (found by measurement): the first implementation read the spill file back 1 MiB at a time with FileHandle.read(upToCount:), but the streaming-write ODS peak was 42 MB at 20 thousand rows and 123 MB at 100 thousand rows (1 million cells) — it grew in proportion to the row count. While rows are being spilled it is flat at 19 MB, so the growth is on the read-back side of close(). An isolating experiment (30 lines that only write a 55 MB temporary file and read it back) showed that Darwin's FileHandle keeps what it has read resident in the process (59 MB with both read(upToCount:) and readData(ofLength:); 8 MB with read(2)). TextSpill.forEachPiece reuses one 1 MiB buffer and reads with read(2) —— the streaming-write ODS went 123 → 23 MB (100 thousand rows), independent of the row count, and the whole-model ODS write (which uses the same spill) went 246 → 217 MB.

The Numbers pressure point — a 256-row tile is a part: each tile is turned into IWA and written to the envelope as soon as it fills, and the body is not held (NumbersDocument.addStreamed records only the id and the location and returns the byte string; encoded(into:) writes the remaining parts into the same envelope). What remains to the end is the table's model, the string list (one entry per unique string — the same nature as the shared string table in the XLSX read, and unavoidable), the lists of styles and formats, the cell count per column, and the row headers (both Numbers and numbers-parser reach row records via the row headers, so they cannot be omitted. About 12 bytes per row are kept in wire format — ProtoMessage.Value.raw was added for this. 12 MB for 1 million rows). Formulas are written as their cached value, rich text as plain text, and links, comments and cell controls are dropped, each counted and warned about (the formula archive of B.18 requires the table's UUID and is left to the whole-model writer). The second and later sheets duplicate the template's already-written sheet: with one table per sheet, the "inheriting a second table" problem of B.18 does not arise, and the inherited lists, dimensions and frame are overwritten by its own close (tiles already written out are not objects, so they are not carried into the duplicate).

The Numbers width rule: a tile row's cell_offsets must by rule have one entry per table column (numbers-parser reads number_of_columns of them). A tile that has been written out cannot be widened, so the table width is decided by the widest row, and a row wider than a tile already written out is refused (unsupportedFeature, saying "put every column in the first row"). Widening within the first tile (256 rows) is fine.

Measured (1 million cells; streamWriteODS / streamWriteNumbers added to the bench): streaming write XLSX 1.9 s, 11 MB; ODS 4.2 s, 22 MB; Numbers 10.3 s, 60 MB (the whole-model writes are XLSX 1.7 s, 258 MB; ODS 3.6 s, 212 MB; Numbers 9.0 s, 289 MB). The README's Limits states these 3 MB figures from the readme of docs/performance.json with machine cross-checking.

Tests: StreamingWriteFormatsTests — stream 2 sheets of 700 rows (3 Numbers tiles' worth) in the 3 formats and read back both whole-model and streaming / consistency of the Numbers document (parts and references; each table's 3 tiles are separate parts) / numbers-parser reads it (skipped if not installed) / LibreOffice reads it and writes it back to XLSX (skipped if absent) / the width rule / a second sheet for CSV / the extension and format: (.tsv, no extension, .dat + ods, .xlsm) / warnings for what cannot be carried (counts of formulas, links and comments; XLSX has no warnings) / a sheet with no rows.

What we did not do: streaming write of Numbers formulas (above). Row heights and column widths (not on Cell). Merges, comments, conditional formatting (the same line as the streaming read — values and formats only).

B.43 Writing images to ODS — a draw:frame in the anchor cell, parts under Pictures/ (Rev 4.26)

Purpose: write the images that B.32 made placeable in XLSX (addImage(_:at:sizing:) / addImage(_:over:)) to ODS too, with the same API. Until now, writing to ODS only counted them and said dropped (B.32; the row "Writing images to ODS" in the gap table of B.39.10).

Mechanism. (1) What LibreOffice does: it puts the picture's bytes under Pictures/ in the envelope, one part each, and adds a manifest:file-entry (with manifest:media-type) to META-INF/manifest.xml. In the body it puts, inside the cell where the picture goes, a draw:frame (svg:width / svg:height, and svg:x / svg:y from the cell's top-left), and the draw:image inside it points at the part with xlink:href="Pictures/…". For a picture stretched to fit a range, the frame also carries table:end-cell-address (the cell one past the bottom-right of the range) and table:end-x / table:end-y —— LibreOffice reads these as the anchor "resize with cell". (2) What breaks if you do not imitate it: a part not in the manifest makes LibreOffice treat the document as "corrupt" and send it to repair. Putting the frame outside the cell (in table:shapes) loses the anchor, and the picture does not move when a row is inserted. (3) So this is what we did: part names are numbered from Pictures/image1.png across the whole document, avoiding the names under Pictures/ carried over in preserved from the source ODS (the original pictures are carried along without being reconnected —— that warning is as before). The frame is inserted into the B.8 writer's cellXML: after the comment and the detective arrows, before the body paragraphs (the order of ODF 1.3 §9.1.4). A position that has a picture but no cell also gets its row and cell written, as with a merge anchor. A picture anchored inside a merge is moved to the merge's origin cell (the element of a covered cell is empty and can hold nothing —— LibreOffice also moves it to the origin).

Dimension conversion: pixels are converted to cm at 96 dpi (px × 2.54 / 96, 3 decimal places —— the way LibreOffice writes it). .original keeps the pixel count, .scaled uses the specified pixel count, and .fitCell is the largest that fits the anchor cell's current size (column width is character count × 7 + 5 px, row height is pt / 0.75 px —— the same conversion as B.32). For a picture fitted to a range, the svg:width / svg:height are provisionally written as the sum of the range's column widths (B.8's 2.0 mm per character) and row heights (pt), and LibreOffice decides the actual size from table:end-cell-address. The judge's verdict: LibreOffice gave priority to end-cell-address and stretched the picture to fill the range —— a picture placed at C3:D4, converted to xlsx, became a twoCellAnchor editAs="twoCell" with its end at the bottom-right of D4 (a range of column width 2.267 cm × 2 by row height 0.452 cm × 2, not the svg:width 3.372 cm we wrote). In a workbook that does not set column widths explicitly, LibreOffice's default column width is wider than our 2.0 mm per character, so the provisional dimensions differ from the actual range, but the picture fits the range.

Reading does not change: the B.8 reader skips draw:frame, so the pictures this writer places do not come back through our own reader (unlike the XLSX read, which keeps pictures in preserved). In the support table, ods.draw.image honestly states write full, read none. The ODS streaming write (B.42) has no entry point for images.

Tests (ODSImageTests): the part goes into the envelope as the caller's bytes unchanged and appears in the manifest with a media-type, the frame is inside the anchor cell, the cm of the 3 sizings (original, specified, fit to cell), the range's end-cell-address, a picture at a position with no cell, 2 pictures in one cell, no name collision with the source ODS's Pictures/. The judge is LibreOffice (skipped visibly via .enabled(if:) if absent): with --convert-to xlsx the picture makes it to xl/media/, and after re-saving with --convert-to ods the draw:image remains.

What we did not do: charts, shapes, text boxes (addChart is still dropped for ODS, as before). Raising pictures into the model in the ODS read. Images in the streaming write.

B.44 The codec set — the same entry points even when only the products you need are linked (Rev 4.32)

2026-09-05. The trigger was a request from Left Right (an in-house comparison app). It wanted Workbook.inspect, which refuses by declared cell count before reading a table, and StreamingReader, which reads one row at a time, but both existed only in the all-in-one product SwiftSheets, and linking the all-in-one puts the unused SheetCSV into the shipped binary (measured: release with symbols stripped, 4.09 → 4.20 MB, about 115 KB. The figure includes the inspect and streaming-read paths). The cost is small, but the essence of the request is not the cost. The README promises "link only the parts you need", yet the moment any one format was left out, all 5 entry points — open, inspect, streaming read, streaming write and convert — disappeared, because they were written as 6 switch statements inside the all-in-one, which also literally contradicted Chapter 2's "L4 has no format-specific branching".

Why "pushing it down" is not enough

The dispatch calls each format's reader. The core SheetCore is on the side that does not know the readers (the far end of the dependency arrow), so the branching cannot simply be moved into the core. Only the "table" can be pushed down; the table's contents (which readers exist) must be handed to the core by the caller. That is CodecSet (explicit composition). We did not adopt a registration scheme where readers write themselves into a roster at startup (the plugin registry of other languages) — the caller cannot see what is in it, it depends on order, and it sits badly with Swift 6 concurrency checking. Nor did we adopt combination products such as "all-in-one minus CSV" — the next combination would add another. With a set, the caller decides the combination.

Design

• CodecSet (SheetCore): a table keyed by SheetFormat, built from [any SpreadsheetCodec.Type]. read(contentsOf:) / read(_:format:options:), inspect(…), write(_:as:) / write(_:to:as:), convert, streamingReader(contentsOf:) / streamingReader(data:…), streamingWriter(url:…). The rules that stand in front of every codec — format detection (SheetFormat.detect / probe), refusing compound files and encryption by name (§1.3, §14.11), the folder form of Numbers (§4.2), telling CSV from TSV by file name — are written here once. The format-independent openDocumentOnlyWarnings (B.17, B.23) and outputFormat also move to the core. If the same format is declared twice, the later one remains (this is not a place to catch a caller's typo, so it is not a precondition).
• Extending the contract: added to SpreadsheetCodec: inspect(_:options:), read(contentsOf:) / inspect(contentsOf:) (the default implementations map the file and defer to the data versions; only Numbers, which has a folder form, overrides them), streamingReader(contentsOf:) / streamingReader(data:…), streamingWriter(url:…). The URL version of the streaming read has no default implementation because each reader has the positional read of B.39.8 Rev 4.31 (a mapping default would be a regression). The 3 formats' inspectors (XLSXInspector / ODSInspector / NumbersInspector) stay package-level, and each codec's inspect exposes them outside the product. The CSV inspect (which only counts rows) was taken over from the all-in-one's inline code into CSVCodec.
• Moving the vessels: the declarations of StreamingReader (B.40.1) and StreamingWriter (B.42) move from the all-in-one to SheetCore. Only a codec can create them (package init) — the reader contracts StreamingRowSource / StreamingRowSink stay package-level, so an outside party cannot plug a home-made format into the set. An intended restriction (publishing the plug-in point would make that contract an API and freeze it).
• The all-in-one is a thin entry point: it holds one CodecSet.all (5 codecs), and Workbook(contentsOf:) / Workbook.inspect / write(to:as:) / convert / StreamingReader(contentsOf:) / StreamingWriter(url:) are all one line into .all. Neither the call forms nor the arguments change. Because StreamingWriter(url:) is a convenience init on a class in another module, it takes the sink out of the vessel the set built and passes it to self.init(sink:format:) (one extra vessel is created, but harmless, since the sink holds the state).
• How it refuses: a format not in the set gets SheetError.unsupportedFeature (the "unimplemented format" slot of §4.3) with "no codec for .csv is in this CodecSet — link the SheetCSV product, or the SwiftSheets product, which has every codec". It names the format and the product. Since the core knows every format for detection, CSV is not made an "unknown format". No new case is added. Changed in Rev 4.41 (B.52) — the refusal text stays, but the answer is SheetError.noCodec(for:).
• The direction of dependencies does not change by a single arrow. SheetDecrypt / SheetEncrypt keep depending on the all-in-one and keep using the existing call forms. scripts/check-no-crypto.sh only walks the 6 module names in order, and since no module is added, it is unchanged.

What changes for users

Users who link the all-in-one: no change. Users who link only the products they need build one set:

import SheetCore          // plus SheetXLSX / SheetODS / SheetNumbers — no SheetCSV, no SwiftSheets
let codecs = CodecSet([.xlsx, .xlsm, .ods, .numbers])
let summary = try codecs.inspect(contentsOf: url)          // before reading: sheets, declared cell count
let workbook = try codecs.read(contentsOf: url).workbook   // the format is judged from the content
let reader = try codecs.streamingReader(contentsOf: url)   // one row at a time

Verification

CodecSetTests: CodecSet.all holds all of SheetFormat.allCases / the all-in-one's call forms and the set's methods return the same answer / an XLSX-only set refuses ODS by format name and product name / declaring the same codec twice gives one entry. A new test target, PartialLinkTests (dependencies are SheetCore, SheetXLSX, SheetODS and SheetNumbers only; it does not use @testable either): opens, inspects, walks and stream-writes each of the 3 formats from bytes and from a URL, and is refused CSV by name at all 7 entry points. Since SwiftPM links the test targets into one bundle, what this target proves is "compiling and running works with the import of just the 4 products". That SheetCSV is absent at the link level was confirmed by the symbol tables and sizes of the 2 executables built for the proposal (the measurement above).

Compatibility (0.18.0, before 1.0)

• Every call form through the all-in-one is unchanged.
• Users who fully qualified SwiftSheets.StreamingReader / SwiftSheets.StreamingWriter change to SheetCore.… (the all-in-one re-exports SheetCore, so nothing changes without qualification).
• SpreadsheetCodec gained 6 requirements. No outside conformers are assumed.

What we did not do

Plugging in outside codecs (above). Combination products (above). The display design on the Left Right side (how to show the streaming read on screen is their plan).

B.45 WebAssembly — reading and writing the same 3 formats where there is no zlib, no threads and no temporary files (Rev 4.33)

2026-09-06. The trigger was the Web version of Stream. Mac and iPad can handle xlsx / ods / numbers with this library, but the Web version alone could handle only xlsx, through a separate Python part. Running this library as is inside the browser makes the conversion implementation one for all 3 surfaces (unlike the "write common parts in Rust and ship them as WebAssembly" idea that Stream's plan rejected, no language is added). Xcode's Swift cannot emit WebAssembly (it lacks the LLVM wasm backend), so we got --swift-sdk swift-6.3.3-RELEASE_wasm through with the swift.org-distributed toolchain of the same version and the Wasm SDK.

What WASI lacks, and what stands in for it

• zlib (DEFLATE, CRC-32): the WASI sysroot has no zlib (it does have libxml2). Deflate.swift gained a third path under #if os(WASI) — reading is a complete RFC 1951 inflater (fixed and dynamic Huffman, stored; the same "walk the canonical table one bit at a time" shape as zlib's puff), writing is uncompressed stored blocks (65,535 bytes each, BFINAL on the last). It is valid DEFLATE that every reader accepts, but the written files are larger (for Stream's 70-row plan, xlsx 102 KB against 20 KB, ods 299 KB against 16 KB; numbers was all stored to begin with, so it is unchanged). The streaming inflater InflateStream accumulates the fragments and inflates them in one go when the end arrives (quadratic effort on a large part; negligible at the size of a plan). CRC-32 is table-driven (the README's "Swift's table lookup does 33 MB in 0.09 s"). The CZlib dependency in Package.swift is limited to the platforms other than WASI (.when(platforms:) can only enumerate positively).
• 32-bit Int: 16 << 30 becomes 0, and the default expansion limit turned into "refuse every file" (measured: every read reported unrecognized format). ZipLimits.defaultMaxExpandedBytes is Int.max under _pointerBitWidth(_32). The ZIP64 marker 0xFFFF_FFFF is read with Int(truncatingIfNeeded:) and compared against Zip.marker32 (the same value on 64-bit, -1 on 32-bit). The writer's limit32 likewise.
• Threads: there is no DispatchQueue.concurrentPerform. The parallel sheet read of XLSX (B.41) is serial on WASI. The workers value is accepted as the caller's wish and not honoured.
• Temporary files and atomic writes: Data.write(options: .atomic) is unavailable on WASI. CodecSet.write(to:) writes directly on WASI. TextSpill (B.39.7) fails in an environment with no temporary area and falls back to the normal path.
• Resource bundles: the generated code for Bundle.module bakes in a path on the build machine. The SheetNumbers resources (the schema, the registry, the empty template) go through NumbersResources.swift, which on WASI reads the fixed /SwiftSheets_SheetNumbers.resources/. The runtime (node's WASI, a browser's thin WASI implementation) mounts a folder under that name.
• libc names: the open / fstat / pread used by ByteSource and TextSpill come from WASILibc.

Verification

The full native test suite (1,071 tests) is unchanged. For the WebAssembly build, Stream's scripts/wasm-smoke.mjs (node's WASI) confirmed that importing an xlsx matches the reference JSON byte for byte, and that writing and reading back xlsx / ods / numbers round-trips. LibreOffice converted the written files of all three formats to PDF. Not confirmed in Numbers itself or Excel itself (stored-block DEFLATE is to the standard, but B.9 has an example of a lenient reader letting something through). There is no WASI job in the Linux CI — the toolchain is limited to the swift.org distribution, and keeping its version in step with the CI's Swift would be a separate chore. The local verification steps are written at the top of Stream's scripts/build-wasm.sh.

B.46 The boundary between the preservation structures and the editing model (Rev 4.35)

Approved 2026-09-07. PreservationStore, OpaquePart, XMLFragment, Relationship, StyleTables, SheetPreservation, ForeignSheet and their members, and Workbook.preserved and Sheet.preserved become package. Closing off writes to the raw data does not change the existing F3, partial reads or loss warnings. anchorTextFormula, sanitizedName, cleanMergedRange and asAssumedOutsideODF stay public. Helper APIs such as the ZIP check are tied to the public SpreadsheetCodec contract, so they are handled on the side that changes CodecSet's public surface.

Define the replacement for sheet state first

public enum SheetContentState: Sendable, Hashable {
    case grid
    case unread
    case nonGrid
}
// Sheet
public var contentState: SheetContentState { get }

grid is an ordinary grid (including new, empty and loaded). unread is a worksheet that ReadOptions.sheets excluded from reading. nonGrid is a sheet that the model does not interpret as a grid. The check looks at isUnread first, then at whether a foreignSheet is present. Holding the bytes of an unread XLSX worksheet does not make it nonGrid. However, a chart sheet left out of the selection stays nonGrid — its kind is declared by the relationship type in the workbook, and is known without parsing the part. Calling it unread would throw away information the reader already has (the warning text in Appendix B.35 also says "a chart sheet"). A grid that could only be partly read because of cellLimit and the like is also grid; this is not a guarantee of a complete read. Check readWarnings for read losses; a read stopped at cellLimit gives a truncated warning naming the sheet (B.92).

Sheet.state is visibility and is independent of this state. contentState is a computed property read from the preservation information, and follows the sheet after a rename or move. Duplication does not follow — duplicateSheet rebuilds the copy's preservation information (it cannot claim the original's part path, r:id or sheetId), so duplicating an unread / non-grid sheet yields an ordinary grid carrying only the cells the model holds. The original bytes are written once, on the original sheet's side. Setting cells on an unread / non-grid sheet does not change its state; the existing save-time warning and byte-preservation rules stand. The limitation that an unread ODS or Numbers sheet comes out empty when saved to the same format, and the limitation that Numbers forms are excluded from the model, are unchanged.

The workbook's preservation summary

public struct PreservationSummary: Sendable {
    public let sourceFormat: SheetFormat?
    public let opaquePartCount: Int
    public let hasVBAProject: Bool
    public init(sourceFormat: SheetFormat?, opaquePartCount: Int, hasVBAProject: Bool)
}
// Workbook
public var preservationSummary: PreservationSummary { get }

An immutable snapshot that mirrors sourceFormat, parts.count and hasVBAProject at the moment it is taken. Taking it does not expand any part. A new workbook gives nil, 0, false. The public initializer exists only to construct summary values and cannot change what the Workbook preserves. The part count does not count XML fragments or the editing model's images and charts, and 0 does not mean there is no preservation information. The source format is no guarantee about the destination format, and the presence of VBA is no guarantee that the destination can carry macros. The generating application is read from sourceInfo, read warnings from readWarnings, write losses from WriteResult. No public equivalent is provided for the list of part names, a per-category summary, raw XML, or removing or replacing individual parts.

Acceptance checks

From a separate SwiftPM package, call the public summary, state and the 4 editing operations, and also confirm that access to the preservation types and to preserved fails. Test partial reads in every format, non-grid sheets, rename / move / duplicate, changes after the summary was taken, and that taking it does not expand compressed data. Pass the existing preservation, style, relationship-ID and warning tests and the full swift test, and run the XLSX / Numbers parity.

B.47 The return value of save and convert must be looked at (Rev 4.36)

Approved 2026-09-08. @discardableResult is removed from the 5 declarations CodecSet.write(_:to:as:options:), CodecSet.convert(_:to:output:readOptions:writeOptions:), Workbook.write(to:as:options:), Workbook.convert(_:to:output:readOptions:writeOptions:) and Workbook.write(to:as:options:password:). A call that does not use the return value becomes a compiler warning. Builds that treat warnings as errors need a migration. Receive it with let result = try workbook.write(to: url) and check warnings; when discarding it on purpose, say so with _ = try workbook.write(to: url).

This is not a mechanism that forces the warnings to be checked. Using only the result's data is possible, and so is an explicit discard. The output bytes, warnings, suggestion, error contract, arguments, return type and save order are unchanged. By the time write(to:) returns, the file is saved. To check before saving, produce the result with write(as:) and save the same data you checked. Read warnings are checked from ReadResult.warnings or Workbook.readWarnings. convert returns the read warnings and then the write warnings, in that order (B.23).

At the time of this decision the plain and encrypting data(as:) were kept. The follow-up B.48 folds them into write(as:).data. Renaming convert's arguments, the streaming API and turning warnings into errors are out of scope. scripts/check-write-result-api.py compiles an external client and confirms, for each of the 5 declarations, the unused-result warning, the warnings-as-errors failure, and that using the result and discarding it explicitly both succeed. It runs on the CI's macOS and Linux.

B.48 Getting the bytes is folded into write (Rev 4.37)

Approved 2026-09-08. The 2 declarations Workbook.data(as:options:) and Workbook.data(as:options:password:) are deleted. No deprecated aliases are kept. The plain form migrates to try wb.write(as: format, options: options).data, the encrypting form to try wb.write(as: format, options: options, password: password).data. Argument defaults follow write's existing contract. Old calls become compile errors.

Both old APIs only returned the data of the corresponding write, so the output processing, errors and save order are unchanged. write(as:) returns a WriteResult without saving to a file. To check warnings and suggestion, receive the result. Taking only data is also possible; the consolidation does not force the warnings to be checked. Losses at read time are checked separately from Workbook.readWarnings. When checking before saving, save the same result.data you checked (B.47).

scripts/check-write-result-api.py checks, in an external client, that using the 2 old declarations fails and that using the plain and encrypting write succeeds. The result's warnings and suggestion, the decrypted result of the encrypted output and the error for an unsupported format are tested. convert's arguments, CodecSet's public surface and streaming are unchanged.

B.49 Aligning convert's arguments with the save API (Rev 4.38)

Approved 2026-09-08. Workbook.convert and CodecSet.convert become convert(_ source: URL, to output: URL, as format: SheetFormat, readOptions: ReadOptions = ReadOptions(), writeOptions: WriteOptions = WriteOptions()) throws -> WriteResult. The Workbook side is static. The old overload with to: for the format and output: for the destination is not kept; old calls become compile errors. Migrate to try Workbook.convert(source, to: destination, as: .csv).

The format stays required. No feature that infers the format from the destination's extension is added. The order, types and defaults of readOptions and writeOptions, throws, WriteResult and the unused-result warning are kept. The order read → write → save, the order of warnings (read side then write side) and the write side's suggestion are kept. The contract that the file is saved by the time it returns is not changed either. The keep-the-arguments position taken at the time of B.47 and B.48 is updated by this follow-up decision.

scripts/check-write-result-api.py verifies the new calls of both declarations (default and explicit options) and confirms that the old labels and omitting the format fail. The conversion result, the saved content and the passing of read and write options are confirmed by behavioural tests.

B.50 Format selection moves to a public Codec value; the per-format implementations become package (Rev 4.39)

Approved 2026-09-09. Public format selection is concentrated in CodecSet. SpreadsheetCodec, the per-format codecs and the per-format streaming readers and writers (122 declarations) become package. CodecSet's 2 declarations stay public but change shape. The format is chosen by a public Codec value that has no public initializer and whose only public member is format. The values come from static properties of each product module — SheetXLSX gives .xlsx and .xlsm, SheetODS .ods, SheetNumbers .numbers, SheetCSV .csv. The format of a product that is not imported cannot be referenced.

Change to CodecSet.init(_ codecs: [Codec]) and codec(for:) throws -> Codec. The old initializer is not kept. The returned Codec gets no public methods such as read or write. Reading and writing go through CodecSet, and through the shared detection and warning handling. When the same format is given more than once the last wins, and formats keeps the order of first appearance. An empty array is allowed too. What contains and codec(for:) consult is the formats registered in that CodecSet; a format that is merely linked into the binary is not treated as available. The error for an unregistered format keeps the current SheetError.unsupportedFeature, and its text points to both linking the product and registering it in the CodecSet (changed to noCodec(for:) in Rev 4.41, B.52; the text is kept). SwiftSheets' CodecSet.all continues to register every format.

StreamingReader.tableNames(inSheet:) throws -> [String?] is added. The order and count of the array match the table index of tableCount(inSheet:) and forEachRow for the same sheet. A table with no name returns nil; "Table" is not synthesised (an actually recorded "Table" or an empty string is returned as is). The default implementation is an array of nils of the same count as tableCount; only Numbers fills in real names. A sheet that does not exist keeps the same error contract as tableCount in the same format.

There are 4 breaking changes with no public replacement: external conformance to SpreadsheetCodec (implementing your own format is not part of the 1.0 public surface), canDecode(ZipInspection), NumbersCodec.templateURL and CSVStreamingReader.pieceSize. Moving from direct calls to CodecSet may add loss warnings for ODF-specific features (an exact match of count and content is not promised). CSVStreamingReader.init(data:options:filename:) goes through the shared input detection and therefore needs try. Out of scope (separate decisions): new SheetError cases, forcing a format on URL input, removing canDecode itself.

scripts/check-codec-api.py checks from a separate SwiftPM package that depends on the checkout. The positive controls are CodecSet([.xlsx, .csv]) and the empty array in the 4 configurations SheetXLSX only, SheetCSV only, several products, and SwiftSheets, and the format of the value codec(for:) returns. The negative controls are the per-format codec types, Codec's initializer, the property of a format that is not imported, read on the returned Codec, and the 2 declarations with no replacement. It runs on the CI's macOS and Linux.

B.51 A streaming write reaches the destination only when it finishes normally (Rev 4.40)

Approved 2026-09-09. The 4 writers of streaming write (B.42) opened the destination itself — CSV with createFile at initialization, XLSX, XLSM and Numbers with ZipFileWriter at initialization, ODS inside close. If something threw midway, the file that had been there before was left truncated. Every format is aligned on writing to a temporary file in the same parent directory as the destination, and moving it into place with a single rename-equivalent only when everything up to the finishing steps succeeded. A failed path does not touch the destination. The contract that the whole-model write(to:as:) already had (B.47) is given to streaming write as well.

The public API has 3 points. StreamingWriter.close() returns a StreamingWriteResult (changed from Void; no @discardableResult). StreamingWriter.cancel() is added — it releases the resources without saving. CodecSet.withStreamingWriter(to:as:sheetName:epoch:csv:_:) is added, and the library performs close and the move only when the closure returns normally. The existing StreamingWriter(url:) and CodecSet.streamingWriter(url:format:sheetName:epoch:csv:) keep their arguments and use the same save contract. Making only the helper API safe is not adopted (the manual API would keep the danger of overwriting directly). Dropping the manual API is not adopted either (there are uses where the code supplying rows is spread over several functions). No synonymous alias API is added on the SwiftSheets side — CodecSet.all.withStreamingWriter(…) is enough.

StreamingWriteResult is a public struct holding only format (the format actually chosen) and warnings (the losses settled at finish), with no public initializer. It does not return Data (that would bring the finished file back into memory in full). It does not carry a row count, a byte count or a suggestion either — it must not become an incomplete substitute result under the same names as WriteResult. Format determination stays the current rule of explicit value → destination extension → xlsx; the refusal for an unregistered format, the CSV options and the date epoch also stay as they are.

Saving has 4 stages. (1) Secure, in the same parent as the destination, a temporary file with a non-colliding name using O_EXCL (permissions are left to 0o666 and the umask, so it looks the same as the current createFile). (2) Write the rows — the destination is not touched. (3) The finishing steps (the ZIP directory, flushing the buffers, closing every handle). (4) Move into place with a single rename-equivalent and return the result. Nothing that can fail is placed after the move. A destination that is a directory or a symbolic link is refused at the start (ioFailure). The parent directory is not created. Because the temporary file is created in the same parent as the destination, the output disk needs extra free space for one finished output (the ODS row spill area is needed on top of that).

The state is internal; no public state property is added. A later call never makes a failed close look like a success. Operations after finishing or after a failure are refused with throws, not precondition (the current XLSX addSheet had no check at all). The warnings property stays: before finishing it is the running tally, and the settled result is read from result.warnings.

The contract when failures pile up. A failure in initialization, in the body, in append or in the per-format close throws the original error as is if the clean-up succeeded, and the destination is as it was (for a new file, not created). A failure in the move (rename) does not fall back to deleting and then moving; it tries to discard the finished temporary file and returns the move's error. Only when the original failure and a clean-up failure coincide are both kept in the public StreamingCleanupError (primaryError and cleanupErrors; no public initializer) — so that a clean-up failure never hides the original cause. When only cancel fails, the first clean-up error is thrown, and if there are several the same wrapper carries the rest. When the writer is released without close or cancel, deinit attempts the clean-up and neither throws nor saves. Zero leftover temporary files after a forced process termination is not promised.

withStreamingWriter runs a synchronous, non-escaping closure. The StreamingWriter it passes is not Sendable (concurrent use from another task is not part of the contract). If the body throws, that error is kept and the writer is cancelled, not closed. If the body catches an append error and returns, the writer is failed, so nothing is saved and the first recorded write error is returned (when the body threw a different error, the body's error takes precedence). close and cancel from inside the managed closure are refused with invalidWorkbook and put the writer into failed — even if the caller catches that error, nothing is saved. Even if the writer can be carried out of the closure, once the processing has ended it is finished or cancelled, so no rows can be added afterwards (the non-escaping annotation alone cannot prevent carrying it out, so the runtime state prevents it).

Making clear what is protected. The subject is ordinary local files, and the promise is not to damage the old file on the I/O errors this processing returns. Durability after a power failure, network file systems, concurrent replacement by another process, and inheriting an existing file's permissions and extended attributes are not promised. For two writers on the same destination the contract is "the last successful save remains"; no conflict detection is added. macOS, iOS and Linux use a same-file-system rename (not FileManager.replaceItemAt). WASI is enabled only in an environment where the same contract could be confirmed by running it; until it can be confirmed, it refuses with unsupportedFeature before touching the destination — no fallback to a non-atomic copy is provided. Approved 2026-09-10: ship it refusing. At implementation time a WASI build could not be made at all (the Swift bundled with Xcode has no WebAssembly backend, and even with the wasm SDK installed it fails with No available targets are compatible with triple "wasm32-unknown-wasip1"), so that rename holds could not be confirmed by running it even once. Keeping the old direct write for WASI alone is not adopted, because it would leave the "path on which the destination can be damaged" that this decision closed off open on WASI alone. The condition for lifting the refusal is confirming the B.51 save contract by running it with the swift.org toolchain and a WASI runtime. No API that lets the caller look at the warnings before saving and then decide is added (by the time the result comes back the save has happened). For that use, write to a different destination or use the whole-model write(as:). A completion result for streaming read, encrypted streaming write, async closures and transactions spanning several files are out of scope.

Checks. For each of the 5 formats, with an existing file and with a new one, confirm that before finishing not a single byte of the old file changes and that a new destination does not exist, and after a successful finish confirm the content with a whole-model read and a streaming read. Failures are injected individually into securing the file (destination not an ordinary file, parent missing), append, addSheet, the per-format close (where each format closes its package and closes the handles), rename and the temporary-file deletion, and the check also asserts that the injection point was actually reached (not relying on a chance permission or full-disk error). When the format is unregistered, confirm that no temporary file is created either. The body's error is thrown as a reference-type error that can be identified, and the check confirms that the same error comes back when the clean-up succeeds and that both remain in a compound failure. For a body that catches a failure and carries on, a repeated close, a repeated cancel, an append after finishing, close/cancel inside the closure, and a writer carried outside — in every case, the process does not crash and nothing is saved. scripts/check-streaming-api.py confirms from a separate SwiftPM client the unused-result warning and the explicit discard (the CI's macOS and Linux). Measurements are taken before and after the change, alternately on the same machine, and reported with time and peak memory paired.

B.52 Answering why it could not be opened with a type — classifying SheetError (Rev 4.41)

Approved 2026-09-10. SheetError.unsupportedFeature(String) housed failures of different natures — it is thrown from 30 places across Sources, and an encrypted file, a format absent from the set, a kind of encryption we do not handle, and a limit of the format itself all land in the same case. For the caller to tell these 4 apart, the only way was to inspect the refusal text as a string: does it contain encrypted, does it start with no codec for? The consumer was left to parse prose the library wrote. The pre-read query SheetFormat.probe already answers the same thing with a type, FormatProbe.unopenable(UnopenableInput), so it was also an inconsistency where only the throwing side had fallen back to strings. Adding a case to a public enum after 1.0 breaks the consumer's exhaustive switch, so this is decided before 1.0.

3 cases are added. No new type and no new vocabulary is created; the public types that already exist are carried as the values.

• unopenable(UnopenableInput) — an input that was identified but this library does not open. For the 4 of encrypted OOXML, encrypted ODF, encrypted Numbers and the old .xls, the value returned by UnopenableInput.error switches from unsupportedFeature to this (the 17 throw sites converge on one accessor). The case name and value are aligned with FormatProbe.unopenable.
• noCodec(for: SheetFormat) — that CodecSet has no codec (the refusal of B.44 and B.50). The text is unchanged and keeps pointing to both linking the product and registering it in the CodecSet.
• unsupportedEncryption(detail: String) — password protection this library does not handle. 10 places on the reading side (Blowfish of ODF 1.1, the standard encryption of Excel 2007, unknown hash, key length or checksum) and 2 on the writing side (CSV is plain text by definition; Numbers encryption is undocumented). It covers both reading and writing.

The remaining 16 places of unsupportedFeature are limits of the format or the environment itself (CSV has 1 sheet, characters the CSV encoding cannot represent, Numbers' 1,000,000 rows × 1,000 columns and types absent from the registry, image formats, streaming write on WASI), and its meaning is narrowed to "cannot be done in this library, this format, this environment". A new refusal that fits no classification can go here, so closing the enum at 1.0 is not a dead end.

Names are given by the fact, not the remedy. The passwordRequired from the 2026-09-07 proposal is not adopted. (1) This library has no "waiting for a password" state — the password is handed over before reading (SheetDecrypt.decrypt(_:password:)), and there is no way to ask back in the middle of a read. (2) A password resolves only 2 of the 4 (encrypted OOXML and encrypted ODF); returning the same name for encrypted Numbers and the old .xls would have the caller's UI keep showing a password field, and the user could type it any number of times and never open the file. (3) Therefore the 4 values of UnopenableInput, which say "what it is", are used as they are. formatNotLinked is not adopted either — it would be a lie when the product is linked and merely has no name in the CodecSet.

The refusal text (the body of description) is not changed by a single character. What changes is only the prefix unsupported: that unsupportedFeature attached: unopenable gives the reason as is, noCodec gives no codec for … as is, and unsupportedEncryption uses the prefix unsupported protection: . SheetFormat.productName is raised from package to public — so that whoever receives noCodec(for:) can write "please add SheetODS" in their own words.