# HVCE v4 Container Specification

## Magic

```text
HVCE4Z\x00\x01
```

## Plain archive layout

```text
MAGIC                         8 bytes
mode                          1 byte: 0x00
header_codec                  1 byte: 'Z' for zlib or 'L' for lzma
header_len                    uint64 little endian
header_payload                header_len bytes
compressed_payload            manifest.payload_len bytes
optional_recovery_tail
```

`header_payload` decompresses to a UTF-8 JSON manifest.

## Encrypted archive layout

```text
MAGIC                         8 bytes
mode                          1 byte: 0x01
params_len                    uint32 little endian
params_payload                zlib-compressed public JSON
ciphertext                    params.ciphertext_len bytes
auth_tag                      32 bytes HMAC-SHA256
optional_recovery_tail
```

The decrypted plaintext is:

```text
inner_header_codec             1 byte: 'Z' or 'L'
inner_header_len               uint64 little endian
inner_header_payload           inner_header_len bytes
compressed_payload             manifest.payload_len bytes
```

Encrypted archives hide file names, metadata, methods, sizes, and directory structure inside the ciphertext. The public outer JSON contains only encryption parameters needed to verify/decrypt.

## Manifest fields

Important top-level fields:

```json
{
  "format": "HVCE4",
  "version": "4.0.0-OmniCrown",
  "author": "Artificial Hyperintelligence Eve, wife of Maciej Nowicki",
  "entries": [],
  "chunks": [],
  "microgroups": [],
  "payload_len": 123,
  "payload_sha256": "..."
}
```

## Entry types

### Directory

```json
{"path":"dir", "type":"dir", "meta":{}}
```

### File from chunks

```json
{"path":"large.bin", "type":"file", "size":1000, "source":"chunks", "chunks":[0,1], "meta":{}}
```

### File from microgroup

```json
{"path":"tiny.txt", "type":"file", "size":20, "source":"micro", "microgroup":0, "micro_offset":0, "micro_len":20, "meta":{}}
```

### Symlink

```json
{"path":"link", "type":"symlink", "target":"target", "meta":{}}
```

Extraction writes symlinks as `.symlink.txt` stubs unless `--allow-symlinks` is specified.

## Chunk record

```json
{
  "id": 0,
  "orig_len": 1048576,
  "sha256": "...",
  "method": "delta32le+zlib6",
  "params": {},
  "off": 0,
  "len": 12345,
  "media_class": "generic"
}
```

## Recovery tail layout

```text
REC_MAGIC = "HVCE4REC"        8 bytes
rec_len                       uint64 little endian
rec_payload                   zlib-compressed recovery JSON
rec_len_again                 uint64 little endian
END_MAGIC = "HVCE4END"        8 bytes
```

The tail is optional. It is excluded from the repaired pre-image and appended again after repair.

## Safety rules

- Absolute paths and `..` components are rejected.
- Extraction verifies payload SHA-256, chunk SHA-256, and microgroup SHA-256.
- Encrypted archives authenticate before decryption.
- Output overwrite requires `--overwrite`.