Milestone 0.12 — Performance optimization¶

Status: complete

Outcome: close the frozen ADR-028 competitive-parity performance gate on every required target/profile with production-compile evidence, resource budgets, and retained 0.11 parity on the candidate ancestry

Depends on: 0.11 (complete — demonstrated Redland parity)

Progress report: docs/reports/0.12.md

0.11 delivered native performance samples and protocol honesty without a blanket faster-than-Redland claim. 0.12 closes the ADR-028 competitive-parity gate on committed three-host production-compile evidence with RSS budgets and retained 0.11 parity. Tip CI diagnostics after library-path isolation show large host-scoped wins on Linux/macOS; suite-wide faster-than-Redland is the separate ADR-029 / milestone 0.13 nine-cell gate (complete). Version 1.0 readiness consumes this milestone’s competitive-parity gate together with 0.13’s suite-wide claim, not 0.11’s parity-only refresh.

Frozen scope¶

Baseline comparison: Redland librdf 1.0.17 public C API versus Oxiland librdf-compat / oxiland-capi, same completed workloads and result validation as compatibility/performance/0.11-suite.json (or a reviewed successor revision frozen before qualification).
Targets: Linux x86-64, macOS Apple Silicon, Windows x86-64.
Build profiles: release-default and any additional production profiles named by the frozen performance matrix. Matrix profile names such as release-default mean Cargo --release (profile release) with the declared feature set—not dev/debug.
Production compile (mandatory): Oxiland artifacts under test are built with cargo build -p oxiland-capi --release --locked (or the equivalent documented release profile). Debug builds, target/debug libraries, debug_assertions = true, and opt-level = 0 are invalid evidence. Redland and the C perf_bench wrappers use equivalent native optimization (at least -O2), recorded in sample provenance. See compatibility/performance/0.12-suite.json protocol.require_production_compile.
Protocol: thresholds and measurement rules in VERIFICATION.md and ADR-028 — throughput median ≥ 0.90 (CI lower > 0.85), latency median ≤ 1.20 (CI upper < 1.40), production compile only, no waiver of required cases.
Compatibility invariant: 0.11 behavioral, source, and ABI evidence must remain green on the same candidate revision. Speed may not be bought by relaxing parity, inventing skips, or unbounded memory/disk growth.

Changing the suite after a failure requires an ADR and CHANGELOG note; cases cannot be deleted or marked optional to turn a loss green.

Known cliffs (starting backlog)¶

Derived from native synthetic: false samples under compatibility/qualification/performance/ at the 0.11 tip:

Case	Observation	Optimization focus
`P-SCAN-10K`	Large Oxiland loss on macOS/Linux	Model iteration / C stream path vs Redland scan
`P-CALL-100K`	Large Oxiland loss on macOS/Linux	Handle/FFI overhead for trivial size queries
Mutation / parse / serialize	Strong Oxiland wins on Unix; near-parity on Windows	Preserve wins; close Windows competitiveness where below gate
ASK / SELECT / CONSTRUCT	Mixed slight wins and losses	Query result streaming and C result adapters
Resource budgets	Empty in the 0.11 suite	Measure and freeze peak RSS and disk ratios

Exact ratios are evidence, not marketing claims. Treat them as the work queue.

Work packages¶

ID	Package	Exit signal
WP-12-01	Freeze 0.12 performance matrix and resource budgets	Checksummed suite revision, host/profile list, RSS/disk maxima, production-compile runbook, and measurement runbook
WP-12-02	Profile and attribute every required loss/tie	Per-case flamegraph or equivalent attribution on release binaries, linked in the progress report
WP-12-03	Optimize C-call and handle overhead	`P-CALL-*` (and related overhead cases) pass the gate on every required profile
WP-12-04	Optimize model scan / stream paths	`P-SCAN-*` passes the gate on every required profile
WP-12-05	Close remaining mutation, I/O, and query gaps	All remaining required throughput/latency cases pass; prior Unix wins do not regress below the threshold
WP-12-06	Windows competitiveness pass	Windows release-default (and required profiles) meet the same statistical gate as Unix
WP-12-07	Resource-safe speed	Peak RSS and disk amplification within frozen budgets on every required profile
WP-12-08	Tooling and release checker	`check-performance-gate.py` accepts only native, revision-bound, production-compile samples; `check-0.12-release.py` (or successor) fails closed on stale/synthetic/debug/incomplete bundles
WP-12-09	Retain 0.11 parity on optimized artifacts	Six-cell differentials, C corpus, ABI-swap, and soak smokes green on the performance candidate
WP-12-10	Publish evidence and user guidance	Progress/release reports, updated `docs/users/performance.md`, and evaluator-facing ratio tables with confidence intervals
WP-12-11	Release decision	No open R-022 trigger; risk register has no performance blocker; soak completes without resetting the gate

Qualification commands¶

Build the measured libraries and harnesses in production mode first:

cargo build -p oxiland-capi --release --locked
# C oracle / perf_bench via compatibility/harness/c_oracle/build.sh (uses --release)

Then evaluate samples that record that provenance:

python3 scripts/check-performance-gate.py RAW_SAMPLES \
  --suite compatibility/performance/0.12-suite.json \
  --output PERFORMANCE_REPORT
python3 scripts/check-0.11-release.py   # parity retention on the candidate
python3 scripts/check-0.12-release.py

Samples must set synthetic: false, bind git_revision and artifact hashes, include filled resource_checks matching the frozen budgets, and include a build object with oxiland.cargo_profile = "release", --release in cargo_flags, debug_assertions = false, and Redland/C harness optimization metadata. Debug or dev Cargo profiles fail the gate.

Exit checklist¶

Milestone 0.12 is complete only when every checkbox is backed by linked native evidence and a green 0.12 release checker.