Initial Commit

openspec/changes/add-drive-storage-archive/specs/drive-storage-7z/spec.md

@@ -0,0 +1,65 @@
+## ADDED Requirements
+
+### Requirement: 7z adapter exposes 7z entries as DriveStorage
+
+The package SHALL export `SevenZipArchiveStorage` implementing the structural `DriveStorage` view. Entry paths inside the archive MUST appear as drive paths with directory separators normalised to `/`.
+
+#### Scenario: Drive lists 7z entries
+
+- **WHEN** a 7z archive containing two entries is wrapped and `drive.list()` is called
+- **THEN** both entry paths are returned
+
+### Requirement: LZMA, LZMA2, and BCJ filter support
+
+The adapter SHALL support LZMA and LZMA2 compression codecs and the BCJ, BCJ2, Delta, and ARM/X86/SPARC preprocessor filters as composed in 7z `Folder` records. Unsupported codec IDs MUST raise `SEVENZ_UNSUPPORTED_CODEC`. Unsupported filter chains MUST raise `SEVENZ_BCJ_FILTER_UNSUPPORTED`.
+
+#### Scenario: LZMA2 + BCJ executable decodes
+
+- **WHEN** a 7z archive whose folder chain is LZMA2 → BCJ over an executable entry is read
+- **THEN** the decoded bytes match the original executable
+
+#### Scenario: Unknown codec errors clearly
+
+- **WHEN** an archive references a codec ID not implemented by the adapter
+- **THEN** the read throws `SEVENZ_UNSUPPORTED_CODEC` with the codec ID in details
+
+### Requirement: Multi-volume support
+
+The adapter SHALL support multi-volume 7z archives using `.7z.001`, `.7z.002`, …, `.7z.NNN` naming. Sibling discovery MUST use the `resolveSibling` callback from `drive-storage-archive-core`. The adapter MUST concatenate volumes in ascending index order before parsing the trailing header.
+
+#### Scenario: Three-volume 7z assembles
+
+- **WHEN** the primary `archive.7z.001` is opened with a `resolveSibling` returning `archive.7z.002` and `archive.7z.003`
+- **THEN** all entries are listed and read
+
+#### Scenario: Out-of-order volume rejected
+
+- **WHEN** `resolveSibling` returns volume 1 at index 2 (i.e. mis-ordered)
+- **THEN** the adapter throws `ARCHIVE_SPLIT_MISSING_VOLUME` with both expected and received indices
+
+### Requirement: Header encryption and per-entry encryption
+
+The adapter SHALL support reading 7z archives with encrypted headers (`7zAES` over the `EncodedHeader` block) and per-entry-encrypted content. The password hook from `drive-storage-archive-core` MUST be invoked lazily on first decryption need.
+
+#### Scenario: Encrypted-header archive opens
+
+- **WHEN** a 7z archive with encrypted headers is opened with a correct-password hook
+- **THEN** entry listing and reading succeed
+
+### Requirement: Read-write with copy-on-write or rewrite
+
+The adapter SHALL support `read-only`, `copy-on-write`, and `rewrite` modes. Writes MUST produce a standards-compliant 7z file readable by reference 7-Zip implementations. Mutations re-encode the affected folder(s) and rewrite the trailing header.
+
+#### Scenario: Round-trip write then read
+
+- **WHEN** an adapter in `copy-on-write` mode writes `inside/n.txt`, flushes, then a new adapter is opened over the flushed bytes
+- **THEN** `inside/n.txt` is listed and reads with the original content
+
+### Requirement: Error code registry
+
+The package SHALL register stable codes including `SEVENZ_HEADER_INVALID`, `SEVENZ_UNSUPPORTED_CODEC`, `SEVENZ_BCJ_FILTER_UNSUPPORTED`, `SEVENZ_CRC_MISMATCH`, `SEVENZ_CORRUPT`.
+
+#### Scenario: Bad signature errors
+
+- **WHEN** the host bytes do not begin with `7z\xBC\xAF\x27\x1C`
+- **THEN** open throws `SEVENZ_HEADER_INVALID`