flemming-it
244ae4c219
Document installing the 8 published modules from chain-modules/reclaim (Forgejo-raw) and the 2026-06-22 fresh-hub verification: test-cohort green (cohort 180000) and durchstich-full running all 5 modules on real GewO XML (plausible deontic tuples + readability), pausing at the approval gate. Note durchstich-gewo-14 is blocked by http.request (chain bundled module, wasm_url 404). Signed-off-by: flemming-it <sf@flemming.it>
183 lines
7.4 KiB
Markdown
183 lines
7.4 KiB
Markdown
# Recl∆Im (F∆I) — Run-Guide (Phase 0)
|
||
|
||
> Stand v0.1.0 — Demo-Modus, ohne externe Daten, ohne Hub-Verbindung.
|
||
|
||
## Layout
|
||
|
||
```
|
||
fai_reclaim/
|
||
├── MACHBARKEITSSTUDIE.md # die Studie (v0.3, AG-intern)
|
||
├── RUN.md # diese Datei
|
||
├── app/ # Flutter-Client, Brand-Skin fai_web
|
||
│ ├── lib/ # Dart-Code (Pages, Widgets, Data, Theme)
|
||
│ ├── assets/
|
||
│ │ ├── fonts/ # SIL-OFL TTFs (setup.sh holt sie)
|
||
│ │ └── fixtures/ # Phase-0 Demo-Daten
|
||
│ ├── macos/ # Plattform-Scaffolds (auto-generiert)
|
||
│ ├── setup.sh # Fonts + Pakete
|
||
│ └── pubspec.yaml
|
||
└── flows/
|
||
└── durchstich-gewo-14.yaml # vertikaler Phase-0-Flow
|
||
```
|
||
|
||
Die acht zugehörigen Module liegen unter `fai_chain_modules/` als
|
||
eigene Crate-Verzeichnisse, ABI `chain:platform`, alle Apache 2.0:
|
||
|
||
- `text-akoma-normalize/` (Pflicht-Eingang, gesetze-im-internet-XML-Adapter)
|
||
- `text-deontic-extract/` (Pflicht-Tupel via Regex + LLM-Vorschlag im Flow)
|
||
- `graph-citation-extract/` (`cites`, `verweist_iVm`)
|
||
- `text-readability-score/` (Flesch-DE + Verweistiefe)
|
||
- `stats-cohort-size/` (DESTATIS-/IHK-Kohorten, Phase 0 mit Stub-Tabelle)
|
||
- `graph-shapley-attribution/` (Pfad-anteilige Splittung)
|
||
- `econ-skm-score/` (Standardkostenmodell P×F×T×h)
|
||
- `law-benefit-score/` (7-dim. Nutzen-Aggregation — das einzige genuin
|
||
domänen-spezifische Modul, gehört in `chain-modules-law/`)
|
||
|
||
## Sofort starten (Demo-UI, kein Hub nötig)
|
||
|
||
```bash
|
||
cd app
|
||
./setup.sh # Fonts + flutter pub get
|
||
./build-macos.sh # Robust-Build (strippt macOS-xattrs vor CodeSign)
|
||
open build/macos/Build/Products/Debug/reclaim_app.app
|
||
```
|
||
|
||
Direkter `flutter run -d macos` funktioniert auch, kann aber bei
|
||
einem frischen Checkout an `com.apple.provenance`-xattrs scheitern
|
||
(macOS-Eigenheit bei via curl/iCloud erstellten Dateien) — dann
|
||
einmal `./build-macos.sh` und danach `flutter run -d macos`.
|
||
|
||
Erwartet: Brand-Landing → Klick auf „App öffnen" →
|
||
NavigationRail (Heatmap / Normen / Freigaben / Hub / Methodik / Recht)
|
||
mit fünf Pilot-Norm-Punkten. Default ist der **Live-Hub-Modus**
|
||
(läuft ein `chain serve` auf 127.0.0.1:50051, werden die fünf Normen
|
||
live ausgewertet — `submit` pro Norm, echte skm/benefit-Achsen). Ohne
|
||
Hub bzw. mit Demo-Toggle im Hub-Reiter: die fünf Fixtures mit
|
||
T4-Demo-Banner.
|
||
|
||
Test-Suite (smoke):
|
||
```bash
|
||
flutter test
|
||
```
|
||
|
||
## Web-Variante (gleiche Codebase, ein Befehl)
|
||
|
||
```bash
|
||
cd app
|
||
./serve-web.sh # baut + serviert auf http://127.0.0.1:8080
|
||
```
|
||
|
||
Funktioniert im Demo- **und** im Live-Hub-Modus: die SDK wählt per
|
||
conditional import den `GrpcWebClientChannel`, sodass der Browser
|
||
denselben Hub auf 127.0.0.1:50051 erreicht (verifiziert: „App öffnen"
|
||
feuert 5× `Submit` über gRPC-Web). Der Hub muss gRPC-Web anbieten —
|
||
`chain serve` tut das auf einer Loopback-Bindung von Haus aus.
|
||
|
||
Produktion: build/web/ auf einen statischen Host kippen
|
||
(F∆I-Pattern: Hetzner-CX + Caddy mit Auto-HTTPS, analog
|
||
`fai_chain` Release-Host). DNS: `reclaim.flemming.ai`.
|
||
|
||
## Hub-Smoke-Test (chain serve läuft separat)
|
||
|
||
Wenn ein `chain serve` lokal auf 127.0.0.1:50051 läuft (vom
|
||
fai_chain-Setup):
|
||
|
||
1. App starten, „Hub"-Reiter öffnen
|
||
2. Host/Port stehen schon, „Hub beim Start nutzen" anschalten
|
||
3. „Verbindung testen" → erwartet `healthy=true`
|
||
4. Falls capabilities installiert sind: „Installierte
|
||
Capabilities" listet sie auf
|
||
5. Der Heatmap-Tab füllt sich automatisch live: `HubRepository.list()`
|
||
führt pro Pilot-Norm den `reclaim-evaluate`-Flow via `submit()` aus
|
||
(json-Inputs für skm/benefit) und mappt `SubmitResponse.outputs`
|
||
(norm/skm/benefit/frust/cohort/duties) in Evaluation-Objekte. Kein
|
||
manuelles `chain run` nötig — die App treibt die Flows selbst. (Der
|
||
Audit-Log speichert keine Outputs, nur Hashes; daher der
|
||
submit-Pfad statt eventLog.) Offene `system.approval`-Aufgaben
|
||
erscheinen separat im „Freigaben"-Reiter zur juristischen Bestätigung.
|
||
|
||
## Modul-Tests (lokal grün ohne Hub)
|
||
|
||
```bash
|
||
for m in text-akoma-normalize text-deontic-extract \
|
||
graph-citation-extract text-readability-score \
|
||
stats-cohort-size graph-shapley-attribution \
|
||
econ-skm-score law-benefit-score; do
|
||
(cd ../fai_chain_modules/$m && cargo test) || break
|
||
done
|
||
```
|
||
|
||
## WASM-Build (für `chain install`)
|
||
|
||
```bash
|
||
cd ../fai_chain_modules/text-akoma-normalize
|
||
cargo build --release --target wasm32-wasip2
|
||
# Artefakt: target/wasm32-wasip2/release/text_akoma_normalize.wasm
|
||
```
|
||
|
||
Selber Aufruf für die anderen sieben Verzeichnisse.
|
||
|
||
## Live-Flow (Default, sobald `chain serve` läuft)
|
||
|
||
```bash
|
||
chain serve &
|
||
chain install text.akoma-normalize text.deontic-extract \
|
||
graph.citation-extract text.readability-score \
|
||
stats.cohort-size graph.shapley-attribution \
|
||
econ.skm-score law.benefit-score \
|
||
http.request system.approval
|
||
chain run flows/durchstich-gewo-14.yaml \
|
||
--input norm_url=https://www.gesetze-im-internet.de/gewo/__14.xml \
|
||
--input cohort_id=berlin-kmu
|
||
chain admin events --limit 10
|
||
chain admin approvals list # Juristen-Gate
|
||
```
|
||
|
||
Im Flutter-Client den `MockRepository` durch eine `HubRepository`
|
||
(gRPC gegen `localhost:50051`) ersetzen — Interface bleibt gleich,
|
||
keine UI-Änderung nötig.
|
||
|
||
## Live über den Store
|
||
|
||
Die 8 Recl∆Im-Module sind publiziert unter
|
||
`chain-modules/reclaim` (Forgejo-raw, `.chain`-Bundles, unsigniert) und
|
||
lassen sich ohne lokalen WASM-Build direkt aus dem Store installieren:
|
||
|
||
```bash
|
||
chain store add "Recl∆Im" \
|
||
https://git.flemming.ai/chain-modules/reclaim/raw/branch/main/store.yaml
|
||
chain store refresh # fetcht den Store (8 Module)
|
||
chain store search # die 8 Capabilities erscheinen als `pub`
|
||
chain install stats.cohort-size text.akoma-normalize \
|
||
text.deontic-extract graph.citation-extract \
|
||
text.readability-score # Download von den Forgejo-raw-URLs
|
||
```
|
||
|
||
Capability-IDs sind **Dash-Form** (`econ.skm-score`, `law.benefit-score`, …);
|
||
der Store-`name:` entspricht exakt der gebündelten `provides.capability`.
|
||
|
||
**End-to-End verifiziert (2026-06-22, frischer isolierter Hub via Temp-`HOME`):**
|
||
|
||
- `chain run flows/test-cohort.yaml --input cohort_id=berlin-kmu`
|
||
→ grün, `cohort.count = 180000` (DESTATIS, Tier T1).
|
||
- `chain run flows/durchstich-full.yaml --input content=@gewo.xml --input cohort_id=berlin-kmu`
|
||
→ alle 5 Module laufen (`normalize → deontic → citations → cohort → frust`),
|
||
Flow pausiert am `system.approval`-Gate (Soll). Auf echter GewO-XML liefert
|
||
die Pipeline plausible deontische Tupel (OBLIGATION/PERMISSION, Confidence
|
||
0.7–0.85) und Lesbarkeit (`flesch_de ≈ 35`, `composite_frust ≈ 3.8`).
|
||
|
||
> GewO-Volltext-XML: `https://www.gesetze-im-internet.de/gewo/xml.zip`
|
||
> (die per-§-URL `…/gewo/__14.xml` liefert inzwischen 404).
|
||
> `durchstich-gewo-14.yaml` braucht zusätzlich `http.request` — dieses
|
||
> bundled-Modul ist derzeit nicht installierbar (chain-seitige `wasm_url`
|
||
> liefert 404; Handoff an chain offen). Nutze solange `durchstich-full`
|
||
> mit `--input content=@<norm>.xml`.
|
||
|
||
## Was Phase 0 NICHT enthält (bewusst)
|
||
|
||
- gRPC-Anbindung Flutter ↔ Hub (Woche 1)
|
||
- Echte NKR-Datenbank-Anbindung (Woche 2-3)
|
||
- DESTATIS GENESIS-API-Adapter (Woche 4)
|
||
- Juristen-Approval-Backend-Anbindung (Woche 5)
|
||
- Volle Akoma-Ntoso-Konvertierung (v0.2)
|
||
- HTML- und FORMEX-Adapter für `text.akoma-normalize` (v0.2/0.3)
|