== Master Header Structure

The AaruHeaderV2 is the fundamental header present at the beginning of every AaruFormat file.
It defines the image's versioning, metadata, layout offset, feature compatibility, and structural alignment.
All subsequent parsing and interpretation of the file depends on the contents of this header.

=== Structure Definition

[source,c]
#define HEADER_APP_NAME_LEN 64
#define GUID_SIZE 16
/**Header, at start of file */
typedef struct AaruHeaderV2
{
    uint64_t identifier;                             ///< File magic (AARU_MAGIC).
    uint8_t  application[AARU_HEADER_APP_NAME_LEN];  ///< UTF-8 creator application name (fixed 64 bytes).
    uint8_t  imageMajorVersion;                      ///< Container format major version.
    uint8_t  imageMinorVersion;                      ///< Container format minor version.
    uint8_t  applicationMajorVersion;                ///< Creator application major version.
    uint8_t  applicationMinorVersion;                ///< Creator application minor / patch version.
    uint32_t mediaType;                              ///< Media type enumeration (value from \ref MediaType).
    uint64_t indexOffset;      ///< Absolute byte offset to primary index block (MUST be > 0; 0 => corrupt/unreadable).
    int64_t  creationTime;     ///< Creation FILETIME (100 ns since 1601-01-01 UTC).
    int64_t  lastWrittenTime;  ///< Last modification FILETIME (100 ns since 1601-01-01 UTC).
    uint8_t  guid[GUID_SIZE];  ///< 128-bit image GUID (binary, not text); stable across children.
    uint8_t  blockAlignmentShift;  ///< log2 block alignment (block size alignment = 2^blockAlignmentShift bytes).
    uint8_t  dataShift;            ///< log2 sectors/items per block-index increment in DDT entries (2^dataShift).
    uint8_t  tableShift;           ///< log2 sectors spanned by each primary DDT entry (0 = single-level).
    uint64_t featureCompatible;    ///< Feature bits: unimplemented bits are ignorable (still R/W safe).
    uint64_t featureCompatibleRo;  ///< Feature bits: unimplemented -> degrade to read-only access.
    uint64_t featureIncompatible;  ///< Feature bits: any unimplemented -> abort (cannot open safely).
} AaruHeaderV2;

=== Field Descriptions

[cols="2,3,6",options="header"]
|===
| Name | Type | Description
| identifier | uint64_t | Header identifier constant. Must match the predefined `AARU_MAGIC` value to validate the format.
| application | uint8_t[HEADER_APP_NAME_LEN] | UTF-16LE in version 1, UTF-8 in version 2, encoded name of the application responsible for creating the image.

Length is defined by `HEADER_APP_NAME_LEN`.
| imageMajorVersion | uint8_t | Major version of the AaruFormat structure.

A bump indicates potential breaking changes.
| imageMinorVersion | uint8_t | Minor version of the format, for backward-compatible structural updates.
| applicationMajorVersion | uint8_t | Major version of the creating application.
| applicationMinorVersion | uint8_t | Minor version of the application.
| mediaType | uint32_t | Media type identifier denoting the nature of the captured content (e.g., floppy, optical disc, tape).
| indexOffset | uint64_t | Absolute file offset to the beginning of the index structure, used to locate blocks throughout the image.
| creationTime | int64_t | Timestamp (Windows filetime) representing when the image was first created.
| lastWrittenTime | int64_t | Timestamp (Windows filetime) of the last modification made to the image.
| guid | uint8_t[GUID_SIZE] | Globally Unique Identifier (GUID) that allows linking of related image derivatives and child snapshots.

Length is defined by `GUID_SIZE`.
| blockAlignmentShift | uint8_t | Determines block alignment boundaries using the formula 2 << blockAlignmentShift.
| dataShift | uint8_t | Determines the maximum number of data items in a block using the formula 2 << dataShift.
| tableShift | uint8_t | Shift used to calculate the number of sectors in a deduplication table entry, using the formula 2 << tableShift.
| featureCompatible | uint64_t | Bitmask of features that, even if not implemented, still allow reading and writing the image.

| featureCompatibleRo | uint64_t | Bitmask of features that allow read-only processing of the image if unsupported.

| featureIncompatible | uint64_t | Bitmask of features that must be supported to read or write the image at all.
|===