Skip to content

Commit ba048d3

Browse files
committed
docs(mla): add scaffold setup, IPC contract and verification gates
1 parent 4d5c441 commit ba048d3

3 files changed

Lines changed: 70 additions & 0 deletions

File tree

‎docs/mla-next/IPC_CONTRACT.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# MLA-Next IPC v1 — Entwurf, noch nicht implementiert
2+
3+
Ziel: unprivilegierter Dart-Host (`packages/la_core` nach Issue #59), GTK-Client. Unix-Domain-Socket in einem privaten Verzeichnis unter XDG_RUNTIME_DIR. Ein Host bindet; GTK und ein optionaler Flutter-Adapter sind Clients. Kein zweiter C-Server am selben Pfad.
4+
5+
## Wire
6+
7+
JSON-RPC 2.0 über UTF-8 JSONL: ein Objekt plus LF je Frame, maximal 65536 Bytes **vor** Parsing. Keine Batch-Requests in v1. `mla.hello` mit Protokollversion/Capabilities zuerst; danach `backup.list`, `backup.watch` und nur später `backup.startUserUnit`. Responses spiegeln die Request-ID; Notifications (`backup.statusChanged`) haben keine ID und keine Antwort.
8+
9+
Beispiel (nur Vertragsanregung, kein vorhandener Backend-Code):
10+
11+
```json
12+
{"jsonrpc":"2.0","id":"r1","method":"mla.hello","params":{"client":"mla-gtk","protocol":1}}
13+
{"jsonrpc":"2.0","id":"r1","result":{"server":"mla-core","protocol":1,"capabilities":["backup.list"]}}
14+
```
15+
16+
`backup.list` liefert `{revision,observedAt,jobs}`; Jobs tragen Unit-ID, Scope (`user|system`), Zustand (`ok|warn|crit|unknown`), Phase und redigierte Evidenz. `stale` ist UI-/Transportstatus, nicht stillschweigend `ok`. Event-Seq/Revisionslücken, Disconnect und Reconnect lösen vollständigen Snapshot-Neuabruf aus. Limitierte Schreibqueue, Timeouts, geordnete Writes und Schutz gegen doppelte Start-Requests gehören zum Implementierungsgate.
17+
18+
## Sicherheitsgrenze
19+
20+
Socket-Verzeichnis 0700, Socket 0600, Eigentümer und Peer-UID prüfen. SO_PEERCRED schützt nicht vor kompromittierten Prozessen derselben UID. Kein Shell-Execute- oder Root-Methodenname im Wire. Schreibende Aktionen erfordern serverseitig festgelegte Capabilities, erneut validierte erlaubte User-Unit, Nutzerbestätigung und Audit; System-Units bleiben lesend. Keine Tokens, Restic-Passwörter oder rohen Journalausgaben übertragen. Die vorhandene polkit-Grenze bleibt getrennt.
21+
22+
Standard-JSON-RPC-Fehler für Parsing/Request/Method/Parameter; definierte anwendungsspezifische Fehler für nicht verfügbar, verboten, beschäftigt und Timeout. Fehlerdaten nur Code, messageKey und retryable, keine Secrets. Ein Schema und positive/negative Contract-Fixtures sind ein eigenes späteres Task-Paket, nicht durch diesen Text als implementiert behauptet.

‎docs/mla-next/VERIFY.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# MLA-Next: Verifikation und Handoff
2+
3+
Stand dieses Branchs: keine hier dokumentierten GTK-Laufzeit-, Zorin-, IPC- oder Performance-Tests ausgeführt. Der Scaffold-Commit ist **kein** Release-Gate.
4+
5+
## Gate 0: Scaffold
6+
7+
- [ ] `python3 -m py_compile prototype/gtk/mla_app.py` grün, Ausgabe und Python-Version erfassen.
8+
- [ ] Auf Zorin OS 18.1 als normaler Nutzer starten; GTK4/libadwaita-Version, Wayland/X11 festhalten.
9+
- [ ] Dashboard, Monitor, Backup und Security anwählen; Titel, rechte Details und unbekannten Backup-Status prüfen.
10+
- [ ] Fenster verkleinern/vergrößern; Tastatur/Fokus, Hell/Dunkel, 100/125/150%-Skalierung prüfen.
11+
- [ ] App ohne Root, ohne Systemschreibfunktion, ohne Secrets in Screenshots/Logs.
12+
13+
## Gate 1: Kern/Registry
14+
15+
- [ ] Issue #59: `dart test` und `dart compile exe`; Probe ohne DISPLAY/WAYLAND_DISPLAY; Binärgröße/Startzeit messen.
16+
- [ ] Issue #60: IDs eindeutig, fehlende/zyklische Abhängigkeiten abgewiesen, Start/Stop/Lazy-Loading getestet; Flutter-Navigation unverändert.
17+
- [ ] Bestehende Repo-Gates nach Scope tatsächlich ausführen: `tool/check-versions.sh`, `dart format`, `flutter analyze`, `flutter test`, Python-Tests.
18+
19+
## Gate 2: IPC und Backup
20+
21+
- [ ] Frame-/UTF-8-/JSON-/Schema-/Timeout-/Reconnect-/Backpressure-Tests; falsche Peer-UID und Event-Lücke.
22+
- [ ] Issue #63: User-/System-Units, Timer, Journal-Fehler und Unknown/Stale mit Fixtures; keine Repo-/Passwortzugriffe.
23+
- [ ] `systemctl --user start` nur nach Bestätigung und serverseitiger Allowlist; Abbruch, Race und Doppel-Request prüfen.
24+
- [ ] Kein grünes Backup allein wegen eines erfolgreichen Unit-Starts; Restore separat beurteilen.
25+
26+
## Agenten-Handoff
27+
28+
Je Aufgabe: Basis-SHA, Pfade, Scope, Failing-Test/Fixture, Umsetzung, Ergebnis von Reviewer 1 (Funktion/UX) und Reviewer 2 (Sicherheit), **wirklich ausgeführte** Gates mit Ausgaben, rote/übersprungene Gates, manuelle Zorin-Prüfung, Rückfallplan. Kein Merge/Release/Policy-Update ohne gesonderte Freigabe.

‎prototype/gtk/README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# MLA GTK4-Prototyp
2+
3+
Isolierter, unprivilegierter UI-Spike auf `feature/mla-gtk-scaffold`. `mla_app.py` zeigt ausschließlich Demo-Daten. Kein IPC, keine echten Backup-/Security-Checks, keine Admin-Aktionen und keine Paketintegration. Der bestehende Flutter-Hub bleibt unverändert.
4+
5+
## Lokaler Start auf Zorin
6+
7+
Prüfe zuerst GTK4/libadwaita/PyGObject auf dem Zielsystem. Ubuntu-basierte Paketnamen sind typischerweise `python3-gi`, `gir1.2-gtk-4.0`, `gir1.2-adw-1`; nichts davon wird durch diesen Branch installiert. Danach im Repo:
8+
9+
```sh
10+
python3 -m py_compile prototype/gtk/mla_app.py
11+
python3 prototype/gtk/mla_app.py
12+
```
13+
14+
**Nicht mit sudo starten.** `py_compile` prüft nur Syntax. Die GUI braucht eine laufende Desktop-Session; Wayland, X11, Skalierung und Theme wurden von diesem Commit nicht verifiziert.
15+
16+
## Geplanter Aufbau
17+
18+
`mla_app.py` ist die minimale Shell mit NavigationSplitView, HeaderBar, vier Fixture-Screens und rechter Kontextfläche. Module, Services, Tests und IPC werden erst in getrennten, überprüften Arbeitspaketen ergänzt. `docs/mla-next/AGENT_PLAN.md` gibt Reihenfolge und Sicherheitsgrenzen vor; `docs/mla-next/IPC_CONTRACT.md` ist ein Wire-Entwurf; `docs/mla-next/VERIFY.md` beschreibt Gates.
19+
20+
Der frühere rsync-Democode aus der Unterhaltung gehört **nicht** zum produktiven Backup-Cockpit aus Issue #63 und wird hier nicht eingecheckt.

0 commit comments

Comments
 (0)