From 202b86aa723cab7ed7db176c187e0cedf3ba48d0 Mon Sep 17 00:00:00 2001 From: jan Date: Mon, 20 Apr 2026 17:39:21 +0200 Subject: [PATCH] Add Qwen 14B handoff documentation --- README.md | 1 + docs/qwen14b_handoff.md | 151 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 152 insertions(+) create mode 100644 docs/qwen14b_handoff.md diff --git a/README.md b/README.md index 77afbae..33f274c 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,7 @@ The current baseline is intentionally strict about unresolved hardware facts. `U - [Architecture](docs/architecture.md) - [Host API](docs/host_api.md) - [Local Software-Only Runbook](docs/local_software_only_runbook.md) +- [Qwen 14B Handoff](docs/qwen14b_handoff.md) - [Show-Control Primitives](docs/show_control_primitives.md) - [Pattern Matrix v1](docs/pattern_matrix_v1.md) - [External Control Bridge](docs/external_control_bridge.md) diff --git a/docs/qwen14b_handoff.md b/docs/qwen14b_handoff.md new file mode 100644 index 0000000..48f3f51 --- /dev/null +++ b/docs/qwen14b_handoff.md @@ -0,0 +1,151 @@ +# Qwen 14B Handoff + +## Zweck + +Diese Datei ist die schnelle Uebergabe fuer ein kleineres Modell wie Qwen 14B. Sie soll den aktuellen Projektstand, die stabile Architekturgrenze und die naechsten sicheren Arbeitspfade kompakt erklaeren, ohne dass zuerst das ganze Repo rekonstruiert werden muss. + +## Aktueller Stand + +- Host-Core ist die zentrale Runtime und bleibt die einzige Kernarchitektur. +- API v1 ist die verbindliche Aussenkante fuer State, Preview, Snapshot, Catalog, Commands und Event-Stream. +- Die Creative Surface lebt in `web/v1/` und ist die operatorische Web-Oberflaeche. +- Die Desktop-GUI in `crates/infinity_host_ui/` bleibt die technische Engineering-/Diagnoseoberflaeche. +- Persistenz, Recovery und Runtime-Show-Store sind vorhanden. +- Show-Control-v1-Primitive sind faktisch eingefroren und dokumentiert. +- Ein generischer externer Control-Pfad ist vorhanden, aber bewusst nicht grandMA-spezifisch. + +## Nicht neu interpretieren + +Diese Grenzen sind verbindlich: + +- keine neue Parallelarchitektur neben Host-Core plus API +- keine direkte grandMA-Kopplung in den Kern +- keine Hardwarevalidierung als Hauptfokus +- Creative Surface bleibt kreative/operatorische Oberflaeche +- Desktop-GUI oder Technical Surface bleibt technische Betriebsoberflaeche + +Wenn Verhalten unklar ist, gilt: + +1. erst alte Referenz dokumentarisch vergleichen +2. dann an bestehende Host-/API-Semantik anpassen +3. nicht stillschweigend neue Bedienlogik erfinden + +## Wo der Arbeitsfortschritt festgehalten ist + +Die wichtigsten Fortschrittsanker liegen hier: + +- [README.md](/home/jan/Documents/RFP/Infinity_Vis_Rust/README.md:1) + Der Einstieg, grobe Struktur und verlinkte Referenzdokumente. +- [docs/show_control_primitives.md](/home/jan/Documents/RFP/Infinity_Vis_Rust/docs/show_control_primitives.md:1) + Die stabile interne Show-Control-v1-Semantik inklusive staged/direct-Trennung, Fehlercodes und Event-Auswirkungen. +- [docs/pattern_matrix_v1.md](/home/jan/Documents/RFP/Infinity_Vis_Rust/docs/pattern_matrix_v1.md:1) + Alter Python-Bezug versus neue Host-Pattern-IDs, Parameterbasis und UI-Arbeitsmodi. +- [docs/external_control_bridge.md](/home/jan/Documents/RFP/Infinity_Vis_Rust/docs/external_control_bridge.md:1) + Zielbild und Regeln fuer die generische externe Steuerkante. +- [docs/control_ownership.md](/home/jan/Documents/RFP/Infinity_Vis_Rust/docs/control_ownership.md:1) + Konflikt- und Ownership-Regeln zwischen Web-UI, technischer GUI und externen Control-Quellen. +- [docs/local_software_only_runbook.md](/home/jan/Documents/RFP/Infinity_Vis_Rust/docs/local_software_only_runbook.md:1) + Reproduzierbarer software-only Startpfad. +- [crates/infinity_host/tests/show_control_v1_golden.rs](/home/jan/Documents/RFP/Infinity_Vis_Rust/crates/infinity_host/tests/show_control_v1_golden.rs:1) + Golden-Trace- und Replay-Schutz fuer die zentrale v1-Semantik. +- Git-Historie: + - `a56cecb` `Software-only show-control readiness baseline` + - `07c52db` `Stabilize control surface and external bridge v1` + +## Projektstruktur + +- `crates/infinity_host/` + Kernruntime, Simulation, Show-Store, Pattern-Logik, externe Control-Semantik. +- `crates/infinity_host_api/` + HTTP- und WebSocket-API v1, DTO-Mapping, Contract-Tests. +- `crates/infinity_host_ui/` + Desktop-Engineering-Oberflaeche fuer technische Konfiguration und Diagnose. +- `crates/infinity_config/` + Projektkonfiguration und Validierung. +- `crates/infinity_protocol/` + Gemeinsame Protokoll- und Modelltypen. +- `web/v1/` + Creative Surface und Technical Surface im Browser. +- `docs/` + Architektur-, Runbook-, Ownership-, Pattern- und API-Dokumentation. +- `scripts/` + Kleine Starthelfer fuer lokalen software-only Betrieb. +- `data/runtime_state.json` + Laufzeitpersistenz fuer Host-State, Runtime-Presets, Gruppen und Snapshots. + +## Wichtigste Dateien nach Thema + +### Host und Semantik + +- [control.rs](/home/jan/Documents/RFP/Infinity_Vis_Rust/crates/infinity_host/src/control.rs:1) +- [simulation.rs](/home/jan/Documents/RFP/Infinity_Vis_Rust/crates/infinity_host/src/simulation.rs:1) +- [show_store.rs](/home/jan/Documents/RFP/Infinity_Vis_Rust/crates/infinity_host/src/show_store.rs:1) +- [scene.rs](/home/jan/Documents/RFP/Infinity_Vis_Rust/crates/infinity_host/src/scene.rs:1) +- [external_control.rs](/home/jan/Documents/RFP/Infinity_Vis_Rust/crates/infinity_host/src/external_control.rs:1) +- [external_bridge.rs](/home/jan/Documents/RFP/Infinity_Vis_Rust/crates/infinity_host/src/external_bridge.rs:1) + +### API + +- [dto.rs](/home/jan/Documents/RFP/Infinity_Vis_Rust/crates/infinity_host_api/src/dto.rs:1) +- [server.rs](/home/jan/Documents/RFP/Infinity_Vis_Rust/crates/infinity_host_api/src/server.rs:1) +- [websocket.rs](/home/jan/Documents/RFP/Infinity_Vis_Rust/crates/infinity_host_api/src/websocket.rs:1) +- [contract.rs](/home/jan/Documents/RFP/Infinity_Vis_Rust/crates/infinity_host_api/tests/contract.rs:1) + +### Web-UI + +- [index.html](/home/jan/Documents/RFP/Infinity_Vis_Rust/web/v1/index.html:1) +- [app.js](/home/jan/Documents/RFP/Infinity_Vis_Rust/web/v1/app.js:1) +- [styles.css](/home/jan/Documents/RFP/Infinity_Vis_Rust/web/v1/styles.css:1) +- [technical.html](/home/jan/Documents/RFP/Infinity_Vis_Rust/web/v1/technical.html:1) +- [technical.js](/home/jan/Documents/RFP/Infinity_Vis_Rust/web/v1/technical.js:1) + +## Was aktuell als stabil gelten soll + +- API v1 nach aussen nicht unkoordiniert brechen. +- Show-Control-v1-Primitive nicht still veraendern. +- Fehlercodes und Event-Semantik nicht neu mischen. +- `Test/Edit` bleibt direkt. +- `Show/Event` bleibt staged plus Commit ueber `Go` oder `Fade Go`. +- Preview-Only und Offline-Status ehrlich anzeigen, keine Fake-Nodes. +- Creative Surface nicht mit technischen Mapping-Details ueberladen. + +## Sichere Arbeitsreihenfolge fuer weitere Aenderungen + +1. Zuerst relevante Docs lesen, nicht direkt Code uminterpretieren. +2. Dann Contract-Tests und Golden-Replays als Schutzplanken ansehen. +3. Danach gezielt nur in der betroffenen Schicht arbeiten: + - Pattern-/Runtime-Logik: `crates/infinity_host/` + - API-Vertrag: `crates/infinity_host_api/` + - Operator-UI: `web/v1/` +4. Danach passende Tests laufen lassen. + +## Empfohlene Minimalpruefungen + +```bash +. "$HOME/.cargo/env" +cargo test -q -p infinity_host +cargo test -q -p infinity_host_api --test contract +``` + +Fuer lokalen software-only Start: + +```bash +. "$HOME/.cargo/env" +cargo run -p infinity_host_api -- --config config/project.example.toml --bind 127.0.0.1:9001 --runtime-state data/runtime_state.json +``` + +## Offene Vorsichtspunkte + +- Das alte Python-Projekt ist derzeit nicht lokal neben dem Repo ausgecheckt. Fuer echte 1:1-Conformance-Vergleiche sollte es bewusst lokal daneben geklont werden. +- Das Runbook enthaelt noch einen veralteten Hinweis aus der frueheren Arbeitsbaum-Phase; aktuell ist das Repo wieder ein echter Git-Clone mit `.git`. +- Die grosse Pattern-Conformance gegen das alte Python-Projekt ist noch nicht vollstaendig als separater, systematischer Abgleich abgeschlossen. + +## Kurzbriefing fuer das naechste Modell + +Wenn du dieses Projekt weiterbearbeitest: + +- halte Host-Core plus API als einzige Grundarchitektur stabil +- behandle die bestehende Show-Control-v1-Semantik als Aussenkante +- nimm das alte Python-Projekt als Primarreferenz fuer UX und Pattern-Verhalten, nicht fuer technische Architektur +- veraendere diskrete UI-Controls, Fehlercodes oder staged/direct-Semantik nicht stillschweigend +- bevor du groessere UI- oder Pattern-Aenderungen machst, vergleiche erst gegen die vorhandenen Docs und Tests