# D1/D2 — Canonical Schema Contract & Fingerprint Tooling (SoT)

**Status:** FORMALLY PERSISTED — authoritative origin/main
**Datum:** 2026-09-08
**Verdict:** D1+D2 FORMALLY PERSISTED TO AUTHORITATIVE SOT

---

## 1. Zweck

Dieses Verzeichnis materialisiert den **CURRENT VERIFIED PRODUCTION SCHEMA CONTRACT (L0)**
als kanonische, deterministisch fingerprintbare Autorität. Es ist das Ergebnis der
D1/D2-Remediation (Schema-Contract + deterministischer Fingerprint) und wurde durch den
unabhängigen D1+D2-Checker mit **Verdict A** bestätigt.

## 2. Canonical Fingerprint

```
b49f64337ffafc0e73d46e009aa802cd0172d59421b7df61d3eb198775c1986d
```

Dieser Fingerprint ist deterministisch (H1==H2==H3), sensitiv auf alle semantischen
Schema-Änderungen (type, nullable, default, PK, UNIQUE, FK, CHECK, index), und fail-closed.

## 3. DR-Reproducibility (ehrlich getrennt)

| Aspekt | Status |
|--------|--------|
| **CURRENT-STATE SCHEMA REPRODUCIBLE FROM L0** | **YES** — frische DB aus L0-SQL rekonstruiert, REBUILT_HASH == PRODUCTION_HASH == b49f6433…, Semantic-Diff TOTAL_MISMATCH=0 |
| **HISTORICAL EVOLUTION REPRODUCIBLE** | **NO** — historische DDL-Chronologie (Wave1→WaveD→Closure) bleibt nicht aus L0 rekonstruierbar |

Der L0-Contract beansprucht ausschliesslich **CURRENT PRODUCTION TRUTH**, nicht historische
Migrationschronologie. Historische Artefakte bleiben immutable.

## 4. Canonical Contract Semantics

| Tabelle | Spalten |
|---------|---------|
| historical_bar | 41 |
| derived_bar | 35 |
| data_ingestion_run | 29 |
| dataset_version | 23 |
| ingestion_provenance | 41 |

**Semantic Overrides (Owner-Canonical):**
- `last_successful_chunk` = **timestamp with time zone / timestamptz** (Production + Owner-Entscheidung)
- `interrupt_reason` = **text** · PRESERVED · origin unknown · do not remove
- `technical_quality` = **text** · nullable · default `'VALID'`

## 5. Historische Wahrheit (nicht rückwirkend ändern)

- **WaveD historisches Artefakt:** `last_successful_chunk = text` (immutable Evidence)
- **Owner/current canonical contract:** `last_successful_chunk = timestamptz`
- Historische Artefakte: Wave1 `6983526da3ca51fd2ececffbef0ccbd66b048a3d11c228000011aaba3e1d6bc5`,
  WaveD `7aa4e2a10c98fa327e000a49f6a497efb5814c8808dba429dfebfc90c544a02b`,
  Closure `e56567f7cfae68da70c11ece6f576e974488f343` — **unverändert**.

## 6. Open Debts (nicht fälschlich geschlossen)

| Debt | Status |
|------|--------|
| **Debt A** — Current-state DR/schema reproducibility gap | **CLOSED** by D1/D2 |
| **Debt A** — Historical DDL evolution provenance gap | **REMAINS OPEN** |
| **Debt B** — interrupt_reason origin unknown | **OPEN** (non-blocking) |
| **Debt C** — WaveD text vs current Owner-canonical timestamptz | **OPEN** (non-blocking) |

## 7. SoT-Layout

```
d1d2-schema-contract/
├── SCHEMA_AUTHORITY.md          # dieses Dokument
├── contract/
│   ├── historical_v2_schema.sql     # L0-Schema-Contract (schema-only)
│   ├── historical_v2_schema.json    # maschinenlesbares kanonisches Modell
│   ├── historical_v2_schema.sha256  # deterministischer Fingerprint
│   └── README.md                    # Contract-Dokumentation
└── tools/
    ├── canonical_schema.py      # Kanonisierungs-Implementierung
    ├── capture_schema.py        # Capture-Parser (read-only)
    ├── compare_schema.py        # Semantic-Diff-CLI
    ├── fingerprint_schema.py    # Fingerprint-CLI
    └── gen_l0_sql.py            # L0-SQL-Generator
```

**Nicht persistiert:** Maker-Evidence, Checker-Evidence, temporäre DBs, /tmp-Dateien,
raw Scratch Outputs, runtime-spezifische Dateien, Credentials/Secrets, Transport-Manifeste,
`gen_evidence.py` (enthält hardcodierte Maker-Pfade, nicht environment-neutral).

## 8. Tooling-Nutzung

```bash
# Fingerprint aus machine contract
python3 tools/fingerprint_schema.py contract/historical_v2_schema.json
# → b49f64337ffafc0e73d46e009aa802cd0172d59421b7df61d3eb198775c1986d

# Semantic-Diff (expected vs actual)
python3 tools/compare_schema.py contract/historical_v2_schema.json <actual_model.json>
# → TOTAL_MISMATCH=0 bei Übereinstimmung; Exit 1 bei Drift (fail-closed)

# L0-SQL generieren
python3 tools/gen_l0_sql.py contract/historical_v2_schema.json --out /tmp/l0.sql
```

Alle Tools sind environment-neutral (keine absoluten Pfade, keine DB-Credentials,
keine mutierenden Production-SQL-Pfade). Read-only.