105 lines
4.4 KiB
Markdown
105 lines
4.4 KiB
Markdown
# 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.
|