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

ADDED Requirements

Requirement: RAR adapter exposes rar entries as DriveStorage (read-only)

The package SHALL export RarArchiveStorage implementing the structural DriveStorage view in read-only mode only. Construction with any mode other than read-only MUST throw ARCHIVE_MODE_READ_ONLY immediately.

Scenario: Construction rejects writable mode

• WHEN new RarArchiveStorage(bytes, { mode: "rewrite" }) is called
• THEN the constructor throws ARCHIVE_MODE_READ_ONLY and does not allocate any decoder state

Scenario: Drive lists rar entries

• WHEN a RAR5 archive containing two entries is wrapped and drive.list() is called
• THEN both entry paths are returned

Requirement: RAR4 and RAR5 format support

The adapter SHALL parse both RAR4 (signature Rar!\x1A\x07\x00) and RAR5 (signature Rar!\x1A\x07\x01\x00) container formats. Format detection MUST happen via magic bytes, and unsupported RAR3-or-older signatures MUST raise RAR_VERSION_UNSUPPORTED.

Scenario: RAR4 archive opens

• WHEN a RAR4 archive is opened
• THEN entries are listed correctly

Scenario: RAR5 archive opens

• WHEN a RAR5 archive is opened
• THEN entries are listed correctly

Requirement: Multi-volume support

The adapter SHALL support RAR5 multi-volume archives using .partN.rar naming (e.g. name.part1.rar, name.part2.rar) and legacy RAR4 multi-volume using .r00, .r01, …, .r99 extensions. Sibling discovery MUST use the resolveSibling callback from drive-storage-archive-core. Each subsequent volume's signature and volume number MUST validate before its bytes are consumed.

Scenario: RAR5 partN volumes assemble

• WHEN the primary archive.part1.rar is opened with a resolveSibling that returns archive.part2.rar and archive.part3.rar
• THEN entries spanning all three volumes are listed and read

Scenario: RAR4 r00..r02 volumes assemble

• WHEN the primary archive.rar is opened with a resolveSibling returning archive.r00, archive.r01
• THEN entries spanning all volumes are read

Scenario: Volume sequence gap errors

• WHEN resolveSibling returns volume 2 with a header indicating volume number 3
• THEN the adapter throws ARCHIVE_SPLIT_MISSING_VOLUME

Requirement: Encrypted header and encrypted entry support

The adapter SHALL support reading entries protected by per-entry passwords and full encrypted-header archives. The password hook from drive-storage-archive-core MUST be invoked lazily on first encrypted-content access.

Scenario: Encrypted-header archive

• WHEN an archive with encrypted headers is opened and the password hook returns the correct passphrase
• THEN entry listing succeeds

Requirement: Browser builds raise typed error

The package SHALL be server-tier. The browser field in package.json MUST resolve to a stub module whose entry points throw RAR_UNAVAILABLE_IN_BROWSER on any call.

Scenario: Browser bundle throws on use

• WHEN a browser bundle that imports RarArchiveStorage calls the constructor
• THEN it throws RAR_UNAVAILABLE_IN_BROWSER

Requirement: Error code registry

The package SHALL register stable codes including RAR_VERSION_UNSUPPORTED, RAR_FILTER_UNSUPPORTED, RAR_UNAVAILABLE_IN_BROWSER, RAR_CORRUPT, RAR_CRC_MISMATCH.

Scenario: CRC mismatch surfaces

• WHEN an entry's stored CRC does not match the decoded bytes
• THEN the read throws RAR_CRC_MISMATCH with the entry path in details