performance.md

title	Performance budgets
description	Reproducible read-only scan, hashing, cache, memory, and artifact-size baselines.

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, enforces every ceiling, and retains an optiflow.performance-baseline.v1 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.

Run the baseline

task performance:check

The equivalent commands are:

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, scenario timings, 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

• Wall time 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.