Initial Commit

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

@@ -0,0 +1,75 @@
+## 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