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

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