Performance budgets

optiflow keeps a versioned synthetic baseline for the read-only scan path. The baseline is a regression guard, not a promise that every filesystem or machine will finish a real collection within the same time.

The authoritative fixture and ceilings are checked in at performance/budgets-v1.json. CI builds an optimized binary, generates the fixture in a temporary directory, executes three independent cold-state trials, enforces every ceiling, and retains an optiflow.performance-baseline.v2 JSON report for review.

Representative fixture

Scenario	Input	Evidence exercised
Cold discovery	1,000 files with distinct sizes	Traversal, content classification, handle-bound observation, SQLite persistence, contract validation, and artifact publication without candidate hashing
Cold hashing	Eight groups of four 1 MiB byte-identical files	Candidate narrowing, complete BLAKE3-256 hashing, exact grouping, persistence, contract validation, and artifact publication
Warm hashing	The unchanged hashing collection and state	Full cache eligibility checks and reuse of all 32 accepted observations

Every run disables optional media probing. The fixture therefore measures the optiflow-owned path rather than an installed ffprobe version or media-decoder performance. It uses only generated bytes and never reads user media. The report still emits deterministic not_applicable profile evidence, so the new report v6 field remains inside the artifact-size budget without importing provider variability.

Enforced ceilings

Measurement	Maximum
Cold discovery wall time	15 seconds
Cold hashing wall time	15 seconds
Warm-cache wall time	10 seconds
Peak resident memory across measured child runs	256 MiB
Committed artifact bytes per accepted observation	4 KiB

These deliberately tolerant ceilings detect order-of-magnitude regressions on shared CI runners. They are not optimization targets, throughput forecasts, or hardware-independent service-level objectives. Tightening a ceiling requires repeatable evidence on the supported CI platform; loosening one requires an explicit explanation in the pull request.

Sampling and enforcement

Each baseline executes three trials against the same immutable generated input and a new state directory for every trial. The harness validates file counts, duplicate groups, and warm-cache reuse in every trial before it evaluates a performance number.

Wall-time ceilings are enforced against the median of the three samples. A sustained regression must therefore exceed its budget in at least two trials; one isolated shared-runner stall remains visible without deciding the build.
Artifact-size ceilings use the largest value observed for each scenario.
Peak resident memory is the largest value observed across every measured child process.
The report retains the raw scenario measurements for all three trials plus the aggregate used for enforcement.

This policy preserves the published ceilings and detects sustained order-of-magnitude regressions while separating them from transient whole-host contention. It does not discard slow samples or weaken correctness checks.

Run the baseline

task performance:check

The equivalent commands are:

python3 -m unittest tests/test_performance_baseline.py
cargo build --locked --release
python3 scripts/run-performance-baseline.py \
  --binary "target/release/optiflow" \
  --budgets "performance/budgets-v1.json" \
  --output "target/performance-baseline.json" \
  --enforce

The report records the tested binary version, operating-system class, architecture, exact fixture and budgets, sampling policy, every raw trial, enforcement aggregates, cache-hit counts, duplicate-group counts, artifact sizes, peak resident memory, and every budget violation. It intentionally excludes hostnames, repository paths, temporary paths, environment values, and source contents.

Interpretation and limitations

Each wall-time sample includes process startup and the complete scan transaction, but not release compilation or fixture generation.
Peak resident memory is the largest measured optiflow child-process value; it is not a component-level allocation profile.
Artifact size covers the committed per-run directory, not SQLite storage or source bytes.
The temporary filesystem does not model removable disks, network mounts, thermal throttling, or concurrent host load.
The baseline does not exercise optional probes, extensions, future transactions, or optimization providers.

Use a profiler and a purpose-built fixture for diagnosis after this broad guard detects a regression. Do not weaken observation, validation, or artifact-commit invariants merely to recover a performance number.

Progress and compatibility

The v0.1.x CLI intentionally emits no live scan-progress stream. Human and JSON callers receive one terminal command result, and cancellation remains cooperative. JSON standard output therefore stays compatible and free of timing-dependent events. A future machine-readable event stream requires its own versioned contract; scripts must not infer progress by parsing files in the state directory.

This baseline adds no command, option, environment variable, database migration, or product JSON contract. The measurement report is CI evidence, not a runtime artifact accepted by report, plan, or flow. The sampling change advances that evidence schema from v1 to v2 because elapsed_seconds now identifies an aggregate and v2 also retains the raw trials.