Read a zip archive as one workbook (csv and xlsx entries as sheets)

[vaceslav]

Read a zip archive as if it were one workbook: every readable entry contributes its sheets to one flat list, and each sheet carries its Source (the entry's path) so a UI can group sheets by it.

Use cases:

1. One large csv, zipped to shrink the upload (a 572 MB export is 60–80 MB zipped), read straight from the archive without unpacking it to disk.
2. Several csv files of one export in one archive.
3. A mixed archive with workbooks and csv files side by side. Rare, but it comes almost for free with 1 and 2.

Design: docs/superpowers/specs/2026-09-25-archive-as-workbook-design.md, part 2.

Prerequisite (part 1, before v0.1, done):

• per-sheet Format / Source / Dialect / Diagnostics;
• MappingPlan.SheetName / SheetSource with structure.sheet-changed.

Scope of this issue (additive, after v0.1):

• Detection by bytes:
  • [Content_Types].xml means a workbook;
  • an OpenDocument spreadsheet is TabularFormat.Ods (done in Read OpenDocument spreadsheets (.ods) #13); another OpenDocument type stays format.unsupported;
  • anything else is TabularFormat.Zip.
• Entries:
  • Skipped silently: directories, __MACOSX/, hidden files.
  • Every other entry is sniffed: an xlsx or ods workbook contributes its sheets, text becomes a csv sheet.
  • Nested archives, other OpenDocument types, OLE2, binary, XML documents and encrypted entries are skipped, each with a reason in FileProfile.SkippedEntries.
• Order and names: sheets are ordered by entry path, ordinally. A csv sheet is named after its file without the extension. Source + Name identify a sheet.
• Csv entries: read as streams. The dialect probe is buffered and rejoined to the front, because an entry stream cannot seek.
• Workbook entries: buffered in memory under MaxEmbeddedWorkbookBytes (default 256 MB, configurable past 2 GB through a chunked buffer), at most one at a time.
• Options: ArchiveCursorOptions (Csv, Xlsx, Ods, MaxEntries, MaxUncompressedBytes, MaxEmbeddedWorkbookBytes); TabularOpenOptions.Archive.
• Tests: built from raw bytes. They cover a zip bomb, junk entries, a workbook renamed to .zip, sheet order that does not depend on entry order, and moving back to an earlier csv sheet.
• Performance: the 5M-row csv zipped vs. unpacked (time, peak memory).

[vaceslav]

Done in a0aea63..88bcd8f.

• A zip that is not itself a workbook reads as one: every csv, xlsx and ods file inside contributes its sheets, in path order, each with its file's path as Source.
• A csv is streamed out of the archive, never unpacked. Its dialect is detected from its own head, and moving back to it reads it again from row 1.
• Workbooks are copied into a chunked in-memory buffer, one at a time. MaxEmbeddedWorkbookBytes defaults to 256 MB and can be set past 2 GB.
• Encrypted, nested-zip, other-OpenDocument, legacy, XML and binary files are listed in SkippedEntries with a reason; directories, hidden files and __MACOSX/ are left out.
• TabularFile.Detect tells a workbook, an ods and an archive apart by the zip's directory.
• Measured on the 572 MB csv zipped to 179 MB: it reads in 4.2 s against 3.0 s unpacked, with the same values and repairs and a flat 56 MB peak.