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

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