# Archive Compatibility Policy

Status: Stage 10 release readiness

This policy defines the archive behavior that future releases must preserve for
V1 archives.

## Reader Guarantees

A compatible ForgePack reader must keep reading V1 archives that use supported
mandatory sections, supported codecs, and valid descriptors.

A reader must fail predictably when it sees:

- unsupported format major version
- unknown required feature
- unsupported codec
- invalid section bounds
- truncated required metadata
- corrupted payload when integrity metadata is present

## Optional Sections

Unknown optional sections may be skipped. Their bytes should be preserved by
future rewrite or append workflows when the operation can do so safely.

V1 currently reserves optional sections for cold metadata, manifest data,
integrity metadata, recovery metadata, and append history.

## Required Features

Required features are part of the compatibility contract. A new required feature
must be introduced only with a documented migration path and tests proving that
older readers reject it with a clear error.

## Codec Compatibility

Codec availability is separate from archive format support. A reader can parse
an archive and still report `UnsupportedCodec` for entries encoded with an
unknown codec.

## Metadata Compatibility

Hot metadata remains the source for basic listing and extraction. Cold metadata
may improve indexing and future workflows, but it must not be required for simple
V1 listing of ordinary archives.
