# How syncroot performance will be measured

There are no published performance numbers yet. This document defines the test
before the results so that someone outside the project can reproduce every
number. Do not quote placeholders or present an empty table as a result.

## Questions the benchmark should answer

The main workload is a folder that already contains many small files while
several processes keep writing. Large one-time transfers matter too, but they
are not the workload syncroot is primarily designed around.

| Question | Measurement |
| --- | --- |
| How long until another device can safely open a change? | Write-to-readable latency, p50 and p99 |
| Does an existing large tree slow down each new change? | Latency as the file count grows |
| What happens when several processes write at once? | Latency with concurrent writers |
| What does the daemon cost while waiting? | Idle CPU |
| Does sync compete with the workload for memory? | Resident memory at scale |
| Where is syncroot likely to be slower? | First full transfer and full-history join |

## Describe every run

Publish these conditions beside each result so another person can recreate the
workload:

- the syncroot commit hash and every compared tool's version;
- CPU, RAM, disk, filesystem, and operating system;
- link speed, RTT, and whether devices use a LAN or private mesh;
- file count, total bytes, file-size distribution, and directory depth;
- writer count and write rate;
- repetitions and aggregation method;
- every non-default setting.

A number without these conditions is not reproducible and should not be used as
a performance claim.

## Planned result tables

These tables are templates, not results.

### Time from write to readable file

Folder: **TODO** files, **TODO** total. Writers: **TODO**. Link: **TODO**.

| Measurement | syncroot | Comparison |
| --- | --- | --- |
| Write-to-readable, p50 | TODO | TODO |
| Write-to-readable, p99 | TODO | TODO |
| Time to converge after 1,000 writes | TODO | TODO |

### Cost as the folder grows

| Files in folder | syncroot p50 | Comparison p50 |
| --- | --- | --- |
| 1,000 | TODO | TODO |
| 10,000 | TODO | TODO |
| 50,000 | TODO | TODO |
| 250,000 | TODO | TODO |

### CPU, memory, and disk

| Measurement | syncroot | Comparison |
| --- | --- | --- |
| Idle CPU, 50k files | TODO | TODO |
| Resident memory, 50k files | TODO | TODO |
| Disk overhead vs. payload | TODO | TODO |

### Workloads where syncroot loses

Every published benchmark must keep at least one meaningful losing workload.
The likely candidates are a first full transfer and joining a folder with a
large retained history.

| Measurement | syncroot | Best comparison |
| --- | --- | --- |
| First full transfer, 10 GB | TODO | TODO |
| Full-history join | TODO | TODO |

## What the harness must do

The planned harness must generate the folder, drive concurrent writers, and
measure from `close()` on device A until device B can read complete content with
the expected hash. It must produce a machine-readable report containing every
condition listed above.

Do not publish a reproduction command until its binary and options exist in the
public repository and work from a clean checkout.

## Rules for publishing results

1. Run tools against the same workload and existing network. Do not compare a
   local direct transfer with a hosted service's datacenter path.
2. Put file count, writer count, link, and RTT beside every result.
3. Keep losing rows and failed runs visible.
4. Publish raw reports and the exact reproduction command.
5. Say that change-driven behavior is faster only after measurements show it.