nordisk/knut

knut-popviz

An egui driver for the knut-native population bulk-loader, plus a headless, robot-testable core.

• lib (knut_popviz) — the population generator + PopvizState, whose state_json() is the external-state contract (no egui types, so it builds and tests without a display).
• bin (knut-popviz, feature gui) — a thin egui shell: a progress bar per label, live rows/s, and the same bulk path as the population example (graphar-falkordb::FalkorDbLoader, no falkordb_bulk_loader).

Run the GUI

cargo run -p knut-popviz --features gui -- \
  --url redis://127.0.0.1:6379 --graph pop --scale 0.001 --drop

FalkorDB autostart (--start-db / KNUT_FALKORDB_AUTOSTART)

Pass --start-db (or set KNUT_FALKORDB_AUTOSTART=1) and, when the configured --url is unreachable, knut-popviz brings up a FalkorDB container from Rust (testcontainers → Podman, per constellation LAW 7 — never a shell script), waits until the module answers, and rewrites the connection to the container's mapped port. Opt-in, so a user with their own DB is never surprised.

cargo run -p knut-popviz --features gui -- --start-db --scale 0.001 --drop

The image is picked from KNUT_FALKORDB_IMAGE (default localhost/knut-falkordb-valkey9:latest — our FalkorDB-on-Valkey-9 build; the module must run on Valkey 9, never stock redis. Override with any valkey-9 FalkorDB image). The container is stopped when the app exits.

Note: --start-db (start the DB) is distinct from --autostart (start the load on the first frame, used by the robot tests below).

Robot-testing (auto, no human)

Two tiers, mirroring the pipeline viewer's introspection:

1. Data-layer matrix — PopvizState::state_json() is asserted directly (no display): the lib unit tests, and tests/robot.rs (#[ignore], needs a FalkorDB at $KNUT_FALKORDB_URL) which drives the real load through run_load over a scale matrix and asserts the introspection reaches phase: "done" with every label loaded == total:

cargo test -p knut-popviz --test robot -- --ignored --nocapture

1. Live GUI smoke — the egui app is observable from outside. With --autostart (or KNUT_POPVIZ_AUTOSTART=1) it runs the load on the first frame and rewrites $KNUT_POPVIZ_STATE (default <tmp>/knut_popviz_state.json) every ~300 ms with the full state (phase, per-label loaded/total, rows_per_s, error, placeholders). A robot launches it under Xvfb/Wayland and polls that JSON as the post-condition oracle:

KNUT_POPVIZ_STATE=/tmp/p.json KNUT_POPVIZ_AUTOSTART=1 \
  knut-popviz --scale 0.001 --drop &
# poll /tmp/p.json until phase == "done", assert loaded == total

Rule: any new visible field in the UI must be added to PopvizState::state_json() — introspection coverage is part of the feature.