syncova-backup/docs/backup-format.md

# Backup-Format

Dieses Dokument beschreibt den **aktuell implementierten** Stand nach Phase 3.

## Zweck

Der Syncova Backup Container ist die **portable** Form eines Backups: eine einzelne, in sich geschlossene Datei mit allem, was zur Wiederherstellung nötig ist. Er dient der Übertragung an ein zweites Repository (PROMPT.md §17), der Archivierung und dem Austausch zwischen Installationen.

Das Repository (Phase 2) legt ein Backup **verteilt** ab — Chunks und Manifest getrennt. Der Container fasst dasselbe Backup in **eine** Datei. Beide Formen sind selbstprüfend und brauchen keine Datenbank.

## Aufbau

```text
+--------------------------------------------------+
| Magic "SYNCOVA1"           8 Byte                |
| Formatversion              2 Byte (Big Endian)   |
| Headerlänge                4 Byte                |
| Header                     JSON                  |
+--------------------------------------------------+
| Abschnitt 1: Typ 1 | Flags 1 | Länge 8 | SHA 32  |
|              Inhalt                              |
| Abschnitt 2 ...                                  |
+--------------------------------------------------+
| Footer-Magic "SYNFOOT1"    8 Byte                |
| Footerlänge                4 Byte                |
| Footer                     JSON                  |
+--------------------------------------------------+
```

Alle Mehrbyte-Zahlen sind Big Endian. Die Byte-Reihenfolge ist Teil des Formats und darf nicht von der Rechnerarchitektur abhängen.

**Abschnittstypen:** Manifest (1), Chunk-Verzeichnis (2), Blockzuordnung (3), Datenblöcke (4), Quellenangaben (5), Integritätsangaben (6). Die Zahlenwerte sind Teil des Vertrags und dürfen **niemals** neu belegt werden — ein bestehender Container würde sonst falsch gedeutet.

## Der Footer steht am Ende

Das ist die tragende Entscheidung des Entwurfs. Erst am Ende stehen alle Prüfsummen fest — und genau daraus folgt die Aussagekraft:

> Ein abgebrochener Schreib- oder Übertragungsvorgang hinterlässt einen Container **ohne** Footer. Er wird dadurch zuverlässig als unvollständig erkannt.

Erst `Close()` macht einen Container gültig. Wer den Vorgang vorher abbricht, hinterlässt Bruchstücke — aber nie ein Gebilde, das sich als vollständiges Backup ausgibt.

## Versionsverhandlung

Der Leser kennt `MinimumReadableVersion` und `MaximumReadableVersion`. Ein Container außerhalb dieser Spanne wird **nicht angetastet**, und die Meldung unterscheidet die Richtung:

- **zu neu** → „Bitte Syncova aktualisieren" (ein Update hilft)
- **zu alt** → Hinweis auf die Mindestversion (ein Update hilft nicht)

Ein falsch interpretiertes Backup ist schlimmer als ein nicht gelesenes.

## Erweiterbarkeit

Jeder Abschnitt trägt seine Länge. Eine spätere Programmversion darf deshalb neue Abschnitte ergänzen — eine ältere überspringt sie, ohne sie zu deuten.

Die Grenze zieht `FlagRequired`:

| Abschnitt | Verhalten einer älteren Version |
| --- | --- |
| unbekannt, optional | wird übersprungen, Container bleibt gültig |
| unbekannt, **erforderlich** | Verarbeitung wird **verweigert** |

Ohne diese Unterscheidung würde eine alte Version einen Container lesen, dem wesentliche Teile fehlen, und Vollständigkeit vortäuschen (PROMPT.md §140).

## Streaming und aufgeschobene Prüfsumme

Der Datenbereich kann beliebig groß werden und darf nie vollständig in den Arbeitsspeicher (PROMPT.md §80). Er wird deshalb als Datenstrom geschrieben — was einen Konflikt erzeugt:

> Die Prüfsumme eines Abschnitts steht erst fest, wenn er vollständig geschrieben ist. Sein Kopf ist zu diesem Zeitpunkt längst in der Ausgabe.

Der naheliegende Ausweg — den Kopf nachträglich überschreiben — verlangt eine rückspulbare Senke und schlösse Pipes und Netzwerkziele aus. Stattdessen trägt ein solcher Abschnitt `FlagDeferredDigest`: sein Kopf-Digest bleibt leer und wird beim Lesen nicht herangezogen.

**Es entsteht dadurch keine Prüflücke.** Die Unversehrtheit ist doppelt gesichert:

1. Jeder einzelne Chunk trägt seine Prüfsumme im Chunk-Verzeichnis; der Import prüft jeden Block gegen seine Kennung.
2. Die Gesamtprüfsumme im Footer deckt Header **und** alle Abschnittsinhalte ab.

## Was die Integritätsprüfung abdeckt

| Angriff / Fehler | Erkannt durch |
| --- | --- |
| Einzelnes Bit verfälscht | Abschnitts-Prüfsumme, sonst Gesamtprüfsumme |
| Container abgeschnitten | fehlender Footer |
| Abschnitt entfernt | Abschnittszahl im Footer |
| Abschnitt **samt passender Prüfsumme** ausgetauscht | Gesamtprüfsumme im Footer |
| Manifest ausgetauscht | Manifest-Hash im Footer |
| Abschlussvermerk auf `false` gesetzt | ausdrückliche Prüfung |
| Fremde Datei | Magic Bytes |

Prüfsummenvergleiche laufen in konstanter Zeit — eine Prüfsumme ist ein Sicherheitsmerkmal, kein bloßer Vergleichswert.

## Export und Import

```bash
syncova-repo export --path <repo> --backup <id> --out backup.syncova
syncova-repo inspect --in backup.syncova          # prüfen ohne einzulesen
syncova-repo import --path <ziel-repo> --in backup.syncova
```

**Export** liest jeden Chunk über `ReadChunk` — die Integritätsprüfung greift also, bevor ein Block in den Container gelangt. Fehlt ein Chunk oder ist er beschädigt, bricht der Export ab und das Kommando **löscht die angefangene Zieldatei**. Ein halber Container wäre eine Falle: er sähe aus wie ein Backup, wäre aber keines.

**Import** macht das Manifest erst sichtbar, **nachdem** alle Abschnitte, Prüfsummen und der Abschlussvermerk stimmen. Ein fehlgeschlagener Import hinterlässt allenfalls Chunks — nie ein scheinbar gültiges Backup. Bereits vorhandene Chunks werden dabei erkannt: dieselbe Deduplizierung wie beim Sichern.

**Inspect** liest den Container vollständig (und prüft damit alle Prüfsummen), ohne etwas zu schreiben. Der Exit-Status ist bei einem unbrauchbaren Container ungleich 0, damit ein Skript oder Monitoring daran anschlägt.

## Grenzen des aktuellen Stands

- **Chunks sind unkomprimiert und unverschlüsselt.** Die Felder `encryption` und `compression` sind bereits Teil des Header-Formats und überstehen die Rundreise — die Verarbeitung folgt in Phase 4. Eine spätere Ergänzung der Felder wäre ein Formatbruch, deshalb stehen sie jetzt schon dort.
- **Der Import lädt den Datenbereich vollständig in den Speicher.** Für Container jenseits weniger Gigabyte ist das nicht tragbar; der Weg über `ChunkIndexEntry.ContainerOffset` ist vorbereitet, aber noch nicht als Datenstrom umgesetzt.
- **Die Blockzuordnung (`SectionBlockMap`) ist definiert, wird aber noch nicht geschrieben.** Sie wird für Disk-Images gebraucht, bei denen logische Bereiche auf Chunks abgebildet werden müssen.
- **Kein Wiederaufsetzen einer abgebrochenen Übertragung.** Ein unvollständiger Container muss vollständig neu erzeugt werden.