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

ADDED Requirements

Requirement: TGZ adapter composes tar over a codec

The package SHALL export TgzArchiveStorage implementing the structural DriveStorage view by composing a tar adapter over a pluggable codec. The default constructor MUST accept codec: ArchiveCodec and SHALL ship a convenience openTarGz(source, opts) that defaults to gzipCodec from @suaveplan/drive-storage-gz.

Scenario: Default tar.gz opens with gzip codec

• WHEN openTarGz(bytes, { mode: "read-only" }) is called on valid .tar.gz bytes
• THEN entries from the inner tar are listed and read correctly

Requirement: Codec slot for tar.bz2, tar.xz, tar.zst

The package SHALL accept any object satisfying the ArchiveCodec interface (compress, decompress). Codecs for bzip2, xz, and zstd are NOT shipped in v0.1.0 but the slot MUST be functional so consumers can plug them in. Construction with no codec MUST raise ARCHIVE_CODEC_MISSING.

Scenario: Custom xz codec works

• WHEN new TgzArchiveStorage(bytes, { codec: customXzCodec }) is constructed and the bytes are a valid .tar.xz
• THEN entries are listed and read correctly using the custom codec's decompress

Scenario: Missing codec rejects clearly

• WHEN new TgzArchiveStorage(bytes, {}) is constructed without a codec
• THEN construction throws ARCHIVE_CODEC_MISSING

Requirement: Read-mostly with full re-encode on write

The adapter SHALL support read-only, copy-on-write, and rewrite modes. Writes MUST re-encode the full tar and then the full codec output. The cost MUST be documented and pendingMutationCount exposed.

Scenario: Round-trip write

• WHEN an adapter in copy-on-write mode adds one entry and calls flush()
• THEN the host bytes contain a valid codec-wrapped tar whose entry list contains the new entry

Requirement: Error code registry

The package SHALL register stable codes including TGZ_CODEC_FAILED, TGZ_INNER_TAR_INVALID. Format-specific errors from the underlying tar and codec packages MUST be propagated unchanged.

Scenario: Inner tar corruption surfaces

• WHEN the codec decompresses successfully but the resulting tar bytes fail header checksum validation
• THEN the error chain contains both TGZ_INNER_TAR_INVALID and the underlying TAR_HEADER_CHECKSUM_INVALID