Initial Commit

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

@@ -0,0 +1,60 @@
+## ADDED Requirements
+
+### Requirement: GZ adapter exposes the wrapped stream as one drive entry
+
+The package SHALL export `GzipArchiveStorage` implementing the structural `DriveStorage` view. Because gzip wraps a single logical stream, the adapter MUST present exactly one entry whose path defaults to the original filename from the gzip `FNAME` field, or to a configurable fallback path when `FNAME` is absent.
+
+#### Scenario: FNAME header used as entry path
+
+- **WHEN** a gzip stream whose `FNAME` field equals `report.csv` is wrapped in `GzipArchiveStorage`
+- **THEN** `drive.list()` returns exactly one entry at `report.csv`
+
+#### Scenario: Fallback path used when FNAME absent
+
+- **WHEN** a gzip stream without an `FNAME` field is opened with `fallbackPath: "data.bin"`
+- **THEN** the single entry appears at `data.bin`
+
+### Requirement: Multi-member gzip streams
+
+The adapter SHALL transparently concatenate sequential gzip members (per RFC 1952 §2.2) when present, returning their decompressed bytes as a single logical entry stream.
+
+#### Scenario: Two concatenated members read as one stream
+
+- **WHEN** a gzip file containing two valid members each holding half of a logical file is read
+- **THEN** the returned stream contains the concatenation of both members' decompressed bytes
+
+### Requirement: Read-write with full re-encode
+
+The adapter SHALL support `read-only`, `copy-on-write`, and `rewrite` modes. Because gzip is a single stream, any write MUST fully re-encode the host bytes. The adapter MUST document this cost.
+
+#### Scenario: Write replaces entire host bytes
+
+- **WHEN** an adapter in `rewrite` mode receives a write to the single entry
+- **THEN** the host bytes are replaced by a freshly encoded gzip stream containing the new content
+
+### Requirement: CRC32 and ISIZE validation
+
+The adapter SHALL validate the trailing CRC32 and ISIZE fields on read. A mismatch MUST raise `GZ_CRC_MISMATCH` or `GZ_ISIZE_MISMATCH` respectively.
+
+#### Scenario: Truncated stream errors
+
+- **WHEN** the host bytes end before a valid CRC32+ISIZE trailer
+- **THEN** the read throws `GZ_TRUNCATED`
+
+### Requirement: Codec export for tgz composition
+
+The package SHALL export a `gzipCodec: ArchiveCodec` object that `@suaveplan/drive-storage-tgz` composes over a tar adapter. The codec MUST expose `compress(stream)` and `decompress(stream)` returning `ReadableStream<Uint8Array>`.
+
+#### Scenario: tgz consumes gzipCodec
+
+- **WHEN** `@suaveplan/drive-storage-tgz` constructs an adapter with `codec: gzipCodec`
+- **THEN** decompression of a `.tar.gz` host file produces the same entry listing as decompressing the gz then opening the tar
+
+### Requirement: Error code registry
+
+The package SHALL register stable codes including `GZ_HEADER_INVALID`, `GZ_CRC_MISMATCH`, `GZ_ISIZE_MISMATCH`, `GZ_TRUNCATED`, `GZ_UNSUPPORTED_FLAG`.
+
+#### Scenario: Bad gzip magic errors
+
+- **WHEN** the first two bytes are not `\x1F\x8B`
+- **THEN** the open throws `GZ_HEADER_INVALID`