Initial Commit

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

@@ -0,0 +1,56 @@
+## ADDED Requirements
+
+### Requirement: TAR adapter exposes tar entries as DriveStorage
+
+The package SHALL export `TarArchiveStorage` implementing the structural `DriveStorage` view. Entry paths inside the tar MUST appear as drive paths with directory separators normalised to `/`.
+
+#### Scenario: Drive lists tar entries
+
+- **WHEN** a tar archive containing `etc/conf` and `etc/hosts` is wrapped in `TarArchiveStorage` and `drive.list("etc/")` is called
+- **THEN** the result contains both `etc/conf` and `etc/hosts`
+
+### Requirement: POSIX, USTAR, and PAX header support
+
+The adapter SHALL parse legacy v7, USTAR, and POSIX.1-2001 PAX extended headers. Long filenames exceeding 100 bytes MUST be reconstructed from PAX `path` records or GNU `L` long-link entries. PAX size records MUST override the 12-octet octal size field.
+
+#### Scenario: PAX long filename round-trips
+
+- **WHEN** a tar entry whose path is 300 bytes long is read
+- **THEN** the entry path is returned unchanged from `list()` and `stat()`
+
+#### Scenario: PAX size record honoured
+
+- **WHEN** an entry's PAX `size` record specifies a value larger than 8 GiB
+- **THEN** the adapter reads the full byte count without truncation
+
+### Requirement: Sparse file extension
+
+The adapter SHALL parse GNU sparse 1.0 extension records and present sparse regions as zero bytes in the reconstructed entry stream. Sparse 0.0/0.1 variants MAY be supported but MUST raise `TAR_SPARSE_VARIANT_UNSUPPORTED` if unsupported rather than silently mis-reading.
+
+#### Scenario: Sparse 1.0 entry reads as zero-filled
+
+- **WHEN** a sparse 1.0 entry with one data region of 1 KiB and one hole of 1 GiB is read
+- **THEN** the returned stream contains the data region followed by 1 GiB of zero bytes
+
+### Requirement: Read-write with append and rewrite
+
+The adapter SHALL support `read-only`, `copy-on-write`, and `rewrite` modes. Tar's sequential format means deletes require full rewrite; the adapter MUST document this cost and expose `pendingMutationCount`. Pure-append writes MAY append blocks before the two-block zero terminator and rewrite only the terminator.
+
+#### Scenario: Append avoids full rewrite
+
+- **WHEN** an adapter in `copy-on-write` mode writes one new entry and calls `flush()`
+- **THEN** the host bytes are appended in place plus a new zero terminator, not fully re-encoded
+
+#### Scenario: Delete triggers full rewrite
+
+- **WHEN** an adapter in `copy-on-write` mode deletes one existing entry and calls `flush()`
+- **THEN** `flush()` writes a complete new archive omitting the deleted entry
+
+### Requirement: Error code registry
+
+The package SHALL register stable codes including `TAR_HEADER_CHECKSUM_INVALID`, `TAR_PAX_HEADER_INVALID`, `TAR_SPARSE_VARIANT_UNSUPPORTED`, `TAR_BLOCK_ALIGNMENT_INVALID`.
+
+#### Scenario: Bad header checksum errors
+
+- **WHEN** a tar header's checksum field does not match the sum of its octets
+- **THEN** the read throws `TAR_HEADER_CHECKSUM_INVALID` with the byte offset in details