Initial Commit

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

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