Docs / Compare workflow
Upload and read the report
VeluneOS Compare is a hosted service in Private Beta. You upload the comparison.velune file you prepared and reviewed; the report comes back in the browser.
1. Sign in and upload
- Open compare.veluneos.ai/compare. Your browser asks for the Beta username and password sent to you. There is no self-service sign-up; request access first.
- Choose
comparison.velune(the page shows the maximum file size) and press Compare. - When it finishes the page shows “Done. Nothing was stored on the server.”, the comparison decision, and the report.
- Download what you need: Report (HTML), Report (Markdown),
comparison_report.json,comparison_summary.md,stream_categories.json. Reports are not kept on the server, so download them before you leave the page.
The upload is processed in a temporary directory that is deleted when the report is returned.
If the upload is rejected
| Code | Meaning | What to do |
|---|---|---|
TRANSFER_CONTRACT_UNSUPPORTED | The file was prepared with an older Beta Kit. | Install Beta Kit 0.1.1b5, re-run velune mapping init and velune prepare. |
TRANSFER_PACKAGE_REQUIRED | The upload is not a comparison.velune from the Beta Kit (for example output of velune-adapter build). | Prepare the file with velune prepare. |
AMBIGUOUS_STREAM_CORRESPONDENCE | A stream pairing is not established by identical topic name or by your confirmation. | Review correspondence_review in mapping.json and prepare again. |
TRANSFER_PACKAGE_INVALID | The files inside the archive do not match their manifest (for example the file was edited). | Prepare the file again; do not modify it after prepare. |
PAYLOAD_TOO_LARGE | The file is larger than the service accepts. | Contact us with the file size (not the file). |
2. The decision
Every comparison returns one stated decision:
| Decision | Meaning |
|---|---|
REVIEW_REQUIRED | Structural differences observed for review. |
NO_MATERIAL_STRUCTURAL_CHANGE | No material structural difference observed in the compared streams and range. It does not mean the system is healthy, correct or safe. |
INCONCLUSIVE_DIFFERENCE | Differences observed, but the recorded evidence does not support asserting them. |
INSUFFICIENT_COVERAGE | Not compared: the recordings share no complete one-second bucket. |
3. Reading the report
Times are relative to the start of each run (T+12s) and the comparison works in complete one-second buckets common to both runs. Streams are named by neutral key (Stream 003, stream.unmapped.003); your labels appear in the category table.
Sections
- Result — the decision, how many supported and inconclusive differences, the first supported difference, and the compared range.
- Structural differences observed — one card per finding, in review order.
- Streams — every stream's observed status, with the note that “no material difference” is bounded to the listed streams and compared buckets.
- What was not compared — run durations and any messages after the last complete common bucket.
- Evidence trace — the events and evidence IDs behind each finding, for reproducibility.
Finding types
- Stream present in Reference only / Target only — a stream exists in one run but not the other.
- Recorded message interval longer / shorter in Target — the interval between messages changed, with values from both runs and whether it returned to the Reference pattern.
- Target (or Reference) recorded no messages while the other did — activity loss, and when it recovered.
- Timestamp representation change — a change in recorded timestamp precision, reported on its own rather than as a slowdown.
Each finding shows
What, Stream, When (the window to investigate), Magnitude (values from both runs), After the window (whether it returned), Evidence and an ID.
Evidence quality
- Comparable — the recorded evidence on both sides supports this observation.
- Limited — supported, but the recorded time axis limits how precisely it can be read.
- Inconclusive — the recorded evidence does not support asserting this difference.
Your stream categories
Below the decision, the Compare page shows the labels from your mapping beside each stream key and how each stream was paired: same_topic_name, customer_confirmed_same_stream, reference_only or target_only. If a key pairs streams you labelled differently, a notice asks you to review it as a possible removal plus addition.
4. Verify and decide
Start with the first finding in review order and open its window in your own tools. Review order is not a severity score. VeluneOS reports structural observations; it does not determine root cause, fault, safety, regression or release readiness. Your engineers decide.
See a complete example: sample report.