ADR · ADR-0003 · v1.1.0

Artifact Naming, SHA256 and Symlink Strategy

accepted v1.0.0 accepted 2026-02-24 Authors: david.sorf Created: 2026-02-24 Updated: 2026-04-09

artifact naming sha256 symlinks integrity

Každý dump artifact je pojmenován timestampem a run ID, doplněn SHA256 checksumem a metadata sidecar souborem. Symlinky latest.dump a meta.latest.json zajišťují rychlý přístup na poslední artefakt bez prohledávání adresáře.

Related docs:

Kontext

Je potřeba:

auditovatelná historie dumpů (více verzí per databáze)
rychlý přístup na nejnovější artefakt bez prohledávání adresáře
ověřitelnost integrity každého dumpu
jednoznačná identifikace artefaktu s konkrétním runem

Zvažované alternativy pro pojmenování:

A) Prostý timestamp bez run ID — kolize při vícenásobném runu ve stejné minutě

B) <run_ts>__<run_id> prefix (zvoleno) — unikátní, seřaditelné, auditovatelné

C) Hash obsahu jako název — ztrácí se časová informace, hůř čitelné

Rozhodnutí

✓ Chosen: B — timestampovaný název s run ID prefixem, SHA256 sidecar, symlinky na latest

Naming schema:

Dump: <run_ts>__<run_id>.dump
Checksum sidecar: <run_ts>__<run_id>.sha256
Metadata sidecar: <run_ts>__<run_id>.meta.json

Symlinky per DB adresář:

latest.dump → poslední dump soubor
meta.latest.json → poslední metadata soubor

SHA256: hash binárního obsahu dump souboru. Slouží pro:

1. Ověření integrity přenosu

2. Detekci duplicitního obsahu (ADR-0005 — skip if same SHA)

3. První level restore validace — při stažení dumpu z restic/storage serveru je SHA256 první kontrolou že dump je kompletní a nepoškozený. Bez uloženého SHA256 nelze tento krok automatizovat. Viz TODO: Restore testing ADR.

Symlinky jsou atomicky přepsány po každém úspěšném runu — vždy ukazují na validní artefakt.

Důsledky

Pozitivní:

Jasná identifikace artefaktu s konkrétním runem — každý soubor je jednoznačně dohledatelný
Rychlý přístup na latest přes symlink — bez ls/sort
Integrita ověřitelná offline: sha256sum -c <run_ts>__<run_id>.sha256
Základna pro deduplikaci (ADR-0005) a change detection (ADR-0006)
SHA256 umožňuje automatizovanou restore validaci (Level 1: stáhni dump, ověř hash — viz TODO Restore testing ADR)

Negativní:

Při častých runech roste počet dump artefaktů bez dalšího lifecycle kroku — nutný prune (ADR-0009, db_bkup_prune_local_after_restic.sh)
[TODO] Stejný problém nastane i pro JSON run history soubory (meta/inventory/*.json, meta/db/**/*.json) — přibývají s každým runem a aktuálně nemají vlastní prune/archivační mechanismus. Toto musí být řešeno v dalších krocích — buď sdíleným retention modelem s dump soubory, nebo samostatnou archivační politikou (např. komprimovat a archivovat history starší než N dní). Viz DS-0001 § roadmap.
Symlinky mohou být zmatoucí v prostředích kde nejsou standardně podporovány (Windows)

Changelog

Version	Date	Author	Note
1.1.0	2026-04-09	david.sorf + claude-sonnet-4-6	Rozšířeno rationale SHA256 o Level 1 restore validaci (stáhnout dump, ověřit hash = první automatizovatelný restore test). Přidán TODO do důsledků: JSON run history soubory (meta/inventory/, meta/db/) nemají vlastní prune/archivační mechanismus — musí být řešeno v dalším kroku, kandidát na samostatnou ADR nebo rozšíření DS-0001 roadmap.
1.0.0	2026-04-09	david.sorf + claude-sonnet-4-6	Migrace z doc/ADR/ADR-0003-artifact-naming-hash-symlinks.md do DAK JSON formátu. Rozšířeno o alternativy A/B/C, detail symlink atomicity a vazby na ADR-0005 a ADR-0006.