UmbrelApps/Docs/Plannen/Actief/003-Testclient/PLAN.md

# Testclient - plan

> **App: Evolu Relay.** Promotie op 09-09-2026, dezelfde dag als het masterplan geschreven werd, op
> verzoek van de gebruiker. Taken staan in [TAKEN.md](TAKEN.md), voortgang in [PROGRESS.md](PROGRESS.md),
> open punten in [OPEN.md](OPEN.md).
>
> Afhankelijk van: niets. De relay draait sinds 28-08-2026 en de haken die dit plan beproeft bestaan al.

## 1. Doel

Een eigen cliënt waarmee je meerdere eigenaars kunt aanmaken, ze op de relay kunt laten verbinden en er
gegevens doorheen kunt duwen, om het toegangsbeleid en de opslag te beproeven zonder Trezor Suite en zonder
hardware.

Aanleiding: Suite is vandaag de enige cliënt, en die vraagt een apparaat dat aan het toestel kan (zie
[Upstream-evolu-relay.md](../../Referenties/Upstream-evolu-relay.md) §9). Daardoor rust een deel van wat we
over deze app opschrijven op redenering in plaats van op een proef. Het scherpste voorbeeld staat in §10 van
datzelfde document: blokkeren werkt pas bij de volgende verbinding. Dat is uit de broncode afgeleid en nooit
gezien.

## 2. Afbakening

Een programma dat buiten de Umbrel draait, op de laptop, en dat via de gepubliceerde relay-poort verbindt.
Meerdere eigenaars naast elkaar, elk met een eigen sleutelmateriaal en een eigen lokale database. Eén
bedieningsvlak waarin je die eigenaars ziet en aanstuurt.

## 3. Niet-doelen

- **Geen tweede relay en geen wijziging aan de app.** Als dit plan een aanpassing in `tools/evolu-relay/`
  nodig lijkt te hebben, is dat een aanwijzing dat er iets misgaat in de opzet, niet een taak. De relay
  wordt beproefd zoals hij draait.
- **Geen ontcijfering van gegevens van Trezor Suite.** De cliënt maakt eigen sleutels en leest zijn eigen
  gegevens. Wat Suite op de relay zet blijft onleesbaar, en dat is de belofte in het manifest. Zie
  `CLAUDE.md`, "Zet geen ontcijfering in deze app", en §11 van het naslagdocument.
- **Geen onderdeel van de app store.** Dit is gereedschap in `tools/` en het gaat nooit in een image of in
  een app-map mee.
- **Geen nabouw van het protocol.** Net als bij de relay geldt: `@evolu/common` doet het werk, wij roepen
  het aan.

## 4. Ontwerp

### 4a. Een eigenaar is een mnemonic plus een eigen map

Evolu leidt een `AppOwner` af uit een mnemonic. Een tweede eigenaar is dus niets anders dan een tweede
mnemonic met een eigen SQLite-bestand ernaast; er is geen accountbegrip dat gedeeld moet worden. De cliënt
bewaart per eigenaar een map met de mnemonic en de database, onder een pad dat in `.gitignore` staat.

Dat sleutelmateriaal is van deze proefopstelling en heeft geen waarde buiten de relay, maar het blijft
sleutelmateriaal: het staat niet in de repo en het wordt niet in een logregel afgedrukt. Het `OwnerId` wel,
want dat is publiek en je hebt het nodig om de eigenaar op de statuspagina terug te vinden (§1b van het
naslagdocument).

### 4b. Eén bedieningsvlak voor de cliënt

**Alles wat de cliënt doet, gebeurt vanuit één scherm.** Geen losse opdrachten per eigenaar en geen tweede
terminal ernaast: je ziet de eigenaars in een lijst en bedient ze daar. Wat dat scherm kan:

| Onderdeel | Wat je ziet of doet |
|-|-|
| De lijst | per eigenaar zijn naam, zijn `OwnerId`, of hij verbonden is, wanneer er voor het laatst iets over de lijn ging, en hoeveel er geschreven is |
| Per eigenaar | aanmaken, verbinden, verbreken, een blob schrijven met een instelbare omvang, teruglezen, en weggooien |
| Het log | wat er per verbinding gebeurt, met tijdstip. Dit is waar de proeven uit §4c af te lezen zijn |
| De relay | het adres waarmee verbonden wordt, en of hij een verbinding aanneemt |

Vorm: een kleine HTTP-server in hetzelfde proces met één pagina ervoor, in de stijl van de statuspagina's
van beide apps. Geen bouwstap en geen framework; die pagina's laten zien dat dat hier genoeg is. De
opdrachtregel blijft eronder bestaan, want stap 2 van §5 heeft hem toch nodig en het is prettig om een proef
te kunnen scripten.

**Aan de server-app wordt niets gedaan.** Bevestigd door de gebruiker op 09-09-2026: die draait en
synchroniseert met Trezor Suite op de Mac. Dit plan raakt `tools/evolu-relay/` dus niet, en een bevinding
uit §4c is materiaal voor **Umbrelapp**, geen taak hier.

**Eén grens om te kennen voordat iemand er knoppen bij wil zetten:** de leerstand openzetten, blokkeren en
labelen kán deze UI niet, en dat is de poortindeling van de app en geen tekortkoming van het gereedschap.
De relay publiceert hostpoort 3852 en daar praat de cliënt mee, maar de agent-API (`GET /api/status`,
`POST /api/command`, `POST /api/label`) hangt achter `app_proxy` met de inlog van umbrelOS, en poort 8000
staat niet op de host. Dat blijft dus op de statuspagina van de app, in een tweede tabblad. Het omzeilen
daarvan zou een onbeschermde poort vragen, en dat haalt precies de bescherming weg waarvoor de poorten in
0.0.2 omgedraaid zijn (`CLAUDE.md`, "De poorten staan omgekeerd ten opzichte van wat je verwacht").

### 4c. Wat er dan te beproeven valt

Dit is de eigenlijke opbrengst, en elk punt is vandaag niet te proberen:

| Proef | Wat er hoort te gebeuren | Waar het vandaan komt |
|-|-|-|
| Onbekende eigenaar, venster dicht | HTTP 401, socket dicht, niets in de database van de relay, wel een regel in de weigerlijst | §10 van het naslagdocument, afgeleid uit de broncode |
| Diezelfde eigenaar toelaten en opnieuw verbinden | de hele geschiedenis komt alsnog binnen, want de cliënt was niets kwijt | §10, punt 3 |
| Blokkeren tijdens een lopende verbinding | de eigenaar blijft schrijven tot hij opnieuw verbindt | §10, punt 4. Open punt 10 van **Umbrelapp** |
| Venster van twee minuten, met de pagina dicht | de teller loopt in het relay-proces en sluit vanzelf | `CLAUDE.md`, "Het tijdvenster loopt in het relay-proces" |
| Eén blob boven `RELAY_MAX_WRITE_BYTES` (1 MB) | geweigerd; meerdere kleinere samen niet, want de grens is per schrijfactie | §8 van het naslagdocument |
| Twee eigenaars die tegelijk verbinden | onafhankelijk, en elk ziet alleen zijn eigen gegevens | §1b |

Wat er als bijvangst uit kan komen, en dat is de reden om de proeven echt te dóen: `owners.json` groeit hier
voor het eerst voorbij één of twee regels, en de statuspagina is nog nooit met een handvol eigenaars en een
volle weigerlijst gezien.

### 4d. Waar het staat, en wat het niet raakt

`tools/relay-client/`, met een eigen `package.json`. Niet in een app-map, want alles daar wordt bij
installatie naar het apparaat gekopieerd (`CLAUDE.md`, "Zet geen CLAUDE.md of andere werkbestanden in een
app-map"). Geen `VERSION`, geen image, geen manifest: er is niets uit te rollen, dus de versieregels van de
twee apps gelden hier niet.

### 4e. Er is geen Evolu-cliënt voor Node, dus die wordt hier samengesteld

**Uitgezocht en werkend gekregen op 09-09-2026, en dit is de belangrijkste uitkomst van de eerste sessie.**
`@evolu/nodejs` 3.1.0 bevat de relay plus losse bouwstenen (de better-sqlite3-driver, een BroadcastChannel,
een klok, `runMain`), maar géén cliënt: er is geen `createEvoluDeps` voor Node zoals `@evolu/web` die voor
de browser heeft. `createEvolu` vraagt `EvoluPlatformDeps`, en die zet `tools/relay-client/src/evolu-node.js`
zelf in elkaar uit de in-memory bouwstenen van `@evolu/common`.

Alles draait in één proces, dus de database-worker en de gedeelde worker zijn de in-memory varianten. Dat is
geen omweg: de documentatie van Evolu noemt ze de terugvaloptie voor platforms zonder echte workers, en er
valt hier niets te winnen met een tweede draad.

Vier dingen die dat kostte, alle vier stil falend en geen van alle uit de typen af te lezen:

1. **`installPolyfills()` uit `@evolu/common/polyfills` moet aangeroepen worden.** Evolu gebruikt
   `Map.prototype.getOrInsertComputed`, en dat heeft Node 24 niet. Zonder de aanroep valt de eerste
   schrijfactie om met "getOrInsertComputed is not a function". Hun eigen documentatie noemt Node 24
   letterlijk als reden dat die polyfill bestaat;
2. **`createEvoluDeps` is geen optionele verpakking.** Dáár wordt de gedeelde worker aan de database-worker
   geknoopt en de "tab leader" aangekondigd. Wie zijn `EvoluPlatformDeps` rechtstreeks aan de run geeft,
   krijgt een instantie die het lijkt te doen tot de eerste schrijfactie afbreekt met "Expected tab leader
   port.";
3. **de AsyncDisposableStack die `initSharedWorker` teruggeeft moet iemand bezitten.** Laat je hem vallen,
   dan wordt hij pas opgeruimd als de run eronder al weg is, en elk afsluiten eindigt met een
   `SuppressedError` waarvan de oorzaak ("Cannot use a disposed object") nergens te zien is;
4. **een defect in een worker komt standaard uit een microtaak naar buiten** en verdwijnt dus. Beide runs
   krijgen daarom een eigen `reportDefect`. Voor een cliënt die bestaat om fouten zichtbaar te maken is dat
   geen luxe.

Punt 4 is bovendien de reden dat de andere drie te vinden waren. Zonder eigen `reportDefect` zegt dit
pakket bij elke fout hetzelfde: "An error was suppressed during disposal", zonder oorzaak.

**Gevolg voor dit plan:** de samenstelling is een eigen bestand met eigen commentaar, en het is het stuk dat
bij een versieverhoging van Evolu als eerste omvalt. De toets die dat moet vangen staat in §7.

## 5. Het werk in grote lijnen

1. **De cliënt-API van `@evolu/common` 8.7.0 verifiëren.** Een eigenaar uit een mnemonic, een schema met een
   kolom waar een blob in past, en verbinden met een `syncUrl`. Dit staat expres eerst: van de relaykant is
   alles nagetrokken, van de cliëntkant niets. Valt die API tegen, dan verandert de rest van dit plan.
2. Een kale opdrachtregel die één eigenaar maakt, verbindt en schrijft. Dat is het moment waarop bekend is
   of het werkt.
3. Meerdere eigenaars naast elkaar, elk in een eigen map, met een register erbij.
4. De UI eromheen: de lijst, de knoppen per eigenaar, en de meldingen uit de verbinding.
5. De proeven uit §4c lopen, en de uitkomsten terugschrijven naar de plek waar de bewering nu staat: §10 van
   het naslagdocument en open punt 10 van **Umbrelapp**.

## 6. Open punten

1. **Hoe zichtbaar is een 401 in de cliënt?** Evolu probeert opnieuw en is ontworpen om een relay te
   overleven die er niet is. Als een weigering en een relay die plat ligt in de cliënt hetzelfde signaal
   geven, is de eerste proef uit §4c niet af te lezen. De uitweg blijft binnen dit gereedschap: een eigen
   WebSocket-poging naast Evolu, met dezelfde `OwnerId` in de URL, die de statuscode wel te zien krijgt.
   Dat is een handeling van een paar regels, want de `OwnerId` staat in de URL van de verbinding (§10 van
   het naslagdocument).
2. **Wat is een zinnige blob om mee te experimenteren?** Willekeurige bytes zijn genoeg voor de bytegrens,
   maar niet om te zien of gegevens werkelijk heen en weer gaan. Iets met leesbare inhoud en een teller is
   waarschijnlijk beter.
3. **Wordt de gegevensmap van de proef opgeruimd?** Twintig eigenaars die blijven staan is rommel, en het
   is sleutelmateriaal. Waarschijnlijk een opdracht die er één weggooit en één die alles weggooit.
4. **Data per eigenaar wissen op de relay staat al open bij Umbrelapp.** Dit gereedschap maakt dat makkelijk
   te beproeven maar lost het niet op; het blijft schrijven in andermans schema (§8 van het naslagdocument).

## 7. Verificatie

**Wat automatisch kan is klein en dat is eerlijk om vooraf te zeggen.** Het meeste van dit gereedschap is
netwerk en UI. Wat wél in de suite hoort:

- het register van eigenaars: aanmaken, teruglezen, een naam die al bestaat, een map die half is;
- het afleiden van een `OwnerId` uit een mnemonic, met een vaste mnemonic en een vaste verwachte uitkomst.
  Dat is de toets die omvalt als de bibliotheek onder ons iets anders gaat doen;
- het lezen van de opdrachtregel.

Alles wat een relay nodig heeft is handwerk, en dat is precies het doel van dit plan: de proeven uit §4c
worden met de hand gedaan en de uitkomst wordt opgeschreven. Een groene suite zegt hier dus weinig, en de
uitslag van dit plan staat in de documenten die het corrigeert.