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

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